Cenários de teste

Como usar

Adicione o header X-Sandbox-Scenario: <cenário> a qualquer chamada de cash-in ou cash-out. Sem o header, o sandbox usa o cenário success por padrão.

curl -X POST https://sandbox.mx.ntxpay.com/api/spei/cash-out \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Sandbox-Scenario: insufficient_funds" \
  -H "Content-Type: application/json" \
  -d '{
    "amountCentavos": 15000,
    "destinationClabe": "012180001234567890",
    "beneficiaryName": "Maria Lopez"
  }'

A maioria dos cenários controla o webhook assíncrono: a resposta HTTP é 201 Created com status: PENDING, e o resultado final chega no webhook. As exceções são timeout e service_unavailable, que falham na resposta HTTP síncrona.

Cenários disponíveis

Os valores canônicos de cenário são: success, pending_long, rejected, returned, insufficient_funds, bad_clabe, timeout, service_unavailable.

Cenários de resultado assíncrono

Retornam 201 PENDING de forma síncrona; o estado final chega via webhook em segundos.

Header Value	Webhook resultante	Notas
`success` (default)	`*.settled` — `status: LIQUIDATED`	Também usado quando nenhum header é enviado
`pending_long`	`*.settled` — `status: LIQUIDATED` após ~30s	Testa liquidação lenta
`rejected`	`*.rejected` — `status: REJECTED`	A rede SPEI rejeitou a transferência
`returned`	`*.returned` — `status: RETURNED`	Aceita e depois devolvida pela contraparte
`insufficient_funds`	`cash_out.rejected` — `status: REJECTED`	Apenas cash-out — simula rejeição por falta de fundos
`bad_clabe`	`cash_out.returned` — `status: RETURNED`	Apenas cash-out — aceita e devolvida por CLABE inválida

Os eventos *.returned são entregues no webhook do tipo refund_in/refund_out (ou all), não no cash_in/cash_out. Para testar os cenários returned e bad_clabe, registre também esses webhooks — veja tipos de webhook.

Cenários de erro síncrono

Falham na própria resposta HTTP — nenhum webhook é enviado.

Header Value	Resposta síncrona
`timeout`	Timeout no processamento (`504`) após ~16s
`service_unavailable`	Serviço temporariamente indisponível (`503`)

Restrições de cash-in: insufficient_funds e bad_clabe não se aplicam a cash-in (não há saldo a debitar, e a CLABE de depósito é gerada pelo sistema). Enviar qualquer um deles em um cash-in retorna 400 com código SCENARIO_NOT_APPLICABLE.

Exemplo: webhook de sucesso

Cenário success em um cash-out — o webhook cash_out recebe:

{
  "event": "transaction.cash_out.settled",
  "transactionId": "56789",
  "amount": 15000,
  "currency": "MXN",
  "status": "LIQUIDATED",
  "destinationClabe": "012180001234567890",
  "sourceClabe": null,
  "reference": "9876543",
  "voucher": "CEP20260326G7H8I9",
  "occurredAt": "2026-03-26T10:00:00.000Z"
}

Exemplo: webhook de rejeição

Cenário insufficient_funds — o webhook cash_out recebe:

{
  "event": "transaction.cash_out.rejected",
  "transactionId": "56790",
  "amount": 15000,
  "currency": "MXN",
  "status": "REJECTED",
  "destinationClabe": "012180001234567890",
  "sourceClabe": null,
  "reference": null,
  "voucher": null,
  "occurredAt": "2026-03-26T10:01:00.000Z"
}

Em status: REJECTED, os campos de comprovante (reference, voucher) vêm null — a rede SPEI nunca confirmou a transação. O formato completo do payload está em Visão Geral de Webhooks.

Restrições

O header X-Sandbox-Scenario funciona exclusivamente em contas sandbox.
Contas de produção que enviem o header recebem:

{
  "statusCode": 400,
  "message": "X-Sandbox-Scenario header is only supported in sandbox mode."
}

Boas práticas

Teste todos os cenários antes de ir ao ar — implemente o tratamento dos quatro status (LIQUIDATED, PENDING, REJECTED, RETURNED).
Roteie pelo campo event — *.settled, *.rejected e *.returned exigem ações diferentes no seu sistema.
Teste com delay — use pending_long para verificar que seu sistema lida bem com liquidação lenta.
Idempotência — deduplique pelo header x-event-id; o mesmo evento pode ser reentregue.

Guia

Sandbox

Webhooks

Autenticação

SPEI

Webhooks Config

Como usar

Cenários disponíveis

Cenários de resultado assíncrono

Cenários de erro síncrono

Exemplo: webhook de sucesso

Exemplo: webhook de rejeição

Restrições

Boas práticas

​Como usar

​Cenários disponíveis

​Cenários de resultado assíncrono

​Cenários de erro síncrono

​Exemplo: webhook de sucesso

​Exemplo: webhook de rejeição

​Restrições

​Boas práticas

Como usar

Cenários disponíveis

Cenários de resultado assíncrono

Cenários de erro síncrono

Exemplo: webhook de sucesso

Exemplo: webhook de rejeição

Restrições

Boas práticas