Payment flow in web embeds

You can embed dLocal’s SmartPix payment experience directly into your application through an iframe.

This keeps users in your app and avoids full-page redirections to external payment pages.

🚧

Prerequisite

This option is only available for the redirect flow.

How it works

With this solution, your web app takes control of the external redirection event within the payment flow. Instead of losing context when the payment page attempts to redirect, your app intercepts the event and opens the bank’s app URL. This keeps your web app active in the background.

Prerequisites

Before starting, ensure you have:

• A web application.
• An existing integration with dLocal’s redirect flow.
• A deep link or universal link to handle the redirection to the bank’s native application after enrollment confirmation.

Integration overview

The integration involves the following steps:

• Creating a payment request.
• Loading the redirect URL in an iframe.
• Intercepting external events to trigger redirections.

Integration steps

Step 1: Create a payment

First, you'll need to create a payment request using the redirect flow. Refer to the Authorization checkout managed by dLocal page for request details.

Example response

{
  "payment": {
    "status": "PENDING",
    "redirect_url": "https://pay.dlocal.com/gmf-apm/smart-pix/R-4-8b4f332f-b2fe-4f35-9cc1-63..."
  }
}

Step 2: Get the redirect URL

After a successful payment request, the API will return a redirect_url that links to dLocal's hosted payment page.

This is the URL of our payment page that you will load in your WebView.

Example URL

https://pay.dlocal.com/gmf-apm/smart-pix/R-4-8b4f332f-b2fe-4f35-9cc1-63...

Step 3: Add the embedded parameter

This is a critical and required step. To ensure our solution works correctly within your WebView, you must append embedded=true to the redirect_url returned in the payment response.

Example URL

https://pay.dlocal.com/gmf-apm/smart-pix/R-4-8b4f332f-b2fe-4f35-9cc1-63...?embedded=true 

Step 4: Open the payment page

Once the URL is modified (with the embedded=true parameter added), load it in an iframe.

Web (HTML)

<iframe src=”https://pay.dlocal.com/gmf-apm/...?embedded=true” />

Step 5: Intercept the redirect event

The final and most important step is to program your web app to detect when the iframe sends an event to redirect to an external domain, such as a bank's website, using a deep link or universal link. You must handle the redirect yourself using your web app capabilities.

Code implementation for URL interception

Web (JavaScript)

The core of this solution lies in intercepting the external redirection event to handle it without interrupting your app's operation in the background. Below is the recommended JavaScript code for your web app to do just that.

  // Define the message handler
  function handleMessage(event) {
    // Always check origin for security if you expect messages only from a known domain
    if (event.origin !== "https://pay.dlocal.com") return;
    if (event.data && event.data.type === "REQUEST_EXTERNAL_OPEN" && event.data.url) {
      // Redirect to the target URL
      window.location.href = event.data.url;
    }
  }
  // Add the listener
  window.addEventListener("message", handleMessage);
  // Example: remove listener later if you need to
  // window.removeEventListener("message", handleMessage);