EBANX

EBANX Integration Guide

Braintree's partnership with EBANX enables Braintree merchants to leverage their existing Braintree integration to process transactions locally in Latin America. We currently support the following countries: Argentina, Brazil, Chile, Colombia, Peru, Mexico.

Supported Operations

Authorization SDK | GraphQL
Capture SDK | GraphQL
Charge SDK | GraphQL
Void SDK | GraphQL
Refund SDK | GraphQL
Verifying a Card SDK | GraphQL

Supported Countries

Country Name	Supported Credit Cards	Supported Debit Cards	3DS Supported/Required	Partial Capture Allowed	TaxId Required	Decimal Supported
Argentina	Mastercard, Visa, Diners, American Express	Mastercard, Visa	Not supported	No	Yes	Yes
Brazil	Mastercard, Visa, Diners, American Express, Elo	Mastercard, Visa, Elo	Supported, required for debit card	Yes	Yes	Yes
Chile	Mastercard, Visa, Diners, American Express	Mastercard, Visa	Not supported	No	No	No
Colombia	Mastercard, Visa, Diners, American Express	Mastercard, Visa	Not supported	No	No	Yes
Costa Rica	Mastercard, Visa, American Express	Mastercard, Visa	Supported, required for non-recurrent transactions	Yes	No	Yes
Egypt	Mastercard, Visa	Mastercard, Visa	Not supported	No	No	Yes
Guatemala	Mastercard, Visa, American Express	Mastercard, Visa	Not supported	Yes	No	Yes
Paraguay	Mastercard, Visa, Diners, American Express	Mastercard, Visa	Not supported	No	Yes	No
Peru	Mastercard, Visa, Diners, American Express	Mastercard, Visa	Not supported	No	No	Yes
Mexico	Mastercard, Visa, American Express	Mastercard, Visa	Not supported	No	No	Yes
South Africa	Mastercard, Visa	Mastercard, Visa	Supported	Yes	Yes	Yes
Uruguay	Mastercard, Visa, Diners	Visa	Not supported	No	Yes	No

Setup

EBANX Configuration & Credentials

Each merchant should have an account with EBANX. To set up an account with EBANX, follow the EBANX Direct API documentation. Once that has been completed, please work with the account manager or TAM to securely share the integration key with Braintree. Ebanx will provide two integration keys for Sandbox and Production environments

Braintree Merchant Account

To process cards with EBANX, you will need currency-specific Braintree merchant accounts for use in your integration. Your account manager TAM can help facilitate this.

CVV Requirements

In situations where an integration will be supporting recurring transactions (e.g. as a monthly software subscription), the CVV will not be present for subsequent transactions. EBANX can relax the restriction that requires the CVV on all transactions, however this has to be manually configured via EBANX. Warning: This may result in lower approval rates.

Refunds

In order to facilitate EBANX refunds in Braintree, merchants MUST configure their EBANX account to send refunds to a card network immediately. By default, EBANX will initially set refunds to PE (pending), and after 30 minutes will send them to a card network. Any refund returned with a status not equal to CO (complete) will be considered a FAILED transaction.

Debit vs. Credit

To use debit cards with the EBANX integration, the debit cards option must be enabled in the EBANX dashboard, for more information see the EBANX debit card guide.

Transactions

Creating a Customer

[SDK, GraphQL] Customer creation is a mandatory step for the EBANX integration, and can be accomplished using either the SDKs or GraphQL API. When creating a customer, although not required fields for Braintree, name (first and last) and email will need to be provided. Not providing a first or last name could lead to issues with transactions for the customer. Not providing an email or full name for a customer will result in PROCESSOR_DECLINED for all transactions created for the customer. An additional taxIdentifiers field must be provided in countries Brazil and Argentina. The tax identifier can contain dashes and dots or also could be passed without them. Example of tax identifiers Brazil - 853.513.468-93 (This can also be passed as 85351346893) Argentina - 30-52135353-1 (This can also be passed as 30521353531)

Tokenize Payment Method

[SDK, GraphQL] Tokenization returns a single use token or nonce of a payment method. Note:billingAddress.countryCode is required for the EBANX integration. When using the SDK, it is recommended to use a payment nonce sent from the client performing the transaction. For more information see receiving a Payment Method nonce from your client for more information.

Vault Payment Method

[SDK, GraphQL] Vaulting a tokenized payment method will create an entity that can be authorized or charged multiple times. Vaulting the payment method directly, a tokenized payment method can be vaulted during authorization [SDK, GraphQL].

Tax Identifiers

An additional taxIdentifier field must be provided in countries Brazil, Argentina, Paraguay, Uruguay. The tax identifier can contain dashes and dots or also could be passed without them. Example of tax identifiers Brazil - 853.513.468-93 (This can also be passed as 85351346893) Argentina - 30-52135353-1 (This can also be passed as 30521353531) Tax Identifiers can be provided in two ways :

