Skip to content
Last updated

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.

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_ALLOWEDThe payer account does not allow payments.
AMOUNT_OVER_LIMITThe amount exceeds the maximum limit for the account.
AUTHORIZATION_EXPIREDThe Payment Authorization was not completed within the allowed period.
BANK_USER_MISMATCHThe authenticated bank user differed from the paying user.
BENEFICIARY_ACCOUNT_BLOCKEDThe beneficiary bank account is blocked.
BENEFICIARY_ACCOUNT_CLOSEDThe beneficiary bank account is closed.
BENEFICIARY_ACCOUNT_ERRORThe Charge could not be completed due to an unexpected error in the beneficiary account.
BENEFICIARY_ACCOUNT_NUMBER_INVALIDThe beneficiary bank account number is invalid or non-existent.
BENEFICIARY_ACCOUNT_TYPE_INVALIDThe beneficiary bank account type does not allow this type of action.
BENEFICIARY_ACCOUNT_TYPE_NOT_SUPPORTEDThe transaction type is not supported or authorized by the beneficiary account.
BENEFICIARY_BANK_REJECTED_CHARGEThe Charge was rejected by the beneficiary's institution.
BENEFICIARY_CANCELLED_RECURRING_PAYMENTThe beneficiary cancelled the recurring payment schedule.
BENEFICIARY_IDENTIFIER_INVALIDThe beneficiary's CPF or CNPJ is incorrect.
BENEFICIARY_IDENTIFIER_MISMATCHThe beneficiary's CPF or CNPJ does not match the account holder.
BENEFICIARY_REVOKED_AUTHORIZATIONThe beneficiary revoked the Payment Authorization.
CANCELLATION_NOT_ALLOWED_CHARGEThe Charge is in a status that does not allow cancellation.
CANCELLATION_NOT_ALLOWED_PAYMENT_AUTHORIZATIONThe Payment Authorization is in a status that does not allow cancellation.
CANCELLED_WHILE_PENDINGThe Charge was cancelled while it was in the PENDING status.
CANCELLED_WHILE_SCHEDULEDThe Charge was cancelled while it was in the SCHEDULED status.
CHARGE_EXCEEDS_AUTHORIZED_AMOUNTThe Charge amount exceeded the limits defined in the Payment Authorization.
CHARGE_PERIOD_LIMIT_REACHEDThe number of Charges exceeded the total allowed for the period, as defined in the Payment Authorization.
CHARGE_SETTLEMENT_FAILEDAn error occurred while processing the Charge settlement.
CHARGE_SETTLEMENT_TIMEOUTThe Charge could not be completed due to a timeout.
DUPLICATE_BENEFICIARY_CHARGEA duplicate Charge was detected for the same beneficiary.
FRAUD_SUSPECTEDThe Charge was rejected due to suspected fraud.
IDENTIFIER_MISMATCHThe Payment Authorization Customer Identifier does not match the account owner identifier in the institution.
INSUFFICIENT_FUNDSInsufficient funds in the payer's bank account.
INSUFFICIENT_PERMISSIONThe payer associated with the Payment Authorization does not have sufficient permissions to perform actions for the account.
INVALID_AMOUNT_QRCODEThe value sent is not valid for the QR Code entered, or the QR Code used to initiate the payment is not valid.
INVALID_CHARGEThis Charge cannot be processed because the Charge has expired, passed its due date, or has an invalid status.
INVALID_PAYMENT_AUTHORIZATIONThe Payment Authorization is in a final state and cannot be used for further Charges.
NO_REASON_PROVIDEDNo error reason was provided by the institution.
OPEN_FINANCE_NETWORK_FAILUREOne 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_TIMEFRAMEThe scheduling attempt was made outside the permitted period and was not accepted by the institution.
PARTIALLY_ACCEPTED_PAYMENT_AUTHORIZATIONThe Payment Authorization must be accepted by all owners of the account.
PAYER_ACCOUNT_TIMEOUT_ERRORThe Charge settlement failed due to a timeout in the payer account.
PAYER_BLOCKED_BY_REGULATORY_REASONThe Charge was rejected because the payer is blocked for regulatory reasons.
PAYER_REVOKED_AUTHORIZATIONThe payer revoked the Payment Authorization.
PAYMENT_CONSENT_MISMATCHThe information provided for this Charge differs from the associated Payment Authorization.
PAYMENT_NOT_COMPLETED_CONSENT_EXPIREDThe Charge was not completed within the authorized time.
PAYMENT_REFUSED_BY_HOLDERThe payer refused the Charge.
PAYMENT_SCHEDULING_FAILUREThe institution failed to schedule the payment.
REJECTED_UNKNOWNThe Payment Authorization was rejected for unknown reasons.
REVOKED_PAYMENT_AUTHORIZATIONThe Charge is associated with a Payment Authorization that was revoked.
REVOKED_UNKNOWNThe Payment Authorization was revoked for unknown reasons.
SAME_ORIGIN_DESTINATION_ACCOUNTSThe beneficiary and payer accounts are the same.
SETTLEMENT_LIMIT_REACHEDThe maximum number of attempts to settle the Charge in the institution was reached.
SYSTEM_ERRORThe request could not be completed due to a system error.
UNEXPECTED_ERROROne of the following:
  • An unexpected error occurred while processing the Charge.
  • An unexpected error occurred while processing the Payment Authorization.
USER_DAILY_LIMIT_REACHEDThe user's maximum daily limit for the account was reached.
USER_PERIOD_LIMIT_REACHEDThe user's maximum limit for the account and for the period was reached.
USER_REJECTEDThe payer rejected the Payment Authorization.
Previous page
 
Copyright © 2020-2025 Belvo. All rights reserved