EBANX Integration Guide

PayPal's partnership with EBANX enables merchants to leverage their existing Braintree integration to process transactions through the PayPal Payment Orchestration platform in the supported markets. This guide helps developers set up this integration by providing the necessary information about required fields, transaction states, and other configuration or processing requirements.

This integration supports transactions in the following countries: Argentina, Brazil, Chile, Colombia, Costa Rica, Egypt, Guatemala, Mexico, Nigeria, Paraguay, Peru, South Africa, and Uruguay. For information about regional requirements and support for specific features, see Country-specific requirements and limitations.

Important Use the Braintree platform for all transaction operations. Performing operations directly with EBANX could create discrepancies and cause synchronization errors.

Features

The following topics describe the capabilities that this EBANX integration supports.

NoteFor information about regional requirements and support for specific features, see Country-specific requirements and limitations.

Core transaction lifecycle

The following table describes the support for core transaction lifecycle operations with this integration.

Legend: ✅ Supported | ❌ Not supported | ⚠️ Conditional or varies by configuration

Capability	Support	Notes
Core transaction lifecycle
Charge (single step)	✅	Authorize and capture in the same call.
Charge (dual step)	⚠️	Varies based on the country. To enable this feature, contact your Braintree account manager (AM) or technical account manager (TAM).
Standalone authorization	✅	Capture the authorization within 5 days.
Capture (full)	✅	Captures a previously authorized transaction. Capture authorizations within 5 days.
Partial capture	⚠️	This feature is supported in Brazil, Costa Rica, Guatemala, Nigeria, South Africa, but it might be enabled only for certain merchants or markets.
Capture greater than authorized amount	❌
Adjust Authorization API (incremental auth or partial reversal during capture or settlement)	❌

Voids and refunds

The following table describes the support for void and refund operations with this integration.

Legend: ✅ Supported | ❌ Not supported | ⚠️ Conditional or varies by configuration

Capability	Support	Notes
Full void (auth reversal)	✅	Voids cancel an authorized transaction prior to settlement.
Partial void	❌
Void on settled transaction	❌	Use refund instead.
Full refund	✅	If you need to enable refunds for more than 90 days after the transaction, contact EBANX.
Partial refund	✅	Refunds cannot exceed the settled amount.
Multiple refunds	✅
Blind credits (refunds for transactions that were processed elsewhere)	❌	Refunds must reference their original transaction.

Payment instruments and methods

The following table describes the support for payment instruments and methods with this integration.

Legend: ✅ Supported | ❌ Not supported | ⚠️ Conditional or varies by configuration

Capability	Support	Notes
Credit cards	✅	Argentina: Mastercard, Visa, Diners, American Express Brazil: Mastercard, Visa, Diners, American Express, Elo Chile: Mastercard, Visa, Diners, American Express Colombia: Mastercard, Visa, Diners, American Express Costa Rica: Mastercard, Visa, American Express Egypt: Mastercard, Visa Guatemala: Mastercard, Visa, American Express Mexico: Mastercard, Visa, American Express Nigeria: Mastercard, Visa, Verve Paraguay: Mastercard, Visa, Diners, American Express Peru: Mastercard, Visa, Diners, American Express Uruguay: Mastercard, Visa, Diners
Debit cards	✅	Argentina: Mastercard, Visa Brazil: Mastercard, Visa, Elo Chile: Mastercard, Visa Colombia: Mastercard, Visa Costa Rica: Mastercard, Visa Egypt: Mastercard, Visa Guatemala: Mastercard, Visa Mexico: Mastercard, Visa Nigeria: Mastercard, Visa, Verve Paraguay: Mastercard, Visa Peru: Mastercard, Visa Uruguay: Mastercard, Visa
Prepaid cards	✅	These transactions are supported if the processor supports prepaid cards.
PLCCs	❌
Gift cards	❌
Apple Pay	❌	In progress
Google Pay	❌	In progress
Android Pay or Samsung Pay	❌
Venmo or PayPal	❌

Data, descriptors, and fraud signals