On a Customer - [SDK,GraphQL] These can be added on a customer create or customer update. Once added to customer, the taxIdentifier will be securely vaulted and used during the transaction.
On a Transaction - [SDK,GraphQL] Note: - The taxIdentifiers need to be provided on every call. These will not be vaulted and will be only used for processing.

Error Codes

If tax identifier is not provided then Braintree will return an error code 2033 and error message Inconsistent Data

Supported Operations with EBANX:

Note: Please use Braintree platform for Authorization, Capture, Charge, Void and Refund Operations. Performing these operations in EBANX without Braintree could lead to discrepancies and synchronization errors.

Authorization [SDK,GraphQL]

Note: Braintree can support a maximum of 48 installments. EBANX might have different limitations related to installment amounts and the number of installments per country Link. If using installments, the transaction amount should be the total amount to charge the customer, including the installment fees Link.

Capture [SDK, GraphQL]

Note: Partial Capture is only supported in Brazil, Guatemala and Costa Rica . If the amount is provided in the capture request (Beside for Brazil), and it is not equal to the authorized amount, the request will be declined, and the SETTLEMENT_DECLINED response will be returned. The authorized transaction in EBANX will not be updated and will be voided after 7 days. Once the transaction is in the SETTLEMENT_DECLINED state in Braintree, it cannot be updated.

Charge (Authorization + Capture in one step) [SDK, GraphQL]

Note: Customer details are required for processing with EBANX. Creating customers within an authorization call is currently not supported.

Void [SDK, GraphQL]

Note:

If a transaction is directly canceled by EBANX, and then the Braintree SDK or GraphQL API performs a void action on the transaction, the SDK or GraphQL API will respond with a success.
Using the ReverseTransaction mutation in the GraphQL API will void a transaction that is not in the SETTLED state, and will refund a transaction that is in the SETTLED state.

Refund [SDK, GraphQL]

Note:

Refunds cannot be performed for an amount greater than the settled amount.
Credit card refunds processed more than 90 days after the original transaction will result in a different refund flow within EBANX. This flow results in a PENDING status to be returned and Braintree will not receive subsequent updates from EBANX on the refund status.

Verifying a Card [GraphQL] Cards can be verified in various ways using the SDK, see this documentation for more details.

Response Codes

Braintree can only display a limited number of response codes since transaction results are controlled by EBANX. When the EBANX decline codes cannot be mapped to a like-to-like Braintree decline codes, Braintree returns code 2000 with message Do Not Honor

Failure Responses

Braintree Error Code	Braintree Error Message	EBANX Error Code	EBANX Error Message
2000	Do Not Honor	BP-REF-2	Payment not found for merchant, hash: X
2001	Insufficent Funds	NOK	Insufficient funds
2004	Expired Card	NOK	Expired Card
2005	Invalid Credit Card Number	NOK	Invalid card or card type
2005	Invalid Credit Card Number	NOK	Invalid card number
2006	Invalid Expiration Date	NOK	Invalid due date
2006	Invalid Expiration Date	BP-DR-57	Parameter is in an invalid format: due_date. Correct Format: dd/MM/yyyy
2006	Invalid Expiration Date	BP-DR-67	Field payment.creditcard.card_due_date is invalid
2010	Card Issuer Declined CVV	NOK	Security code mismatch
2015	Transaction Not Allowed	NOK	High risk transaction
2015	Transaction Not Allowed	BP-DR-113	Customer document blocked by compliance
2019	Invalid Transaction	BP-DR-33	Invalid value for instalments: X (single value)
2019	Invalid Transaction	BP-DR-34	Invalid value for instalments: X (range)
2019	Invalid Transaction	BP-DR-79	The amount of instalments is larger than the maximum allowed for merchant
2019	Invalid Transaction	BP-DR-89	The amount of instalments is not allowed – blocked values are: {payment.api.instalments.blocked}"
2024	Card Type Not Enabled	BP-DR-35	Invalid payment_type_code: X
2024	Card Type Not Enabled	BP-DR-36	Payment type is not active
2024	Card Type Not Enabled	BP-DR-38	Payment type not allowed in Direct API (full mode): X
2025	Set Up Error – Merchant	BP-DPAR-4	Invalid integration key
2027	Set Up Error - Amount	BP-DR-117	Value per instalment cannot be lower than R$5.00
2029	Setup Error - Card	BP-R-11	Payment type does not support instalments
2029	Setup Error - Card	BP-DR-97	Instalment payments are not allowed for prepaid cards.
2029	Setup Error - Card	BP-DR-100	Instalment payments are not allowed for debit cards
2033	Inconsistent Data	NOK	Broken communication
2033	Inconsistent Data	NOK	Communication mismatch
2033	Inconsistent Data	BP-DR-15	Field payment.email is required
2033	Inconsistent Data	BP-DR-22	Field payment.document is required
2033	Inconsistent Data	BP-DR-23	Field payment.document must be a valid {document}
2033	Inconsistent Data	BP-DR-98	Customer Email Associated with multiple countries
2054	Reversal amount does not match authorization amount	BP-REF-6	Refund amount is greater than payment amount: X and X
2054	Reversal amount does not match authorization amount	BP-REF-9	Pending refund amount for payment would be greater than payment amount: X
2059	Address Verification Failed	NOK	Incorrect customer data
2064	Invalid Currency Code	BP-DR-3	Field payment.currency_code is required
2064	Invalid Amount	BP-DR-5	Field payment.amount_total is required
2103	Invalid Amount	BP-CAP-10	Invalid Amount
3000	Failed	NOK	Not accepted
3001	Error	NOK	Not accepted
4004	Already Refunded	BP-REF-14	Refund is already confirmed
4004	Already Refunded	BP-REF-17	A refund already exists with this merchant_refund_code: X
4006	Capture Amount Exceeded Allowable Limit	BP-CAP-12	Payment cannot be captured, amount must be equal or less than {currency_code} {max_amount}
4001	Settlement Declined	BP-REF-5	Refund amount must be positive
4001	Settlement Declined	BP-REF-7	Payment status is not CO, cannot be refunded: X
4024	Refund Time Limit Exceeded	BP-REF-19	Credit card payment's open date is older than 85 days ago.

