If you are getting an error that you cannot solve when trying to create transactions, please get in touch with our Support team with the JSON body of the request you have sent.
API Errors
The following list includes the primary errors that can be received when a request is not accepted because it failed basic validation, such as authentication, required fields, or formatting rules.
In most of these cases, the payout is not created, and the request must be corrected before retrying.
| Error Code | Description |
|---|---|
| 0_DUPLICATE_EXTERNAL_ID | A payout with the provided external_reference already exists for this Shop ID. |
| 0_PAYOUT_EXTERNAL_REFERENCE_ALREADY_ASSOCIATED_WITH_SHOPID | A payout with the provided external_reference already exists for this Shop ID. |
| 0_PAYOUT_INVALID_ACCOUNT | The value in account_number does not meet the required format or parameters. Please verify and try again. |
| 0_PAYOUT_REQUIRED_ACCOUNT_AGENCY_NUMBER | The value in agency_number is missing or does not meet the required parameters. Please verify and try again. |
| 0_PAYOUT_REQUIRED_DOCUMENT_NUMBER | The value in document_number is missing or does not meet the required parameters. Please verify and try again. |
| 0_PAYOUT_REQUIRED_DOCUMENT_TYPE | The document_type field was not provided. Please verify and try again. |
| 0_UNAUTHORIZED | The request could not be processed due to a credential mismatch. Please contact Merchant Support. |
| 001_VALIDATION_ERROR | The payout cannot be processed due to restrictions on the specified user. Contact Merchant Support for details. |
| BLOCKED_BY_CUSTOMER_LIMIT_RULE | The payout cannot be processed because the user has reached a risk prevention limit. |
| CUSTOMER_INVALID_AGE | The customer does not meet the minimum age requirement (underaged). |
| CUSTOMER_INVALID_ID | The provided personal identification number (ID card/cédula) is invalid or does not match official records. |
| CUSTOMER_INVALID_STATUS | The customer's personal id has been canceled or invalidated by the government. |
| CUSTOMER_IS_IN_INTERNATIONAL_LISTS | The customer appears on international watchlists for Money Laundering or Terrorism Financing. |
| CUSTOMER_SUSPENDED | The document number has been suspended by the government due to suspected criminal or illegal activities. |
| INVALID_ACCOUNT_AGENCY_NUMBER | The payout failed due to a missing or invalid agency number. |
| INVALID_AMOUNT | The value provided for "amount" is not a valid integer. |
| PAYMENT_PSP_ERROR | Generic error message received from the PSP; typically caused by a timeout on the provider side during high-traffic periods. |
| PAYOUT_BALANCE_INSUFFICIENT | The merchant balance is insufficient to process this payout. |
| PAYOUT_COUNTRY_NOT_ENABLED | Payout services are not available for the merchant in the selected country. Please contact Merchant Support. |
| PAYOUT_MERCHANT_NOT_ENABLED | Payout services are not enabled for this merchant. Please contact Merchant Support. |
Processing Errors
The following list includes the primary errors that may occur after the payout has been successfully created and is being processed with local providers or banking networks.
| Error Code | Description |
|---|---|
| ACCOUNT_ID_MISMATCH | The provided customer identification does not match the associated bank account number. |
| BANK_REJECTION | The payout was rejected by the receiving bank. Please verify the account status and try again. |
| BLOCKED_BANK_ACCOUNT | The payout failed because the specified bank account does not exist, is blocked, or is disabled. |
| ERROR_TRYING_TO_PROCESS_PAYOUT | The payout could not be processed after several attempts. Verify that the submitted data is correct and try again. |
| INVALID_BANK_ACCOUNT | The bank account number provided is incorrect. Please review the data and try again. |
| INVALID_BANK_CODE | The bank code provided is incorrect or not recognized. Please verify the code and try again. |
| INVALID_BANK_DETAILS | One or more of the submitted bank details are invalid. Please review the data and try again. |
| INVALID_CURRENCY | The specified bank account is set in a different currency than the one requested for the payout. |
| INVALID_EMAIL | The email address provided is not in a valid format. |
| INVALID_PIX_KEY | The provided PIX key is invalid. Please review the information and try again. |
| PAYOUT_BLOCKED_BY_DAILY_LIMIT_RULE | The payout cannot be processed because the user has reached their daily limit. They can try again on the next calendar day. |
| PAYOUT_BLOCKED_BY_MONTHLY_LIMIT_RULE | The payout cannot be processed because the user has reached their monthly limit. They can try again on the next calendar month. |
| RECIPIENT_BANK_LIMIT_REACHED | The receiving bank account cannot accept the payout because it has reached a specific limit (e.g., daily volume or transaction count). The customer should contact their bank for details. |
| TRANSACTION_MAX_AMOUNT | The payout amount exceeds the maximum transaction limit allowed. |
| TRANSACTION_MIN_AMOUNT | The payout amount is below the minimum transaction limit allowed. |
| UNEXPECTED_ERROR | An internal error occurred at the provider level while processing the payout. Please try again; if the issue persists, contact Merchant Support. |