Braintree

Braintree, a PayPal service, is a full-stack payment platform. Through the PayPal Payment Orchestration platform, Braintree merchants can process credit and debit card transactions in supported markets with EBANX acting as the payment processor.

This guide covers how the integration works, supported countries and card brands, required fields mapping, configuration steps, and troubleshooting.

Features

• Credit and debit card processing - Accept Visa, Mastercard, American Express, Diners, and local card brands (Elo, Verve) across 13 countries through EBANX acquiring.
• Dashboard-configured integration - EBANX is enabled as a processing backend within the Braintree platform; no direct EBANX API integration is required by the merchant.
• 3D Secure - Supported for card transactions in Brazil (required for debit cards) and Costa Rica (required for customer-initiated transactions).
• Vaulting - Store and reuse tokenized payment methods for recurring or repeat transactions.
• Refunds - Full, partial, and multiple refunds are supported for settled transactions.

Requirements

Before starting the integration, ensure you have the following:

• Braintree account - An active Braintree merchant account. If you do not have one, sign up at Braintree.
• EBANX account - An active EBANX merchant account. Contact EBANX Sales to set up your account.
• EBANX credentials - Your EBANX Integration Key (sandbox and production), provided by the EBANX integrations team during onboarding.
• Currency-specific merchant accounts - Braintree merchant accounts configured for each currency you intend to process. Your Braintree account manager (AM) or technical account manager (TAM) can assist.

How it works

1. 1 The customer initiates a purchase on the merchant's website or app.

2. 2 The merchant creates a transaction using the Braintree SDK or GraphQL API.

3. 3 Braintree routes the payment to EBANX for processing in the target market.

4. 4 EBANX processes the payment with the local acquirer and returns the result to Braintree.

5. 5 Braintree relays the transaction outcome back to the merchant.

6. 6 The merchant displays the payment confirmation to the customer.

Supported payment methods

Payment Method	Countries	Card Brands
Credit cards	Argentina, Brazil, Chile, Colombia, Costa Rica, Egypt, Guatemala, Mexico, Nigeria, Paraguay, Peru, South Africa, Uruguay	Visa, Mastercard, American Express, Diners, Elo (BR), Verve (NG)
Debit cards	Argentina, Brazil, Chile, Colombia, Costa Rica, Egypt, Guatemala, Mexico, Nigeria, Paraguay, Peru, South Africa, Uruguay	Visa, Mastercard, Elo (BR), Verve (NG)
Prepaid cards	Same as credit/debit cards	Supported if the processor supports prepaid cards

Info

For country-specific card brand availability, refer to the Braintree EBANX integration guide.

Key details

• Integration type - Dashboard-configured (via Braintree platform)
• Supported operations - Charge (single step), Authorize, Capture, Void, Refund
• 3D Secure - Supported in Brazil (required for debit) and Costa Rica (required for CIT). Can be enabled for additional markets via Braintree AM/TAM.
• Card on File / Vault - Supported through Braintree's vaulting
• Recurring billing - Supported for cards via Braintree's subscription engine
• Installments - Supported via installmentCount field
• Partial capture - Supported in Brazil, Costa Rica, Guatemala, Nigeria, South Africa
• Settlement currency - Configured during EBANX onboarding
• Authorization window - Capture authorizations within 5 days

Fields mapping

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

Braintree field	EBANX field	Required	Notes
customer.firstName + customer.lastName	payment.name	Yes	Customer creation is mandatory before transacting
customer.email	payment.email	Yes
customer.phone	payment.phone_number	Conditional	Can be relaxed for all countries
billing.streetAddress	payment.address	Conditional	Required for BR, AR, CL, CO, MX, PE
billing.locality	payment.city	Conditional	Required for BR, AR, CL, CO, MX, PE
billing.region	payment.state	Conditional	Required for BR, AR, CL, CO, MX, PE
billing.postalCode	payment.zipcode	Conditional	Required for BR, AR, CL, CO, MX, PE
billing.countryCode	payment.country	Yes	Two-letter ISO country code. Provided during tokenization.
currencyIsoCode	payment.currency_code	Yes	Uppercase
amount	payment.amount_total	Yes	Transaction amount in the specified currency
customer.taxIdentifiers	payment.document	Conditional	Required for BR, AR, UY, PY
orderId	payment.order_number	No
installmentCount	payment.installments	No
taxAmount	payment.taxes.iva_co	No	Colombia and local entities only
paymentMethod.number	payment.card.card_number	Yes	Test cards are remapped in sandbox
paymentMethod.expirationMonth + paymentMethod.expirationYear	payment.card.card_due_date	Yes	Format: MM/YYYY
paymentMethod.cvv	payment.card.card_cvv	No	Omitted for recurring or vaulted transactions
paymentMethod.cardholderName	payment.card.card_name	Yes
descriptor.name	payment.card.soft_descriptor	No	Not supported in Chile or Mexico
threeDSecureData.eciFlag	payment.card.threeds_eci	No	Brazil debit 3DS
threeDSecureData.cavv	payment.card.threeds_cryptogram	No
threeDSecureData.dsTransactionId	payment.card.threeds_trxid	No
vaultedCredentialType	payment.cof_info	No	CoF fields for MIT or stored credential flows

