# Introduction

V1 vs V2 Error Codes
Our Payments API provides error details in different parameters depending on the version you use:

- **Payment Authorizations & Charges (V2):** Uses `status_reason_code` (in `UPPERCASE`) and `status_reason_message`. The table below lists all possible `UPPERCASE` codes for this version.
- **Payment Intents & Charges (V1):** Uses `failure_code` (in `lowercase`) and `failure_message`. For example, `beneficiary_bank_revoked_authorization` or `invalid_pix_key`.


When a Payment Authorization or an associated Charge (V2) encounters an error, Belvo updates the `status` of the given resource. Additionally, Belvo provides detailed information regarding the status change in the `status_reason_code` and `status_reason_message` parameters to help you understand what went wrong.

Below is a comprehensive table of all possible `status_reason_code` values and their corresponding messages:

| Code  | Message (EN Only) |
|  --- | --- |
| `ACCOUNT_NOT_ALLOWED` | The payer account does not allow payments. |
| `AMOUNT_OVER_LIMIT` | The amount exceeds the maximum limit for the account. |
| `AUTHORIZATION_EXPIRED` | The Payment Authorization was not completed within the allowed period. |
| `BANK_USER_MISMATCH` | The authenticated bank user differed from the paying user. |
| `BENEFICIARY_ACCOUNT_BLOCKED` | The beneficiary bank account is blocked. |
| `BENEFICIARY_ACCOUNT_CLOSED` | The beneficiary bank account is closed. |
| `BENEFICIARY_ACCOUNT_ERROR` | The Charge could not be completed due to an unexpected error in the beneficiary account. |
| `BENEFICIARY_ACCOUNT_NUMBER_INVALID` | The beneficiary bank account number is invalid or non-existent. |
| `BENEFICIARY_ACCOUNT_TYPE_INVALID` | The beneficiary bank account type does not allow this type of action. |
| `BENEFICIARY_ACCOUNT_TYPE_NOT_SUPPORTED` | The transaction type is not supported or authorized by the beneficiary account. |
| `BENEFICIARY_BANK_REJECTED_CHARGE` | The Charge was rejected by the beneficiary's institution. |
| `BENEFICIARY_CANCELLED_RECURRING_PAYMENT` | The beneficiary cancelled the recurring payment schedule. |
| `BENEFICIARY_IDENTIFIER_INVALID` | The beneficiary's CPF or CNPJ is incorrect. |
| `BENEFICIARY_IDENTIFIER_MISMATCH` | The beneficiary's CPF or CNPJ does not match the account holder. |
| `BENEFICIARY_REVOKED_AUTHORIZATION` | The beneficiary revoked the Payment Authorization. |
| `CANCELLATION_NOT_ALLOWED_CHARGE` | The Charge is in a status that does not allow cancellation. |
| `CANCELLATION_NOT_ALLOWED_PAYMENT_AUTHORIZATION` | The Payment Authorization is in a status that does not allow cancellation. |
| `CANCELLED_WHILE_PENDING` | The Charge was cancelled while it was in the PENDING status. |
| `CANCELLED_WHILE_SCHEDULED` | The Charge was cancelled while it was in the SCHEDULED status. |
| `CHARGE_EXCEEDS_AUTHORIZED_AMOUNT` | The Charge amount exceeded the limits defined in the Payment Authorization. |
| `CHARGE_PERIOD_LIMIT_REACHED` | The number of Charges exceeded the total allowed for the period, as defined in the Payment Authorization. |
| `CHARGE_SETTLEMENT_FAILED` | An error occurred while processing the Charge settlement. |
| `CHARGE_SETTLEMENT_TIMEOUT` | The Charge could not be completed due to a timeout. |
| `DUPLICATE_BENEFICIARY_CHARGE` | A duplicate Charge was detected for the same beneficiary. |
| `FRAUD_SUSPECTED` | The Charge was rejected due to suspected fraud. |
| `IDENTIFIER_MISMATCH` | The Payment Authorization Customer Identifier does not match the account owner identifier in the institution. |
| `INSUFFICIENT_FUNDS` | Insufficient funds in the payer's bank account. |
| `INSUFFICIENT_PERMISSION` | The payer associated with the Payment Authorization does not have sufficient permissions to perform actions for the account. |
| `INVALID_AMOUNT_QRCODE` | The value sent is not valid for the QR Code entered, or the QR Code used to initiate the payment is not valid. |
| `INVALID_CHARGE` | This Charge cannot be processed because the Charge has expired, passed its due date, or has an invalid status. |
| `INVALID_PAYMENT_AUTHORIZATION` | The Payment Authorization is in a final state and cannot be used for further Charges. |
| `NO_REASON_PROVIDED` | No error reason was provided by the institution. |
| `OPEN_FINANCE_NETWORK_FAILURE` | One of the following:- The payment was refused by the SPI system.
- There was a failure in the SPI infrastructure.
- There was a failure in the DICT infrastructure.
- There was a failure in the PKI infrastructure.
- There was a failure in the receiving PSP infrastructure.
- There was a failure in the account holder infrastructure.

 |