The following table describes the support for data, descriptors, and fraud signals with this integration.

Legend: ✅ Supported | ❌ Not supported | ⚠️ Conditional or varies by configuration

Capability	Support	Notes
Address Verification System (AVS) or Card Verification Value (CVV) response handling	✅
Dynamic descriptors	⚠️	Not supported in Chile or Mexico. For additional country-specific information, see Country-specific requirements and limitations.
Network tokens	⚠️	Can be enabled only for Brazil. For more information, see Network token support.
Level 2, Level 3, or lodging data	❌
3D Secure (3DS)	⚠️	This functonality is supported in Brazil and required for debit cards. It is supported in Costa Rica and required for customer-initiated transactions. To enable 3DS for additional markets, contact your Braintree AM or TAM.

Verifications

The following table lists the verifications that this integration supports.

Legend: ✅ Supported | ❌ Not supported | ⚠️ Conditional or varies by configuration

Capability	Support	Notes
$0 verification	✅
Non-zero dollar verification	❌	Use $0 verification instead. EBANX performs a ghost authorization and void with a minimum amount if needed.

Before you begin

This integration requires setup on both Braintree and EBANX. Before you begin the integration, complete these setiup tasks.

On Braintree: To process card transactions through EBANX, you need currency-specific Braintree merchant accounts for use in your integration. Your account manager (AM) or technical account manager (TAM) can assist you in setting these up. If you do not have a dedicated AM or TAM for Braintree, contact [email protected] for support.
On EBANX: Set up an account with EBANX using the EBANX Direct API documentation. EBANX provides 2 integration keys: 1 for sandbox and 1 for production.

Note When you have your EBANX account, work with your AM or TAM to securely share the EBANX integration key with Braintree.If you do not have a dedicated AM or TAM for Braintree, contact [email protected] for support.

Also review the following EBANX-specific requirements to ensure that you are in compliance before processing transactions through EBANX:

CVV requirements: Recurring transactions and transactions that use vaulted cards do not includes a CVV. EBANX can relax the CVV requirement, but you must configure it manually. This change can affect approval rates.
Refunds: Configure EBANX to send synchronous responses for refunds. Without this configuration, all refunds return as FAILED or SETTLEMENT_DECLINED. Merchants can enable refunds for periods that exceed 90 days, but after you enable this change, all refunds become asynchronous and return SETTLING. When EBANX confirms the status of the refunds, they transition to SETTLED or SETTLEMENT_DECLINED.
Debit cards: To use debit cards with the EBANX integration, you must enable the debit cards option in the EBANX dashboard. For more information, see the EBANX debit card guide.
Dual step transaction: To perform a dual-step authorization and immediate capture using the Braintree SDK or GraphQL API, work with EBANX to enable this setting.
Relaxing required fields: If you are unable to provide required values, such as phone number or street number, contact EBANX to relax these requirements. For more information, see Required fields.

After you complete all necessary setup, proceed to Transactions to create your first transaction.

Transactions

After you complete the necessary setup, use the Braintree SDK or GraphQL API to create and manage transactions.

Important Use the Braintree platform for all transaction operations. Performing operations directly with EBANX could create discrepancies and cause synchronization errors.

For general information about Braintree transactions, see:

Transaction creation

Use the Braintree SDK or GraphQL API to create a transaction. The following sections list the fields that EBANX transactions require and tells how they map to EBANX's API. Add these values to your existing Braintree transaction creation call.

The following table describes the fields that an EBANX transaction requires.

Field	Location	How to provide	Notes
`amount`	Transaction	Include in transaction	Transaction amount in the smallest currency unit
`customer.firstName`	Customer	Create the Braintree customer first. If you cannot add to the customer, contact your Braintree AM or TAM.
`customer.lastName`	Customer	Create the Braintree customer first. If you cannot add to the customer, contact your Braintree AM or TAM.
`customer.email`	Customer	Create the Braintree customer first. If you cannot add to the customer, contact your Braintree AM or TAM.
`billing.countryCode`	Payment method	Include during tokenization	Two-letter ISO country code
`taxIdentifiers`	Customer	If you cannot add this value to the customer, contact your Braintree AM or TAM.	Required in Argentina, Brazil, Paraguay, and Uruguay For more information, see Tax identifier.
`card.cardholderName`	Payment method	Include during tokenization	Name as it appears on the card