Info

If you are unable to provide required values such as phone number or street number, contact EBANX to relax these requirements.

Instructions

Follow the steps below.

1. Set up your EBANX account

   Contact the EBANX integrations team to establish your merchant account and obtain your EBANX Integration Key (sandbox and production). During onboarding, EBANX will configure the supported countries, payment methods, and settlement parameters for your account.

2. Configure Braintree merchant accounts

   Work with your Braintree account manager (AM) or technical account manager (TAM) to set up currency-specific Braintree merchant accounts for the markets you intend to process. If you do not have a dedicated AM or TAM, contact Braintree Support for assistance.

   Share your EBANX Integration Key securely with your Braintree AM or TAM to complete the backend configuration.

3. Configure EBANX-specific requirements

   Review and configure the following EBANX-specific settings:

   • CVV requirements - Recurring transactions and vaulted cards do not include a CVV. EBANX can relax the CVV requirement, but this must be configured manually and can affect approval rates.
   • Refunds - Configure EBANX to send synchronous responses for refunds. Without this configuration, all refunds return as FAILED or SETTLEMENT_DECLINED.
   • Debit cards - To use debit cards, enable the debit cards option in the EBANX dashboard.
   • Dual-step transactions - To perform authorize-then-capture flows, work with EBANX to enable this setting.

4. Create customers and vault payment methods

   Customer creation is mandatory for the EBANX integration. When creating a customer, firstName, lastName, and email are required — not providing these will result in PROCESSOR_DECLINED for all transactions.

   For countries that require a tax identifier (Brazil, Argentina, Paraguay, Uruguay), add taxIdentifiers to the customer record or include them on each transaction.

5. Integrate Braintree on your client and server

   Use the standard Braintree SDK or GraphQL API to accept payments. No EBANX-specific code is needed on the merchant side.

   For card payments, follow the standard Braintree card integration using Drop-in UI, Hosted Fields, or the server-side Transactions API.

6. Configure webhooks

   Set up Braintree webhooks to receive asynchronous notifications about transaction status changes.

   Follow the Braintree Webhooks guide to configure your webhook endpoint.

7. Congratulations!

   Your Braintree integration is now configured to process payments through EBANX. Use the testing section below to validate your setup before going live.

Warning

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

Limitations

• No direct EBANX API access - Merchants interact exclusively with the Braintree API. EBANX-specific features not exposed through Braintree (such as EBANX Payment Page or EBANX.js) are not available.
• Card-only - This integration supports credit and debit cards only. Other EBANX-supported methods (such as Pix, Boleto, or OXXO) are not available through the Braintree Payment Orchestration integration.
• Timeout - The maximum processing timeout for transactions routed through Braintree to EBANX is 27 seconds.
• No partial void - Partial voids are not supported. Use refund instead for settled transactions.
• No capture greater than authorized amount - The captured amount cannot exceed the originally authorized amount.
• Dynamic descriptors - Not supported in Chile or Mexico.

Testing

Use the Braintree sandbox environment to test card transactions. Configure the EBANX gateway using your EBANX Sandbox Integration Key.

Braintree provides test card numbers that simulate successful and declined transactions. Test cards are remapped in the sandbox environment.

Going live

Before going live, verify the following:

• EBANX has confirmed your merchant account is active for production.
• Your Braintree account is configured for production with EBANX processing enabled.
• You have successfully processed test transactions in the Braintree sandbox.
• Webhook endpoints are configured and responding correctly to transaction status events.
• Error handling is implemented for declined transactions and timeouts.
• Tax identifiers are correctly configured for countries that require them (BR, AR, PY, UY).

Troubleshooting

Transactions are being declined

Verify that the card's issuing country is in a supported EBANX region. Check the Braintree transaction response for the specific decline reason and refer to the EBANX error codes for details.

PROCESSOR_DECLINED on all transactions for a customer

Ensure that the customer record includes firstName, lastName, and email. Missing name or email causes all transactions to be declined.

Tax identifier errors (error code 2033)

Brazil, Argentina, Paraguay, and Uruguay require the taxIdentifier field. If not provided, Braintree returns error code 2033 with message "Inconsistent Data." Add the tax identifier to the customer record or include it on each transaction.

Timeout errors

The maximum timeout for EBANX-processed transactions through Braintree is 27 seconds. If you experience frequent timeouts, contact EBANX support to investigate processing delays.

Refunds returning as FAILED

Ensure EBANX is configured to send synchronous responses for refunds. Without this configuration, all refunds return as FAILED or SETTLEMENT_DECLINED. Contact EBANX to enable synchronous refund responses.

Resources

Sample Cards

Click here to view mock card data to validate your payment integration.

Click to explorechevron_right

API Reference

Click here to access detailed API documentation to integrate efficiently.

Click to explorechevron_right

Mock Customer Data

Click here to view mock customer data for testing and validating user flows.

Click to explorechevron_right

Error Codes

Click here to review common error codes to troubleshoot and resolve issues quickly.

Click to explorechevron_right

Still need help?

We hope this article was helpful. If you still have questions, you can explore the following options:

• Merchant support: Contact our support team at sales.engineering@ebanx.com for assistance.
• Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.