dLocal | Primer

dLocal powers local payments in emerging markets, connecting global merchants with consumers across Africa, Asia, Latin America and the Middle East. Through Primer you can process cards, digital wallets and a wide range of local payment methods on a single dLocal connection.

At a glance

Supported payment methods

Payment method	Payment method type	Integration guide
Card	`PAYMENT_CARD`	Card
Apple Pay	`APPLE_PAY`	Apple Pay
Google Pay	`GOOGLE_PAY`	Google Pay
Boleto	`DLOCAL_BOLETO`	Boleto
Mercado Pago	`DLOCAL_MERCADO_PAGO`	Mercado Pago
NuPay	`DLOCAL_NUPAY`	NuPay
OXXO	`DLOCAL_OXXO`	OXXO
PicPay	`DLOCAL_PICPAY`	PicPay
Pix	`DLOCAL_PIX`	Pix
Pix Automático	`DLOCAL_PIX_AUTOMATICO`	Pix Automático

Supported capabilities

Capability	Card	Apple Pay and Google Pay	Local payment methods
Authorization and capture	Yes	Yes	Yes
Partial capture	Yes	Yes	Yes
Authorization adjustment	No	No	No
Refund	Yes	Yes	Yes
Partial refund	Yes	Yes	Yes
Multiple refunds	Yes	Yes	Yes
Recurring and merchant-initiated payments	Yes	Yes	Pix Automático only
Network tokens	No	No	No

Some capabilities must be enabled on your dLocal account. Contact dLocal to confirm which features are available to you.

3D Secure

Primer performs 3D Secure authentication using the Perform 3DS action and passes the authentication result to dLocal as third party (MPI) data. You do not need to run 3D Secure on the dLocal side.

Get started with dLocal

Before you begin

If this is your first connection, make sure to follow the Get started guide to begin processing payments with Primer. You need an active dLocal merchant account with access to the dLocal Merchant Dashboard. Before you connect, ask your dLocal contact to:

Enable allow_network_tx_reference on your account if you intend to process card merchant-initiated payments.
Enable the local payment methods you plan to offer, such as Pix and Pix Automático.

Credentials

Field	Where to find it
X_Login	dLocal Merchant Dashboard, under Settings > Integration, in the Production credentials section.
X_Trans_Key	dLocal Merchant Dashboard, under Settings > Integration, in the Production credentials section.
Secret Key	Request it from dLocal under Settings > Integration. It is not shown by default.

Configure in the Dashboard

Add dLocal to your Dashboard

Go to Integrations, select New integration, search for dLocal and enter your credentials.

Configure webhooks in dLocal

Log in to the dLocal dashboard and go to integration settings. Under Endpoint configuration, paste your Primer callback URL into both the Refunds URL field and the Payins notification URL field, then select Save changes.The Payins notification URL is required for Pix Automático.

Activate the payment methods on the Checkout

Go to Checkout and activate the dLocal payment methods you want to offer.

Route payments with Workflows

In Workflows, select dLocal in the Authorize payment action.

Prepare the client session

dLocal needs payer identity and country information that it cannot derive from the payment method alone. Provide these fields in the client session.

Parameter	Required	Description
customer.nationalDocumentId	Yes	The payer’s tax or national identity document number, for example a CPF or CNPJ in Brazil. dLocal rejects payments without it.
customer.emailAddress	Yes	Sent to dLocal as the payer email.
order.countryCode	Yes	Determines which dLocal country entity processes the payment. If it is absent, Primer falls back to the billing address country code.
customer.billingAddress	Recommended	Street, city, state and postal code are passed to dLocal as the payer address.

Saved cards and merchant-initiated payments

dLocal supports recurring and merchant-initiated card payments using the network transaction reference from the initial customer-initiated payment. See recurring payments for the general Primer flow. Ask your dLocal contact to enable allow_network_tx_reference on your account before you process merchant-initiated payments. Without it, dLocal rejects the subsequent transactions. Pix Automático is the only local payment method on dLocal that supports recurring payments.

Considerations

National document ID is mandatory. dLocal requires customer.nationalDocumentId on card payments. Collect it in your checkout, or payments fail before they reach the issuer.
Merchant-initiated payments need an account flag. Card MITs only work once dLocal enables allow_network_tx_reference.
Local payment methods are asynchronous. Most dLocal local payment methods settle after the customer completes an out-of-band action, so the payment reaches a final status through a webhook rather than in the authorization response. Fulfil orders only on a final status.
Local payment methods need to be enabled by dLocal. Pix, Pix Automático and the other local methods are not active by default. Engage your dLocal contact before you activate them on the Checkout.

Test in sandbox

Connect your dLocal test account to your Primer Sandbox environment. Toggle Test mode in the dLocal dashboard before you copy your credentials, because sandbox and production credentials are different.

Card
Apple Pay
Google Pay
Merchant-initiated

Test a 3DS challenge. Primer performs the authentication, so use Primer’s 3D Secure test cards and enter the one time passcode when the challenge appears.

Network	Card number	OTP
Visa	`4916 9940 6425 2017`	`1234`
Mastercard	`5306 8899 4283 3340`	`1234`

Enter 1234 to pass the challenge or 1111 to fail it. See testing 3D Secure for the full list, including the cards to use on iOS and Android.Test without a 3DS challenge. Use the Perform 3DS action without a mandated challenge indicator. In Primer Sandbox a mandated challenge always produces a challenge, whatever card you use.Send customer.nationalDocumentId in the client session on every card test. dLocal rejects card payments without it.Test a saved card. Make a payment that saves the card, then pay again with the saved payment method.

Ask dLocal to enable allow_network_tx_reference on your test account before you start. Without it, dLocal rejects merchant-initiated payments.Make a customer-initiated payment that saves the card, then create a merchant-initiated payment with the saved payment method. Primer sends the network transaction reference from the first payment on each subsequent one.Pix Automático is the only local payment method on dLocal that supports recurring payments. Test it from the Pix Automático page.

How sandbox differs from production

Behaviour	What to expect in sandbox
Card number substitution	Primer replaces test card numbers before sending them to dLocal, so the card recorded on the dLocal side can differ in network and last four digits from the one you entered. Primer records the card you entered against the payment. Real cards are never substituted in production.
3D Secure challenges	A mandated challenge indicator always produces a challenge, whatever card you use. Test frictionless flows with the Perform 3DS action without a mandated challenge.
Local payment methods	Local payment methods complete through a simulated out-of-band action rather than a real one, so the timing of the final status does not reflect production.

Troubleshooting

Primer maps dLocal’s card rejection codes to its own decline reasons, so you normally work with Primer decline codes rather than dLocal’s. See decline codes for the full list.

Go live

Before switching to production, confirm that:

Your dLocal production account is active for the payment methods you want to offer.
You have added dLocal in your Primer production environment using your production credentials.
Your production webhook endpoints are configured in the dLocal dashboard, covering both the Refunds URL and the Payins notification URL.
dLocal has enabled allow_network_tx_reference on your production account if you process merchant-initiated payments.
You handle the PAYMENT.STATUS webhook and fulfil orders only on a final status.