📘
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.