How to Accept OXXO pay Cash Payments

This guide shows you how to accept cash payments at OXXO convenience stores in Mexico. OXXO is Mexico’s largest convenience store chain, making it ideal for customers who prefer to pay with cash or don’t have bank accounts.

When to Use OXXO

OXXO payments are perfect for:

Customers without bank accounts or credit cards.
E-commerce customers who prefer cash payments.
Areas with high OXXO store density.
Building trust with cash-preferred demographics.

Step 1: Create and Send the Payment Request

OXXO payments are simple to set up - just specify the payment type and amount. Send your payment request to the Process Transaction endpoint and the API will generate a payment voucher for your customer:

curl -X POST https://stage.tonder.io/api/v1/process/ \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation_type": "payment",
    "amount": 250.00,
    "currency": "MXN",
    "customer": {
      "name": "María Isabel Fernández",
      "email": "maria.fernandez@email.com"
    },
    "payment_method": {
      "type": "oxxopay"
    },
    "client_reference": "order-123"
  }'

For detailed information about all available request fields and their requirements, see the Create a Payment guide.

Step 2: Handle the Response

OXXO payments start with a pending status and include payment instructions for the customer:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "operation_type": "payment",
  "status": "pending",
  "amount": 250.00,
  "currency": "MXN",
  "payment_instructions": {
    "reference_code": "99900012345678",
    "barcode": "||99900012345678||",
    "store_name": "oxxopay",
    "expiration_date": "2024-07-29T23:59:59Z",
    "instructions": [
      "Acude a cualquier tienda OXXO",
      "Presenta este código de barras en caja",
      "Paga exactamente $250.00 MXN en efectivo"
    ]
  },
  "voucher_pdf": "https://api.tonder.io/vouchers/abc123.pdf",
  "created_at": "2024-07-26T10:30:00Z"
}

The response contains key fields you need to handle the OXXO payment flow:

Field	Description
`id`	Unique transaction identifier - store this for status checking
`status`	Current payment status - will be `pending` initially
`payment_instructions.reference_code`	OXXO pay reference code for payment
`payment_instructions.barcode`	Barcode to display to customer
`payment_instructions.expiration_date`	When the payment voucher expires
`voucher_pdf`	URL to download the payment voucher PDF

Id and Status Fields ValidationCheck that you received a valid id and status before proceeding. If either is missing or invalid, do not display payment instructions and handle the error appropriately.

Payment confirmation is near-instant under normal conditions. Once a customer pays at an OXXO store, confirmation typically arrives within minutes. However, OXXO’s system may hold a payment in pending status for up to 3 hours while it checks for internal failures or potential refund scenarios. This is expected behaviour and does not indicate a problem.If a payment remains pending beyond 3 hours, contact soporte@tonder.io so the team can investigate with the payment provider.

Step 3: Display Payment Instructions to Your Customer

Present the payment voucher clearly to help customers complete their OXXO payment successfully. Create a user-friendly page that displays all necessary information for the customer to pay at any OXXO store:

Show the barcode prominently

Display the barcode in a format the customer can easily show to the cashier.

Include the reference code

Show the reference_code as backup in case the barcode can’t be scanned.

Provide clear instructions

Use the instructions array to guide the customer through the payment process.

Highlight the expiration date

Make sure customers know when the voucher expires.

Offer the PDF voucher

Provide a link to download the voucher_pdf for printing.

Here’s an example of a customer voucher template:

<div class="OXXO Pay-voucher">
  <h2>Completa tu pago en OXXO Pay</h2>
  
  <div class="barcode">
    <img src="data:image/png;base64,{BARCODE_IMAGE}" />
    <p>Código: 99900012345678</p>
  </div>
  
  <div class="amount">
    <h3>Monto a pagar: $250.00 MXN</h3>
  </div>
  
  <div class="instructions">
    <h4>Instrucciones:</h4>
    <ol>
      <li>Acude a cualquier tienda OXXO Pay</li>
      <li>Presenta este código de barras en caja</li>
      <li>Paga exactamente $250.00 MXN en efectivo</li>
    </ol>
  </div>
  
  <div class="expiration">
    <p><strong>Vence:</strong> 29 de julio, 2024</p>
  </div>
  
  <a href="{VOUCHER_PDF_URL}" class="download-button">
    Descargar comprobante PDF
  </a>
</div>

Step 4: Track Payment Status

OXXO payments follow this status flow:

