OXXO Pay
Generate an OXXO Pay voucher, how long it lasts, and how you learn it was paid.
Accept cash payments at OXXO convenience stores in Mexico. OXXO is the country's largest convenience store chain, ideal for customers who prefer cash or don't have a bank account.
When to use OXXO
- Customers without a bank account or card.
- E-commerce customers who prefer cash.
- Areas with high OXXO store density.
Step 1: create the request
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": "ORD-001"
}'Step 2: handle the response
OXXO payments start in pending and include the payment instructions:
{
"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"
}| Field | Description |
|---|---|
id | Unique transaction identifier — store it for status checking. |
status | Payment status — initially pending. |
payment_instructions.reference_code | OXXO Pay reference code. |
payment_instructions.barcode | Barcode to display to the customer. |
payment_instructions.expiration_date | Voucher expiration date. |
voucher_pdf | URL to download the PDF voucher. |
Confirmation usually arrives within minutes of paying at a store. However, OXXO's system may hold a
payment in pending for up to 3 hours while it checks for internal failures or potential refunds.
This is expected behavior. If it remains pending beyond 3 hours, contact support.
Step 3: display the instructions
Display the barcode so the customer can show it at the register.
Show the reference_code as a backup in case the barcode can't be scanned.
Use the instructions array to guide the customer.
Indicate when the voucher expires and offer to download the voucher_pdf.
Limits
OXXO Pay has a minimum of $10 MXN and a maximum of $10,000 MXN per transaction. See the full table in Limits.