ZypfyDocs Acessar painel
Depósitos MXN (México)

Criar cobrança MXN (depósito · SPEI)

POSThttps://api.zypfy.com/api/payments/mx/deposit

Cria 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 mandouO que acontece
O valor cheioDepósito COMPLETED, crédito integral menos a taxa.
Menos que o pedidoA transferência é recusada e devolvida ao pagador. Não há crédito, e a cobrança segue PENDING até expirar.
Mais que o pedidoA 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

Respostas

201Cobrança MXN criada. Exiba a CLABE ao pagador.
  • messagestring
  • depositobject
    campos de deposit
    • idinteger
      exemplo: 987654
    • transaction_idstring
      exemplo: pi_01JJ...
    • external_idstring
      exemplo: mx_dep_123456
    • statusstring
      exemplo: PENDING
    • currencystring
      exemplo: MXN
    • amount_mxnnumber
      exemplo: 500
    • payment_methodstring
      exemplo: spei
    • clabestring
      exemplo: 706969250450582169
    • beneficiarystring
      exemplo: Zypfy
    • referencestring
      exemplo: PAGO-12345
    • bankstring
      exemplo: STP
    • checkout_urlstring | null

      Página hospedada para o pagador copiar a CLABE (opcional).

400Dados de entrada inválidos.
  • messagestring

    Mensagem humana descrevendo o erro.

    exemplo: Invalid amount.
  • codestring | null

    Código opcional de erro para roteamento no seu sistema.

  • min_amountnumber (float) | null

    Presente em erros de valor abaixo do mínimo configurado.

  • max_amountnumber (float) | null

    Presente em erros de valor acima do máximo absoluto.

  • limitnumber (float) | null

    Presente em erros de limite diário por transação excedido.

  • retry_after_secondsinteger | null

    Presente em erros WITHDRAWAL_COOLDOWN / 429.

403Depósito México não habilitado nesta conta.
  • messagestring

    Mensagem humana descrevendo o erro.

    exemplo: Invalid amount.
  • codestring | null

    Código opcional de erro para roteamento no seu sistema.

  • min_amountnumber (float) | null

    Presente em erros de valor abaixo do mínimo configurado.

  • max_amountnumber (float) | null

    Presente em erros de valor acima do máximo absoluto.

  • limitnumber (float) | null

    Presente em erros de limite diário por transação excedido.

  • retry_after_secondsinteger | null

    Presente em erros WITHDRAWAL_COOLDOWN / 429.

500Erro interno ou provedor indisponível. É seguro tentar novamente em alguns segundos com o mesmo external_id.
  • messagestring

    Mensagem humana descrevendo o erro.

    exemplo: Invalid amount.
  • codestring | null

    Código opcional de erro para roteamento no seu sistema.

  • min_amountnumber (float) | null

    Presente em erros de valor abaixo do mínimo configurado.

  • max_amountnumber (float) | null

    Presente em erros de valor acima do máximo absoluto.

  • limitnumber (float) | null

    Presente em erros de limite diário por transação excedido.

  • retry_after_secondsinteger | null

    Presente em erros WITHDRAWAL_COOLDOWN / 429.