Error Codes

About EBANX error codes.

Learn about error codes and what they mean.

This page contains codes and descriptions of all errors that may occur when you communicate with the Platforms API.

If after reading this section you are still not sure how to interpret a specific error, contact the Support Team.

Don’t waste your time (or money) with error codes When an API call fails, EBANX will return a JSON object containing the error details below:

{

"status": "ERROR",

"status_code": "BP-SA-1",

"status_message": "Parameter integration_key not informed"

}

That way, you confirm where the error is and can correct quickly. Observe the following table and verify the “status_code” that appears, besides the error messages (“status_message”) that EBANX uses, with a brief description of it.

That way, you confirm where the error is and can correct quickly. Observe the following links for each Integration Method on the API – EBANX Direct and EBANX Payment Page.

API Error codes

• Payments related erros
• Card related errors
• Customer related errors
• General errors

Error codes, messages and descriptions

search

Code arrow_downward	Error message arrow_downward	Description arrow_downward
BP-CH-1	Payment type group is not active: {group_code}	Some payment method is not enabled. Contact our Integration Team.
BP-DR-0	Payment already exists with merchant_payment_code: X (created on X, status is X)	There can be only one payment in the system with the same merchant payment code.
BP-DR-2	Field payment is required	The field was not filled.
BP-DR-3	Field payment.currency_code is required	The field was not filled.
BP-DR-5	Field payment.amount_total is required	The field was not filled.
BP-DR-6	Amount reported is less than the minimum amount	The payment amount is too low.
BP-DR-7	Amount must be less than X	The payment amount is too high.
BP-DR-8	If passed, amount_itens + amount_shipping must be equal to amount_total	The amount sent was not right.
BP-DR-9	Field payment.merchant_payment_code is required	The field was not filled.
BP-DR-10	Parameter merchant_payment_code can have 40 characters maximum	The parameter has more characters than the limit allowed.
BP-DR-11	Parameter payment.order_number can have 40 characters maximum	The parameter has more characters than the limit allowed.
BP-DR-12	Parameter X can have 20 characters maximum	The parameter has more characters than the limit allowed.
BP-DR-35	Invalid payment_type_code: X	The payment method is not enabled. Contact our Integration Team.
BP-DR-36	Payment type is not active	The payment method is not enabled. Contact our Integration Team.
BP-DR-38	Payment type not allowed in Direct API (full mode): X	Not all payment types are allowed in full mode, please refer to documentation.
BP-DR-41	Field payment.person_type must contain a valid person_type	The parameter sent was not valid.
BP-DR-47	Parameter payment.directdebit.bank_account can have 10 characters maximum	The parameter has more characters than the limit allowed.
BP-DR-50	Payment type not allowed in Direct API (full mode): {payment_type_code}	The payment method is not allowed. Contact our Integration Team.
BP-DR-57	Parameter is in an invalid format: due_date. Correct Format: dd/MM/yyyy	The parameter was not sent on the right format.
BP-DR-58	Parameter is invalid: due_date – exceeds more than {days} days	The parameter ‘due_date’ exceeds the numbers of days that is in the configuration.
BP-DR-59	Parameter is invalid: due_date – less than permitted	The parameter ‘due_date’ is too short.
BP-DR-68	Field payment.directdebit.bank_account is required	The field was not filled.
BP-DR-69	Parameter payment.directdebit.bank_agency can have 10 characters maximum	The parameter has more characters than the limit allowed.
BP-DR-70	Field payment.directdebit.bank_agency is required	The field was not filled.
BP-DR-71	Parameter payment.directdebit.bank_code can have 5 characters maximum	The parameter has more characters than the limit allowed.
BP-DR-72	Field payment.directdebit.bank_code is required	The field was not filled.
BP-DR-73	Field payment.directdebit is required for this payment type	The field was not filled.
BP-DR-77	Country is not enabled	The country is not available on your account. Contact our Integration Team.
BP-DR-78	Country not enabled for merchant	The country is not available on your account. Contact our Integration Team.
BP-DR-80	It was not possible to generate CIP. Please try again.	Some error happened on the transaction.
BP-DR-81	Currency code {currency_code} not allowed for payment type code: {payment_type_code}.	The supplied currency cannot be used for the chosen payment method.
BP-DR-82	Parameter payment.note can have 200 characters maximum.	The note parameter must have 200 characters or less.
BP-DR-84	Duplicate payment for the same customer and amount within {minutes} minutes.	Lock for preventing customer to be billed twice for the same transaction.
BP-DR-85	Field payment.sub_account is required.	The field was not filled.
BP-DR-86	Parameter is invalid: payment.sub_account.	The parameter sent was not valid.
BP-DR-87	Field payment.sub_account.name is required.	The field was not filled.
BP-DR-88	Field payment.sub_account.image_url is required.	The field was not filled.
BP-DR-91	Field payment.institution_code is required.	The field was not filled.
BP-DR-92	Field payment.institution_code is not a valid bank code.	The parameter sent was not valid.
BP-DR-93	Error creating this payment within PSE ACH. Error code: ?.	Something went wrong with the payment operation.
BP-DR-99	Field payment.sub_account.image_url must be https	The image URL that you are trying to send must be with https.
BP-DR-102	Too many attempts	The customer tried too many times the same transaction in a short period of time.
BP-DR-105	Missing Parameter for Flow method	Parameter payment.flow_payment_method is required. You read more about HERE.
BP-DR-118	Invalid Sub Account data	The Sub Account sent in request is not valid.
BP-DR-130	For 3DS 2.0 transactions, field payment.card.threeds_cryptogram is required	The Cryptogram field was not filled.
BP-DR-131	For 3DS 2.0 transactions, field payment.card.threeds_eci is required	The ECI field was not filled.
BP-DR-132	For 3DS 2.0 transactions, field payment.card.threeds_cryptogram and payment.card.threeds_eci are required	The Cryptogram and ECI fields were not filled.
BP-DR-138	Parameter payment.card.threeds_trxid is mandatory for 3DS Data Only	The Directory Server Transaction ID was not filled and it is mandatory when you are sending a transaction with 3DS Data Only Authentication
BP-DR-139	Parameter payment.card.threeds_version is invalid. The valid values are 1 (for 3DS 1.0) and 2 (for 3DS 2.0)	The ThreeDSecure version sent is invalid. You should use 1, for 3DS 1.0, or 2 for 3DS 2.0
BP-DR-173	Field payment.amount_total cannot contain ","	Field payment.amount_local sent is invalid. You should use "."
BP-REF-1	Parameter hash not informed	The field was not filled.
BP-REF-2	Payment not found for merchant, hash: X	The payment was not found. Contact our Integration Team.
BP-REF-3	Parameter operation not informed (must be request or cancel)	The field was not filled.
BP-REF-4	Parameter amount not informed	The field was not filled.
BP-REF-5	Refund amount must be positive	You are trying to send a negative refund.
BP-REF-6	Refund amount is greater than payment amount: X and X	The refund and the payment amount does not match.
BP-REF-7	Payment status is not CO, cannot be refunded: X	The payment status is not CO (Confirmed) so it cannot be refunded.
BP-REF-8	Payment has chargebacks, cannot be refunded: X	The payments has chargebacks so it cannot be refunded.
BP-REF-9	Pending refund amount for payment would be greater than payment amount: X	The amount of the refund and the payment does not match.
BP-REF-10	Parameter description not informed	The field was not filled.
BP-REF-11	Parameters not informed: refund_id or merchant_refund_code	optionally generated by the merchant and also be used to identify a refund.
BP-REF-12	Refund not found with id = X and merchant_refund_code = Y	See above
BP-REF-13	Refund is already cancelled	Refund is already cancelled
BP-REF-14	Refund is already confirmed	Refund is already confirmed
BP-REF-15	Invalid operation: X	You are trying an invalid operation.
BP-REF-16	Parameter merchant_refund_code can have 20 characters maximum	The parameter has more characters than the limit allowed.
BP-REF-17	A refund already exists with this merchant_refund_code: X	There is already a refund with this merchant code.
BP-REF-18	Insufficient balance to create new refund. please contact finance@ebanx.com	Insufficient balance.
BP-REF-19	Credit card payment’s open date is older than 85 days ago.	The payment is too old.
BP-REF-20	Request cannot contain both payment.card and payment.creditcard entries.	Only one parameter should be used: payment.creditcard or payment.card.
BP-REF-21	Invalid Transaction.	Customer document blocked by Compliance.
BP-REF-22	Partial refund is not supported in [Payment Type] payments.	Partial refund is not supported in payments with a specific payment type.
BP-REF-23	Invalid bank info: Invalid bank name	Bank name provided is not valid.
BP-REF-24	Invalid bank info: Bank info is not allowed for this country	This country does not support the refund bank info flow.
BP-REF-25	Empty bank details	The bank details field cannot be empty for this bank.
BP-REF-26	Invalid bank detail [Operation code]	The bank detail operation code is invalid.
BP-REF-27	Invalid bank name	The bank name does not exist.
BP-REF-28	Invalid account type	This account type is not a valid option.
BP-REF-29	Refund is not available for savings account of bank {bank_name}	Refund is not available for savings account on this specific bank.
BP-REF-30	Invalid bank branch	The branch is not valid for this bank.
BP-REF-31	Invalid bank account	The bank account is invalid.
BP-REF-33	The bank_info field is missing	The bank_info field cannot be empty.
BP-REF-34	This refund was not created with bank info	It's not possible to update the bank info of this refund because it was not created with bank info.
BP-REF-35	This refund is not awaiting for bank info update	The refund status and substatus must be CO-AW for the bank info to be updated.
BP-REF-36	Payment hash and Refund identification do not match	The payment hash must match with refund_id or merchant_refund_code.
BP-REF-37	Invalid clabe	Invalid clabe.
BP-REF-38	Could not infer bank from clabe	We couldn't find the bank of this clabe.
BP-REF-39	Refund with Single Transaction	It is not allowed to cancel a refund that has Single Transaction.
BP-REF-40	Refund amount must be at least 50.00 CLP	For the country CHILE it is not possible to do a refund with an amount less than 50.00 CLP
BP-CAN-1	Parameter hash not informed	The field was not filled.
BP-CAN-2	Payment not found for merchant	The payment was not found for this merchant. Please check your parameter.
BP-CAN-3	Payment is already cancelled	Payment is already cancelled.
BP-CAN-4	Payment cannot be cancelled	Payment cannot be cancelled.
BP-US-1	Parameter hash not informed	The field was not filled.
BP-US-2	Payment not found for merchant, hash: X	The payment was not found for this merchant. Please check your parameter.
BP-US-3	Parameter status not informed	The field was not filled.
BP-US-4	Status must be either CO or CA	The status must be either CO or CA
BP-US-5	Operation NOT allowed in production mode	The updateStatus operation can only be used in the test environment. In production mode, the status changes are performed exclusively by the EBANX system.
BP-Q-1	Parameters hash or merchant_payment_code not informed	The field was not filled.
BP-Q-2	Payment not found for merchant	The payment was not found for this merchant. Please check your parameter.
BP-CAP-1	Parameters hash or merchant_payment_code not informed	The field was not filled.
BP-CAP-2	Payment not found for merchant	The payment was not found for this merchant. Please check your parameter.
BP-CAP-3	Payment cannot be captured, status is: CA	The payment cannot be captured.
BP-CAP-4	Payment has already been captured, status is: CO	The payment has already been captured.
BP-CAP-5	Payment cannot be captured, status is: OP	The payment cannot be captured.
BP-CAP-6	Payment cannot be captured, payment_type_code is:	The payment cannot be captured.
BP-CAP-7	Payment cannot be captured, auto_capture is: true	The payment cannot be captured.
BP-CAP-8	Payment cannot be captured, capture_available is: false	The payment cannot be captured.
BP-CAP-9	Payment cannot be captured, pre_approved is: false	The payment cannot be captured.
BP-CAP-10	Invalid amount	The amount that you are trying to use is invalid.
BP-CAP-11	Partial capture not available	Partial capture not available.
BP-CAP-12	Payment cannot be captured, amount must be equal or less than {currency_code} {max_amount}	The payment amount exceeds the limit.
BP-REF-CAN-1	Payment can not be cancelled and can not generate a refund. Payment status is CA	Payment can not be cancelled and can not generate a refund.
BP-DMO-1	Payment not found for merchant: merchant_payment_code={merchant_payment_code}	The payment was not found for this merchant. Please check your parameter.
BP-DMO-2	Only payments with status OP can be modified (your payment status is {status})	Only payments with status OP can be modified.
BP-DOC-01	Invalid document: {document}	Invalid document.
BP-DOC-02	Invalid currency code: ADS, expected any of USD, BRL, EUR, MXN, PEN.	The currency sent on the request was not valid.
BP-ZIP-1	Zipcode code not informed	The field was not filled.
BP-ZIP-2	Zipcode is not valid	The parameter sent was not valid.
BP-ZIP-3	The address could not be retrieved	The address could not be retrieved.
BP-DR-111	Could not validate document. Please try again	The document could not be validated.

