dLocal

dLocal Limited is a Uruguayan financial technology company. It provides cross-border payments connecting global merchants to emerging markets, focusing on building out the infrastructure for financial services in Latin America and expanding to other global markets.

Chargebee integrates directly with dLocal to process payments. This guide covers the direct integration.

For help with an existing dLocal connection or migration to the direct integration, contact Chargebee Support.

Supported payment methods

Chargebee supports these local payment methods through dLocal. Configure dLocal first, then turn on the method in Chargebee.

• GCash — Philippines (PHP), recurring
• Mercado Pago — Brazil, Chile, Mexico, and Colombia, recurring
• Nequi QR — Colombia (COP), one-time
• NuPay — Brazil (BRL), recurring
• OVO — Indonesia (IDR), recurring
• PicPay — Brazil (BRL), recurring
• Pix — Brazil
• Thai QR — Thailand (THB), one-time

Integration options

You can integrate dLocal using the following:

The direct dLocal integration supports 3D Secure (3DS) authentication for card payments. With Chargebee Hosted Pages, Chargebee redirects the customer to complete the challenge when dLocal requires authentication.

For custom Chargebee.js and Chargebee API integrations, follow the 3DS Helper flow: create a Payment Intent on your server, complete authentication with the 3DS Helper, and use the authorized Payment Intent to add a payment source or create a subscription.

Supported countries, currencies, and documents

In the table below, you can find the country code and currency of the countries currently covered by dLocal. You can also find the document used in each country, which needs to be entered in the Payer Object.

Multiple countries/currencies support in dLocal

The support for countries and currencies in dLocal can be described in two scenarios:

Scenario 1: Collecting cross-border payments without a local entity.

In this scenario, dLocal facilitates local payment collection across various markets and remits funds in either USD or EUR. You will be provided with a single dLocal account featuring a balance in either USD or EUR. To configure this in Chargebee, set up one dLocal account and designate your merchant country code as the base country code (for example, US or EU). Use smart routing to direct payments to this dLocal account for your desired combinations.

Scenario 2: Managing multiple local entities for local currency transactions.

If you operate multiple local entities and aim to charge your customers locally while accepting payments in their respective currencies, you must establish separate dLocal accounts for each country, each designated with its country code. Consider the following example for clarity:

Example: You operate local entities in Argentina and Brazil, intending to collect payments and settle transactions in the local currencies of each country. Consequently, you must set up two distinct dLocal accounts (one for Argentina and one for Brazil), each equipped with unique credentials. Configure these accounts separately in Chargebee, ensuring you specify your respective merchant country codes during setup. Additionally, configure smart routing in Chargebee to direct payments from specific currencies to the corresponding dLocal account. This configuration is vital; failure to do so may result in payment failures or misrouting of funds.

Retrieving key information from dLocal

Retrieve the x_login, x_trans_key, and Secret key from dLocal before connecting your gateway in Chargebee. You also need the merchant country associated with your dLocal account.

1. Sign in to your dLocal account. If you don't have an account, you can create one here.

2. Go to Settings from the left navigation menu.

3. Select the INTEGRATION tab.

4. Copy the x_login, x_trans_key, and Secret key provided under the Sandbox credentials for later use when configuring dLocal in Chargebee.

   

Configure dLocal in your Chargebee Site

Follow these steps to enable and configure dLocal in Chargebee:

1. Log into your Chargebee site.

2. Go to Settings > Configure Chargebee > Payment Gateways.

3. Click Add Gateway and select dLocal.

   

4. Enter x_login in Login, x_trans_key in Transaction Key, and Secret key in Secret Key. Select the country associated with your dLocal account from Merchant Country Code.

5. Click Connect.

   

6. The gateway is configured successfully. You will be redirected to the Configure dLocal page.

7. On the Configure dLocal page, click Manage for Cards.

8. Enable the following: a. Card verification: Chargebee validates the card with a test authorization for a micro amount, which is refunded immediately. Cards cannot be added if this authorization fails. b. Always retain card information in dLocal when customer updates it: Enabling this option stores the updated card information in dLocal rather than the default gateway.