| `OUTSIDE_ALLOWED_TIMEFRAME` | The scheduling attempt was made outside the permitted period and was not accepted by the institution. |
| `PARTIALLY_ACCEPTED_PAYMENT_AUTHORIZATION` | The Payment Authorization must be accepted by all owners of the account. |
| `PAYER_ACCOUNT_TIMEOUT_ERROR` | The Charge settlement failed due to a timeout in the payer account. |
| `PAYER_BLOCKED_BY_REGULATORY_REASON` | The Charge was rejected because the payer is blocked for regulatory reasons. |
| `PAYER_REVOKED_AUTHORIZATION` | The payer revoked the Payment Authorization. |
| `PAYMENT_CONSENT_MISMATCH` | The information provided for this Charge differs from the associated Payment Authorization. |
| `PAYMENT_NOT_COMPLETED_CONSENT_EXPIRED` | The Charge was not completed within the authorized time. |
| `PAYMENT_REFUSED_BY_HOLDER` | The payer refused the Charge. |
| `PAYMENT_SCHEDULING_FAILURE` | The institution failed to schedule the payment. |
| `REJECTED_UNKNOWN` | The Payment Authorization was rejected for unknown reasons. |
| `REVOKED_PAYMENT_AUTHORIZATION` | The Charge is associated with a Payment Authorization that was revoked. |
| `REVOKED_UNKNOWN` | The Payment Authorization was revoked for unknown reasons. |
| `SAME_ORIGIN_DESTINATION_ACCOUNTS` | The beneficiary and payer accounts are the same. |
| `SETTLEMENT_LIMIT_REACHED` | The maximum number of attempts to settle the Charge in the institution was reached. |
| `SYSTEM_ERROR` | The request could not be completed due to a system error. |
| `UNEXPECTED_ERROR` | One of the following:- An unexpected error occurred while processing the Charge.
- An unexpected error occurred while processing the Payment Authorization.

 |
| `USER_DAILY_LIMIT_REACHED` | The user's maximum daily limit for the account was reached. |
| `USER_PERIOD_LIMIT_REACHED` | The user's maximum limit for the account and for the period was reached. |
| `USER_REJECTED` | The payer rejected the Payment Authorization. |


## V1 failure codes (Payment Intents and Charges)

The table above lists V2 `status_reason_code` values. Payment Intents and Charges (V1) return `failure_code` and `failure_message` in `lowercase` instead—for example in V1 `PAYMENT_INTENTS` webhooks with `webhook_code` `STATUS_UPDATE`.

| Failure code  | Failure message (EN only) | When it can occur |
|  --- | --- | --- |
| `invalid_pix_key` | The provided Pix Key is invalid. | Payment Intent `STATUS_UPDATE` when the beneficiary Pix Key in the payment cannot be validated. |