Cobro SPEI (MXN)

Documentación de la API · Zypher Global

Generar credenciales

POST /cashin · "currency": "MXN"

Genera una referencia SPEI/CLABE para el pagador en México. El campo amount decide el MODO: com amount = cobro DINÁMICO (CLABE por valor); sem amount = la CLABE FIJA de la cuenta (valor abierto). La confirmación llega a tu webhook.

Cobro dinámico (por valor)

Envía el amount → devolvemos una CLABE/referencia para ESE pago. Es el flujo del día a día (pedido único).

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 }
  ]
}
Respuesta
{
  "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"
}

Consulta luego por el request_number/transaction_id (un solo pago). Ver Consultar Transacciones.

Toda respuesta MXN (dinámica y CLABE fija) incluye bank_name y beneficiary. Muestra estos datos en tu pantalla de pago junto a la CLABE: que el pagador vea el banco (STP) y el nombre del beneficiario aumenta la confianza y la conversión del SPEI.

CLABE por venta (valor abierto · estática)

Llama a la MISMA ruta /cashin con "currency": "MXN" SIN el campo amount, enviando un external_id por venta → devolvemos una CLABE de VALOR ABIERTO solo de esa venta. El mismo external_id devuelve la MISMA CLABE (idempotente en el retry); external_id nuevo = CLABE nueva. El pagador envía cualquier valor vía SPEI. Autenticación, KYC y SPEI activo son los mismos del cash-in normal.
Body
{
  "currency": "MXN",
  "external_id": "PEDIDO-123",
  "webhook_url": "https://seusistema.com/webhooks/zypherglobal",
  "splits": [
    { "username": "operador_mx", "percentage": 10 }
  ]
}
Respuesta
{
  "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"
}
  • Cada venta gana su PROPIA CLABE (18 dígitos). Dos leads de la MISMA cuenta (ej.: Lucas y Maria) NUNCA colisionan, cada uno tiene su CLABE y su external_id. Una venta no cae sobre la otra.
  • El external_id es TUYO (tú lo envías, nosotros NO lo generamos; solo lo devolvemos en el webhook). Es la CLAVE del reuso: mismo external_id = misma CLABE (idempotente); external_id nuevo = CLABE nueva.
  • Cada CLABE es de valor ABIERTO y puede recibir varios pagos, cada uno genera su propio webhook con e2e único (clave de conciliación por pago).
  • Cuando paga, la receiverClabe en el webhook identifica la venta → disparamos el webhook con el external_id correcto. El campo origin: "static" distingue este flujo del depósito por valor.
SIN external_id → devolvemos una CLABE PERMANENTE de la cuenta (dirección de cobro/wallet); ahí no existe atribución por venta, concilia por e2e. Para automatizar ventas, envía SIEMPRE un external_id por venta.

¿Revendes a tus propios clientes? El external_id es el pedido de TU sistema, el valor entra en tu saldo MXN y tú retransmites el webhook al cliente final.

Como la CLABE fija no tiene transaction_id por pago, consulta la LISTA de cobros por clabe/external_id en Consultar Transacciones. Splits y webhook: Splits (reparto) · Webhooks.

OXXO (ficha pagada en efectivo)

Misma ruta /cashin y el MISMO saldo MXN, pero con "method": "OXXO": generamos una ficha que el pagador lleva a cualquier tienda OXXO y paga en efectivo. La respuesta ya trae la referencia y el código de barras al instante, para mostrarlos en tu pantalla. Rango aceptado: 10 a 10,000 MXN, y el pagador debe pagar el monto exacto.
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". Obligatorio (es lo que lo distingue del SPEI/CLABE).
  • amount — entre 10 y 10,000 MXN. Fuera del rango devuelve amount_below_min/amount_above_limit.
  • payerData (name, email) — opcionales: se completan automáticamente si se omiten.
  • generateCheckout — opcional (por defecto true = página alojada). Usa false para recibir la ficha cruda en payee_data y mostrarla en tu pantalla.
  • splits — opcional: OXXO acepta reparto (split) igual que SPEI/PIX, aplicado en el crédito cuando el pago se confirma. Ver Splits (reparto).
Respuesta (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 — número de la referencia OXXO que el pagador indica en la caja.
  • barcode — URL de imagen (PNG) del código de barras, muéstralo directo en tu pantalla.
La ficha queda pending hasta que el pagador va a la tienda (puede tardar horas o días, normal para efectivo). La confirmación llega a tu webhook cuando se realiza el pago y acredita tu saldo MXN. Reconcilia por request_number/external_id.
Webhook, cuando el pagador paga en la tienda
{
  "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"
}
  • Solo se dispara cuando el pago está confirmado (la ficha puede quedar pending por horas/días). Concilia por transaction_id/request_number/external_id, el mismo que guardaste al generar.
  • Si enviaste splits, el reparto ya se aplicó en el crédito antes de este webhook. Detalles en Webhooks.
AnteriorCobro PIX (BRL) Siguiente Cobro USDT
¿Esta página fue útil?