dLocal
Last updated: April 29, 2022
Our partnership with dLocal allows you to accept payments from customers across Latin America using both international and local card schemes.
Information
To start accepting payments via dLocal, please contact your Account Manager.
Warning
Local card schemes are not supported by our Frames solution. Merchants must be PCI-SAQ D compliant to use them, and must provide the card information directly in the payment request.
A dLocal payment request uses the same endpoint as a standard card payment, and is structured similarly, but there are a few important differences.
For Latin American countries, merchants are required to provide their customers' identification numbers along with all authorization requests. Depending on the customer's country of residence, a differing type of identification number might be required, so a customer-specific country field needs to be sent in the authorization request.
Also, the billing country associated with the payer's data may not be the same as the customer's country of residence (if, for instance, the payer is different from the customer). For this reason, a specific field for the merchant customer's country of residence needs to be specified explicitly.
Use the details below to set up your request.
post
https://api.checkout.com/payments
Note
When testing dLocal payment methods in sandbox, make sure you include the name and email fields in the processing object. See them in the processing object in the following example.
Use the approved field to check whether or not the authorization was successful ("approved": true). If your authorization was not successful, it's possible the payment used an invalid/expired card, or a valid card with an insufficient available balance.
If you received a 202 response, the payment requires a redirect. For example, if the payment is 3D Secure.
Make a payment request using the same endpoint and parameters as above, with two differences:
- Set
source.typetodlocal. - Latin American card numbers (
source.number) are between 12-19 characters in length.
Card number validation
Because Latin American card numbers vary in length and structure, they cannot be validated with a Luhn check. You should disable this check when making a dlocal payment request to avoid the card number being flagged as invalid to the customer and to prevent the request from being rejected.
Information
Paying in installments works with both international and local card schemes, provided the card was issued by a local bank.
Paying in installments is a popular way of paying by credit card in Latin America. It allows customers to receive the goods or services straight away, but spread the cost of the purchase over several months.
When a customer pays via an installment plan, the purchase is split into multiple smaller payments, or installments. The first payment is charged to the customer's card immediately, and subsequent installments are charged every 30 days until their purchase has been fully paid.
To make an installment payment, include the processing.dlocal.installments object in your request, and set the number of payments to be made each year with the processing.dlocal.installments.count field.
The number of payments a customer can make per year in an installment plan varies by country:
- In Argentina, Brazil, Chile, Colombia and Peru, the customer can make 1 to 12 payments a year.
- In Mexico, the customer can make either 3, 6, 9 or 12 payments a year.
The customer will be charged a fee by their bank for making payments via an installment plan, and you must make these fees clear to your customers.
These fees change frequently, so you should request the latest fee tables from dLocal regularly to ensure your customers are kept up to date.
Displaying installment fees
Use the fee tables from dLocal to build a user interface that shows the customer:
- The fees per installment payment, using the formula
(order amount + order amount * interest) / number of installments. - The total cost of the plan, including the fees, using the formula
purchase amount + (purchase amount * interest fee).
Note
When accepting payments in installments in Latin American countries, you are legally required to show the customer the fees for each individual installment as well as the total cost of the plan.