Débito bancario fallido - TapiPay

Se dispara cuando el banco rechaza un débito domiciliado contra la cuenta CLABE que tu usuario tiene adherida. El cobro no se concretó.

El evento reporta ese intento de cobro, no un cambio de estado de la deuda.


`type`	`AUTO_DEBIT_FAILED`
`status`	Siempre `"FAILED"`
Llave de idempotencia	`operationId`

El payload

Campo	Tipo	Presente	Descripción
`type`	String	Siempre	Siempre `"AUTO_DEBIT_FAILED"`.
`operationId`	String	Siempre	Identificador único del débito bancario.
`status`	String	Siempre	Siempre `"FAILED"`.
`amount`	Number	Siempre	Monto solicitado del débito.
`bank`	String	Siempre	Nombre del banco.
`accountLast4`	String \| null	Variable	Últimos 4 dígitos de la cuenta o CLABE. `null` cuando el banco no lo informa.
`bankErrorCode`	String \| null	Variable	Código de error del banco. `null` cuando el banco no informa motivo.
`bankErrorDescription`	String \| null	Variable	Descripción del motivo de rechazo. `null` cuando el banco no informa motivo.
`externalRequestId`	String \| null	Variable	Tu identificador de la solicitud, para correlacionar contra tu sistema. `null` cuando no viene informado.
`companyCode`	String \| null	Siempre	Código de la empresa. La clave siempre viene; el valor puede ser `null`.
`companyName`	String \| null	Siempre	Nombre de la empresa. Mismo criterio que `companyCode`.
`hash`	String \| null	Siempre	Hash de verificación. `null` si no tienes llave pública configurada.

El detalle del rechazo (bankErrorCode y bankErrorDescription) llega siempre que el banco lo informe, en la raíz del payload. A diferencia de los eventos de tarjeta, no depende del flag sendErrorInfo ni viaja dentro de additionalData.

Nunca vas a recibir la CLABE completa. Solo llegan los últimos 4 dígitos, y si ese dato llega con un formato distinto del esperado, TapiPay lo emite como null en lugar de reenviarlo.

Ejemplos

{
  "type": "AUTO_DEBIT_FAILED",
  "operationId": "d3b1f2a0-1234-4a5b-8c9d-0e1f2a3b4c5d",
  "status": "FAILED",
  "amount": 150000,
  "bank": "Santander",
  "accountLast4": "4321",
  "bankErrorCode": "NSF",
  "bankErrorDescription": "Fondos insuficientes",
  "externalRequestId": "INV-2026-001",
  "companyCode": "MX-S-12345",
  "companyName": "ACME",
  "hash": "encrypted-base64-string"
}

{
  "type": "AUTO_DEBIT_FAILED",
  "operationId": "d3b1f2a0-1234-4a5b-8c9d-0e1f2a3b4c5d",
  "status": "FAILED",
  "amount": 150000,
  "bank": "Santander",
  "accountLast4": null,
  "bankErrorCode": null,
  "bankErrorDescription": null,
  "externalRequestId": null,
  "companyCode": "MX-S-12345",
  "companyName": "ACME",
  "hash": null
}

Campos comunes, hash e idempotencia

Lo que comparten todos los webhooks de esta familia.