Payment page Error codes

• Payments related erros
• Card related errors
• Customer related errors
• General errors

Error codes, messages and descriptions

search

Code arrow_downward	Error message arrow_downward	Description arrow_downward
BP-R-1	Parameter is required: currency_code	The field was not filled.
BP-R-2	Parameter is required: amount	The field was not filled.
BP-R-3	Parameter is required: merchant_payment_code	The field was not filled.
BP-R-6	Parameter payment_type_code not informed	The field was not filled.
BP-R-7	Payment type is not active	The payment type is not enabled on your account. Contact our Integration Team.
BP-R-8	Invalid payment_type_code	The parameter sent was not valid.
BP-R-9	Amount must be positive: X	The amount is being sent if a minus(-). Check your request.
BP-R-10	Amount must be greater than X	The amount is too low.
BP-R-11	Payment type does not support instalments	You are trying to apply instalment on a payment type which not support it. For example: boleto.
BP-R-14	Parameter merchant_payment_code can have 20 characters maximum	The parameter has more characters than the limit allowed.
BP-R-15	Parameter order_number can have 40 characters maximum	The parameter has more characters than the limit allowed.
BP-R-16	Parameter user_value_1 can have 20 characters maximum	The parameter has more characters than the limit allowed.
BP-R-16	Parameter user_value_2 can have 20 characters maximum	The parameter has more characters than the limit allowed.
BP-R-16	Parameter user_value_3 can have 20 characters maximum	The parameter has more characters than the limit allowed.
BP-R-16	Parameter user_value_4 can have 20 characters maximum	The parameter has more characters than the limit allowed.
BP-R-16	Parameter user_value_5 can have 20 characters maximum	The parameter has more characters than the limit allowed.
BP-R-17	Payment status is not OP (open): X	This payment does not have the OP status.
BP-R-18	Parameter is invalid: person_type	The parameter sent was not valid.
BP-R-19	Checkout by CNPJ is not enabled	Checkout by CNPJ is not enabled on your account. Contact our Integration Team if you want to change it.
BP-R-20	Parameter is in an invalid format: due_date. Correct Format: dd/MM/yyyy	The parameter sent was not valid.
BP-R-21	Parameter is invalid: due_date – exceeds more than X days	The parameter sent was not valid.
BP-R-22	Parameter is invalid: due_date – less than permitted	The parameter sent was not valid.
BP-R-24	Parameter is required: country	The field was not filled.
BP-R-25	Country is not enabled	The country that you are trying to make a payment is not enabled. Contact our Integration Team.
BP-R-26	Country is not enabled for merchant	The country that you are trying to make a payment is not enabled on your account. Contact our Integration Team.
BP-R-27	Payment type is not enabled for merchant	The payment type that you are trying to make a payment is not enabled. Contact our Integration Team.
BP-R-32	Amount must be less than X	The amount is too high.