Fields that Braintree passes to EBANX

The following table maps Braintree fields to their corresponding EBANX fields for authorize and charge operations.

Legend: ✅ Required | ⚠️ Conditional or varies by configuration

Braintree field	EBANX field	Required	Notes
`customer.firstName` + `customer.lastName`	`payment.name`	✅
`customer.email`	`payment.email`	✅
`customer.phone`	`payment.phone_number`	⚠️	Can be relaxed for all countries
`billing.streetAddress`	`payment.address`	⚠️	Required for BR, AR, CL, CO, MX, PE
`billing.locality`	`payment.city`	⚠️	Required for BR, AR, CL, CO, MX, PE
`billing.region`	`payment.state`	⚠️	Required for BR, AR, CL, CO, MX, PE
`billing.postalCode`	`payment.zipcode`	⚠️	Required for BR, AR, CL, CO, MX, PE
`currencyIsoCode`	`payment.currency_code`	✅	Uppercase
`amount`	`payment.amount_total`	✅	Direct
`customer.taxIdentifiers`	`payment.document`	⚠️	Required for BR, AR, UY, PY Note: You can override this setting through `processingOverrides.customerTaxIdentifier`.
`orderId`	`payment.order_number`	Optional
`installmentCount`	`payment.installments`	Optional
`taxAmount`	`payment.taxes.iva_co`	Optional	Colombia and local entities only
`paymentMethod.number`	`payment.card.card_number`	✅	Test cards are remapped in the sandbox environment.
`paymentMethod.expirationMonth` + `expirationYear`	`payment.card.card_due_date`	✅	Format: `MM/YYYY`
`paymentMethod.cvv`	`payment.card.card_cvv`	Optional	Omitted for recurring or vaulted transactions
`paymentMethod.cardholderName`	`payment.card.card_name`	✅
`descriptor.name`	`payment.card.soft_descriptor`	Optional	Not supported in Chile or Mexico
`threeDSecureData.eciFlag`	`payment.card.threeds_eci`	Optional	Brazil debit 3DS
`threeDSecureData.cavv`	`payment.card.threeds_cryptogram`	Optional
`threeDSecureData.dsTransactionId`	`payment.card.threeds_trxid`	Optional
`vaultedCredentialType`	`payment.cof_info`	Optional	Credentials on File (CoF) fields sent for merchant-initiated transaction (MIT) or stored credential flows.

Customer creation

Customer creation is a mandatory step for the EBANX integration. You can do this using either the Braintree SDK or GraphQL API.

When you create a customer, name (first and last) and email are required for EBANX transactions, even though they are not required fields in Braintree. Not providing a first or last name could lead to transaction issues. Not providing an email or full name will result in PROCESSOR_DECLINED for all transactions that customer creates.

Vaulted payment methods

Vaulting a tokenized payment method creates a reusable token that can be authorized or charged multiple times. You can vault a payment method in 2 ways:

Direct vaulting of an already-tokenized payment method
During the authorization process using the SDK or GraphQL API

Tax identifiers

Brazil, Argentina, Paraguay, and Uruguay require the taxIdentifier field. The tax identifier can contain dashes and dots, or it can be passed without them.

Examples:

Brazil: 853.513.468-93 (can also be passed as 85351346893)
Argentina: 30-52135353-1 (can also be passed as 30521353531)

You can provide the tax identifier in 2 ways:

On a customer using the SDK or GraphQL API: You can add this value when you create or update a customer. After you add it, the taxIdentifier is securely vaulted and used during the transaction.
On a transaction using the SDK or GraphQL API: You must provide the taxIdentifiers on every call. These are not vaulted and are only used for processing.

