> ## Documentation Index > Fetch the complete documentation index at: https://primer.io/docs/llms.txt > Use this file to discover all available pages before exploring further. # dLocal > Process card, wallet and local payment method payments in emerging markets through dLocal. 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](https://primer.io/docs/connections/payment-methods/card/overview.md) | | Apple Pay | `APPLE_PAY` | [Apple Pay](https://primer.io/docs/connections/payment-methods/apple-pay/overview.md) | | Google Pay | `GOOGLE_PAY` | [Google Pay](https://primer.io/docs/connections/payment-methods/google-pay/overview.md) | | Boleto | `DLOCAL_BOLETO` | [Boleto](https://primer.io/docs/connections/payment-methods/boleto/dlocal.md) | | Mercado Pago | `DLOCAL_MERCADO_PAGO` | [Mercado Pago](https://primer.io/docs/connections/payment-methods/mercado-pago/dlocal.md) | | NuPay | `DLOCAL_NUPAY` | [NuPay](https://primer.io/docs/connections/payment-methods/nupay/dlocal.md) | | OXXO | `DLOCAL_OXXO` | [OXXO](https://primer.io/docs/connections/payment-methods/oxxo/dlocal.md) | | PicPay | `DLOCAL_PICPAY` | [PicPay](https://primer.io/docs/connections/payment-methods/picpay/dlocal.md) | | Pix | `DLOCAL_PIX` | [Pix](https://primer.io/docs/connections/payment-methods/pix/dlocal.md) | | Pix Automático | `DLOCAL_PIX_AUTOMATICO` | [Pix Automático](https://primer.io/docs/connections/payment-methods/pix-automatico/dlocal.md) | ### 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
> [!NOTE] > > 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](https://primer.io/docs/workflows/apps/native-apps/primer-payments-app/perform-3ds-action.md) 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](https://primer.io/docs/get-started/overview.md) to begin processing payments with Primer. You need an active dLocal merchant account with access to the [dLocal Merchant Dashboard](https://dashboard.dlocal.com/login). 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 **1. Add dLocal to your Dashboard** Go to [Integrations](https://dashboard.primer.io/integrations), select **New integration**, search for dLocal and enter your credentials. **2. Configure webhooks in dLocal** Log in to the dLocal dashboard and go to [integration settings](https://dashboard.dlocal.com/settings/integration). 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. **3. Activate the payment methods on the Checkout** Go to [Checkout](https://dashboard.primer.io/checkout) and activate the dLocal payment methods you want to offer. **4. Route payments with Workflows** In [Workflows](https://primer.io/docs/workflows/overview.md), 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](https://primer.io/docs/api-reference/v2.4/api-reference/client-session-api/create-a-client-session.md#body-customer-national-document-id) | 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](https://primer.io/docs/api-reference/v2.4/api-reference/client-session-api/create-a-client-session.md#body-customer-email-address) | Yes | Sent to dLocal as the payer email. | | [order.countryCode](https://primer.io/docs/api-reference/v2.4/api-reference/client-session-api/create-a-client-session.md#body-order-country-code) | Yes | Determines which dLocal country entity processes the payment. If it is absent, Primer falls back to the billing address country code. | | [customer.billingAddress](https://primer.io/docs/api-reference/v2.4/api-reference/client-session-api/create-a-client-session.md#body-customer-billing-address) | 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](https://primer.io/docs/get-started/recurring-payments.md) 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. > [tab] Card > > **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](https://primer.io/docs/testing/3d-secure.md) 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. > [tab] Apple Pay > > Apple Pay payments do not require a 3DS challenge. The wallet supplies the cryptogram, which Primer passes to dLocal. See [Apple Pay](https://primer.io/docs/connections/payment-methods/apple-pay/overview.md) for how to set up and test Apple Pay, including recurring payments. > [tab] Google Pay > > **Test Google Pay on Android.** Use an Android device signed in to a Google account enrolled in the Google Pay test card suite. These sandbox payments do not require a 3D Secure challenge. > > dLocal processes Google Pay as PAN only credentials rather than network tokens, and supports recurring payments on them. > [tab] Merchant-initiated > > 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](https://primer.io/docs/connections/payment-methods/pix-automatico/dlocal.md) 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](https://primer.io/docs/concepts/decline-codes/overview.md) for the full list. ## Go live Before switching to production, confirm that: 1. Your dLocal production account is active for the payment methods you want to offer. 2. You have added dLocal in your Primer **production** environment using your **production** credentials. 3. Your production webhook endpoints are configured in the dLocal dashboard, covering both the Refunds URL and the Payins notification URL. 4. dLocal has enabled `allow_network_tx_reference` on your production account if you process merchant-initiated payments. 5. You handle the [PAYMENT.STATUS webhook](https://primer.io/docs/api-reference/endpoints/v2.4/payment-webhooks/payment-status-update.md) and fulfil orders only on a final status. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.