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

# Payment Failed

> Webhook notification sent when a payment fails

<Note>
  This webhook is sent when a payment has failed.
</Note>

## Webhook Structure

<ParamField body="id" type="string (UUID)" required>
  Unique identifier for this event
</ParamField>

<ParamField body="time" type="string (ISO 8601)" required>
  Timestamp of when the event occurred
</ParamField>

<ParamField body="type" type="string" required>
  The type of event. Value: `payment.failed`
</ParamField>

<ParamField body="data" type="object" required>
  The event data containing the details below
</ParamField>

### Data Fields

<ParamField body="data.paymentId" type="string (UUID)" required>
  Unique identifier of the failed payment
</ParamField>

<ParamField body="data.scheme" type="string" required>
  Payment scheme. Available values: `SCT`, `SCT_INST`, `INTERNAL`
</ParamField>

<ParamField body="data.direction" type="string" required>
  Payment direction. Available values: `INBOUND`, `OUTBOUND`
</ParamField>

<ParamField body="data.errors" type="array" required>
  List of errors indicating the reason(s) for the failure. Each error contains the fields below.
</ParamField>

<ParamField body="data.errors[].code" type="string" required>
  Error code indicating the reason for the failure. See [Error Codes](#error-codes) below.
</ParamField>

<ParamField body="data.errors[].message" type="string">
  Human-readable description of the error
</ParamField>

## Error Codes

<Note>
  New error codes may be added in future versions. Consumers should handle unknown codes gracefully.
</Note>

| Code                               | ISO  | Description                                 |
| ---------------------------------- | ---- | ------------------------------------------- |
| `INCORRECT_ACCOUNT_NUMBER`         | AC01 | Incorrect account number                    |
| `CLOSED_ACCOUNT`                   | AC04 | Closed account                              |
| `BLOCKED_ACCOUNT`                  | AC06 | Blocked account                             |
| `TRANSACTION_FORBIDDEN`            | AG01 | Transaction forbidden                       |
| `INVALID_BANK_OPERATION_CODE`      | AG02 | Invalid bank operation code                 |
| `DUPLICATE_PAYMENT`                | AM05 | Duplication                                 |
| `MISSING_CREDITOR_ADDRESS`         | BE04 | Missing creditor address                    |
| `INVALID_BIC`                      | RC01 | Bank identifier incorrect                   |
| `END_CUSTOMER_DECEASED`            | MD07 | End customer deceased                       |
| `NOT_SPECIFIED_REASON_CUSTOMER`    | MS02 | Not specified reason customer generated     |
| `NOT_SPECIFIED_REASON_AGENT`       | MS03 | Not specified reason agent generated        |
| `MISSING_DEBTOR_ACCOUNT_OR_ID`     | RR01 | Missing debtor account or identification    |
| `MISSING_DEBTOR_NAME_OR_ADDRESS`   | RR02 | Missing debtor name or address              |
| `MISSING_CREDITOR_NAME_OR_ADDRESS` | RR03 | Missing creditor name or address            |
| `REGULATORY_REASON`                | RR04 | Regulatory reason                           |
| `AML_REJECTED`                     | RR04 | AML check completed with rejection          |
| `AML_FAILED`                       | RR04 | AML check failed to initialize or timed out |
| `INSUFFICIENT_FUNDS`               | —    | Insufficient funds on the account           |
| `LEDGER_TRANSACTION_FAILED`        | —    | Ledger transaction could not be processed   |
| `GATEWAY_REJECTED`                 | —    | Payment rejected by gateway                 |
| `INVALID_REQUEST`                  | —    | Invalid payment request                     |
| `SYSTEM_ERROR`                     | —    | Internal system error                       |
| `OTHER`                            | —    | Unknown error                               |

## Request Example

```json theme={null}
{
  "id": "e1f6a4b3-8c2d-4e7f-b1a9-4d6c0e3f2b5a",
  "time": "2025-01-15T10:30:00Z",
  "type": "payment.failed",
  "data": {
    "paymentId": "019cde3d-c93f-7e6b-da54-6a1b3c4e7f0d",
    "scheme": "SCT",
    "direction": "OUTBOUND",
    "errors": [
      {
        "code": "TRANSACTION_FORBIDDEN",
        "message": "Transaction forbidden (AG01) (via Oversight)"
      }
    ]
  }
}
```