Note If you do not provide the taxIdentifier where it is required, Braintree returns error code 2033 with this message: Inconsistent Data.

Transaction object support

The following topics describe support for transaction operations and CVV handling with this integration.

Supported transaction operations

The following table lists the transaction request fields that this integration supports.

Legend: ✅ Supported | ❌ Not supported | ⚠️ Conditional or varies by country, merchant configuration, or processor |

Transaction operation	Support
Sale	✅
Find	✅
Void	✅
Refund	✅
Submit for settlement	✅
Clone	✅
Search	✅
Adjust Authorization	❌
Hold in Escrow	❌
Release from Escrow	❌
Submit for Partial Settlement	❌
Cancel Release	❌

CVV handling

For recurring transactions or when using vaulted cards, the CVV might not be present, which can cause lower approval rates. To relax the CVV requirements in EBANX, configure it manually.

Transaction status mapping

The following table maps EBANX response statuses to Braintree transaction statuses. For general information about Braintree result objects, see Result Objects.

Operation	EBANX response	Braintree transaction status	Additional information
Authorize	OK / Successful	`AUTHORIZED`	Dual-step transaction Important: Capture payment within 5 days.
Authorize	Retry	`FAILED`	You can configure a retry option on Braintree or implement your own retry logic.
Authorize	NOK or Decline	`PROCESSOR_DECLINED`	Hard decline from acquirer
Authorize	API error	`FAILED`	You can configure a retry option on Braintree or implement your own retry logic.
Charge	OK or Successful	`SETTLED`	You can configure this for single-step or dual-step transactions.
Charge	Retry	`FAILED`	In this rare event, Braintree reconciles the transaction. For more information, see FAILED status during charge.
Charge	NOK / Decline	`PROCESSOR_DECLINED`	Hard decline from acquirer
Charge	API error	`FAILED`
Capture	OK / Successful	`SETTLED`
Capture	API error	`SETTLING`	In this rare event, Braintree reconciles the transaction, working with EBANX, and changes its status to either `SETTLED` or `SETTLEMENT_DECLINED`. Do not ship goods or provide service until the status is `SETTLED`. For more infomration, see SETTLING status with HTTP errors.
Capture	NOK or Declined	`SETTLEMENT_DECLINED`	This is a rare event. It might indicate that the authorization expired.
Refund	OK or Successful	`SETTLED`
Refund	API error	`SETTLING`	Rare event. Braintree will reconcile the transaction with EBANX and move it to `SETTLED` or `SETTLEMENT_DECLINED`. For more information, see SETTLING status with HTTP errors.
Refund	NOK or Unsuccessful	`SETTLEMENT_DECLINED`	This should be a rare event, but it can be more common if there are disputes or chargebacks or if you are attempting to refund after 90 days or more.
Refund	Retry	`FAILED`
VerifyCard	OK or Successful	`VERIFIED`
VerifyCard	Retry	`FAILED`
VerifyCard	NOK or Decline	`PROCESSOR_DECLINED`
VerifyCard	API error	`FAILED`

SETTLING status with HTTP errors

In rare cases when EBANX returns HTTP 4xx or 5xx errors after a successful authorization, the transaction remains in SETTLING status. This can happen due to network or server overload or it EBANX is unavailable.

Reconciliation logic: Braintree queries EBANX for transaction information 3 times daily. If EBANX confirms authorization, Braintree retries capture, and the transaction ultimately transitions to SETTLED. If EBANX declines, Braintree marks the transaction as SETTLEMENT_DECLINED and sends notification by email.

FAILED status during charge

If Braintree receives no inline response from EBANX due to network errors or timeouts, the transaction status is FAILED. Braintree reconciles this transaction. If the transaction is identified as successful during reconciliation, the status is updated from FAILED to SETTLED, and a refund is automatically initiated. The refund follows its own transaction lifecycle (SETTLED, SETTLEMENT_DECLINED, SETTLING, or FAILED). The original transaction remains SETTLED. This operation can be retried. For more information, see Retries.

Retries

