ZypfyDocs Acessar painel
Guia de integração

Depósitos MXN (México)

Cobranças no México via SPEI: gere uma CLABE, receba em saldo MXN, converta para BRL e saque via PIX.

Depósitos MXN (México)

Além do PIX brasileiro, a Zypfy processa cobranças no México via SPEI — o sistema de transferências interbancárias do Banco de México. Você gera uma CLABE de 18 dígitos e o cliente mexicano transfere para ela pelo app do banco dele.

Fluxo completo

código
┌──────────┐   1. POST /api/payments/mx/deposit   ┌──────────┐
│  Seu     │ ────────────────────────────────────▶│  Zypfy  │
│  backend │                                      │          │
└────┬─────┘◀── 2. { clabe, reference, ... } ─────┴─────┬────┘
     │                                                  │
     │ 3. Exibe CLABE + beneficiário + referência       │
     ▼                                                  │
┌──────────┐                                            │
│  Cliente │                                            │
│  no MX   │                                            │
└────┬─────┘                                            │
     │ 4. Transfere via SPEI no app do banco            │
     ▼                                                  │
┌───────────────────────────────────────────────────────┴────┐
│                  SPEI (Banco de México)                     │
└───────────────────────────────────────────────────────┬────┘
                                                        │
     ┌─────────────────────────────────────────────────┘
     │ 5. Webhook: type=Deposit, currency=MXN, status=COMPLETED
     ▼
┌──────────┐
│  Seu     │ ── 6. Confirma o pedido       ┌──────────────────────┐
│  backend │                               │ Saldo em MXN         │
└────┬─────┘                               │ (wallets.balance_mxn)│
     │                                     └──────────┬───────────┘
     │ 7. POST /api/accounts/mxn/convert (MXN → BRL)  │
     ▼                                                 ▼
┌──────────────────────────────────────────────────────────┐
│  Saldo em BRL  ──▶  8. POST /api/withdrawals/withdraw    │
│                     (saque normal via PIX)               │
└──────────────────────────────────────────────────────────┘

Criar a cobrança

código
POST https://api.zypfy.com/api/payments/mx/deposit

Headers: Authorization: Bearer SEU_TOKEN, Content-Type: application/json.

O token é o mesmo da Autenticação — não existe credencial separada para o México.

Body

json
{
  "amount": 500.00,
  "external_id": "order-mx-2026-0001",
  "clientCallbackUrl": "https://minhaloja.com/webhooks/deposit",
  "customer": {
    "name": "Juan Pérez",
    "email": "[email protected]"
  },
  "description": "Pedido 0001"
}
CampoTipoObrigatórioDescrição
amountnumbersimValor em MXN (pesos) que o cliente vai transferir. Use decimais, não centavos: 500.00.
external_idstringsimSeu identificador do pedido. Também é a chave de idempotência (veja abaixo).
customer.namestringnãoNome do pagador. Default: "Cliente".
customer.emailstringnãoE-mail do pagador.
clientCallbackUrlstringnãoURL que receberá o webhook. Se omitida, usa a URL configurada no portal.
descriptionstringnãoDescrição livre repassada ao provedor.
utm_sourcestringnãoOrigem/LeadId da campanha. Máx. 255. Veja Rastreamento de campanhas abaixo.
utm_mediumstringnãoMedium (cpc, organic, ...). Máx. 64.
utm_campaignstringnãoNome da campanha. Máx. 255.
utm_contentstringnãoIdentificador do criativo/variação. Máx. 255.
utm_termstringnãoKeyword/termo. Máx. 255.
platformstringnãoLabel livre de plataforma de tracking. Máx. 32.
srcstringnãoParâmetro extra usado por Utmify e AdOptify.
sckstringnãoParâmetro extra usado por Utmify e AdOptify.
productsarraynãoItens do pedido repassados aos trackers (máx. 20). priceInCents em centavos de peso.
skip_utmifybooleannãotrue não dispara a Utmify nesta cobrança.
skip_xtrackybooleannãotrue não dispara a Xtracky nesta cobrança.
skip_adoptifybooleannãotrue não dispara a AdOptify nesta cobrança.

Resposta 201

