dLocal Integration Guide

After you complete this integration, you can process card transactions across many markets through dLocal using your existing Braintree integration.

PayPal's partnership with dLocal enables merchants to leverage their existing Braintree integration to process transactions through the PayPal Payment Orchestration platform. This guide helps developers with an existing Braintree integration use PayPal's Payment Orchestration platform to process transactions through dLocal.

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

Features

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

NoteFor information about the availability and requirements of specific features in the various countries in which this integration is supported, 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
Charge (single step)	✅	Authorize and capture in the same call.
Charge (dual step)	✅	Authorization, followed by a separate capture call
Standalone authorization	✅	Capture the authorization within 7 days.
Capture (full)	✅	Capture a previously authorized transaction.
Partial capture	✅	Supported in all countries. To confirm enablement, contact your Braintree account manager (AM) or technical account manager (TAM).
Capture greater than authorized amount	❌
Adjust Authorization API (incremental auth or partial reversal)	❌

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	✅	Refunds cannot exceed the settled amount.
Partial refund	✅	Refunds cannot exceed the settled amount.
Multiple refunds	✅
Blind credits (refunds for transactions that were processed elsewhere)	❌	Refunds must reference the 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	✅	For card brands by country, see the country-specific requirements.
Debit cards	✅	For card brands by country, see the country-specific requirements.
Prepaid cards	⚠️	Supported where the processor supports prepaid cards
PLCCs	❌
Gift cards	❌
Apple Pay	❌
Google Pay	❌
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) and Card Verification Value (CVV) response handling	✅	AVS and CVV results are returned in standard response fields.
Dynamic descriptors	⚠️	Varies by country
Network tokens	✅	Supported in all countries. To enable this feature, contact AM o TAM. For more information, see Network token support.
Level 2, Level 3, or lodging data	❌
3D Secure (3DS)	⚠️	Supported in all countries. Required for all initial transactions in Indonesia and Japan and for debit card transactions in Brazil. For more information, see Country-specific requirements and limitations.

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	✅

Before you begin

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

On Braintree: To process card transactions through dLocal, you need currency-specific Braintree merchant accounts for use in your integration. For help with this setup, contact your AM or TAM.
On dLocal: Each merchant must have an account with dLocal. After you create your dLocal account, work with your AM or TAM to securely share the account's API and integration keys with Braintree. dLocal provides separate API keys for sandbox and production environments. For more information about setting up a dLocal account, see the dLocal API documentation

Note If you do not have a dedicated AM or TAM for Braintree, contact [email protected] for support.

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

Network tokens: To enable Braintree-managed network tokens for your account, contact your AM or integration engineer. Merchant-provided ("Bring Your Own") network tokens must also be enabled through your dLocal account. For more information, see Network tokens.
3DS requirements: In Indonesia and Japan, 3DS is required for all initial transactions. In Brazil, 3DS is required for debit card transactions. To enable 3DS for additional markets, contact your Braintree AM or TAM.
Tax identifiers: Argentina, Brazil, and Japan require a taxIdentifiers value for every transaction. For more information, see Tax identifiers.
Decimal currency support: Some countries do not support decimal amounts. For those countries, the amount field must be an integer. For more information, see the Decimals column in the country-specific requirements table.
Installment limits: Braintree supports a maximum of 48 installments. dLocal enforces country-level limits: Mexico supports only 3, 6, 9, 12, or 18 installments; all other countries support 1–12 installments.

Transactions

After you complete 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 dLocal 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 dLocal transactions require and how they map to dLocal's API. Add these values to your existing Braintree transaction creation call.

Creating a dLocal transaction requires the following fields.

Field	Location	How to provide	Notes
`amount`	Transaction	Include in transaction	The transaction amount must be an integer in countries where decimals are not supported. For more information, see the Decimals column in the country-specific requirements table.
`customer.firstName`	Customer	Create the Braintree customer first. If you cannot add this value, contact your Braintree AM or TAM.
`customer.lastName`	Customer	Create the Braintree customer first. If you cannot add this value, contact your Braintree AM or TAM.
`customer.email`	Customer	Create the Braintree customer first. If you cannot add this value, 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, contact your Braintree AM or TAM.	Required in Argentina, Brazil, and Japan. For more information, see Tax identifiers.
`card.cardholderName`	Payment method	Include during tokenization	Name as it appears on the card

Customer creation

