Cobrança SPEI (MXN)

Documentação da API · Zypher Global

Gerar credenciais

POST /cashin · "currency": "MXN"

Gera uma referência SPEI/CLABE para o pagador no México. O campo amount decide o MODO: com amount = cobrança DINÂMICA (CLABE por valor); sem amount = a CLABE FIXA da conta (valor aberto). A confirmação chega no seu webhook.

Cobrança dinâmica (por valor)

Envie o amount → devolvemos uma CLABE/referência para AQUELE pagamento. É o fluxo do dia a dia (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 }
  ]
}
Resposta
{
  "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"
}

Consulte depois pelo request_number/transaction_id (um pagamento só). Veja Consultar Transações.

Toda resposta MXN (dinâmica e CLABE fixa) traz bank_name e beneficiary. Mostre esses dados na sua tela de pagamento junto da CLABE: o pagador ver o banco (STP) e o nome do beneficiário aumenta a confiança e a conversão do SPEI.

CLABE por venda (valor aberto · estática)

Chame a MESMA rota /cashin com "currency": "MXN" SEM o campo amount, mandando um external_id por venda → devolvemos uma CLABE de VALOR ABERTO só daquela venda. Mesmo external_id devolve a MESMA CLABE (idempotente no retry); external_id novo = CLABE nova. O pagador envia qualquer valor via SPEI. Autenticação, KYC e SPEI ativo são os mesmos do cash-in normal.
Body
{
  "currency": "MXN",
  "external_id": "PEDIDO-123",
  "webhook_url": "https://seusistema.com/webhooks/zypherglobal",
  "splits": [
    { "username": "operador_mx", "percentage": 10 }
  ]
}
Resposta
{
  "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 venda ganha a SUA CLABE (18 dígitos). Dois leads da MESMA conta (ex.: Lucas e Maria) NUNCA colidem, cada um tem a sua CLABE e o seu external_id. Uma venda não cai por cima da outra.
  • O external_id é SEU (você envia, a gente NÃO gera; só ecoa no webhook). Ele é a CHAVE do reuso: mesmo external_id = mesma CLABE (idempotente); external_id novo = CLABE nova.
  • Cada CLABE é de valor ABERTO e pode receber vários pagamentos, cada um vira um webhook próprio com e2e único (chave de reconciliação por pagamento).
  • Quando paga, a receiverClabe no webhook identifica a venda → disparamos o webhook com o external_id certo. O campo origin: "static" distingue este fluxo do depósito por valor.
SEM external_id → devolvemos uma CLABE PERMANENTE da conta (endereço de recebimento/wallet); aí a atribuição por venda não existe, reconcilie por e2e. Para automatizar vendas, mande SEMPRE um external_id por venda.

Revende pros seus próprios clientes? O external_id é o pedido do SEU sistema, o valor cai no seu saldo MXN e você repassa o webhook pro cliente final.

Como a CLABE fixa não tem transaction_id por pagamento, consulte a LISTA de recebimentos por clabe/external_id em Consultar Transações. Splits e webhook: Splits (repasse) · Webhooks.

OXXO (voucher pago em dinheiro)

Mesma rota /cashin e MESMO saldo MXN, mas com "method": "OXXO": geramos um voucher (boleto) que o pagador leva a qualquer loja OXXO e paga em dinheiro. A resposta já traz a referência e o código de barras na hora, para você exibir na sua tela. Faixa aceita: 10 a 10.000 MXN, e o pagador deve pagar o valor exato.
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". Obrigatório (é o que distingue do SPEI/CLABE).
  • amount — entre 10 e 10.000 MXN. Fora da faixa retorna amount_below_min/amount_above_limit.
  • payerData (name, email) — opcionais: preenchidos automaticamente se ausentes.
  • generateCheckout — opcional (padrão true = página hospedada). Use false para receber o voucher cru em payee_data e exibir na sua tela.
  • splits — opcional: OXXO aceita repasse (split) igual ao SPEI/PIX, aplicado no crédito quando o pagamento confirma. Veja Splits (repasse).
Resposta (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 da referência OXXO que o pagador informa no caixa.
  • barcode — URL de imagem (PNG) do código de barras, exiba direto na sua tela.
O voucher fica pending até o pagador ir à loja (pode levar horas ou dias, normal para dinheiro). A confirmação chega no seu webhook quando o pagamento é feito e credita seu saldo MXN. Reconcilie por request_number/external_id.
Webhook, quando o pagador paga na loja
{
  "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"
}
  • Só dispara quando o pagamento é confirmado (o voucher pode ficar pending por horas/dias). Case pelo transaction_id/request_number/external_id, o mesmo que você guardou ao gerar.
  • Se você mandou splits, o repasse já foi aplicado no crédito antes deste webhook. Detalhes em Webhooks.
AnteriorCobrança PIX (BRL) Próximo Cobrança USDT
Esta página foi útil?