Version: current

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

Error codes, messages and descriptions
Code
Error message
Description
BP-CH-1Payment type group is not active: {group_code}Some payment method is not enabled. Contact our Integration Team.
BP-DR-0Payment 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-2Field payment is requiredThe field was not filled.
BP-DR-3Field payment.currency_code is requiredThe field was not filled.
BP-DR-5Field payment.amount_total is requiredThe field was not filled.
BP-DR-6Amount reported is less than the minimum amountThe payment amount is too low.
BP-DR-7Amount must be less than XThe payment amount is too high.
BP-DR-8If passed, amount_itens + amount_shipping must be equal to amount_totalThe amount sent was not right.
BP-DR-9Field payment.merchant_payment_code is requiredThe field was not filled.
BP-DR-10Parameter merchant_payment_code can have 40 characters maximumThe parameter has more characters than the limit allowed.
BP-DR-11Parameter payment.order_number can have 40 characters maximumThe parameter has more characters than the limit allowed.
BP-DR-12Parameter X can have 20 characters maximumThe parameter has more characters than the limit allowed.
BP-DR-35Invalid payment_type_code: XThe payment method is not enabled. Contact our Integration Team.
BP-DR-36Payment type is not activeThe payment method is not enabled. Contact our Integration Team.
BP-DR-38Payment type not allowed in Direct API (full mode): XNot all payment types are allowed in full mode, please refer to documentation.
BP-DR-41Field payment.person_type must contain a valid person_typeThe parameter sent was not valid.
BP-DR-47Parameter payment.directdebit.bank_account can have 10 characters maximumThe parameter has more characters than the limit allowed.
BP-DR-50Payment type not allowed in Direct API (full mode): {payment_type_code}The payment method is not allowed. Contact our Integration Team.
BP-DR-57Parameter is in an invalid format: due_date. Correct Format: dd/MM/yyyyThe parameter was not sent on the right format.
BP-DR-58Parameter is invalid: due_date – exceeds more than {days} daysThe parameter ‘due_date’ exceeds the numbers of days that is in the configuration.
BP-DR-59Parameter is invalid: due_date – less than permittedThe parameter ‘due_date’ is too short.
BP-DR-68Field payment.directdebit.bank_account is requiredThe field was not filled.
BP-DR-69Parameter payment.directdebit.bank_agency can have 10 characters maximumThe parameter has more characters than the limit allowed.
BP-DR-70Field payment.directdebit.bank_agency is requiredThe field was not filled.
BP-DR-71Parameter payment.directdebit.bank_code can have 5 characters maximumThe parameter has more characters than the limit allowed.
BP-DR-72Field payment.directdebit.bank_code is requiredThe field was not filled.
BP-DR-73Field payment.directdebit is required for this payment typeThe field was not filled.
BP-DR-77Country is not enabledThe country is not available on your account. Contact our Integration Team.
BP-DR-78Country not enabled for merchantThe country is not available on your account. Contact our Integration Team.
BP-DR-80It was not possible to generate CIP. Please try again.Some error happened on the transaction.
BP-DR-81Currency 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-82Parameter payment.note can have 200 characters maximum.The note parameter must have 200 characters or less.
BP-DR-84Duplicate payment for the same customer and amount within {minutes} minutes.Lock for preventing customer to be billed twice for the same transaction.
BP-DR-85Field payment.sub_account is required.The field was not filled.
BP-DR-86Parameter is invalid: payment.sub_account.The parameter sent was not valid.
BP-DR-87Field payment.sub_account.name is required.The field was not filled.
BP-DR-88Field payment.sub_account.image_url is required.The field was not filled.
BP-DR-91Field payment.institution_code is required.The field was not filled.
BP-DR-92Field payment.institution_code is not a valid bank code.The parameter sent was not valid.
BP-DR-93Error creating this payment within PSE ACH. Error code: ?.Something went wrong with the payment operation.
BP-DR-99Field payment.sub_account.image_url must be httpsThe image URL that you are trying to send must be with https.
BP-DR-102Too many attemptsThe customer tried too many times the same transaction in a short period of time.
BP-DR-105Missing Parameter for Flow methodParameter payment.flow_payment_method is required. You read more about HERE.
BP-DR-118Invalid Sub Account dataThe Sub Account sent in request is not valid.
BP-DR-130For 3DS 2.0 transactions, field payment.card.threeds_cryptogram is requiredThe Cryptogram field was not filled.
BP-DR-131For 3DS 2.0 transactions, field payment.card.threeds_eci is requiredThe ECI field was not filled.
BP-DR-132For 3DS 2.0 transactions, field payment.card.threeds_cryptogram and payment.card.threeds_eci are requiredThe Cryptogram and ECI fields were not filled.
BP-REF-1Parameter hash not informedThe field was not filled.
BP-REF-2Payment not found for merchant, hash: XThe payment was not found. Contact our Integration Team.
BP-REF-3Parameter operation not informed (must be request or cancel)The field was not filled.
BP-REF-4Parameter amount not informedThe field was not filled.
BP-REF-5Refund amount must be positiveYou are trying to send a negative refund.
BP-REF-6Refund amount is greater than payment amount: X and XThe refund and the payment amount does not match.
BP-REF-7Payment status is not CO, cannot be refunded: XThe payment status is not CO (Confirmed) so it cannot be refunded.
BP-REF-8Payment has chargebacks, cannot be refunded: XThe payments has chargebacks so it cannot be refunded.
BP-REF-9Pending refund amount for payment would be greater than payment amount: XThe amount of the refund and the payment does not match.
BP-REF-10Parameter description not informedThe field was not filled.
BP-REF-11Parameters not informed: refund_id or merchant_refund_codeoptionally generated by the merchant and also be used to identify a refund.
BP-REF-12Refund not found with id = X and merchant_refund_code = YSee above
BP-REF-13Refund is already cancelledRefund is already cancelled
BP-REF-14Refund is already confirmedRefund is already confirmed
BP-REF-15Invalid operation: XYou are trying an invalid operation.
BP-REF-16Parameter merchant_refund_code can have 20 characters maximumThe parameter has more characters than the limit allowed.
BP-REF-17A refund already exists with this merchant_refund_code: XThere is already a refund with this merchant code.
BP-REF-18Insufficient balance to create new refund. please contact finance@ebanx.comInsufficient balance.
BP-REF-19Credit card payment’s open date is older than 85 days ago.The payment is too old.
BP-REF-20Request cannot contain both payment.card and payment.creditcard entries.Only one parameter should be used: payment.creditcard or payment.card.
BP-REF-21Invalid Transaction.Customer document blocked by Compliance.
BP-CAN-1Parameter hash not informedThe field was not filled.
BP-CAN-2Payment not found for merchantThe payment was not found for this merchant. Please check your parameter.
BP-CAN-3Payment is already cancelledPayment is already cancelled.
BP-CAN-4Payment cannot be cancelledPayment cannot be cancelled.
BP-US-1Parameter hash not informedThe field was not filled.
BP-US-2Payment not found for merchant, hash: XThe payment was not found for this merchant. Please check your parameter.
BP-US-3Parameter status not informedThe field was not filled.
BP-US-4Status must be either CO or CAThe status must be either CO or CA
BP-US-5Operation NOT allowed in production modeThe 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-1Parameters hash or merchant_payment_code not informedThe field was not filled.
BP-Q-2Payment not found for merchantThe payment was not found for this merchant. Please check your parameter.
BP-CAP-1Parameters hash or merchant_payment_code not informedThe field was not filled.
BP-CAP-2Payment not found for merchantThe payment was not found for this merchant. Please check your parameter.
BP-CAP-3Payment cannot be captured, status is: CAThe payment cannot be captured.
BP-CAP-4Payment has already been captured, status is: COThe payment has already been captured.
BP-CAP-5Payment cannot be captured, status is: OPThe payment cannot be captured.
BP-CAP-6Payment cannot be captured, payment_type_code is:The payment cannot be captured.
BP-CAP-7Payment cannot be captured, auto_capture is: trueThe payment cannot be captured.
BP-CAP-8Payment cannot be captured, capture_available is: falseThe payment cannot be captured.
BP-CAP-9Payment cannot be captured, pre_approved is: falseThe payment cannot be captured.
BP-CAP-10Invalid amountThe amount that you are trying to use is invalid.
BP-CAP-11Partial capture not availablePartial capture not available.
BP-CAP-12Payment cannot be captured, amount must be equal or less than {currency_code} {max_amount}The payment amount exceeds the limit.
BP-REF-CAN-1Payment can not be cancelled and can not generate a refund. Payment status is CAPayment can not be cancelled and can not generate a refund.
BP-DMO-1Payment not found for merchant: merchant_payment_code={merchant_payment_code}The payment was not found for this merchant. Please check your parameter.
BP-DMO-2Only payments with status OP can be modified (your payment status is {status})Only payments with status OP can be modified.
BP-DOC-01Invalid document: {document}Invalid document.
BP-DOC-02Invalid currency code: ADS, expected any of USD, BRL, EUR, MXN, PEN.The currency sent on the request was not valid.
BP-ZIP-1Zipcode code not informedThe field was not filled.
BP-ZIP-2Zipcode is not validThe parameter sent was not valid.
BP-ZIP-3The address could not be retrievedThe address could not be retrieved.
BP-DR-111Could not validate document. Please try againThe document could not be validated.