9. Click Save.

   

10. Click Apply.

    

Prerequisites

1. Mandatory fields: a. Document ID: Mandatory for most Latin American countries. If you are using Chargebee hosted pages, Chargebee will automatically show this when dLocal is applicable. No need to make additional configurations. b. Customer name: This needs to be collected either at the card level, billing address level, or in additional_info. If you are using Chargebee hosted pages, make these fields mandatory in the checkout settings. c. Customer email: This needs to be collected either at the customer level or billing address level. If you are using Chargebee hosted pages, make the email field mandatory in the checkout settings.

   

2. If you are integrating using Chargebee APIs, you can send all the required information in the "additional info" area within the payment section of various APIs: {"dLocal": {"document_id": "test", "name": "hello", "email": "test@abc.com"}}

3. Properties that can be set in additional info are document_id, name, email, and merchant_id.

The following example uses the documented Brazil test card and document ID. Replace {site}, {site_api_key}, {customer_id}, and {gateway_account_id} with the values from your Chargebee test site.

For card payments that require 3DS, use the Payment Intent flow instead of calling create_card directly.

curl --location --globoff 'https://{site}.chargebee.com/api/v2/payment_sources/create_card' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--user '{site_api_key}:' \
--data-urlencode 'customer_id={customer_id}' \
--data-urlencode 'card%5Bgateway_account_id%5D={gateway_account_id}' \
--data-urlencode 'card%5Bnumber%5D=4111111111111111' \
--data-urlencode 'card%5Bcvv%5D=123' \
--data-urlencode 'card%5Bexpiry_year%5D=2030' \
--data-urlencode 'card%5Bexpiry_month%5D=03' \
--data-urlencode 'card%5Bfirst_name%5D=Test' \
--data-urlencode 'card%5Blast_name%5D=Customer' \
--data-urlencode 'card%5Bbilling_addr1%5D=Test address' \
--data-urlencode 'card%5Bbilling_addr2%5D=Test street' \
--data-urlencode 'card%5Bbilling_city%5D=Sao Paulo' \
--data-urlencode 'card%5Bbilling_state_code%5D=SP' \
--data-urlencode 'card%5Bbilling_state%5D=Sao Paulo' \
--data-urlencode 'card%5Bbilling_zip%5D=01000000' \
--data-urlencode 'card%5Bbilling_country%5D=BR' \
--data-urlencode 'card%5Badditional_information%5D={"dlocal":{"document_id":"11111111111","name":"Test Customer","email":"test@example.com"}}'

Supported Tokens

This integration supports the following tokens in the mentioned format:

Test Card Details and Document ID

Test Document ID - 11111 11111 1 (Brazil) Test Cards:

1. Visa - 4111 1111 1111 1111 Expiry - 03/30 CVV - 123
2. [Brazil] Elo card - 5066 9911 1111 1118 Expiry - 03/30 CVV - 737
3. [Brazil] Hipercard - 6062 8288 8866 6688 Expiry - 03/30 CVV - 737

Checkout Flow

Checkout of dLocal is a typical card checkout flow as it contains the following steps:

1. Once you initiate checkout, click Proceed to Checkout from the Your Order page to initiate a purchase.

   

2. Enter your email to proceed and click Next.

   

3. Provide your First Name, Last Name, and Email, then click Next.

   

4. Complete your Billing Address and click Next.

   

5. Select Credit Card as the payment method.

   

6. Enter the Card details - Card Number, Expiry Month & Year, CVV, and Document Number based on the billing country chosen in the previous step.

7. Click Next.

   

8. Review your order and click Pay & subscribe. The button also shows the amount due.

   

Statement descriptor

Chargebee supports statement descriptors for dLocal transactions. dLocal enforces a character limit of 22 characters for these descriptors.

Allowed special characters are:

• hyphen (-)
• underscore (_)
• comma (,)
• dot (.)
• space
• forward slash (/)
• ampersand (&)
• asterisk (*)