OXXO

Quick Reference

WhatOXXO cash payments

WhyReach cash-preferred customers at 20,000+ OXXO stores across Mexico

Reading Time8 min

DifficultyBeginner

PrerequisitesAuthentication → Environment

What is OXXO

OXXO is Mexico's largest convenience store chain with over 20,000 locations. OXXO Pay allows customers to pay for online purchases with cash by presenting a barcode at any OXXO store. This reaches customers who prefer cash or lack bank accounts.

Feature	Detail
Market	Mexico
Currency	MXN
Settlement	D+1 to D+2
Chargebacks	None — cash payment
Default expiration	72 hours (configurable)
Max amount	MXN $10,000 per transaction

How it works

Merchant creates charge

Your server calls POST /api/v1/bank/wallet/charge/ with type_charge: "oxxo" and currency: "MXN".

A55 generates barcode

The API returns a barcode and payment reference number for the customer.

Customer visits OXXO store

The customer presents the barcode (printed or on screen) at any OXXO cashier and pays in cash.

Settlement and confirmation

OXXO confirms the payment to A55. A55 sends a webhook with status: "paid".

Payment flow

OXXO lifecycle

Status	Description
issued	Barcode generated; awaiting payment
pending	Registered; awaiting cash payment at store
paid	Cash payment confirmed by OXXO
expired	No payment received before deadline
error	Generation or processing error

Create an OXXO charge

POST/api/v1/bank/wallet/charge/Bearer TokenCreate an OXXO payment

cURL
Python

curl -X POST https://core-manager.a55.tech/api/v1/bank/wallet/charge/ \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_uuid": "00000000-0000-0000-0000-000000000000",
    "merchant_id": "11111111-1111-1111-1111-111111111111",
    "payer_name": "Ana López",
    "payer_email": "ana.lopez@example.com",
    "payer_tax_id": "LOAA900215MDFRNN01",
    "payer_cell_phone": "+5215598765432",
    "installment_value": 800,
    "installment_count": 1,
    "items": [{"name":"Online Course","quantity":1,"total_amount":800,"unit_amount":800,"sku":"COURSE-MX-001","code":"OC001"}],
    "payer_address": {"street":"Calle Madero","address_number":"10","complement":"","neighborhood":"Centro Histórico","city":"Ciudad de México","state":"CDMX","postal_code":"06000","country":"MX"},
    "currency": "MXN",
    "due_date": "2026-12-31T23:59:59Z",
    "description": "Online course enrollment",
    "type_charge": "oxxo",
    "webhook_url": "https://yoursite.com/webhook",
    "redirect_url": "https://yoursite.com/confirmation"
  }'

import requests

charge = requests.post(
    "https://core-manager.a55.tech/api/v1/bank/wallet/charge/",
    headers={"Authorization": f"Bearer {access_token}", "Content-Type": "application/json"},
    json={
        "wallet_uuid": "00000000-0000-0000-0000-000000000000",
        "merchant_id": "11111111-1111-1111-1111-111111111111",
        "payer_name": "Ana López",
        "payer_email": "ana.lopez@example.com",
        "payer_tax_id": "LOAA900215MDFRNN01",
        "payer_cell_phone": "+5215598765432",
        "installment_value": 800,
        "installment_count": 1,
        "items": [{"name": "Online Course", "quantity": 1, "total_amount": 800, "unit_amount": 800, "sku": "COURSE-MX-001", "code": "OC001"}],
        "payer_address": {"street": "Calle Madero", "address_number": "10", "complement": "", "neighborhood": "Centro Histórico", "city": "Ciudad de México", "state": "CDMX", "postal_code": "06000", "country": "MX"},
        "currency": "MXN",
        "due_date": "2026-12-31T23:59:59Z",
        "description": "Online course enrollment",
        "type_charge": "oxxo",
        "webhook_url": "https://yoursite.com/webhook",
        "redirect_url": "https://yoursite.com/confirmation",
    },
)
data = charge.json()
barcode = data["barcode"]
reference = data["payment_reference"]

Response example

{
  "charge_uuid": "c5d3e6f7-8901-bcde-f234-567890abcdef",
  "currency": "MXN",
  "type": "oxxo",
  "status": "issued",
  "barcode": "0123456789012345678",
  "payment_reference": "A55-OXX-20261231-001",
  "due_date": "2026-12-31T23:59:59Z",
  "charge_payment_url": "https://pay.a55.tech/charge/c5d3e6f7-8901-bcde-f234-567890abcdef"
}

Field	Description
`barcode`	Barcode the customer presents at the OXXO cashier
`payment_reference`	Reference number shown on the receipt
`due_date`	Deadline after which the charge expires

Expiration

The default OXXO expiration is 72 hours (3 days). Configure via due_date. After expiration, the charge is marked expired and a webhook is sent.

Barcode display

Display the barcode as both a scannable image and a text string. Some OXXO cashiers prefer to type the reference manually if the scanner fails.

Settlement timing

Scenario	Settlement
Standard OXXO payment	D+1 to D+2 business days

OXXO settlement process

When a customer pays at an OXXO store, the cashier scans the barcode and collects cash. OXXO batches all payments at end-of-day and sends settlement files to the payment processor. A55 receives confirmation in the next 1–2 business days and triggers the paid webhook. Weekend payments are typically settled on the next business day.

Common errors

Error	Cause	Fix
`invalid_currency`	Currency is not `MXN`	OXXO only supports Mexican Pesos
`amount_exceeds_maximum`	Amount over MXN $10,000	Split into multiple charges or use SPEI
`amount_below_minimum`	Amount below MXN $1.00	OXXO requires a minimum of MXN $1.00 per transaction
`oxxo_generation_failed`	Barcode generation failed	Retry; if persistent, contact support

SPEI →Real-time bank transfers in Mexico Credit card →Card payments with installments

Quick Reference

What is OXXO​

How it works​

Merchant creates charge

A55 generates barcode

Customer visits OXXO store

Settlement and confirmation

Payment flow​

OXXO lifecycle​

Create an OXXO charge​

Response example​

Expiration​

Settlement timing​

Common errors​