Payment page Error codes

Error codes, messages and descriptions
Code
Error message
Description
BP-R-1Parameter is required: currency_codeThe field was not filled.
BP-R-2Parameter is required: amountThe field was not filled.
BP-R-3Parameter is required: merchant_payment_codeThe field was not filled.
BP-R-6Parameter payment_type_code not informedThe field was not filled.
BP-R-7Payment type is not activeThe payment type is not enabled on your account. Contact our Integration Team.
BP-R-8Invalid payment_type_codeThe parameter sent was not valid.
BP-R-9Amount must be positive: XThe amount is being sent if a minus(-). Check your request.
BP-R-10Amount must be greater than XThe amount is too low.
BP-R-11Payment type does not support instalmentsYou are trying to apply instalment on a payment type which not support it. For example: boleto.
BP-R-14Parameter merchant_payment_code can have 20 characters maximumThe parameter has more characters than the limit allowed.
BP-R-15Parameter order_number can have 40 characters maximumThe parameter has more characters than the limit allowed.
BP-R-16Parameter user_value_1 can have 20 characters maximumThe parameter has more characters than the limit allowed.
BP-R-16Parameter user_value_2 can have 20 characters maximumThe parameter has more characters than the limit allowed.
BP-R-16Parameter user_value_3 can have 20 characters maximumThe parameter has more characters than the limit allowed.
BP-R-16Parameter user_value_4 can have 20 characters maximumThe parameter has more characters than the limit allowed.
BP-R-16Parameter user_value_5 can have 20 characters maximumThe parameter has more characters than the limit allowed.
BP-R-17Payment status is not OP (open): XThis payment does not have the OP status.
BP-R-18Parameter is invalid: person_typeThe parameter sent was not valid.
BP-R-19Checkout by CNPJ is not enabledCheckout by CNPJ is not enabled on your account. Contact our Integration Team if you want to change it.
BP-R-20Parameter is in an invalid format: due_date. Correct Format: dd/MM/yyyyThe parameter sent was not valid.
BP-R-21Parameter is invalid: due_date – exceeds more than X daysThe parameter sent was not valid.
BP-R-22Parameter is invalid: due_date – less than permittedThe parameter sent was not valid.
BP-R-24Parameter is required: countryThe field was not filled.
BP-R-25Country is not enabledThe country that you are trying to make a payment is not enabled. Contact our Integration Team.
BP-R-26Country is not enabled for merchantThe country that you are trying to make a payment is not enabled on your account. Contact our Integration Team.
BP-R-27Payment type is not enabled for merchantThe payment type that you are trying to make a payment is not enabled. Contact our Integration Team.
BP-R-32Amount must be less than XThe 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.