Customer creation is a mandatory step for the dLocal integration, and you can use either the Braintree SDK or GraphQL API to do it. When you create a customer, dLocal requires the name (first and last) and email, even though they are not required fields in Braintree. If you do not provide a first or last name, or you do not provide an email address, all transactions that customer creates could fail (PROCESSOR_DECLINED).

Vaulted payment methods

Vaulting a tokenized payment method creates a reusable token that can be authorized or charged multiple times. A tokenized payment method can also be vaulted during authorization. For more information, see the vault guide (SDK) or the vault guide (GraphQL).

Tax identifiers

Argentina, Brazil, and Japan require the taxIdentifiers 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 automatically.
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.

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

Installments

Braintree supports a maximum of 48 installments. dLocal enforces country-level limits:

Merchants in Mexico can offer only 3, 6, 9, 12, or 18 installments.
All other countries can offer 1–12 installments.

Pass the desired installment count using the installmentCount field on the transaction.

Transaction object support

Not all Braintree transaction operations are available with dLocal. The following table lists the transaction request operations that this integration supports.

Legend: ✅ Supported | ❌ Not supported

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	❌

Transaction status mapping

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

Operation	dLocal response	Braintree transaction status	Additional information
Authorize	Successful	`AUTHORIZED`	Dual-step transaction. Capture payment within 7 days.
Authorize	Declined	`PROCESSOR_DECLINED`	Hard decline from acquirer
Authorize	API error or unreachable	`FAILED`	You can configure a retry option on Braintree or implement your own retry logic.
Charge	Successful	`SETTLED`	You can configure this as a single step or a dual step.
Charge	Declined	`PROCESSOR_DECLINED`	Hard decline from acquirer
Charge	API error or unreachable	`FAILED`	In this rare event, Braintree reconciles the transaction. For more information, see FAILED status during charge.
Capture	Successful	`SETTLED`
Capture	Declined	`SETTLEMENT_DECLINED`	Although rare, this can be more common if the authorization has expired.
Capture	API error or unreachable	`SETTLING`	In this rare event, Braintree reconciles the transaction. Do not ship goods or provide service until the status is `SETTLED`. For more information, see SETTLING status with HTTP errors.
Refund	Successful	`SETTLED`
Refund	Declined	`SETTLEMENT_DECLINED`	This can occur if the transaction is disputed or if a refund is attempted after the refund window.
Refund	API error or unreachable	`SETTLING`	In this rare event, Braintree reconciles the transaction. For more information, see SETTLING status with HTTP errors.
Void	Any	`VOIDED`
VerifyCard	Successful	`VERIFIED`
VerifyCard	Declined	`PROCESSOR_DECLINED`
VerifyCard	API error or unreachable	`FAILED`

SETTLING status with HTTP errors

In rare cases when dLocal 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 if dLocal is unavailable.

Reconciliation logic: Braintree queries dLocal for transaction information periodically. If dLocal confirms the transaction, Braintree retries the operation. If dLocal declines, Braintree marks the transaction as SETTLEMENT_DECLINED.

Possible outcomes:

If dLocal approves, the status changes to SETTLED.
If dLocal declines, the status changes to SETTLEMENT_DECLINED.

FAILED status during charge

If Braintree receives no inline response from dLocal 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 original transaction remains SETTLED. This operation can be retried. For more information, see Retries.

Retries

Follow these guidelines when handling retries for dLocal 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 level. For help with configuration, contact your TAM.

Network tokens

Network tokens replace raw card numbers with a payment-method-specific token, which can improve authorization rates and reduce fraud. dLocal supports network tokens, and 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 integration engineer. 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 also enable third-party network tokens on the merchant's account through dLocal. To coordinate enablement, contact your Braintree AM or TAM.

Response codes

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

To find the details for the dLocal response message, use one 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. For more information about the approval and decline outcomes (TransactionSettlementProcessorResponse and TransactionAuthorizationProcessorResponse), see the GraphQL APi refeference.

Test cards

Braintree provides a set of test card numbers for sandbox testing. Use these test cards to validate your integration in the sandbox environment before going live. With the dLocal integration, Braintree test card numbers are automatically mapped to dLocal test card numbers for end-to-end testing.

Note

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 dLocal directly without modification.

Credit cards: Success

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

Card brand	Braintree test number	Automatically mapped?
Mastercard	`5555555555554444`	✅
Visa	`4012888888881881`	✅

Credit cards: Failure

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

