Criar cobrança MXN (depósito · SPEI)
https://api.zypfy.com/api/payments/mx/depositCria uma cobrança para o México via SPEI (transferência bancária) e
retorna uma CLABE de 18 dígitos para a qual o cliente mexicano deve
transferir. Diferente do PIX, não há QR Code — o pagador usa a CLABE,
o beneficiário (beneficiary) e a referência (reference) no app do banco.
Ao ser liquidada, a Zypfy dispara o mesmo webhook de depósito
(/your-server/webhooks/deposit) com currency: "MXN", e o valor é
creditado no seu saldo em MXN (balance_mxn).
Valor divergente (importante)
No SPEI o pagador digita o valor no app do banco — diferente do PIX, onde o QR Code carrega o valor exato. Por isso a cobrança e a transferência podem não bater, e o desfecho depende de para que lado a diferença foi:
| O pagador mandou | O que acontece |
|---|---|
| O valor cheio | Depósito COMPLETED, crédito integral menos a taxa. |
| Menos que o pedido | A transferência é recusada e devolvida ao pagador. Não há crédito, e a cobrança segue PENDING até expirar. |
| Mais que o pedido | A transferência é aceita, mas o crédito é limitado ao valor do pedido. O excedente não vira saldo. |
Cobranças que nunca receberam nada continuam PENDING até expirar —
essas nunca geram crédito nem webhook de aprovação.
O webhook de liquidação traz amount (o que entrou), amount_expected (o
que você cobrou) e partial — decida a entrega pelo amount.
Saldo em MXN e como sacar
amount é o valor em MXN (pesos) que o cliente vai pagar (ex.: 500.00).
O depósito é creditado num saldo separado em MXN (balance_mxn, veja
GET /api/accounts/balance) — não vira reais automaticamente.
Para receber em reais, converta o saldo MXN→BRL com
POST /api/accounts/mxn/convert (usa o câmbio configurado pela Zypfy) e
depois saque os reais normalmente via POST /api/withdrawals/withdraw (PIX).
Rastreamento (Utmify · Xtracky · AdOptify)
A cobrança MXN aceita os mesmos campos de rastreamento do PIX
(utm_source, utm_medium, utm_campaign, utm_content, utm_term,
platform, src, sck, products[]) e dispara os mesmos eventos nas
integrações habilitadas no portal: waiting_payment ao gerar a CLABE e
paid na liquidação.
A venda é enviada em pesos, com a moeda marcada como MXN no payload
— ela não é convertida para reais nem somada ao faturamento em BRL do
seu dashboard de tracking.
Para suprimir o disparo numa cobrança específica, envie
skip_utmify, skip_xtracky ou skip_adoptify como true.
Idempotência
external_id é a chave de idempotência: repetir a chamada com o mesmo
external_id enquanto a cobrança estiver PENDING/COMPLETED devolve a
mesma transação (HTTP 200, idempotent: true) em vez de criar outra.
Corpo da requisição
amountnumberobrigatórioValor em MXN (pesos) que o cliente vai pagar.
exemplo:500external_idstringobrigatórioIdentificador único do seu sistema (chave de idempotência).
exemplo:mx_dep_123456customerobjectobrigatóriocampos de customer
namestringobrigatórioexemplo:Juan Pérezemailstring (email)exemplo:[email protected]
clientCallbackUrlstring (uri)URL de webhook (opcional; usa o fallback do portal se ausente).
exemplo:https://cliente.com/webhooks/depositdescriptionstringexemplo:Pedidoutm_sourcestring | nullLeadId/origem do tracker. Veja "Rastreamento" acima.
exemplo:facebookutm_mediumstring | nullexemplo:cpcutm_campaignstring | nullexemplo:mexico_black_fridayutm_contentstring | nullexemplo:ad_variation_autm_termstring | nullexemplo:spei_checkoutplatformstring | nullexemplo:ZYPFYsrcstring | nullParâmetro extra da Utmify/AdOptify.
sckstring | nullParâmetro extra da Utmify/AdOptify.
productsarray de objectItens do pedido repassados a Utmify/AdOptify (máx. 20).
priceInCentsé em centavos de peso. Se omitido, a Zypfy envia um produto sintético "Depósito SPEI" com o valor total.campos de products
idstringexemplo:sku-1namestringexemplo:Plano MensalplanIdstring | nullplanNamestring | nullquantityintegerexemplo:1priceInCentsintegerexemplo:50000
skip_utmifybooleanNão dispara a Utmify nesta cobrança.
exemplo:falseskip_xtrackybooleanNão dispara a Xtracky nesta cobrança.
exemplo:falseskip_adoptifybooleanNão dispara a AdOptify nesta cobrança.
exemplo:false
Respostas
201Cobrança MXN criada. Exiba a CLABE ao pagador.
messagestringdepositobjectcampos de deposit
idintegerexemplo:987654transaction_idstringexemplo:pi_01JJ...external_idstringexemplo:mx_dep_123456statusstringexemplo:PENDINGcurrencystringexemplo:MXNamount_mxnnumberexemplo:500payment_methodstringexemplo:speiclabestringexemplo:706969250450582169beneficiarystringexemplo:Zypfyreferencestringexemplo:PAGO-12345bankstringexemplo:STPcheckout_urlstring | nullPágina hospedada para o pagador copiar a CLABE (opcional).
400Dados de entrada inválidos.
messagestringMensagem humana descrevendo o erro.
exemplo:Invalid amount.codestring | nullCódigo opcional de erro para roteamento no seu sistema.
min_amountnumber (float) | nullPresente em erros de valor abaixo do mínimo configurado.
max_amountnumber (float) | nullPresente em erros de valor acima do máximo absoluto.
limitnumber (float) | nullPresente em erros de limite diário por transação excedido.
retry_after_secondsinteger | nullPresente em erros
WITHDRAWAL_COOLDOWN/ 429.
403Depósito México não habilitado nesta conta.
messagestringMensagem humana descrevendo o erro.
exemplo:Invalid amount.codestring | nullCódigo opcional de erro para roteamento no seu sistema.
min_amountnumber (float) | nullPresente em erros de valor abaixo do mínimo configurado.
max_amountnumber (float) | nullPresente em erros de valor acima do máximo absoluto.
limitnumber (float) | nullPresente em erros de limite diário por transação excedido.
retry_after_secondsinteger | nullPresente em erros
WITHDRAWAL_COOLDOWN/ 429.
500Erro interno ou provedor indisponível. É seguro tentar novamente em
alguns segundos com o mesmo external_id.
messagestringMensagem humana descrevendo o erro.
exemplo:Invalid amount.codestring | nullCódigo opcional de erro para roteamento no seu sistema.
min_amountnumber (float) | nullPresente em erros de valor abaixo do mínimo configurado.
max_amountnumber (float) | nullPresente em erros de valor acima do máximo absoluto.
limitnumber (float) | nullPresente em erros de limite diário por transação excedido.
retry_after_secondsinteger | nullPresente em erros
WITHDRAWAL_COOLDOWN/ 429.