SPEI charge (MXN)

API Documentation · Zypher Global

Generate credentials

POST /cashin · "currency": "MXN"

Generates a SPEI/CLABE reference for the payer in Mexico. The amount field decides the MODE: com amount = DYNAMIC charge (CLABE by amount); sem amount = the account FIXED CLABE (open amount). The confirmation arrives at your webhook.

Dynamic charge (by amount)

Send amount → we return a CLABE/reference for THAT payment. It is the day-to-day flow (single order).

Body
{
  "currency": "MXN",
  "amount": 500.00,
  "name": "Juan Pérez",
  "document": "PEPJ800101HDFRRL09",
  "description": "Pedido #123",
  "external_id": "PEDIDO-123",
  "webhook_url": "https://seusistema.com/webhooks/zypherglobal",
  "splits": [
    { "username": "operador_mx", "percentage": 10 }
  ]
}
Response
{
  "ok": true,
  "reference": "REF123456",
  "clabe": "012345678901234567",
  "amount": 500.00,
  "fee": 5.00,
  "currency": "MXN",
  "request_number": "pr_...",
  "transaction_id": "pr_...",
  "status": "pending",
  "bank_name": "STP (Sistema de Transferencia y Pagos)",
  "beneficiary": "Zypher"
}

Query later by request_number/transaction_id (a single payment). See Query Transactions.

Every MXN response (dynamic and fixed CLABE) includes bank_name and beneficiary. Show these on your payment screen next to the CLABE: letting the payer see the bank (STP) and the beneficiary name builds trust and boosts SPEI conversion.

CLABE per sale (open amount · static)

Call the SAME route /cashin with "currency": "MXN" WITHOUT the amount field, sending an external_id per sale → we return an OPEN-AMOUNT CLABE just for that sale. The same external_id returns the SAME CLABE (idempotent on retry); a new external_id = a new CLABE. The payer sends any amount via SPEI. Authentication, KYC and active SPEI are the same as the normal cash-in.
Body
{
  "currency": "MXN",
  "external_id": "PEDIDO-123",
  "webhook_url": "https://seusistema.com/webhooks/zypherglobal",
  "splits": [
    { "username": "operador_mx", "percentage": 10 }
  ]
}
Response
{
  "ok": true,
  "static": true,
  "open_value": true,
  "currency": "MXN",
  "external_id": "PEDIDO-123",
  "clabe": "012345678901234567",
  "transaction_id": "spc...",
  "bank_name": "STP (Sistema de Transferencia y Pagos)",
  "beneficiary": "Zypher"
}
  • Each sale gets its OWN CLABE (18 digits). Two leads on the SAME account (e.g. Lucas and Maria) NEVER collide, each has its own CLABE and its own external_id. One sale never lands on top of another.
  • The external_id is YOURS (you send it, we do NOT generate it; we only echo it in the webhook). It is the reuse KEY: same external_id = same CLABE (idempotent); a new external_id = a new CLABE.
  • Each CLABE is OPEN-amount and can receive multiple payments, each one becomes its own webhook with a unique e2e (per-payment reconciliation key).
  • When paid, the receiverClabe in the webhook identifies the sale → we fire the webhook with the right external_id. The origin: "static" field distinguishes this flow from the by-amount deposit.
WITHOUT external_id → we return a PERMANENT account CLABE (receiving address/wallet); there is no per-sale attribution then, reconcile by e2e. To automate sales, ALWAYS send an external_id per sale.

Reselling to your own clients? The external_id is the order in YOUR system, the amount lands in your MXN balance and you relay the webhook to the end client.

Since the fixed CLABE has no transaction_id per payment, query the LIST of receipts by clabe/external_id in Query Transactions. Splits and webhook: Splits (pass-through) · Webhooks.

OXXO (voucher paid in cash)

Same route /cashin and the SAME MXN balance, but with "method": "OXXO": we generate a voucher the payer takes to any OXXO store and pays in cash. The response already returns the reference and the barcode right away, for you to show on your screen. Accepted range: 10 to 10,000 MXN, and the payer must pay the exact amount.
Body
{
  "currency": "MXN",
  "method": "OXXO",
  "amount": 250.00,
  "payerData": {
    "name": "Luis Hernandez",
    "email": "[email protected]"
  },
  "external_id": "PEDIDO-123",
  "webhook_url": "https://seusistema.com/webhooks/zypherglobal",
  "splits": [
    { "username": "operador_mx", "percentage": 10 }
  ]
}
  • method — "OXXO". Required (this is what distinguishes it from SPEI/CLABE).
  • amount — between 10 and 10,000 MXN. Out of range returns amount_below_min/amount_above_limit.
  • payerData (name, email) — optional: filled automatically if omitted.
  • generateCheckout — optional (default true = hosted page). Use false to receive the raw voucher in payee_data and show it on your own screen.
  • splits — optional: OXXO supports split just like SPEI/PIX, applied on credit when the payment confirms. See Splits (pass-through).
Response (generateCheckout: false)
{
  "ok": true,
  "currency": "MXN",
  "amount": 250.00,
  "fee": 5.00,
  "method": "OXXO",
  "request_number": "oxxo_...",
  "transaction_id": "oxxo_...",
  "status": "pending",
  "awaiting_instruction": false,
  "transfer_type": "REFERENCE",
  "payee_data": {
    "transferType": "REFERENCE",
    "reference": "8204240000119882",
    "barcode": "https://static.muwe.mx/.../abc.png"
  }
}
  • reference — the OXXO reference number the payer gives at the register.
  • barcode — image URL (PNG) of the barcode, show it directly on your screen.
The voucher stays pending until the payer goes to the store (may take hours or days, normal for cash). Confirmation arrives on your webhook when payment is made and credits your MXN balance. Reconcile by request_number/external_id.
Webhook, when the payer pays at the store
{
  "type": "cashin",
  "origin": "dynamic",
  "status": "confirmed",
  "amount": 250.00,
  "fee": 5.00,
  "request_number": "oxxo_...",
  "transaction_id": "oxxo_...",
  "external_id": "PEDIDO-123",
  "e2e": "E...",
  "provider": "Zypher Global"
}
  • Fires only when the payment is confirmed (the voucher may stay pending for hours/days). Match by transaction_id/request_number/external_id, the same you stored when generating.
  • If you sent splits, the split was already applied on credit before this webhook. Details at Webhooks.
PreviousPIX charge (BRL) Next USDT charge
Was this page helpful?