> ## 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. # Mercado Pago via dLocal > Let customers securely make payments using Mercado Pago via dLocal on your website or mobile application. Mercado Pago via dLocal redirects the customer to Mercado Pago, where they approve the payment using their wallet balance, a stored card, or Mercado Crédito. Mercado Pago is the payments arm of Mercado Libre and one of the most widely held wallets in Latin America. Through dLocal it is available in six markets, each with its own local currency. | One off payment | Refunds | Recurring | Cancel | | - | - | - | - | | ✓ | ✓ | x | x | > [!NOTE] > > Mercado Pago via dLocal is asynchronous. dLocal confirms the payment by webhook once the customer approves it in Mercado Pago, so fulfil orders only on a final status. Full and partial refunds are supported, and a payment can be refunded more than once. ### Supported markets
Market `order.countryCode` `currencyCode`
Argentina `AR` `ARS`
Brazil `BR` `BRL`
Chile `CL` `CLP`
Colombia `CO` `COP`
Mexico `MX` `MXN`
Uruguay `UY` `UYU`
> [!WARNING] > > To route payments in Chile in `CLP`, you must request special currency access from Primer. Raise a ticket on the [Support Portal](https://portal.support.primer.io/servicedesk/customer/portal/11) before you go live in Chile — without it, CLP payments cannot be processed. ## Get started with Mercado Pago via dLocal ### Before you begin If this is your first payment method, make sure to follow the [Get started guide](https://primer.io/docs/get-started/overview.md) to begin processing payments with Primer. Mercado Pago is not active on a dLocal account by default. Ask your dLocal contact to enable it before you activate it on the Checkout. ### Configure in the Dashboard 1. **Add Mercado Pago via dLocal payment method to your Dashboard** Go to the [integrations](https://dashboard.primer.io/integrations) section of the Dashboard, click on the 'New Integration' button and search for dLocal. Follow the instructions to connect your dLocal account to your Primer Dashboard. 2. **Activate Mercado Pago via dLocal on the Checkout** Go to the [Checkout](https://dashboard.primer.io/checkout) section of the Dashboard and activate the Mercado Pago via dLocal payment method. Add a display condition so it only appears where it can be paid, restrict it to the currencies of the markets you support. 3. **Configure a Workflow to process payments made with Mercado Pago via dLocal** Go to [Workflows](https://primer.io/docs/workflows), and ensure there is a workflow with the **Authorization** action configured to process APMs. ### Prepare the client session dLocal leverages the following parameters to process a payment. Pass them when creating the client session. | Parameter Name | Required | Description | | - | - | - | | [orderId](https://primer.io/docs/api-reference/v2.4/api-reference/client-session-api/create-a-client-session.md#body-order-id) | ✓ | A unique identifier for the order. Maximum 255 characters. | | [currencyCode](https://primer.io/docs/api-reference/v2.4/api-reference/client-session-api/create-a-client-session.md#body-currency-code) | ✓ | The three-letter currency code in ISO 4217 format. Must be the local currency of the market you are processing in — see [Supported markets](#supported-markets). | | [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) | ✓ | The payer's tax or national identity document, in the format used by the market you are processing in. dLocal rejects payments without it. | | [customer.emailAddress](https://primer.io/docs/api-reference/v2.4/api-reference/payments-api/create-a-payment.md#body-customer-email-address) | ✓ | Sent to dLocal as the payer email. | | [customer.firstName](https://primer.io/docs/api-reference/v2.4/api-reference/payments-api/create-a-payment.md#body-customer-first-name) | ✓ | Combined with the last name and sent to dLocal as the payer name. | | [customer.lastName](https://primer.io/docs/api-reference/v2.4/api-reference/payments-api/create-a-payment.md#body-customer-last-name) | ✓ | Combined with the first name and sent to dLocal as the payer name. | | [order.countryCode](https://primer.io/docs/api-reference/v2.4/api-reference/client-session-api/create-a-client-session.md#body-order-country-code) | ✓ | Determines which dLocal country entity processes the payment. Must be one of the [supported markets](#supported-markets). 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/payments-api/create-a-payment.md#body-customer-billing-address) | Recommended | Street, house number, city, state and postal code are passed to dLocal as the payer address. | ## Prepare the SDK for payments > [tab] Web > > > [!NOTE] > > > > Use the payment method type `DLOCAL_MERCADO_PAGO` wherever the code below references `YOUR_PAYMENT_METHOD_TYPE`. > > > [tab] Primer Checkout (recommended) > > > > Primer Checkout is our latest web SDK, built around declarative web components. Once Mercado Pago via dLocal is enabled in your [Dashboard](https://dashboard.primer.io/checkout), the default `` layout renders it automatically alongside your other methods — no payment-method-specific markup is required. > > > > ```html theme={"dark"} > > > > ``` > > > > #### Custom layouts > > > > Only reach for [primer-payment-method](https://primer.io/docs/sdk/primer-checkout-web/components/primer-payment-method.md) if you're building a custom layout and need to place Mercado Pago via dLocal at a specific position. The element only renders when the type is enabled in your Dashboard and returned by the server for this checkout. > > > > ```html theme={"dark"} > > > > > >
> > > >
> > > > > > ``` > > > > For dynamic rendering based on what the server returns, listen to [primer:methods-update](https://primer.io/docs/sdk/primer-checkout-web/events-reference.md) or use [primer-payment-method-container](https://primer.io/docs/sdk/primer-checkout-web/components/primer-payment-method-container.md) for declarative filtering. > > > [tab] Universal Checkout (legacy) > > > > ##### Set up redirects > > > > If Mercado Pago via dLocal can't be shown in a popup, Universal Checkout redirects the customer back to your site using the `returnUrl` passed in the `redirect` options. See [Handle redirects & deep links](https://primer.io/docs/sdk/web/v2.x.x/handle-redirects-and-deeplinks.md#set-up-redirects) for the full flow. > > > > ```typescript theme={"dark"} > > const options = { > > container: "#checkout-container", > > redirect: { > > returnUrl: "https://mystore.com/checkout", > > }, > > onCheckoutComplete({ payment }) { > > console.log("Checkout complete.", payment); > > }, > > }; > > ``` > > > > ##### Show Universal Checkout > > > > Mercado Pago via dLocal is automatically presented when calling [Primer.showUniversalCheckout](https://primer.io/docs/sdk/web/v2.x.x/primer/methods/showUniversalCheckout.md). > > > > ```typescript theme={"dark"} > > import { Primer } from "@primer-io/checkout-web"; > > > > try { > > await Primer.showUniversalCheckout(clientToken, options); > > } catch (e) { > > // handle error > > } > > ``` > > > > Check the [customization guide](https://primer.io/docs/checkout/drop-in/customization.md#styling-payment-method-button) to learn how to customize payment method buttons. > > > [tab] Headless Universal Checkout (legacy) > > > > Create a `RedirectPaymentMethodManager` for Mercado Pago via dLocal using [createPaymentMethodManager](https://primer.io/docs/sdk/web/v2.x.x/primer-headless-checkout/methods/createPaymentMethodManager.md#redirect), then call `start()` to begin the redirect flow. > > > > ```typescript theme={"dark"} > > const manager = await headless.createPaymentMethodManager("YOUR_PAYMENT_METHOD_TYPE"); > > > > if (manager) { > > manager.addEventListener("click", () => { > > // Optional: run custom logic before the redirect flow starts. > > }); > > > > await manager.start(); > > } > > ``` > > > > Refer to the full guide for [handling payment methods with redirect](https://primer.io/docs/checkout/headless.md#step-4c-handle-payment-methods-with-redirect). > [tab] iOS > > > [!NOTE] > > > > Use the payment method type `DLOCAL_MERCADO_PAGO` wherever the code below references `YOUR_PAYMENT_METHOD_TYPE`. > > #### Set up redirects > > Redirect-based payment methods present a webpage or open a third-party app for the customer to authorize the payment. To return to your app once the customer has authorized the payment, include the `urlScheme` parameter when configuring `PrimerPaymentMethodOptions`. > > ```swift theme={"dark"} > let settings = PrimerSettings( > // ... > paymentMethodOptions: PrimerPaymentMethodOptions( > urlScheme: "your-url-scheme://" // e.g. primer://, yourscheme:// > ) > // ... > ) > ``` > > When the customer is redirected back to your app, iOS calls `application(_:continue:restorationHandler:)`. Forward the call to the Primer SDK so the checkout can continue the flow. > > ```swift theme={"dark"} > import PrimerSDK > import UIKit > > @UIApplicationMain > class AppDelegate: UIResponder, UIApplicationDelegate { > // ... > func application( > _ application: UIApplication, > continue userActivity: NSUserActivity, > restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void > ) -> Bool { > return Primer.shared.application( > application, > continue: userActivity, > restorationHandler: restorationHandler > ) > } > } > ``` > > #### Show the payment method > > > [tab] Universal Checkout (drop-in) > > > > Mercado Pago via dLocal is automatically presented when calling [Primer.shared.showUniversalCheckout](https://primer.io/docs/sdk/ios/v2.x.x/primer/methods/showUniversalCheckout.md). > > > > ```swift theme={"dark"} > > class MyViewController: UIViewController { > > func startUniversalCheckout() { > > Primer.shared.showUniversalCheckout(clientToken: self.clientToken) > > } > > } > > ``` > > > > Check the [customization guide](https://primer.io/docs/checkout/drop-in/customization.md#styling-payment-method-button) to learn how to customize payment method buttons. > > > [tab] Headless Universal Checkout > > > > Mercado Pago via dLocal requires a [Native UI Manager](https://primer.io/docs/checkout/headless.md#native-ui-manager) to be presented to the customer. > > > > ```swift theme={"dark"} > > // 👇 Create the payment method manager > > let nativeUIPaymentMethodManager = try PrimerHeadlessUniversalCheckout.NativeUIManager( > > paymentMethodType: "YOUR_PAYMENT_METHOD_TYPE" > > ) > > > > // 👇 Show the payment method > > try nativeUIPaymentMethodManager.showPaymentMethod(intent: .checkout) > > ``` > > > > See [NativeUIManager.init](https://primer.io/docs/sdk/ios/v2.x.x/primer-headless-checkout/native-ui-manager/init.md) for the full API. As many redirect-based payment methods share this approach, we recommend centralizing the implementation — see the worked example in the [Native UI Manager guide](https://primer.io/docs/checkout/headless.md#native-ui-manager). > [tab] Android > > > [!NOTE] > > > > Use the payment method type `DLOCAL_MERCADO_PAGO` wherever the code below references `YOUR_PAYMENT_METHOD_TYPE`. > > > [tab] Universal Checkout (drop-in) > > > > Mercado Pago via dLocal is automatically presented when calling [Primer.instance.showUniversalCheckout](https://primer.io/docs/sdk/android/v2.x.x/primer/methods/showUniversalCheckout.md). > > > > ```kotlin theme={"dark"} > > class CheckoutActivity : AppCompatActivity() { > > private fun setupObservers() { > > viewModel.clientToken.observe(this) { clientToken -> > > showUniversalCheckout(clientToken) > > } > > } > > > > private fun showUniversalCheckout(clientToken: String) { > > Primer.instance.showUniversalCheckout(this, clientToken) > > } > > } > > ``` > > > > Check the [customization guide](https://primer.io/docs/checkout/drop-in/customization.md#styling-payment-method-button) to learn how to customize payment method buttons. > > > [tab] Headless Universal Checkout > > > > Mercado Pago via dLocal requires a [Native UI Manager](https://primer.io/docs/checkout/headless.md#native-ui-manager) to be presented to the customer. > > > > ```kotlin theme={"dark"} > > // 👇 Create the payment method manager > > val nativeUiManager = PrimerHeadlessUniversalCheckoutNativeUiManager.newInstance("YOUR_PAYMENT_METHOD_TYPE") > > > > // 👇 Show the payment method > > nativeUiManager.showPaymentMethod(this, PrimerSessionIntent.CHECKOUT) > > ``` > > > > See [NativeUiManager.newInstance](https://primer.io/docs/sdk/android/v2.x.x/primer-headless-checkout/native-ui-manager/newInstance.md) for the full API. As many redirect-based payment methods share this approach, we recommend centralizing the implementation — see the worked example in the [Native UI Manager guide](https://primer.io/docs/checkout/headless.md#native-ui-manager). ## Test in sandbox Connect your dLocal **test** account to your Primer Sandbox environment. Toggle **Test mode** in the dLocal dashboard before copying your credentials, sandbox and production credentials are different. Run the following for each market you intend to support. 1. Create a client session with `order.countryCode`, `currencyCode` and `customer.nationalDocumentId` set for that market. 2. Select Mercado Pago at the checkout. 3. Complete the payment on the Mercado Pago hosted page. 4. Drive a `PAID` callback from dLocal. 5. Confirm Primer resumes the payment once and the final status is **Settled**. Also confirm that the correct Mercado Pago branding and logo are shown for the country under test. | Market | `order.countryCode` | `currencyCode` | Test document | | - | - | - | - | | Brazil | `BR` | `BRL` | CPF request a valid-format document from dLocal | | Mexico | `MX` | `MXN` | RFC or CURP request a valid-format document from dLocal | | Argentina | `AR` | `ARS` | CUIT or DNI request a valid-format document from dLocal | | Chile | `CL` | `CLP` | RUT request a valid-format document from dLocal | | Colombia | `CO` | `COP` | CC or NIT request a valid-format document from dLocal | | Uruguay | `UY` | `UYU` | CI request a valid-format document from dLocal | ## Go live Ensure to use production credentials, and confirm with dLocal that Mercado Pago is enabled on your production account for each market you intend to support. Make sure `order.countryCode` and `currencyCode` match one of the [supported markets](#supported-markets) on every payment you route to it. If you are going live in Chile, confirm your `CLP` currency access has been granted by Primer. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.