Skip to main content

​
Overview

Iframe mode allows you to embed the Payviox payment flow directly into your website, providing a seamless user experience without redirecting customers away from your page.
Domain whitelisting required: Your domain must be whitelisted in your Payviox dashboard settings to use iframe mode.

​
How it works

1

Create payment session

Your application creates a payment session with iframe mode enabled.
2

Embed iframe

The SDK automatically creates and embeds an iframe in your specified target element.
3

Customer completes payment

Customer interacts with the payment form inside the iframe without leaving your page.
4

Handle completion

Listen for completion events via postMessage API to handle successful payments.

​
Basic implementation

​
Minimal iframe integration

The simplest iframe integration requires just a target container: 
const payviox = new Payviox('your_api_token');

// Create session with iframe mode
await payviox.createSession({
  amount: 5000,
  currency: 'USD',
  customer: 'customer_abc123',
  description: 'Order #12345',
  paymentMethodId: 'pm_card',
  order_id: 'order_12345',
  items: [
    {
      name: 'Product A',
      quantity: 1,
      price: 5000
    }
  ]
}, {
  iframeMode: true,
  iframeConfig: {
    iframeTarget: document.getElementById('payment-container'),
    width: '100%',
    height: '500px'
  }
});
The payment form will be loaded directly inside the specified container element.

​
Configuration options

​
Iframe configuration parameters

​
iframeMode
boolean
required
Enable iframe integration mode. Must be set to true.
​
iframeConfig
object
required
Configuration object for iframe behavior and appearance.

​
Handling iframe events

When using iframe mode, the payment page communicates with the parent window via the postMessage API. The SDK handles these events automatically, but you can also listen for them directly if you are embedding the iframe without the SDK.

​
Event types

Event typeDescriptionPayload
payviox:redirectPayment requires a full-page redirect (to a payment provider or success/failure URL){ type: 'payviox:redirect', redirect: 'https://...' }
payviox:closeCustomer clicked “Back to merchant” — the iframe should be removed{ type: 'payviox:close' }
Redirect-type payments (PayPal, Pallapay, etc.) cannot be displayed inside an iframe due to security restrictions (X-Frame-Options). When the customer selects one of these methods, the payment page sends a payviox:redirect event to navigate the full page to the provider.

​
Standalone integration (without SDK)

If you embed the Payviox iframe manually without using the SDK, you must listen for these events yourself: 
const PAYVIOX_ORIGIN = 'https://secure.payviox.com';

window.addEventListener('message', (event) => {
  if (event.origin !== PAYVIOX_ORIGIN) return;

  if (event.data?.type === 'payviox:redirect') {
    // Payment requires full-page redirect (provider or success/failure URL)
    window.location.href = event.data.redirect;
  } else if (event.data?.type === 'payviox:close') {
    // Customer wants to go back — remove the iframe
    document.getElementById('payment-container').innerHTML = '';
  }
});
Always validate event.origin against https://secure.payviox.com before acting on any message.

​
Troubleshooting

Possible causes:
  • Domain not whitelisted
  • Invalid iframe target element
  • Content Security Policy blocking iframe
Solution:
// Verify that target element exists
const target = document.getElementById('payment-container');
if (!target) {
  console.error('Payment container not found');
}

// Check console for CSP errors
// Add to your HTML if needed:
// <meta http-equiv="Content-Security-Policy" 
//       content="frame-src https://secure.payviox.com;">
Solution: Set a fixed minimum height or use viewport units:
iframeConfig: {
  height: '600px',  // or 'max(600px, 80vh)'
  style: 'min-height: 500px;'
}
Solution: Ensure you’re listening before creating the session:
// First configure the listener
window.addEventListener('message', handlePaymentMessage);

// Then create the session
await payviox.createSession(params, iframeConfig);

​
Best practices

Recommended practices for iframe integration:
  1. Provide visual feedback: Show loading states while the iframe loads
  2. Handle errors gracefully: Display user-friendly messages for errors
  3. Mobile optimization: Test on various screen sizes
  4. Accessibility: Ensure keyboard navigation works properly
  5. Performance: Initialize iframes only when needed (lazy loading)

​
Next steps

Error handling

Handle payment errors gracefully

Payment methods

Discover available payment options

Testing

Test iframe integration

Webhooks

Process server-side events