pending - Waiting for customer to pay at store.
success - Cash payment received and confirmed.

Webhooks provide real-time notifications when payment status changes. Set up webhooks to receive payment confirmations automatically:

{
  "event": "payment.status_changed",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "success",
    "amount": 250.00,
    "completed_at": "2024-07-27T14:30:00Z",
    "store_location": "OXXO Colonia Roma"
  }
}

If you prefer not to use webhooks, you can check payment status via API:

curl -X GET https://stage.tonder.io/api/v1/transactions/550e8400-e29b-41d4-a716-446655440000/ \
  -H "Authorization: Token YOUR_API_KEY"

Step 5: Handle OXXO-Specific Scenarios

There are some specificities to consider when using OXXO payments:

Payment Timing

OXXOPay confirmations are near-instant under normal conditions:

Confirmation typically arrives within 10 minutes of the customer paying at the store.
In some cases, OXXO’s system holds the status in pending for up to 3 hours while processing internal checks. This is normal.
If a payment remains pending beyond 3 hours and customer claims payment was made, report it to soporte@tonder.io.
OXXO stores are typically open 24/7.
Vouchers expire after 5 days if unpaid.

Amount Limits

Regarding the amount limits, OXXO has the following restrictions:

Minimum amount is $20 MXN (varies by configuration).
Maximum amount is $10,000 MXN per transaction.
Daily limits may apply per customer.

Common Issues

Some common issues that may occur when using OXXO payments are:

Issue	Cause	Solution
`amount_too_high`	Exceeds OXXO Pay limits	Split into multiple payments
`amount_too_low`	Below minimum threshold	Increase amount or use different method
`expired_voucher`	Customer paid after expiration	Create new payment request

Best Practices for OXXO Payments

Follow the best practices below to integrate OXXO payments:

Customer Communication

Send payment instructions via email and SMS.
Include store locator links to help customers find nearby OXXO stores.
Provide clear expiration date warnings.
Offer customer support for payment questions.

Order Management

Keep orders in “pending payment” status until confirmed.
Send reminder emails before voucher expiration.
Have a process for handling expired payments.
Consider offering payment extensions for loyal customers.

Technical Implementation

Generate barcode images for better user experience.
Make vouchers mobile-friendly for easy display at stores.
Cache PDF vouchers for faster loading.
Implement retry logic for voucher generation.

Implementation Example

Here is an example of how to implement OXXO payments. This code displays the payment voucher information on the frontend:

// Frontend: Display OXXO pay voucher
function displayOXXOVoucher(response) {
  const voucher = response.payment_instructions;
  
  document.getElementById('barcode').textContent = voucher.barcode;
  document.getElementById('reference').textContent = voucher.reference_code;
  document.getElementById('amount').textContent = `$${response.amount} MXN`;
  document.getElementById('expiration').textContent = 
    new Date(voucher.expiration_date).toLocaleDateString('es-MX');
  document.getElementById('pdf-link').href = response.voucher_pdf;
  
  // Show instructions
  const instructionsList = document.getElementById('instructions');
  voucher.instructions.forEach(instruction => {
    const li = document.createElement('li');
    li.textContent = instruction;
    instructionsList.appendChild(li);
  });
}

Next Steps

Set up webhooks to receive notifications when OXXO payments are completed.
Learn about HTTP response codes to handle different API responses.
Explore SPEI bank transfers for customers who prefer bank payments.

Introduction

Direct Integration Guides

Webhooks

Reference Pages

Payment Methods

Resources

How to Accept OXXO pay Cash Payments

When to Use OXXO

Step 1: Create and Send the Payment Request

Step 2: Handle the Response

Step 3: Display Payment Instructions to Your Customer

Step 4: Track Payment Status

Step 5: Handle OXXO-Specific Scenarios

Best Practices for OXXO Payments

Implementation Example

Next Steps

​When to Use OXXO

​Step 1: Create and Send the Payment Request

​Step 2: Handle the Response

​Step 3: Display Payment Instructions to Your Customer

​Step 4: Track Payment Status

​Step 5: Handle OXXO-Specific Scenarios

​Best Practices for OXXO Payments

​Implementation Example

​Next Steps

When to Use OXXO

Step 1: Create and Send the Payment Request

Step 2: Handle the Response

Step 3: Display Payment Instructions to Your Customer

Step 4: Track Payment Status

Step 5: Handle OXXO-Specific Scenarios

Best Practices for OXXO Payments

Implementation Example

Next Steps