Embedding dLocal payment pages
Understand which dLocal-hosted payment pages support iframe and WebView embedding, and which integration patterns to use when they don't.
Embedding dLocal-hosted payment pages inside an iframe, WebView, or other embedded container is not supported. This applies to Checkout redirect and any other page served at a redirect_url, including APM hosted pages.
Smart Fields is not affectedSmart Fields embeds individual PCI-scoped card fields into your page by design. It does not embed a full dLocal-hosted payment page, so this restriction does not apply.
Why embedding is not supported
dLocal does not test or guarantee behavior when its hosted pages are loaded inside embedded containers. If you embed them anyway, you may encounter:
- Layout or display issues inside constrained containers
- Authentication or navigation failures caused by browser privacy controls, such as third-party cookie restrictions and referrer stripping
- Broken flows when dLocal updates its security headers or framing policies, which can happen at any time
dLocal does not provide support or SLA coverage for issues that only occur when a payment page is embedded.
Supported integration options
If you need a payment integration, use one of the supported patterns:
- Checkout redirect — redirect the customer to the dLocal-hosted payment page in a full browser context.
- Full API — build and host the payment experience on your own frontend.
- Smart Fields — embed PCI-scoped card fields directly into your page.
The right choice depends on the payment method, the experience you need, and your PCI scope.
Exception: SmartPix
SmartPix is the only dLocal payment flow with documented embedded support. Follow the canonical guides to implement it:
Do not adapt the SmartPix embedded pattern to other dLocal products. The behavior is specific to SmartPix and is not guaranteed to work elsewhere.
Updated 19 days ago