Failed bank debit - TapiPay

Fires when the bank declines an autopay debit against the CLABE account your user has enrolled. The charge did not go through.

The event reports that charge attempt, not a change in the state of the debt.


`type`	`AUTO_DEBIT_FAILED`
`status`	Always `"FAILED"`
Idempotency key	`operationId`

The payload

Field	Type	Present	Description
`type`	String	Always	Always `"AUTO_DEBIT_FAILED"`.
`operationId`	String	Always	Unique identifier of the bank debit.
`status`	String	Always	Always `"FAILED"`.
`amount`	Number	Always	Requested debit amount.
`bank`	String	Always	Bank name.
`accountLast4`	String \| null	Variable	Last 4 digits of the account or CLABE. `null` when the bank does not report it.
`bankErrorCode`	String \| null	Variable	Bank error code. `null` when the bank reports no reason.
`bankErrorDescription`	String \| null	Variable	Description of the decline reason. `null` when the bank reports no reason.
`externalRequestId`	String \| null	Variable	Your request identifier, to correlate against your system. `null` when it is not reported.
`companyCode`	String \| null	Always	Company code. The key is always there; the value can be `null`.
`companyName`	String \| null	Always	Company name. Same rule as `companyCode`.
`hash`	String \| null	Always	Verification hash. `null` if you have no public key configured.

The decline detail (bankErrorCode and bankErrorDescription) always arrives when the bank reports it, at the root of the payload. Unlike card events, it does not depend on the sendErrorInfo flag and does not travel inside additionalData.

You will never receive the full CLABE. Only the last 4 digits arrive, and if that value comes in an unexpected format, TapiPay emits it as null instead of forwarding it.

Examples

{
  "type": "AUTO_DEBIT_FAILED",
  "operationId": "d3b1f2a0-1234-4a5b-8c9d-0e1f2a3b4c5d",
  "status": "FAILED",
  "amount": 150000,
  "bank": "Santander",
  "accountLast4": "4321",
  "bankErrorCode": "NSF",
  "bankErrorDescription": "Insufficient funds",
  "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
}

Common fields, hash and idempotency

What every webhook in this family shares.