Webhook refund_out - NTX Pay API

Cuándo se dispara

El webhook del tipo refund_out recibe el evento transaction.cash_out.returned: una transferencia que enviaste fue devuelta por el banco de la contraparte. El saldo correspondiente se acredita de vuelta en tu cuenta. Escenarios comunes:

CLABE de destino inválida o cuenta cerrada
El beneficiario/banco de la contraparte rechazó la transferencia después de la aceptación inicial
Devolución dentro del plazo de la red SPEI

Payload

{
  "event": "transaction.cash_out.returned",
  "transactionId": "56789",
  "amount": 50000,
  "currency": "MXN",
  "status": "RETURNED",
  "destinationClabe": "012180001234567890",
  "sourceClabe": null,
  "reference": "9876543",
  "voucher": null,
  "occurredAt": "2026-05-14T09:15:00.000Z"
}

El transactionId es el mismo del cash-out original — úsalo para correlacionar y marcar el pago como devuelto.

Headers

Header	Valor
`x-event-id`	UUID único del evento (úsalo para dedupe)
`X-NTXPay-Signature`	`sha256=<hmac>` del cuerpo crudo

Respuesta Esperada

200 OK en un máximo de 10 segundos.

Procesamiento

const event = JSON.parse(rawBody.toString());
if (event.event === 'transaction.cash_out.returned') {
  // El crédito del saldo de vuelta ya ocurrió automáticamente
  await markPayoutReturned(event.transactionId, event.amount);
}

Para el handler completo con validación HMAC y dedupe en Node.js, Python, Java y Go, consulta Implementación.