Webhook cash_in - NTX Pay API

Quando dispara

O webhook do tipo cash_in recebe os eventos do ciclo de vida de uma cobrança criada via POST /api/spei/cash-in:

`event`	`status`	Significado
`transaction.cash_in.settled`	`LIQUIDATED`	A transferência SPEI chegou na CLABE descartável e foi liquidada
`transaction.cash_in.rejected`	`REJECTED`	A rede SPEI rejeitou a transferência
`transaction.cash_in.expired`	`EXPIRED`	A CLABE expirou (~24h) sem receber a transferência
`transaction.cash_in.pending`	`PENDING`	Atualização intermediária de processamento

A devolução de um cash-in já liquidado (transaction.cash_in.returned) é entregue no webhook do tipo refund_in, não no cash_in.

Payload

{
  "event": "transaction.cash_in.settled",
  "transactionId": "12345",
  "amount": 50000,
  "currency": "MXN",
  "status": "LIQUIDATED",
  "destinationClabe": "012180001234567890",
  "sourceClabe": "646180123456789012",
  "payerName": "Juan Perez",
  "reference": "1234567",
  "voucher": "CEP20260512A1B2C3",
  "occurredAt": "2026-05-12T14:31:05.000Z"
}

destinationClabe — a CLABE descartável emitida na criação da cobrança
sourceClabe — a CLABE do pagador (quando informada pela rede)
amount — valor em centavos MXN
Campos de referência (reference, voucher) podem vir null dependendo do fluxo

Headers

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

Resposta Esperada

Responda 200 OK em menos de 10 segundos. Em caso de qualquer status diferente de 2xx, o NTX Pay tenta novamente até 5 vezes em backoff exponencial.

HTTP/1.1 200 OK
Content-Type: application/json

{"received": true}

Processamento

Marque o pedido como pago somente quando event for transaction.cash_in.settled (ou status: LIQUIDATED):

const event = JSON.parse(rawBody.toString());
if (event.event === 'transaction.cash_in.settled') {
  await markOrderPaid(event.transactionId, event.amount);
}

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