refund_in Webhook - NTX Pay API

When it fires

The refund_in webhook type receives the transaction.cash_in.returned event: a cash-in you received was returned to the payer. The corresponding balance is debited from your account. Common scenarios:

Reversal due to fraud or error
Return within the SPEI network’s window

Payload

{
  "event": "transaction.cash_in.returned",
  "transactionId": "12345",
  "amount": 50000,
  "currency": "MXN",
  "status": "RETURNED",
  "destinationClabe": "012180001234567890",
  "sourceClabe": "646180123456789012",
  "reference": "1234567",
  "voucher": null,
  "occurredAt": "2026-05-14T11:45:00.000Z"
}

The transactionId is the same as the original cash-in — use it to locate the order and mark it as reversed.

Headers

Header	Value
`x-event-id`	Unique event UUID (use for dedupe)
`X-NTXPay-Signature`	`sha256=<hmac>` of the raw body

Expected Response

200 OK within 10 seconds.

Processing

const event = JSON.parse(rawBody.toString());
if (event.event === 'transaction.cash_in.returned') {
  // The balance debit has already happened automatically
  await markOrderRefunded(event.transactionId, event.amount);
}

For the complete handler with HMAC validation and dedupe in Node.js, Python, Java, and Go, see Implementation.