Pix via dLocal

Pix via dLocal redirects the customer to a dLocal hosted page presenting a Pix QR code and copy-and-paste key. The customer completes the transfer from their banking app and the funds settle instantly. Pix is Brazil’s instant payment scheme, developed by the Banco Central do Brasil for real-time payments between individuals, companies and government entities. It is available in Brazil only, in BRL.

One off payment	Refunds	Recurring	Cancel
✓	✓	x	x

Pix via dLocal is asynchronous. dLocal confirms the payment by webhook once the customer completes the transfer in their banking app, so fulfil orders only on a final status. Full and partial refunds are supported, and a payment can be refunded more than once.

Get started with Pix via dLocal

Before you begin

If this is your first payment method, make sure to follow the Get started guide to begin processing payments with Primer. Pix is not active on a dLocal account by default. Ask your dLocal contact to enable it before you activate it on the Checkout. You need credentials from the dLocal Merchant Dashboard. If you do not have an account, contact your dLocal account manager or support@dlocal.com. To get sandbox credentials, toggle Test mode in the top right of the dLocal dashboard, a blue bar appears across the top to confirm you are in test mode. Your x_login, x_trans_key and secret key are under Settings > Integration, on the Integration tab.

Configure in the Dashboard

Add Pix via dLocal payment method to your Dashboard Go to the integrations section of the Dashboard, click on the ‘New Integration’ button and search for dLocal. Enter your x_login, x_trans_key and secret key, then click Connect.
Add your MID Enter your dLocal AccountId in the MID box. You can find it at the top of the dLocal dashboard.
Configure the webhook in dLocal Copy the callback URL that Primer shows you during setup and paste it into the Refunds URL field in the dLocal dashboard, under your API keys.
Activate Pix via dLocal on the Checkout Go to the Checkout section of the Dashboard and toggle on Pix. Add a display condition so Pix only appears where it can be paid at a minimum, Currency = BRL.
Configure a Workflow to process payments made with Pix via dLocal Go to Workflows and create a workflow with a Payment created trigger and an Authorize payment action with Auto-continue enabled. Pix via dLocal is a web redirect connection, so no further steps are needed.

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	✓	A unique identifier for the order. Maximum 255 characters.
currencyCode	✓	The three-letter currency code in ISO 4217 format. Pix is available in Brazil only, so this must be `BRL`.
customer.nationalDocumentId	✓	The payer’s CPF or CNPJ. Pix payments do not process without it.
customer.emailAddress	✓	Sent to dLocal as the payer email.
customer.firstName	✓	Combined with the last name and sent to dLocal as the payer name.
customer.lastName	✓	Combined with the first name and sent to dLocal as the payer name.
order.countryCode	✓	Determines which dLocal country entity processes the payment. Pix is available in Brazil only, so this must be `BR`. If it is absent, Primer falls back to the billing address country code.
customer.billingAddress	Recommended	Street, house number, city, state and postal code are passed to dLocal as the payer address.

Prepare the SDK for payments

Web
iOS
Android

Use the payment method type DLOCAL_PIX wherever the code below references YOUR_PAYMENT_METHOD_TYPE.

Primer Checkout (recommended)
Universal Checkout (legacy)
Headless Universal Checkout (legacy)

Primer Checkout is our latest web SDK, built around declarative web components. Once Pix via dLocal is enabled in your Dashboard, the default <primer-checkout> layout renders it automatically alongside your other methods — no payment-method-specific markup is required.

<primer-checkout client-token="your-client-token"></primer-checkout>

Custom layouts

Only reach for primer-payment-method if you’re building a custom layout and need to place Pix 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.

<primer-checkout client-token="your-client-token">
  <primer-main slot="main">
    <div slot="payments">
      <primer-payment-method type="YOUR_PAYMENT_METHOD_TYPE"></primer-payment-method>
    </div>
  </primer-main>
</primer-checkout>

For dynamic rendering based on what the server returns, listen to primer:methods-update or use primer-payment-method-container for declarative filtering.

Set up redirects

If Pix 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 for the full flow.

const options = {
  container: "#checkout-container",
  redirect: {
    returnUrl: "https://mystore.com/checkout",
  },
  onCheckoutComplete({ payment }) {
    console.log("Checkout complete.", payment);
  },
};

Show Universal Checkout

Pix via dLocal is automatically presented when calling Primer.showUniversalCheckout.

import { Primer } from "@primer-io/checkout-web";

try {
  await Primer.showUniversalCheckout(clientToken, options);
} catch (e) {
  // handle error
}

Check the customization guide to learn how to customize payment method buttons.

Create a RedirectPaymentMethodManager for Pix via dLocal using createPaymentMethodManager, then call start() to begin the redirect flow.

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.

Use the payment method type DLOCAL_PIX 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.

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.

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

Universal Checkout (drop-in)
Headless Universal Checkout

Pix via dLocal is automatically presented when calling Primer.shared.showUniversalCheckout.

class MyViewController: UIViewController {
  func startUniversalCheckout() {
    Primer.shared.showUniversalCheckout(clientToken: self.clientToken)
  }
}

Check the customization guide to learn how to customize payment method buttons.

Pix via dLocal requires a Native UI Manager to be presented to the customer.

// 👇 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 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.

Use the payment method type DLOCAL_PIX wherever the code below references YOUR_PAYMENT_METHOD_TYPE.

Universal Checkout (drop-in)
Headless Universal Checkout

Pix via dLocal is automatically presented when calling Primer.instance.showUniversalCheckout.

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 to learn how to customize payment method buttons.

Pix via dLocal requires a Native UI Manager to be presented to the customer.

// 👇 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 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.

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.

Go live

Ensure to use production credentials, and confirm with dLocal that Pix is enabled on your production account. Refunds URL webhook must be configured in your production dLocal dashboard as well as in sandbox.