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
┌──────────┐ 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
POST https://api.zypfy.com/api/payments/mx/depositHeaders: 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
{
"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"
}| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
amount | number | sim | Valor em MXN (pesos) que o cliente vai transferir. Use decimais, não centavos: 500.00. |
external_id | string | sim | Seu identificador do pedido. Também é a chave de idempotência (veja abaixo). |
customer.name | string | não | Nome do pagador. Default: "Cliente". |
customer.email | string | não | E-mail do pagador. |
clientCallbackUrl | string | não | URL que receberá o webhook. Se omitida, usa a URL configurada no portal. |
description | string | não | Descrição livre repassada ao provedor. |
utm_source | string | não | Origem/LeadId da campanha. Máx. 255. Veja Rastreamento de campanhas abaixo. |
utm_medium | string | não | Medium (cpc, organic, ...). Máx. 64. |
utm_campaign | string | não | Nome da campanha. Máx. 255. |
utm_content | string | não | Identificador do criativo/variação. Máx. 255. |
utm_term | string | não | Keyword/termo. Máx. 255. |
platform | string | não | Label livre de plataforma de tracking. Máx. 32. |
src | string | não | Parâmetro extra usado por Utmify e AdOptify. |
sck | string | não | Parâmetro extra usado por Utmify e AdOptify. |
products | array | não | Itens do pedido repassados aos trackers (máx. 20). priceInCents em centavos de peso. |
skip_utmify | boolean | não | true não dispara a Utmify nesta cobrança. |
skip_xtracky | boolean | não | true não dispara a Xtracky nesta cobrança. |
skip_adoptify | boolean | não | true não dispara a AdOptify nesta cobrança. |
Resposta 201
{
"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"
}
}| Campo | Descrição |
|---|---|
clabe | A conta destino. 18 dígitos. É o que o cliente digita no app do banco. |
beneficiary | Nome do beneficiário que o cliente deve informar. |
reference | Referência numérica da transferência. Peça ao cliente para preenchê-la — ela ajuda na conciliação. |
bank | Banco liquidante da CLABE. |
checkout_url | Pá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_id | Identificador 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:
{
"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 transferiu | O que acontece |
|---|---|
| O valor cheio | Depósito COMPLETED, crédito integral menos a taxa. |
| Menos que o cobrado | A 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 cobrado | A transferência é aceita, mas o crédito é limitado ao valor cobrado. O excedente não vira saldo. |
O que vem no webhook
{
"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"
}amount— o que efetivamente entrou e virou saldo (bruto, antes da taxa). É por ele que você credita o pedido.amount_expected— o valor que você cobrou.partial—truesó se o crédito tiver ficado abaixo do cobrado.
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.
Checkout SPEI: link sem valor
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.
POST https://api.zypfy.com/api/payments/mx/checkoutHeaders: Authorization: Bearer SEU_TOKEN, Content-Type: application/json.
Body
{
"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"
}| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
external_id | string | sim | Seu identificador do pedido. Também é a chave de idempotência: repetir a chamada devolve o mesmo link. |
amount | number | não | Omita para valor livre. Se enviar, o link vira valor fixo e o cliente só confirma. Mínimo 1.00. |
min_amount | number | não | Piso do valor livre. Default 1.00. |
max_amount | number | não | Teto do valor livre. Default 500000.00. |
suggested_amounts | array | não | Até 6 botões de valor sugerido na página. |
display_name | string | não | Nome da sua loja exibido ao pagador. |
description | string | não | Texto exibido abaixo do nome da loja. |
customer.name / customer.email | string | não | Preenchem o pagador quando você já os conhece. |
clientCallbackUrl | string | não | URL do webhook. Se omitida, usa a do portal. |
expires_in_hours | integer | não | Validade do link. Default 168 (7 dias), máx. 720 (30 dias). |
utm_*, src, sck, products, skip_* | — | não | Iguais aos da cobrança direta; são repassados ao depósito na hora da emissão. |
Resposta 201
{
"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:
- o cliente informa quanto vai transferir (respeitando
min_amount/max_amount); - 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;
- quando o SPEI liquida, a página confirma sozinha e você recebe o mesmo webhook de depósito MXN, com o seu
external_ideamountigual ao que entrou.
Prazos
| O que | Validade |
|---|---|
| O link (sessão) | expires_in_hours — default 7 dias, máx. 30 dias. |
| A CLABE emitida dentro dele | 24h — 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.
Status do link
status | Significado |
|---|---|
OPEN | Criado; o cliente ainda não informou o valor. |
GENERATED | CLABE emitida, aguardando a transferência. |
PAID | Pagamento confirmado (o depósito virou COMPLETED). |
EXPIRED | O 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.
{
"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:
| Momento | Evento |
|---|---|
| Ao criar a cobrança (CLABE gerada) | waiting_payment |
| Ao liquidar o SPEI | paid |
Dois pontos específicos do México:
- A venda é enviada em pesos. O valor vai com a moeda marcada como
MXNno payload — não é convertido para reais nem somado ao seu faturamento em BRL dentro do tracker. priceInCentsé em centavos de peso. Se você omitirproducts, a Zypfy envia um item sintético"Depósito SPEI"com o valor total da cobrança.
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":
{
"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:
statusfinal éCOMPLETEDouFAILED. EmFAILEDvem tambémerror_code.amounté o valor bruto que efetivamente entrou, em MXN.feeé a taxa, também em MXN.- O que entra no seu saldo é o líquido:
amount - fee. amount_expected,amount_paidepartialexistem porque no SPEI o pagador digita o valor. Num pagamento integralamounteamount_expectedsão iguais epartialéfalse. Veja Valor divergente.- O webhook é assinado com HMAC, igual ao do PIX — valide antes de confiar. Veja Verificando a assinatura dos webhooks.
- Use
currencypara rotear: o mesmo endereço de webhook recebe depósitos BRL e MXN.
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:
{
"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:
POST https://api.zypfy.com/api/accounts/mxn/convert{
"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
{
"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
| HTTP | code | O que fazer |
|---|---|---|
| 400 | VALIDATION | Faltou amount ou external_id, ou amount não é um número positivo. |
| 403 | MXN_DISABLED | Depósito México não liberado nesta conta. Fale com o suporte. |
| 403 | DEPOSIT_DISABLED | Depósitos bloqueados na conta (kill switch geral). Fale com o suporte. |
| 404 | VALIDATION | Usuário do token não encontrado. Refaça a autenticação. |
| 502 | PROVIDER_INVALID_RESPONSE | O provedor não devolveu transaction_id ou CLABE. Repita com o mesmo external_id. |
| 4xx | PROVIDER_ERROR | O provedor recusou a requisição. A mensagem detalha o motivo. |
| 500 | INTERNAL | Erro 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
| HTTP | code | O que fazer |
|---|---|---|
| 400 | INVALID_AMOUNT | amount ausente ou não positivo. |
| 400 | INSUFFICIENT_MXN_BALANCE | Saldo MXN menor que o pedido. O campo detail traz available_mxn e requested_mxn. |
| 404 | WALLET_NOT_FOUND | Carteira não encontrada para a conta. |
| 503 | RATE_UNAVAILABLE | Câmbio não configurado no momento. Tente novamente mais tarde ou fale com o suporte. |
| 500 | INTERNAL | Erro interno. Verifique o saldo antes de repetir. |
A tabela geral continua em Códigos de Erro.
Checklist de integração
- Peça ao suporte a liberação do depósito México na sua conta.
- Autentique normalmente e reaproveite o token (Autenticação).
- Chame
POST /api/payments/mx/depositcomamountem pesos e umexternal_idseu. - 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.
- Se usa tracker, envie os
utm_*(esrc/sck/products) na mesma chamada e ligue a integração no portal. - Trate o webhook filtrando por
currency: "MXN"e valide a assinatura HMAC. - 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. - Converta o saldo com
POST /api/accounts/mxn/convertquando quiser realizar em reais. - Saque os reais via Saques PIX.