Iframe Integration Guide

When embedding the Payrails Web SDK inside an iframe, navigation behavior (redirects, new tabs, popups) adapts automatically to escape the iframe where appropriate. This guide explains how to configure the SDK and the host iframe for each payment flow.

Iframe Sandbox Attributes

Add the following attributes to your iframe to ensure the SDK functions correctly:

<iframe
  src="https://payments.example.com/checkout"
  sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-top-navigation"
></iframe>

Attribute	Purpose
`allow-scripts`	SDK execution
`allow-same-origin`	API calls, cookie access
`allow-forms`	Form submissions
`allow-popups`	`openInNewTab: true` and fallback new-tab behavior
`allow-top-navigation`	Allows `redirectFor3DS: true` and `openInNewTab: false` to redirect the parent page

If allow-top-navigation is not set, the SDK automatically falls back to opening a new browser tab. The authorization result is then resolved by monitoring the tab's closure and polling the execution status.

Configuration Options

1. Popup Payment Methods (hardcoded)

Certain payment methods (e.g. PIX) always display in a popup overlay regardless of configuration. This is automatic and requires no setup.

2. `redirectFor3DS` — 3D Secure Challenge Handling

Controls how 3DS authentication challenges are presented during card payments.

Set at: Payrails.init() (client-level, cannot be changed after initialization)

const payrails = Payrails.init(initResponse, {
  redirectFor3DS: true,
});

Value	Not in iframe	In iframe
`false` (default)	Modal popup overlay	Modal popup overlay
`true`	Redirects current page	Redirects top-level page

Iframe fallback chain when true:

Try window.top.location.assign() — works for same-origin and allow-top-navigation iframes
Fall back to window.open() — opens 3DS in a new tab, polls for result when tab closes
Last resort: redirect within the iframe itself

3. `openInNewTab` — Redirect Payment Method Handling

Controls how generic redirect payment methods (Mercado Pago, etc.) navigate to the provider's page.

Set at: Dropin config (per payment method) or standalone element options

// Dropin
const dropin = payrails.dropin({
  paymentMethodsConfiguration: {
    mercadoPago: {
      openInNewTab: true,
    },
  },
});

// Standalone element
const button = payrails.genericRedirectButton({
  openInNewTab: true,
  paymentMethod: { paymentMethodCode: 'mercadoPago' },
});

Value	Not in iframe	In iframe
`false` (default)	Redirects current page	Redirects top-level page
`true`	Opens new browser tab	Opens new browser tab (from top window when accessible)

Iframe fallback chain when false:

Same as redirectFor3DS: true — tries top-level navigation first, falls back to a new tab, then to in-iframe redirect.

Behavior Matrix

Config	Value	Not in iframe	In iframe
Popup APMs	(hardcoded)	Popup overlay	Popup overlay
`redirectFor3DS`	`false`	Popup overlay	Popup overlay
`redirectFor3DS`	`true`	Redirect current page	Redirect top-level page
`openInNewTab`	`false`	Redirect current page	Redirect top-level page
`openInNewTab`	`true`	New browser tab	New browser tab

Examples

Dropin inside an iframe

Parent page (merchant site):

<iframe
  src="/payment"
  sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-top-navigation"
  style="width: 100%; height: 500px; border: none;"
></iframe>

Payment page (inside iframe):

const payrails = Payrails.init(initResponse, {
  redirectFor3DS: true,
});

const dropin = payrails.dropin({
  paymentMethodsConfiguration: {
    preselectFirstPaymentOption: true,
    cards: {
      showCardHolderName: false,
      showExistingCards: true,
    },
    mercadoPago: {
      openInNewTab: true,
    },
  },
  returnInfo: {
    success: 'https://merchant.com/success',
    cancel: 'https://merchant.com/cancel',
    error: 'https://merchant.com/error',
  },
});

dropin.mount('#dropin');

With this setup:

Card 3DS → redirects the top-level page (merchant.com)
Mercado Pago → opens in a new browser tab
PIX → popup overlay inside the iframe

Standalone elements inside an iframe

const payrails = Payrails.init(initResponse, {
  redirectFor3DS: true,
});

// Card payment — 3DS will redirect the top-level page
const cardForm = payrails.cardForm({
  showSingleExpiryDateField: true,
});

const paymentButton = payrails.paymentButton({
  redirectFor3DS: true,
  translations: { label: 'Pay with Card' },
  events: {
    onAuthorizeSuccess: () => console.log('Success'),
    onAuthorizeFailed: (e) => console.log('Failed', e),
  },
});

// Mercado Pago — opens in a new tab
const mpButton = payrails.genericRedirectButton({
  openInNewTab: true,
  paymentMethod: { paymentMethodCode: 'mercadoPago' },
  returnInfo: {
    success: 'https://merchant.com/success',
    cancel: 'https://merchant.com/cancel',
    error: 'https://merchant.com/error',
  },
  translations: { label: 'Pay with Mercado Pago' },
  events: {
    onAuthorizeSuccess: () => console.log('Success'),
    onAuthorizeFailed: (e) => console.log('Failed', e),
  },
});

cardForm.mount('#card-form');
paymentButton.mount('#pay-button');
mpButton.mount('#mp-button');

Configuration Reference

Config	Scope	Set at	Dropin	Standalone
`redirectFor3DS`	Card 3DS only	`Payrails.init()`	Read from client options	Also accepted on `paymentButton()`
`openInNewTab`	Redirect APMs only	Per payment method	`paymentMethodsConfiguration.mercadoPago.openInNewTab`	`genericRedirectButton({ openInNewTab })`
Popup APMs	Hardcoded APMs	Automatic	No config needed	No config needed