Iframe integration

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

Create payment session

Your application creates a payment session with iframe mode enabled.

Embed iframe

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

Customer completes payment

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

Handle completion

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

Basic implementation

Recommended: session created by your backend

Your server creates the session with your secret key, and the SDK embeds it — the recommended integration, in iframe form:

const payviox = new Payviox('pk_live_your_key');

const { session_id } = await fetch('/api/checkout', { method: 'POST' }).then((r) => r.json());

payviox.openIframe(session_id, {
  iframeTarget: document.getElementById('payment-container'),
  width: '100%',
  height: '500px'
});

Minimal iframe integration (no backend)

The SDK creates the session itself; it only needs 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: 'stripe_credit',
  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

boolean

required

Enable iframe integration mode. Must be set to true.

object

required

Configuration object for iframe behavior and appearance.

Show Iframe configuration properties

HTMLElement

required

DOM element where the iframe will be inserted. Must be a valid HTML element.

iframeTarget: document.getElementById('payment-container')

string

default:"100%"

Width of the iframe. Can be any valid CSS width value.

width: '100%'  // or '500px', '80vw', etc.

string

default:"400px"

Height of the iframe. Can be any valid CSS height value.

height: '600px'  // or '100vh', '80%', etc.

boolean

default:"false"

Remove the default iframe border for a seamless integration.

withoutBorder: true

boolean

default:"false"

Make the iframe background transparent to match your page design.

transparentBackground: true

string

default:""

Additional CSS styles to apply to the iframe.

style: 'box-shadow: 0 4px 6px rgba(0,0,0,0.1); border-radius: 12px;'

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 type	Description	Payload
`payviox:redirect`	Payment requires a full-page redirect (to a payment provider or success/failure URL)	`{ type: 'payviox:redirect', redirect: 'https://...' }`
`payviox:close`	Customer 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

Iframe not displaying

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;">

Iframe height not adjusting

Solution: Set a fixed minimum height or use viewport units:

iframeConfig: {
  height: '600px',  // or 'max(600px, 80vh)'
  style: 'min-height: 500px;'
}

Messages not received

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:

Provide visual feedback: Show loading states while the iframe loads
Handle errors gracefully: Display user-friendly messages for errors
Mobile optimization: Test on various screen sizes
Accessibility: Ensure keyboard navigation works properly
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

SDK - Getting Started

SDK - Integration

SDK - API Reference

Overview

How it works

Basic implementation

Recommended: session created by your backend

Minimal iframe integration (no backend)

Configuration options

Iframe configuration parameters

Handling iframe events

Event types

Standalone integration (without SDK)

Troubleshooting

Best practices

Next steps

Error handling

Payment methods

Testing

Webhooks

​Overview

​How it works

​Basic implementation

​Recommended: session created by your backend

​Minimal iframe integration (no backend)

​Configuration options

​Iframe configuration parameters

​Handling iframe events

​Event types

​Standalone integration (without SDK)

​Troubleshooting

​Best practices

​Next steps

Error handling

Payment methods

Testing

Webhooks

Overview

How it works

Basic implementation

Recommended: session created by your backend

Minimal iframe integration (no backend)

Configuration options

Iframe configuration parameters

Handling iframe events

Event types

Standalone integration (without SDK)

Troubleshooting

Best practices

Next steps