OXXO
Quick Reference
O que é OXXO
OXXO é a maior rede de lojas de conveniência do México, com mais de 20.000 locais. O OXXO Pay permite que clientes paguem compras online em dinheiro apresentando um código de barras em qualquer loja OXXO. Isso alcança clientes que preferem dinheiro ou não possuem conta bancária.
| Característica | Detalhe |
|---|---|
| Mercado | México |
| Moeda | MXN |
| Liquidação | D+1 a D+2 |
| Chargebacks | Nenhum — pagamento em dinheiro |
| Validade padrão | 72 horas (configurável) |
| Valor máximo | MXN $10.000 por transação |
Como funciona
Comerciante cria a cobrança
Seu servidor chama POST /api/v1/bank/wallet/charge/ com type_charge: "oxxo" e currency: "MXN".
A55 gera o código de barras
A API retorna um código de barras e um número de referência de pagamento para o cliente.
Cliente vai à loja OXXO
O cliente apresenta o código de barras (impresso ou na tela) em qualquer caixa OXXO e paga em dinheiro.
Liquidação e confirmação
O OXXO confirma o pagamento para a A55. A A55 envia um webhook com status: "paid".
Fluxo de pagamento
Ciclo de vida do OXXO
| Status | Descrição |
|---|---|
| issued | Código de barras gerado; aguardando pagamento |
| pending | Registrado; aguardando pagamento em dinheiro na loja |
| paid | Pagamento em dinheiro confirmado pelo OXXO |
| expired | Nenhum pagamento recebido antes do prazo |
| error | Erro na geração ou processamento |
Criar uma cobrança OXXO
/api/v1/bank/wallet/charge/Bearer TokenCriar um pagamento OXXO- 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"]
Exemplo de resposta
{
"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"
}
| Campo | Descrição |
|---|---|
barcode | Código de barras que o cliente apresenta no caixa do OXXO |
payment_reference | Número de referência exibido no comprovante |
due_date | Prazo após o qual a cobrança expira |
Vencimento
O vencimento padrão do OXXO é de 72 horas (3 dias). Configure via due_date. Após o vencimento, a cobrança é marcada como expired e um webhook é enviado.
Exiba o código de barras tanto como imagem escaneável quanto como texto. Alguns caixas do OXXO preferem digitar a referência manualmente se o scanner falhar.
Prazo de liquidação
| Cenário | Liquidação |
|---|---|
| Pagamento OXXO padrão | D+1 a D+2 dias úteis |
Processo de liquidação do OXXO
Quando um cliente paga em uma loja OXXO, o caixa escaneia o código de barras e recebe o dinheiro. O OXXO agrupa todos os pagamentos no final do dia e envia arquivos de liquidação ao processador de pagamentos. A A55 recebe a confirmação em 1 a 2 dias úteis e dispara o webhook paid. Pagamentos realizados no fim de semana geralmente são liquidados no próximo dia útil.
Erros comuns
| Erro | Causa | Solução |
|---|---|---|
invalid_currency | A moeda não é MXN | OXXO aceita apenas Pesos Mexicanos |
amount_exceeds_maximum | Valor acima de MXN $10.000 | Divida em múltiplas cobranças ou use SPEI |
amount_below_minimum | Valor abaixo do mínimo do provedor | Verifique o valor mínimo do OXXO |
oxxo_generation_failed | Falha na geração do código de barras | Tente novamente; se persistir, entre em contato com o suporte |