EBANX Direct API – Error Codes

This page's content:

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:

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.

Related Links

Payments

Error code Error message Description
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-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 Check the refund ID returned when it was created. The refund ID can also be obtained in the query operation for the payment. The merchant_refund_code is 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-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.

Cards

Error code Error message Description
BP-DR-33 Invalid value for instalments: X (single value) The parameter sent was not valid.
BP-DR-34 Invalid value for instalments: X (range) The parameter sent was not valid.
BP-DR-48 Field payment.creditcard is required for this payment type The field was not filled.
BP-DR-49 Field payment.creditcard.card_number is required The field was not filled.
BP-DR-51 Field payment.creditcard.card_name is required The field was not filled.
BP-DR-52 Parameter payment.creditcard.card_name can have 50 characters maximum The parameter has more characters than the limit allowed.
BP-DR-54 Field payment.creditcard.card_cvv is required The field was not filled.
BP-DR-55 Parameter payment.creditcard.card_cvv can have 4 characters maximum The parameter has more characters than the limit allowed.
BP-DR-56 Field payment.creditcard.card_due_date is required The field was not filled
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-61 It was not possible to create the token for this credit card It was not possible to complete the operation. You can learn more about it HERE.
BP-DR-62 Recurring payments are not enabled for this merchant Recurring payment is not allowed on your account. Contact our Integration Team.
BP-DR-63 Token not found for this acquirer Token not found for this acquirer. You can check your request to see if everything is right.
BP-DR-64 Token not found Token not found. Checked if the token is being sent right.
BP-DR-65 The provided token is already in use The token that you are trying to create already exist.
BP-DR-66 Token not valid. The token length must be between 32 and 128 characters The parameter has more characters than the limit allowed.
BP-DR-67 Field payment.creditcard.card_due_date is invalid The parameter sent was not valid.
BP-DR-75 Card number is invalid The parameter sent was not valid.
BP-DR-79 The amount of instalments is larger than the maximum allowed for merchant The number of instalments is not allowed. Contact our Integration Team.
BP-DR-83 Foreign credit card cannot be processed. The credit card was issued in a country other than the country of the acquirer.
BP-DR-89 The amount of instalments is not allowed – blocked values are: {payment.api.instalments.blocked} The number of instalments is not allowed. Contact our Integration Team.
BP-DR-94 The token’s credit card has expired The token that you are trying to use is expired.
BP-DR-95 Parameter payment.card.card_name must be a valid name: number isn’t allowed The customer may have mistaken the fields and put the number of the card instead of the name.
BP-DR-96 Token expired The token has expired.
BP-DR-97 Instalment payments are not allowed for prepaid cards. Instalment payments are not allowed for prepaid cards.
BP-DR-100 Instalment payments are not allowed for debit cards Instalment payments are not allowed for debit cards.
BP-DR-101 Card is not eligible for ecommerce The card provided by the customer cannot be used for online transactions
BP-DR-112 Too many attempts resulting in Insufficient Funds for this card Customer reached the attempt limit for Insufficient Funds card (2 attempts).
BP-DR-113 Invalid transaction Customer document blocked by Compliance
BP-DR-117 Value per instalment cannot be lower than R$5.00 The minimum amount per instalment is 5 BRL, either send a smaller number of instalments or a transaction with a higher value..

Customer

Error code Error message Description
BP-DR-13 Field payment.name is required The field was not filled.
BP-DR-14 Parameter payment.name can have 100 characters maximum The parameter has more characters than the limit allowed.
BP-DR-15 Field payment.email is required The field was not filled.
BP-DR-16 Parameter payment.email can have 100 characters maximum The parameter has more characters than the limit allowed.
BP-DR-17 Field payment.email must be a valid email The e-mail sent was not valid.
BP-DR-18 Customer is disabled on EBANX Customer is suspended on EBANX. If unexpected, please contact EBANX Support Team.
BP-DR-19 Field payment.birth_date is required The field was not filled.
BP-DR-20 Field payment.birth_date must be a valid birth date (dd/MM/yyyy) The birth date sent was not valid.
BP-DR-21 Customer must be at least 16 years old The customer has not the age required.
BP-DR-22 Field payment.document is required The field was not filled.
BP-DR-23 Field payment.document must be a valid {document} Documents per country list:
  • Brazil: CPF
  • Argentina: DNI, CUIT, CUIL and CDI.
  • Chile: RUT
  • Colombia: CC, CE and NIT.
