Webhook refund_out - NTX Pay API

Quando dispara

O webhook do tipo refund_out recebe o evento transaction.cash_out.returned: uma transferência que você enviou foi devolvida pelo banco da contraparte. O saldo correspondente é creditado de volta na sua conta. Cenários comuns:

CLABE de destino inválida ou conta encerrada
Beneficiário/banco da contraparte rejeitou a transferência após a aceitação inicial
Devolução dentro do prazo da rede 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"
}

O transactionId é o mesmo do cash-out original — use-o para correlacionar e marcar o pagamento como devolvido.

Headers

Header	Valor
`x-event-id`	UUID único do evento (use para dedupe)
`X-NTXPay-Signature`	`sha256=<hmac>` do corpo bruto

Resposta Esperada

200 OK em até 10 segundos.

Processamento

const event = JSON.parse(rawBody.toString());
if (event.event === 'transaction.cash_out.returned') {
  // O crédito do saldo de volta já aconteceu automaticamente
  await markPayoutReturned(event.transactionId, event.amount);
}

Para o handler completo com validação HMAC e dedupe em Node.js, Python, Java e Go, veja Implementação.