OXXO（墨西哥便利店现金支付）
Quick Reference
WhatOXXO 现金支付
Why覆盖墨西哥 20,000+ 家 OXXO 门店，触达偏好现金的客户
Reading Time8 分钟
Difficulty初级
Prerequisites身份验证 → 环境配置
什么是 OXXO
OXXO 是墨西哥最大的便利店连锁品牌，拥有超过 20,000 家门店。OXXO Pay 允许客户在任意 OXXO 门店出示条形码并以现金支付线上订单，覆盖偏好现金或无银行账户的客户群体。
| 特性 | 详情 |
|---|---|
| 市场 | 墨西哥 |
| 币种 | MXN |
| 结算 | D+1 到 D+3 |
| 拒付 | 无——现金支付 |
| 默认过期时间 | 72 小时（可配置） |
| 单笔上限 | MXN $10,000 |
运作方式
1
商户创建收费
您的服务器调用 POST /api/v1/bank/wallet/charge/，设置 type_charge: "oxxo" 和 currency: "MXN"。
2
A55 生成条形码
API（应用程序编程接口）返回条形码和付款引用号，供客户使用。
3
客户前往 OXXO 门店
客户在任意 OXXO 收银台出示条形码（打印或屏幕展示）并以现金支付。
4
结算与确认
OXXO 向 A55 确认支付。A55 发送 webhook（网络钩子），状态为 paid。
支付流程
OXXO 生命周期
| 状态 | 说明 |
|---|---|
| issued | 条形码已生成；等待付款 |
| pending | 已登记；等待门店现金付款 |
| paid | OXXO 已确认现金付款 |
| expired | 截止前未收到付款 |
| failed | 生成或处理错误 |
创建 OXXO 收费
POST
/api/v1/bank/wallet/charge/Bearer Token创建 OXXO 支付- cURL
- Python
- JavaScript
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": "王芳",
"payer_email": "wangfang@example.com",
"payer_tax_id": "LOAA900215MDFRNN01",
"payer_cell_phone": "+5215598765432",
"installment_value": 800,
"installment_count": 1,
"items": [{"name":"在线课程","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-04-05T23:59:59Z",
"description": "在线课程注册",
"type_charge": "oxxo",
"webhook_url": "https://yoursite.com/webhook",
"redirect_url": "https://yoursite.com/confirmation"
}'
import requests
try:
response = 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": "王芳",
"payer_email": "wangfang@example.com",
"payer_tax_id": "LOAA900215MDFRNN01",
"payer_cell_phone": "+5215598765432",
"installment_value": 800,
"installment_count": 1,
"items": [{"name": "在线课程", "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-04-05T23:59:59Z",
"description": "在线课程注册",
"type_charge": "oxxo",
"webhook_url": "https://yoursite.com/webhook",
"redirect_url": "https://yoursite.com/confirmation",
},
)
response.raise_for_status()
data = response.json()
print(f"条形码：{data['barcode']}")
print(f"付款引用：{data['payment_reference']}")
except requests.exceptions.HTTPError as e:
print(f"请求失败（HTTP {e.response.status_code}）：{e.response.text}")
try {
const response = await fetch(
"https://core-manager.a55.tech/api/v1/bank/wallet/charge/",
{
method: "POST",
headers: {
Authorization: `Bearer ${accessToken}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
wallet_uuid: "00000000-0000-0000-0000-000000000000",
merchant_id: "11111111-1111-1111-1111-111111111111",
payer_name: "王芳",
payer_email: "wangfang@example.com",
payer_tax_id: "LOAA900215MDFRNN01",
payer_cell_phone: "+5215598765432",
installment_value: 800,
installment_count: 1,
items: [{ name: "在线课程", 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-04-05T23:59:59Z",
description: "在线课程注册",
type_charge: "oxxo",
webhook_url: "https://yoursite.com/webhook",
redirect_url: "https://yoursite.com/confirmation",
}),
}
);
if (!response.ok) throw new Error(`请求失败（HTTP ${response.status}）：${await response.text()}`);
const { barcode, payment_reference } = await response.json();
console.log("条形码：", barcode);
} catch (err) {
console.error("创建 OXXO 收费失败：", err.message);
}
响应示例
{
"charge_uuid": "c5d3e6f7-8901-bcde-f234-567890abcdef",
"currency": "MXN",
"type": "oxxo",
"status": "issued",
"barcode": "0123456789012345678",
"payment_reference": "A55-OXX-20261231-001",
"due_date": "2026-04-05T23:59:59Z",
"charge_payment_url": "https://pay.a55.tech/charge/c5d3e6f7-8901-bcde-f234-567890abcdef"
}
| 字段 | 说明 |
|---|---|
barcode | 客户在 OXXO 收银台出示的条形码 |
payment_reference | 收据上显示的引用号 |
due_date | 到期时间，过期后收费失效 |
过期
OXXO 默认过期时间为 72 小时（3 天）。可通过 due_date 配置。过期后，收费标记为 expired 并发送 webhook。
条形码展示
同时展示可扫描的条形码图片和文本字符串。部分 OXXO 收银员在扫描器故障时偏好手动输入引用号。
结算时间
| 场景 | 结算 |
|---|---|
| 标准 OXXO 支付 | D+1 到 D+3 个工作日 |
OXXO 结算流程
客户在 OXXO 门店付款后，收银员扫描条形码并收取现金。OXXO 在当日结束时批量汇总所有支付，并将结算文件发送给支付处理方。A55 在 1–3 个工作日内收到确认并触发 paid webhook。周末支付通常在下一个工作日结算。
常见错误
| 错误 | 原因 | 解决方案 |
|---|---|---|
invalid_currency | 币种非 MXN | OXXO 仅支持墨西哥比索 |
amount_exceeds_maximum | 金额超过 MXN $10,000 | 拆分为多笔收费或改用 SPEI |
amount_below_minimum | 金额低于服务商最低限额 | 查看 OXXO 最低金额 |
oxxo_generation_failed | 条形码生成失败 | 重试；持续失败请联系支持团队 |