json
{
  "message": "MXN deposit created successfully.",
  "deposit": {
    "id": 123456,
    "transaction_id": "pi_9f2c1a4b7e",
    "external_id": "order-mx-2026-0001",
    "status": "PENDING",
    "currency": "MXN",
    "amount_mxn": 500.00,
    "payment_method": "spei",
    "clabe": "646180111812345678",
    "beneficiary": "ZYPFY SPEI",
    "reference": "9182736450",
    "bank": "STP",
    "checkout_url": "https://checkout.provedor.mx/pi_9f2c1a4b7e"
  }
}
CampoDescrição
clabeA conta destino. 18 dígitos. É o que o cliente digita no app do banco.
beneficiaryNome do beneficiário que o cliente deve informar.
referenceReferência numérica da transferência. Peça ao cliente para preenchê-la — ela ajuda na conciliação.
bankBanco liquidante da CLABE.
checkout_urlPágina externa de pagamento devolvida pela rede liquidante, quando disponível. Não é o checkout da Zypfy — para uma tela pronta com a sua marca, use o Checkout SPEI.
transaction_idIdentificador Zypfy da transação. Use nas Consultas.

Mostre ao pagador, no mínimo, a CLABE, o beneficiário e a referência.

Idempotência

external_id é a chave de idempotência, por conta e por gateway. Repetir a chamada com o mesmo external_id enquanto a cobrança estiver PENDING ou COMPLETED devolve a mesma transação — HTTP 200 com idempotent: true — em vez de criar uma segunda CLABE:

json
{
  "message": "Deposit already exists.",
  "idempotent": true,
  "deposit": {
    "id": 123456,
    "transaction_id": "pi_9f2c1a4b7e",
    "external_id": "order-mx-2026-0001",
    "status": "PENDING",
    "currency": "MXN",
    "amount_mxn": 500.00,
    "clabe": "646180111812345678",
    "reference": "9182736450"
  }
}

Isso torna o retry seguro: se sua chamada deu timeout, repita com o mesmo external_id e você recupera a CLABE original.

Valor divergente

No SPEI o pagador digita o valor no app do banco — diferente do PIX, onde o QR Code carrega o valor exato. Como a cobrança e a transferência são digitadas em lugares diferentes, elas podem não bater, e o desfecho depende do lado da diferença:

O pagador transferiuO que acontece
O valor cheioDepósito COMPLETED, crédito integral menos a taxa.
Menos que o cobradoA transferência é recusada e devolvida ao pagador pela rede. Não há crédito, e a cobrança segue PENDING até expirar.
Mais que o cobradoA transferência é aceita, mas o crédito é limitado ao valor cobrado. O excedente não vira saldo.

O que vem no webhook

json
{
  "type": "Deposit",
  "external_id": "order-mx-2026-0001",
  "transaction_id": "pi_9f2c1a4b7e",
  "status": "COMPLETED",
  "currency": "MXN",
  "amount": 500.00,
  "amount_expected": 500.00,
  "amount_paid": 500.00,
  "partial": false,
  "fee": 12.50,
  "payment_method": "spei",
  "updated_at": "2026-08-27T01:20:00.000Z"
}

Cobranças que ninguém pagou

Se o cliente não transferir nada — ou se a transferência dele for recusada por valor a menor — a cobrança fica PENDING até expirar. Não há crédito nem webhook de aprovação, e nada muda no seu saldo.

Quando você não sabe o valor na hora de gerar — é o cliente que decide quanto vai depositar — não dá para criar a CLABE antes: no SPEI ela nasce vinculada a um valor, e transferência a menor é devolvida.

O checkout inverte a ordem. Você cria um link sem valor, manda ao cliente, e é ele quem declara o valor na página. A CLABE só é emitida nesse momento, já casada com o que ele vai transferir.

código
POST https://api.zypfy.com/api/payments/mx/checkout

Headers: Authorization: Bearer SEU_TOKEN, Content-Type: application/json.

Body

json
{
  "external_id": "order-mx-2026-0001",
  "display_name": "Mi Tienda",
  "description": "Recarga de saldo",
  "suggested_amounts": [100, 250, 500],
  "min_amount": 50.00,
  "max_amount": 5000.00,
  "clientCallbackUrl": "https://minhaloja.com/webhooks/deposit"
}
CampoTipoObrigatórioDescrição
external_idstringsimSeu identificador do pedido. Também é a chave de idempotência: repetir a chamada devolve o mesmo link.
amountnumbernãoOmita para valor livre. Se enviar, o link vira valor fixo e o cliente só confirma. Mínimo 1.00.
min_amountnumbernãoPiso do valor livre. Default 1.00.
max_amountnumbernãoTeto do valor livre. Default 500000.00.
suggested_amountsarraynãoAté 6 botões de valor sugerido na página.
display_namestringnãoNome da sua loja exibido ao pagador.
descriptionstringnãoTexto exibido abaixo do nome da loja.
customer.name / customer.emailstringnãoPreenchem o pagador quando você já os conhece.
clientCallbackUrlstringnãoURL do webhook. Se omitida, usa a do portal.
expires_in_hoursintegernãoValidade do link. Default 168 (7 dias), máx. 720 (30 dias).
utm_*, src, sck, products, skip_*—nãoIguais aos da cobrança direta; são repassados ao depósito na hora da emissão.

