Test scenarios

How to use

Add the X-Sandbox-Scenario: <scenario> header to any cash-in or cash-out call. Without the header, the sandbox uses the success scenario by default.

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"
  }'

Most scenarios control the asynchronous webhook: the HTTP response is 201 Created with status: PENDING, and the final result arrives via webhook. The exceptions are timeout and service_unavailable, which fail in the synchronous HTTP response.

Available scenarios

The canonical scenario values are: success, pending_long, rejected, returned, insufficient_funds, bad_clabe, timeout, service_unavailable.

Asynchronous result scenarios

Return 201 PENDING synchronously; the final state arrives via webhook within seconds.

Header Value	Resulting webhook	Notes
`success` (default)	`*.settled` — `status: LIQUIDATED`	Also used when no header is sent
`pending_long`	`*.settled` — `status: LIQUIDATED` after ~30s	Tests slow settlement
`rejected`	`*.rejected` — `status: REJECTED`	The SPEI network rejected the transfer
`returned`	`*.returned` — `status: RETURNED`	Accepted and later returned by the counterparty
`insufficient_funds`	`cash_out.rejected` — `status: REJECTED`	Cash-out only — simulates rejection due to insufficient funds
`bad_clabe`	`cash_out.returned` — `status: RETURNED`	Cash-out only — accepted and returned due to an invalid CLABE

*.returned events are delivered to the refund_in/refund_out webhook type (or all), not to cash_in/cash_out. To test the returned and bad_clabe scenarios, register those webhooks as well — see webhook types.

Synchronous error scenarios

Fail in the HTTP response itself — no webhook is sent.

Header Value	Synchronous response
`timeout`	Processing timeout (`504`) after ~16s
`service_unavailable`	Service temporarily unavailable (`503`)

Cash-in restrictions: insufficient_funds and bad_clabe do not apply to cash-in (there is no balance to debit, and the deposit CLABE is generated by the system). Sending either of them on a cash-in returns 400 with code SCENARIO_NOT_APPLICABLE.

Example: success webhook

success scenario on a cash-out — the cash_out webhook receives:

{
  "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"
}

Example: rejection webhook

insufficient_funds scenario — the cash_out webhook receives:

{
  "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"
}

With status: REJECTED, the receipt fields (reference, voucher) come back null — the SPEI network never confirmed the transaction. The full payload format is in the Webhooks Overview.

Restrictions

The X-Sandbox-Scenario header works exclusively on sandbox accounts.
Production accounts that send the header receive:

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

Best practices

Test every scenario before going live — implement handling for all four statuses (LIQUIDATED, PENDING, REJECTED, RETURNED).
Route by the event field — *.settled, *.rejected, and *.returned require different actions in your system.
Test with delay — use pending_long to verify that your system handles slow settlement gracefully.
Idempotency — deduplicate by the x-event-id header; the same event may be redelivered.

Guide

Sandbox

Webhooks

Authentication

SPEI

Webhooks Config

How to use

Available scenarios

Asynchronous result scenarios

Synchronous error scenarios

Example: success webhook

Example: rejection webhook

Restrictions

Best practices

​How to use

​Available scenarios

​Asynchronous result scenarios

​Synchronous error scenarios

​Example: success webhook

​Example: rejection webhook

​Restrictions

​Best practices

How to use

Available scenarios

Asynchronous result scenarios

Synchronous error scenarios

Example: success webhook

Example: rejection webhook

Restrictions

Best practices