> ## Documentation Index
> Fetch the complete documentation index at: https://devs.tapipay.la/llms.txt
> Use this file to discover all available pages before exploring further.

# Failed bank debit

> The bank declined an autopay debit. It carries the decline reason when the bank reports one.

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

<Note>
  The event reports **that charge attempt**, not a change in the state of the debt.
</Note>

|                     |                     |
| ------------------- | ------------------- |
| **`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.                            |

<Note>
  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`.
</Note>

<Warning>
  **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.
</Warning>

## Examples

<CodeGroup>
  ```json With a bank reason theme={null}
  {
    "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"
  }
  ```

  ```json No reason and no public key theme={null}
  {
    "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
  }
  ```
</CodeGroup>

<Card title="Common fields, hash and idempotency" icon="bookmark" href="/en/webhooks">
  What every webhook in this family shares.
</Card>