Resposta 201

json
{
  "message": "MXN checkout created successfully.",
  "checkout": {
    "token": "14af1d995efb0bced082255962a04eeb",
    "url": "https://pay.zypfy.com/mx/14af1d995efb0bced082255962a04eeb",
    "external_id": "order-mx-2026-0001",
    "amount_mode": "open",
    "amount_mxn": null,
    "min_amount_mxn": 50.00,
    "max_amount_mxn": 5000.00,
    "suggested_amounts": [100, 250, 500],
    "currency": "MXN",
    "status": "OPEN",
    "expires_at": "2026-09-03T00:10:18.000Z"
  }
}

Mande checkout.url ao cliente — em um botão, no WhatsApp, por e-mail. A página cuida do resto:

  1. o cliente informa quanto vai transferir (respeitando min_amount/max_amount);
  2. a Zypfy emite a CLABE e exibe monto exato, CLABE, beneficiário, banco e referência, com botão de copiar e o prazo de validade;
  3. quando o SPEI liquida, a página confirma sozinha e você recebe o mesmo webhook de depósito MXN, com o seu external_id e amount igual ao que entrou.

Prazos

O queValidade
O link (sessão)expires_in_hours — default 7 dias, máx. 30 dias.
A CLABE emitida dentro dele24h — teto do SPEI, não é configurável.

Se a CLABE vencer antes do pagamento, o mesmo link emite outra: o cliente só reabre a URL. Isso é o que permite mandar o link uma vez e não precisar gerar nada de novo a cada tentativa.

Se o cliente quiser trocar o valor

Enquanto não pagar, ele pode voltar e informar outro valor. A CLABE anterior é cancelada e outra é emitida no lugar, então existe sempre uma única CLABE válida por link — sem risco de o cliente pagar em uma conta antiga com valor diferente.

statusSignificado
OPENCriado; o cliente ainda não informou o valor.
GENERATEDCLABE emitida, aguardando a transferência.
PAIDPagamento confirmado (o depósito virou COMPLETED).
EXPIREDO link passou da validade.

Para acompanhar do seu lado, GET /api/payments/mx/checkout?external_id=order-mx-2026-0001 lista os links da sua conta com o status atual. A confirmação oficial continua sendo o webhook de depósito — o link é só a tela do pagador.

Referência completa em Criar link de checkout MXN.

Rastreamento de campanhas (opcional)

A cobrança MXN aceita os mesmos campos de rastreamento do PIX e alimenta as mesmas integrações: Utmify, Xtracky e AdOptify.

json
{
  "amount": 500.00,
  "external_id": "order-mx-2026-0001",
  "customer": {
    "name": "Juan Pérez",
    "email": "[email protected]"
  },

  "utm_source":   "FB",
  "utm_medium":   "cpc",
  "utm_campaign": "mexico_black_friday",
  "utm_content":  "ad_variation_a",
  "utm_term":     "spei_checkout",
  "src":          "criativo-A",
  "sck":          "subconta-loja-9",

  "products": [
    { "id": "sku-1", "name": "Plano Mensal", "quantity": 1, "priceInCents": 50000 }
  ]
}

Os eventos são os mesmos do PIX:

MomentoEvento
Ao criar a cobrança (CLABE gerada)waiting_payment
Ao liquidar o SPEIpaid

Dois pontos específicos do México:

Para suprimir o disparo em uma cobrança específica, envie skip_utmify, skip_xtracky ou skip_adoptify como true.

A configuração de cada tracker fica no portal; a da AdOptify está detalhada em Integração AdOptify.

Webhook

Quando o SPEI é liquidado (ou falha), a Zypfy chama a sua clientCallbackUrl com o mesmo formato de webhook de depósito do PIX, com currency: "MXN":

