Criar link de checkout MXN (SPEI) — valor opcional
https://api.zypfy.com/api/payments/mx/checkoutCria 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
POST /api/payments/mx/checkout(semamount) → devolvecheckout.url.- Você manda essa URL ao pagador.
- Ele informa o valor, recebe a CLABE e transfere.
- Na liquidação você recebe o mesmo webhook de depósito do fluxo MXN,
com
currency: "MXN"e o seuexternal_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
external_idstringobrigatórioIdentificador único do seu sistema (chave de idempotência).
exemplo:mx_checkout_123456amountnumber | nullValor fixo em MXN (pesos). Omita para o pagador digitar o valor na página (valor livre). Mínimo aceito:
1.00.exemplo:500min_amountnumber | nullPiso do valor livre (default
1.00).exemplo:50max_amountnumber | nullTeto do valor livre (default
500000.00).exemplo:5000suggested_amountsarray de numberAté 6 botões de valor sugerido exibidos na página.
display_namestring | nullNome da sua loja exibido ao pagador.
exemplo:Mi Tiendadescriptionstring | nullexemplo:Recarga de saldocustomerobject | nullcampos de customer
namestringexemplo:Juan Pérezemailstring (email)exemplo:[email protected]
clientCallbackUrlstring (uri) | nullURL de webhook (opcional; usa o fallback do portal se ausente).
expires_in_hoursinteger | nullValidade do link em horas (default 168, máx. 720).
exemplo:168utm_sourcestring | nullutm_mediumstring | nullutm_campaignstring | nullutm_contentstring | nullutm_termstring | nullplatformstring | nullsrcstring | nullsckstring | nullskip_utmifybooleanskip_xtrackybooleanskip_adoptifyboolean
Respostas
200Já existia um checkout com esse external_id (idempotente).
201Checkout criado.
messagestringcheckoutobjectcampos de checkout
tokenstringexemplo:14af1d995efb0bced082255962a04eeburlstringURL para mandar ao pagador.
exemplo:https://pay.zypfy.com/mx/14af1d995efb0bced082255962a04eebexternal_idstringexemplo:mx_checkout_123456amount_modestringopen= o pagador digita o valor.valores:openfixedamount_mxnnumber | nullmin_amount_mxnnumber | nullmax_amount_mxnnumber | nullsuggested_amountsarray de numbercurrencystringexemplo:MXNstatusstringOPENaguardando o pagador informar o valor ·GENERATEDCLABE emitida ·PAIDpagamento confirmado ·EXPIREDlink vencido.valores:OPENGENERATEDPAIDEXPIREDexpires_atstring (date-time)created_atstring (date-time)
403Conta sem depósito México liberado (MXN_DISABLED) ou depósitos bloqueados.
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.