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

Criar link de checkout MXN (SPEI) — valor opcional

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

Cria um link de checkout para o México e devolve a URL que você manda ao pagador (botão, WhatsApp, e-mail). É a forma de cobrar sem saber o valor na hora de gerar: amount é opcional e, quando você o omite, quem digita o valor é o próprio pagador na página — a CLABE só é emitida depois disso, já casada com o valor que ele declarou.

Por que não existe "CLABE sem valor"

No SPEI a CLABE nasce vinculada a um valor, e transferência menor que o valor da cobrança é recusada e devolvida ao pagador pela rede — não vira crédito. Emitir a CLABE só depois que o pagador declara quanto vai mandar é o que mantém cobrança e transferência casadas.

Fluxo

  1. POST /api/payments/mx/checkout (sem amount) → devolve checkout.url.
  2. Você manda essa URL ao pagador.
  3. Ele informa o valor, recebe a CLABE e transfere.
  4. Na liquidação você recebe o mesmo webhook de depósito do fluxo MXN, com currency: "MXN" e o seu external_id.

A sessão vale pelo prazo que você definir (expires_in_hours, default 7 dias, máx. 30 dias) e a CLABE emitida dentro dela vale 24h — teto do SPEI. Se a CLABE vencer antes do pagamento, o mesmo link emite outra.

Idempotência

external_id é a chave: repetir a chamada devolve a mesma sessão e a mesma URL (HTTP 200, idempotent: true).

Corpo da requisição

Respostas

200Já existia um checkout com esse external_id (idempotente).
201Checkout criado.
  • messagestring
  • checkoutobject
    campos de checkout
    • tokenstring
      exemplo: 14af1d995efb0bced082255962a04eeb
    • urlstring

      URL para mandar ao pagador.

      exemplo: https://pay.zypfy.com/mx/14af1d995efb0bced082255962a04eeb
    • external_idstring
      exemplo: mx_checkout_123456
    • amount_modestring

      open = o pagador digita o valor.

      valores: open fixed
    • amount_mxnnumber | null
    • min_amount_mxnnumber | null
    • max_amount_mxnnumber | null
    • suggested_amountsarray de number
    • currencystring
      exemplo: MXN
    • statusstring

      OPEN aguardando o pagador informar o valor · GENERATED CLABE emitida · PAID pagamento confirmado · EXPIRED link vencido.

      valores: OPEN GENERATED PAID EXPIRED
    • expires_atstring (date-time)
    • created_atstring (date-time)
403Conta sem depósito México liberado (MXN_DISABLED) ou depósitos bloqueados.
  • 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.