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.

​
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