StatusDescription
AcceptedThe transaction was accepted.
Not acceptedThe transaction was not approved. Advise customer to contact the credit card issuer.
Insufficient fundsThe credit card has no funds at the time of the transaction. Advise customer to use another credit card.
Incorrect customer dataThe customer data is incorrect. Advise customer to review their data.
Expired cardThe card has already expired. Advise customer to use another credit card.
Security code mismatchThe security code is incorrect. Advise customer to review the security code.
Invalid card or card typeThe credit card is an invalid, nonexistent or unblocked card. Advise contacting the credit card issuer.
Invalid card numberThe credit card number is invalid. Advise customer to review the credit card data.
3-D Secure required3-D Secure is enabled for the credit card. Advise customer to use another credit card.
TimeoutThe connection timed out at some point of the stream. Retry at any time.
No response from acquirerAcquirer did not respond the request. Retry at any time.
Acquirer response errorAcquirer response has an error. Retry at any time.
Broken communicationThe connection was broken at some point of the stream. Retry at any time
Communication mismatchBad communication between EBANX and the acquirer. Retry at any time.
Cannot fulfill transactionThe transaction could not be fulfilled or was already executed. Do not retry.
Cannot cancel transactionThe transaction could not be cancelled. Do not retry
Invalid due dateThe credit card due date is invalid. Advise customer to review the credit card data.
Inactive cardThe credit card is not active. Retry at any time.
RefundedAn issue has been issued for this credit card. Do not retry.
Unknown acquirer errorThe acquirer experienced a strange error. Retry at any time.
High risk transactionThe transaction was declined for having a high probability of being fraudulent.
Issuer does not support installmentsThe selected number of installments is not available for this card.
Cannot process transaction at this momentAcquirer 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:

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 ou this form and our comercial 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.
Last updated on by Fernando Pankiewicz Gomes