Caveats

Argentina

Partial capture is not supported.
taxIdentifiers is required

Brazil

3DS required for debit card Authorization.
taxIdentifiers is required.

Chile

Braintree doesn't support decimal in the amount field for Chile, and it must be an integer.
Partial capture is not supported.
Dynamic descriptors will not be supported.

Costa Rica

3DS required for non-recurrent transactions.

Egypt

Partial capture is not supported.

Peru

Partial capture is not supported.

Mexico

Dynamic descriptors will not be supported.
Partial capture is not supported.

Paraguay

Partial capture is not supported.
taxIdentifiers is required
Braintree doesn't support decimal in the amount field for Paraguay, and it must be an integer.

South Africa

3DS is supported. Additional configuration is required.
taxIdentifiers is required (National ID or Passport ID).

Uruguay

Partial capture is not supported.
taxIdentifiers is required
Braintree doesn't support decimal in the amount field for Uruguay, and it must be an integer.

Test Cards

Braintree provides a set of test card numbers that can be used in sandbox to test integrations. Merchants can use different card numbers to exercise various scenarios. However, with the EBANX integration there are some limitations because EBANX does not support the same set of test card numbers. When using the Braintree integration a subset of the Braintree test card numbers have been mapped to EBANX test card numbers. Because we map the credit cards in sandbox to facilitate end-to-end testing, there may be discrepancies in reporting in sandbox. However, in production, the card numbers are sent to EBANX directly without any modification.

📔 EBANX test card numbers, Braintree test card numbers

Credit Cards | Success

Card brand	Test number	EBANX number	Automatically mapped?
American Express	378282246310005	371449635398431	✅
Diner's Club	36259600000004	30569309025904	✅
Discover	6011000991300009	6011111111111117	✅
Mastercard	5555555555554444	5555555555554444	Pass-thru*
Visa	4111111111111111	4111111111111111	Pass-thru

_{* = For Mexico, this value will be treated as a debit card.}

Credit Cards | Failure

Scenario	Test number	EBANX number	Automatically mapped?	Braintree result
Insufficient funds	4000111111111115	4716909774636285	✅	Processor Declined
Invalid Data	5105105105105100	5102026827345142	✅	Processor Declined
Not Approved	378734493671000	378568775709157	✅	Processor Declined
Card Expired	6011000990139424	6011088896715918	✅	Processor Declined

Debit Cards

See the Debit vs. Credit section to ensure these transactions are configured correctly.

Card brand	Test number	EBANX number	Automatically mapped?
Visa	4012000033330125	4242424242424242	✅

For Mexico, the test card number 5555555555554444 will be treated as a debit card.

Mandatory Fields

Email is a mandatory field from Ebanx required for all countries.
Either of Customer's firstName or lastName is required. Both cannot be empty for all countries.
Tax Identifiers are mandatory required for countries
- Brazil
- Argentina
- Paraguay
- Uruguay

If any of these fields are not provided then Braintree will return an error code 2033 and error message Inconsistent Data

Limitations

Blind credits

Blind credits are not supported through EBANX.

WebHook Support

Currently webhooks are not supported via Braintree for this integration.

Dynamic descriptors

Dynamic descriptor support is limited with EBANX.
Values are limited to 10-15 characters based on locale.
This applies to all LATAM regions in EBANX. This is a limitation with the banks.
Brazil and Argentina do allow dynamic descriptors, however, they are limited and do not support URLs.