Scenario	Braintree test number	Automatically mapped?	Braintree result
Insufficient funds or decline	`4000111111111115`	✅	`PROCESSOR_DECLINED`
Invalid data	`5105105105105100`	✅	`PROCESSOR_DECLINED`

Country-specific requirements and limitations

This integration supports transactions in the following countries: Argentina, Bolivia, Brazil, Chile, Colombia, Costa Rica, Dominican Republic, Ecuador, El Salvador, Guatemala, Honduras, Indonesia, Japan, Malaysia, Mexico, Nicaragua, Panama, Paraguay, Peru, Philippines, Thailand, Uruguay, and Vietnam. Some countries have different requirements for card brands, 3DS, tax identifiers, or decimal handling. The following table describes these requirements and limitations by country.

Country	Credit cards	Debit cards	3DS	Tax ID required	Decimals supported	Additional notes
Argentina	Mastercard, Visa, American Express, Agencard, Cabal, Maestro, Naranja, Nativa, Tarjeta Shopping	Mastercard, Visa, Cabal	✅	✅	❌	`amount` must be an integer.
Bolivia	Mastercard, Visa	Mastercard, Visa	✅	❌	❌	`amount` must be an integer.
Brazil	Mastercard, Visa, Discover, American Express, Elo, JCB, Aura, Hipercard, Mercado Libre Card	Mastercard, Visa, Maestro, Elo	Required for debit transactions	✅	✅
Chile	Mastercard, Visa, Magna, CMR Falabella, Líder Mastercard, Diners Club Chile	Mastercard, Visa, American Express, RedCompra	✅	❌	❌	`amount` must be an integer.
Colombia	Mastercard, Visa, American Express, Codensa, Diners Club	Mastercard, Visa	✅	❌	❌	`amount` must be an integer.
Costa Rica	Mastercard, Visa, Discover, American Express, JCB, Diners	Mastercard, Visa	✅	❌	❌	`amount` must be an integer.
Dominican Republic	Mastercard, Visa, American Express	Mastercard, Visa	✅	❌	❌	`amount` must be an integer.
Ecuador	Mastercard, Visa, Alia, Diners, American Express	Mastercard, Visa	✅	❌	✅
El Salvador	Mastercard, Visa, Discover, American Express, JCB, Diners	Mastercard, Visa	✅	❌	✅
Guatemala	Mastercard, Visa, JCB, American Express, Discover, Diners	Mastercard, Visa	✅	❌	❌	`amount` must be an integer.
Honduras	Mastercard, Visa, JCB, American Express, Discover, Diners	Mastercard, Visa	✅	❌	❌	`amount` must be an integer.
Indonesia	Mastercard, Visa, JCB	Mastercard, Visa	Required for all initial transactions	❌	✅
Japan	Mastercard, Visa, Diners, American Express, JCB	Mastercard, Visa	Required for all initial transactions	✅	✅
Malaysia	Mastercard, Visa, Union Pay	Mastercard, Visa	✅	❌	✅
Mexico	Mastercard, Visa, American Express, Carnet	Mastercard, Visa, Carnet	✅	❌	✅	Installments limited to 3, 6, 9, 12, and 18.
Nicaragua	Mastercard, Visa, American Express, Diners, Discover, JCB	Mastercard, Visa	✅	❌	❌	`amount` must be an integer.
Panama	Mastercard, Visa, American Express, Diners, Discover, JCB	Mastercard, Visa, Clave	✅	❌	✅
Paraguay	Mastercard, Visa, American Express	Mastercard, Visa	✅	❌	❌	`amount` must be an integer.
Peru	Mastercard, Visa, American Express, Diners	Mastercard, Visa	✅	❌	❌	`amount` must be an integer.
Philippines	Mastercard, Visa	Mastercard, Visa	✅	❌	✅
Thailand	Mastercard, Visa, Union Pay, Diners, JCB	Mastercard, Visa	✅	❌	❌	`amount` must be an integer.
Uruguay	Mastercard, Visa, American Express, Lider, OCA	Mastercard, Visa	✅	❌	❌	`amount` must be an integer.
Vietnam	Mastercard, Visa, JCB, Napas	Mastercard, Visa	✅	❌	✅

Next steps

After you complete your integration, use the following resources to test and go live.

Test your integration using the sandbox test cards.
Review the Braintree testing guide for additional sandbox options.
Contact your Braintree AM or TAM when you're ready to go live.

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