Understanding transaction_status in credit card transactions

The credit card transaction status will be returned in the response of the direct and query API methods in the payment.transaction_status node.

{

"payment": {

"transaction_status":

{

"acquirer": "EBANX",

"code": "NOK",

"description": "Not accepted"

}

}

}

caution

You must not rely on these codes to confirm a payment, but you can use them to improve the user experience on your application.

Status	Description
Accepted	The transaction was accepted.
Not accepted	The transaction was not approved. Advise customer to contact the credit card issuer.
Insufficient funds	The credit card has no funds at the time of the transaction. Advise customer to use another credit card.
Incorrect customer data	The customer data is incorrect. Advise customer to review their data.
Expired card	The card has already expired. Advise customer to use another credit card.
Security code mismatch	The security code is incorrect. Advise customer to review the security code.
Invalid card or card type	The credit card is an invalid, nonexistent or unblocked card. Advise contacting the credit card issuer.
Invalid card number	The credit card number is invalid. Advise customer to review the credit card data.
3-D Secure required	3-D Secure is enabled for the credit card. Advise customer to use another credit card.
Timeout	The connection timed out at some point of the stream. Retry at any time.
No response from acquirer	Acquirer did not respond the request. Retry at any time.
Acquirer response error	Acquirer response has an error. Retry at any time.
Broken communication	The connection was broken at some point of the stream. Retry at any time
Communication mismatch	Bad communication between EBANX and the acquirer. Retry at any time.
Cannot fulfill transaction	The transaction could not be fulfilled or was already executed. Do not retry.
Cannot cancel transaction	The transaction could not be cancelled. Do not retry
Invalid due date	The credit card due date is invalid. Advise customer to review the credit card data.
Inactive card	The credit card is not active. Retry at any time.
Refunded	An issue has been issued for this credit card. Do not retry.
Unknown acquirer error	The acquirer experienced a strange error. Retry at any time.
High risk transaction	The transaction was declined for having a high probability of being fraudulent.
Issuer does not support installments	The selected number of installments is not available for this card.
Cannot process transaction at this moment	Acquirer could not process the request at the moment. Retry at any time.

Localized error codes

We've prepared a JSON file with localized error messages. You can download it here.

Alternatively, you can check this two pages:

• Spanish error messages
• Portuguese error messages

Still need help?

We hope this article was enlightening, but in case we’ve failed to take out your doubts you have the following options to keep on seeking for answers:

• If you’re not our partner yet and would like to know more about our prices and conditions please fill our this form and our commercial team will get in touch with you.
• In case you’re already our partner please get in touch with our support team at integration@ebanx.com.