Pruebas en Sandbox
Descripción General
El entorno sandbox le permite simular diferentes escenarios de webhook sin afectar transacciones reales. Use el encabezado X-Sandbox-Scenario en cualquier solicitud para controlar el resultado del webhook recibido.
Esta funcionalidad opera solo en sandbox. En producción, el encabezado es ignorado y el comportamiento está determinado por el resultado real de la transacción.
Cómo Usar
Agregue el encabezado X-Sandbox-Scenario a cualquier solicitud de Cash-In, Cash-Out o Refund:
curl -X POST https://api.ntxpay.com/api/pix/cash-out \
-H "Authorization: Bearer $TOKEN" \
-H "X-Sandbox-Scenario: error:insufficient-funds" \
-H "Content-Type: application/json" \
-d '{
"value": 150.00,
"details": {
"key": "recipient@email.com",
"keyType": "EMAIL",
"name": "Recipient Name",
"document": "39284918812"
},
"externalId": "test-error-001"
}'const response = await axios.post(
'https://api.ntxpay.com/api/pix/cash-out',
{
value: 150.00,
details: {
key: 'recipient@email.com',
keyType: 'EMAIL',
name: 'Recipient Name',
document: '39284918812',
},
externalId: 'test-error-001',
},
{
headers: {
Authorization: `Bearer ${token}`,
'X-Sandbox-Scenario': 'error:insufficient-funds',
},
}
);response = requests.post(
"https://api.ntxpay.com/api/pix/cash-out",
json={
"value": 150.00,
"details": {
"key": "recipient@email.com",
"keyType": "EMAIL",
"name": "Recipient Name",
"document": "39284918812",
},
"externalId": "test-error-001",
},
headers={
"Authorization": f"Bearer {token}",
"X-Sandbox-Scenario": "error:insufficient-funds",
},
)Escenarios Disponibles
Escenarios de Error
Simule diferentes tipos de fallos en webhooks:
| Valor del Encabezado | Descripción | Estado del Webhook |
|---|---|---|
error:insufficient-funds | Cuenta sin saldo suficiente | ERROR |
error:invalid-pix-key | La clave PIX no existe en DICT | ERROR |
error:document-mismatch | El documento no coincide con el titular de la clave | ERROR |
error:account-blocked | Cuenta de destino bloqueada o cerrada | ERROR |
error:duplicate-id | ID de envío duplicado | ERROR |
Escenario de Éxito
| Valor del Encabezado | Descripción | Estado del Webhook |
|---|---|---|
success | Fuerza éxito (comportamiento predeterminado) | CONFIRMED |
| (sin encabezado) | Comportamiento predeterminado del sandbox | CONFIRMED |
Escenarios de Retraso
Simule procesamiento lento para probar timeouts y reintentos:
| Valor del Encabezado | Descripción | Estado del Webhook |
|---|---|---|
delayed:5s | Éxito después de 5 segundos adicionales | CONFIRMED |
delayed:30s | Éxito después de 30 segundos adicionales | CONFIRMED |
delayed:60s | Éxito después de 60 segundos adicionales | CONFIRMED |
El retraso máximo permitido es de 120 segundos. Los valores superiores serán limitados automáticamente.
Ejemplos de Webhooks Recibidos
Webhook de Éxito (predeterminado)
{
"event": "CashOut",
"status": "CONFIRMED",
"transactionType": "PIX",
"movementType": "DEBIT",
"transactionId": "12345",
"externalId": "test-success-001",
"endToEndId": "E17745159XI4QA0EGFU",
"feeAmount": 0.50,
"originalAmount": 150.00,
"finalAmount": 150.50,
"processingDate": "2026-03-26T10:00:00.000Z",
"errorCode": null,
"errorMessage": null,
"counterpart": {
"name": "Recipient Name",
"document": "*.284.918-**",
"bank": {}
},
"metadata": {}
}Webhook de Error (error:insufficient-funds)
{
"event": "CashOut",
"status": "ERROR",
"transactionType": "PIX",
"movementType": "DEBIT",
"transactionId": "12345",
"externalId": "test-error-001",
"endToEndId": null,
"feeAmount": 0.50,
"originalAmount": 150.00,
"finalAmount": 150.50,
"processingDate": "2026-03-26T10:00:00.000Z",
"errorCode": "INSUFFICIENT_FUNDS",
"errorMessage": "Conta sem saldo",
"counterpart": {
"name": null,
"document": null,
"bank": {}
},
"metadata": {}
}Cuando el estado es ERROR, el campo endToEndId será null (ya que el PIX nunca fue confirmado por el Banco Central) y los campos errorCode y errorMessage describen la razón del fallo.
Endpoints Compatibles
El encabezado X-Sandbox-Scenario funciona con todos los endpoints transaccionales:
| Endpoint | Método | Descripción |
|---|---|---|
/api/pix/cash-in | POST | Generar cobro PIX (QR Code) |
/api/pix/cash-out | POST | Pago PIX por clave |
/api/pix/cash-out/qrcode | POST | Pago PIX por QR Code |
/api/pix/refund-in | POST | Solicitud de devolución |
Comportamiento
La API procesa la solicitud normalmente y retorna 201 Created con estado PENDING.
El encabezado no altera la respuesta inmediata -- solo el webhook posterior.
Después de ~1 segundo (o más, si usa delayed:), el webhook se envía a la URL configurada con el escenario simulado.
Su sistema recibe el webhook con el estado correspondiente al escenario (CONFIRMED o ERROR) y debe procesarlo acorde.
Importante: El encabezado X-Sandbox-Scenario controla solo el webhook. La respuesta HTTP del endpoint siempre retorna éxito (201 Created) con status: "PENDING", independientemente del escenario elegido. El resultado final (éxito o error) llega vía webhook.
Restricciones
El encabezado X-Sandbox-Scenario funciona exclusivamente con cuentas configuradas en modo sandbox. Si su cuenta está configurada con un proveedor de producción y envía el encabezado, la API retornará un error:
{
"statusCode": 400,
"message": "X-Sandbox-Scenario header is only supported in sandbox mode. This account is not configured with a sandbox provider."
}Asegúrese de que su cuenta esté en modo sandbox antes de usar esta funcionalidad. Si recibe este error, contacte a suporte@ntxpay.com para verificar la configuración de su cuenta.
Mejores Prácticas
Pruebe todos los escenarios
Implemente manejo para cada estado de webhook (CONFIRMED, PENDING, ERROR) antes de ir a producción.
Valide los campos de error
Cuando status es ERROR, use errorCode y errorMessage para determinar la acción apropiada (reintentar, notificar al usuario, etc.).
Pruebe con retraso
Use escenarios delayed: para verificar que su sistema maneje correctamente webhooks que tardan más en llegar.
Idempotencia
Use transactionId como clave de idempotencia. El mismo webhook puede ser reenviado en caso de fallo en la entrega.