Follow these guidelines when handling retries for EBANX transactions:

Do not build a duplicate capture or refund retry loop when you see success: true but the status is SETTLING.
Always confirm that the transaction status is SETTLED before you ship goods or provide service.
You can configure retries on FAILED transactions at the merchant account ID (MAID) level. For help with configuration, contact your Braintree AM or TAM.

Network tokens

EBANX supports network tokens. The integration includes 2 provisioning options:

Braintree-managed network tokens: Braintree provisions and manages network tokens on your behalf. To enable Braintree-managed network tokens for your account, contact your AM or TAM. For more information, see the Getting Started with Network Tokens guide.
Bring Your Own Network Token: Use network tokens that you've provisioned through another provider. You must enable third-party network tokens on the merchant's account through EBANX. To enable this feature, contact EBANX support.

Response codes

Braintree can display only a limited number of response codes, because EBANX controls transaction outcomes. When EBANX decline codes do not map to equivalent Braintree decline codes, Braintree returns the code 2000 with this message: Do Not Honor.

The following table maps EBANX error codes to their Braintree equivalents.

.

Braintree error code	Braintree error message	EBANX error code	EBANX message
`2000`	Do Not Honor	`BP-REF-2`	Payment not found for merchant, hash: X
`2001`	Insufficient 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

To find the details for the EBANX response message, use eiher of these options:

SDK: additional_processor_response. For more information, see the SDK documentation.
GraphQL: PaymentStatusEvent.processorResponse.additionalInformation. For more information, see the GraphQL documentation.

Test cards

Braintree provides a set of test card numbers for sandbox testing. With the EBANX integration, some Braintree test card numbers are automatically mapped to EBANX test card numbers.

Note Because credit cards are mapped in the sandbox to facilitate end-to-end testing, there might be discrepancies in reporting. In production, card numbers are sent to EBANX directly without modification.

Credit cards: Success

The following test cards return a successful response in the sandbox environment.

Card brand	Braintree test number	EBANX test number	Automatically mapped?
American Express	`378282246310005`	`371449635398431`	✅
Diner's Club	`36259600000004`	`30569309025904`	✅
Discover	`6011000991300009`	`6011111111111117`	✅
Mastercard	`5555555555554444`	`5555555555554444`	Pass-through
Visa	`4111111111111111`	`4111111111111111`	Pass-through

Debit cards

Use the following debit card for testing.

Card brand	Braintree test number	EBANX test number	Automatically mapped?
Visa Debit	`4012000033330125`	`4242424242424242`	Pass-through

Credit cards: Failure

The following test cards return a declined response in the sandbox environment.

Scenario	Braintree test number	EBANX test 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`

Country-specific requirements and limitations

The following table describes additional requirements and limitations by country.

Country	Caveats
Argentina	Partial capture is not supported. `taxIdentifiers` is required.
Brazil	3DS is required for debit card authorization. `taxIdentifiers` is required.
Chile	The `amount` field must be an integer (decimal values are not supported). Partial capture is not supported. Dynamic descriptors are not supported.
Colombia	IVA/VAT is optionally passed through the `taxAmount` field. Partial capture is not supported.
Costa Rica	3DS is required for non-recurring transactions. Local processing is not supported.
Egypt	Partial capture is not supported. Local processing is not supported.
Guatemala	Local processing is not supported.
Mexico	Dynamic descriptors are not supported. Partial capture is not supported.
Nigeria	Partial capture is not supported. 3DS support will be added but is not yet supported. Local processing is not supported.
Paraguay	Partial capture is not supported. `taxIdentifiers` is required. The `amount` field must be an integer (decimal values are not supported). Local processing is not supported.
Peru	Partial capture is not supported.
South Africa	3DS is supported. Additional configuration is required. `taxIdentifiers` is required (National ID or Passport ID). Local processing is not supported.
Uruguay	Partial capture is not supported. `taxIdentifiers` is required. The `amount` field must be an integer (decimal values are not supported). Local processing is not supported.

The following resources provide additional information about EBANX and Braintree transactions.