json
{
  "type": "Deposit",
  "external_id": "order-mx-2026-0001",
  "transaction_id": "pi_9f2c1a4b7e",
  "status": "COMPLETED",
  "currency": "MXN",
  "amount": 500.00,
  "amount_expected": 500.00,
  "amount_paid": 500.00,
  "partial": false,
  "fee": 12.50,
  "payment_method": "spei",
  "updated_at": "2026-08-03T22:14:07.000Z"
}

Pontos de atenção:

Se o webhook falhar, concilie por Consultas — o comportamento é o mesmo do PIX.

Saldo em MXN

O depósito México não vira reais automaticamente. Ele credita um saldo separado, em pesos, que aparece em GET /api/accounts/balance:

json
{
  "message": "Wallet balance retrieved successfully.",
  "total_balance": 15230.44,
  "balance": 15230.44,
  "balance_block": 0,
  "balance_mxn": 487.50,
  "available_balance": 15230.44
}

balance continua sendo o saldo em reais. balance_mxn é o saldo em pesos. São carteiras independentes.

Converter MXN → BRL

Para transformar pesos em reais:

código
POST https://api.zypfy.com/api/accounts/mxn/convert
json
{
  "amount": 487.50
}

amount é quanto você quer converter, em MXN. O câmbio é definido pela Zypfy — você não envia a cotação, ela volta no campo rate.

Resposta 200

json
{
  "message": "MXN converted to BRL successfully.",
  "converted_mxn": 487.50,
  "credited_brl": 146.25,
  "rate": 0.30,
  "balance_mxn": 0.00,
  "balance": 15376.69
}

A operação é atômica: debita converted_mxn do saldo MXN e credita credited_brl no saldo BRL no mesmo movimento. balance_mxn e balance na resposta já são os saldos posteriores.

Sacar

Depois de converter, o dinheiro está em reais no saldo normal. O saque é o fluxo padrão, sem nada de específico do México — veja Saques PIX.

Não existe saque direto em MXN: a ordem é sempre depósito MXN → converter → saque PIX em BRL.

Códigos de erro

POST /api/payments/mx/deposit

HTTPcodeO que fazer
400VALIDATIONFaltou amount ou external_id, ou amount não é um número positivo.
403MXN_DISABLEDDepósito México não liberado nesta conta. Fale com o suporte.
403DEPOSIT_DISABLEDDepósitos bloqueados na conta (kill switch geral). Fale com o suporte.
404VALIDATIONUsuário do token não encontrado. Refaça a autenticação.
502PROVIDER_INVALID_RESPONSEO provedor não devolveu transaction_id ou CLABE. Repita com o mesmo external_id.
4xxPROVIDER_ERRORO provedor recusou a requisição. A mensagem detalha o motivo.
500INTERNALErro interno. Repita com o mesmo external_id.

Em manutenção programada, depósitos também podem ser bloqueados — o comportamento é o mesmo do PIX.

POST /api/accounts/mxn/convert

HTTPcodeO que fazer
400INVALID_AMOUNTamount ausente ou não positivo.
400INSUFFICIENT_MXN_BALANCESaldo MXN menor que o pedido. O campo detail traz available_mxn e requested_mxn.
404WALLET_NOT_FOUNDCarteira não encontrada para a conta.
503RATE_UNAVAILABLECâmbio não configurado no momento. Tente novamente mais tarde ou fale com o suporte.
500INTERNALErro interno. Verifique o saldo antes de repetir.

A tabela geral continua em Códigos de Erro.

Checklist de integração

  1. Peça ao suporte a liberação do depósito México na sua conta.
  2. Autentique normalmente e reaproveite o token (Autenticação).
  3. Chame POST /api/payments/mx/deposit com amount em pesos e um external_id seu.
  4. Exiba CLABE + beneficiário + referência ao pagador — ou, se você não sabe o valor na hora de gerar, crie um Checkout SPEI e mande só o link.
  5. Se usa tracker, envie os utm_* (e src/sck/products) na mesma chamada e ligue a integração no portal.
  6. Trate o webhook filtrando por currency: "MXN" e valide a assinatura HMAC.
  7. Credite o pedido pelo líquido do que entrou (amount - fee). Lembre que transferência a menor é recusada e devolvida ao pagador — veja Valor divergente.
  8. Converta o saldo com POST /api/accounts/mxn/convert quando quiser realizar em reais.
  9. Saque os reais via Saques PIX.