BP-DR-24 Field payment.zipcode is required This is the CEP (postal address code).
BP-DR-25 Field payment.address is required The field was not filled.
BP-DR-26 Field payment.street_number is required The field was not filled.
BP-DR-27 Field payment.city is required The field was not filled.
BP-DR-28 Field payment.state is required The field was not filled.
BP-DR-29 Field payment.state must be a valid state code For a list of Brazilian state codes, refer to: http://en.wikipedia.org/wiki/States_of_Brazil
BP-DR-31 Field payment.phone_number is required The field was not filled.
BP-DR-32 Parameter payment.phone_number must be a valid phone number The parameter sent was not valid.
BP-DR-39 CPF, name, and birth date do not match: X EBANX checks if the CPF belongs to the person making the payment, matching the name and the date of birth.
BP-DR-40 This payment exceeds the maximum amount per month. Customer current balance: X Customer reached the payment limit for the period.
BP-DR-42 Field payment.responsible is required The field was not filled.
BP-DR-43 Field payment.responsible.name is required The field was not filled.
BP-DR-44 Field payment.responsible.document is required The field was not filled.
BP-DR-45 Field payment.responsible.birth_date is required The field was not filled.
BP-DR-46 Company responsible’s CPF, name, and birthdate do not match: (.*) Some parameters are not matched.
BP-DR-90 This customer is in our blocklist: {reason}. The customer is disabled on our system.
BP-DR-98 Customer e-mail is associated with payments for {customer.country}, not {payment.country}, please use another e-mail The country of the payment does not match the country of the customer.
BP-DR-103 Customer disabled Customer temporarily inactivated (excessive number of credit cards).

General

Error code Error message Description
BP-DR-1 Mode must be either full or iframe Check direct API available modes.
BP-DR-4 Currency is not active in the system: X EBANX currently does not support the currency.
BP-DR-104 Invalid notification_url The field notification_url contains an invalid URL.
BP-DR-106 You have reached the limit of your processing trial. Make sure you send the documents to unlock this limit or send an email to your business manager. Your account have a limit of how much it could process and you have reached that limit. You must upload your documents (Dashboard) to continue processing payments, or, talk with your business manager.
BP-DR-108 Invalid FX Token. The given FX Token is invalid.
BP-DR-109 FX Token not enabled. Talk with your business manager to enable FX Token.
BP-DR-110 FX Token: Base currency not enabled. FX Token: Target currency not enabled. FX Token: Currency not found. You are trying use an invalid currency.
BP-DPAR-1 Request_body is empty The request body is not being set by your system, please check if everything is right.
BP-DPAR-2 Invalid JSON expression Something is wrong with the JSON that you are trying to send. Check it looking for blank space on typos, that may be the problem.
BP-DPAR-3 Field integration_key is required The field was not filled.
BP-DPAR-4 Invalid integration key The integration key it is not being accepted on the request. Check if there is any typos on the string.
BP-DPAR-5 Merchant account is not active The merchant account is not enabled, please contact EBANX Support Team.
BP-DPAR-6 This merchant account is restricted to testing (use your production account or request one) The merchant account is not allowed in the production environment.
BP-DPAR-7 This merchant account cannot be used for testing (use your test account or request one) The merchant account is not allowed in the test environment.
BP-EX-1 Currency code not informed The currency was not filled.
BP-EX-2 Currency is not active in the system The currency is not enabled.
DA-0 Unknown error Unknown error. Contact the Integration Team.
DA-1 Empty operation parameter The field was not filled.
DA-2 Unrecognized operation: {operation} Invalid operation.
BP-SA-1 Parameter integration_key not informed The field was not filled.
BP-SA-2 Invalid integration key The integration key it is not being accepted on the request. Check if there is any typos on the string.
BP-SA-3 Merchant account is not active The merchant account is not enabled, please contact EBANX Support Team.
BP-SA-4 This merchant account is restricted to testing (use your production account or request one) Contact the Integration Team.
BP-SA-5 This merchant account cannot be used for testing (use your test account or request one) Contact the Integration Team.

First Steps

Integration Methods

Sandbox Testing