Manual Installation

Direct iframe integration with Flintn Payment Checkout using postMessage communication.

Setup

1. Create a container

<div id="payment-container" style="width: 100%; max-width: 440px; height: 600px;"></div>

2. Create and mount the iframe

const ORIGIN = 'https://pay.flintn.com';

const container = document.getElementById('payment-container');

const iframe = document.createElement('iframe');
iframe.src = ORIGIN + '/iframe/';
iframe.title = 'Checkout form';
iframe.style.cssText = 'width: 100%; height: 100%; border: none;';
iframe.sandbox = 'allow-scripts allow-forms allow-popups allow-same-origin';
iframe.allow = 'payment *; clipboard-write';
container.appendChild(iframe);

3. Send configuration

The iframe expects a WIDGET_CONFIG message with your checkout config. Send it both on load and when the iframe signals WIDGET_READY:

const config = {
  clientSessionId: 'your_client_session_id',
  isCardHolderRequired: true, // optional, default: true
  successRedirectUrl: 'https://example.com/success', // optional
};

function sendConfig() {
  if (!iframe.contentWindow) return;
  iframe.contentWindow.postMessage(
    { type: 'WIDGET_CONFIG', payload: config },
    ORIGIN,
  );
}

iframe.addEventListener('load', sendConfig);

4. Handle events

Listen for payment events from the iframe:

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

  const { type, payload } = event.data || {};

  switch (type) {
    case 'WIDGET_READY':
      sendConfig();
      break;

    case 'PAYMENT':
      if (payload.status === 'PAYMENT_SUCCESS') {
        console.log('Payment succeeded:', payload.data);
      } else {
        console.log('Payment failed:', payload.error);
      }
      break;

    case 'EXPRESS_PAYMENT':
      if (payload.status === 'PAYMENT_SUCCESS') {
        console.log('Express payment succeeded:', payload.data);
      } else {
        console.log('Express payment failed:', payload.error);
      }
      break;

    case 'REDIRECT':
      if (payload?.url) {
        window.location.href = payload.url;
      }
      break;
  }
});

Configuration

Option	Type	Required	Default	Description
clientSessionId	string	✅	—	Client session ID from Flintn backend
isCardHolderRequired	boolean	❌	true	Require cardholder name field
successRedirectUrl	string	❌	—	Redirect URL after successful payment

Note: isCardHolderRequired only applies when using Primer as the payment provider.

Events

Outgoing (you → iframe)

Type	Description
WIDGET_CONFIG	Send checkout configuration to the iframe

Incoming (iframe → you)

Type	Description
WIDGET_READY	Iframe is loaded and ready to receive config
PAYMENT	Card payment completed (success or error)
EXPRESS_PAYMENT	Express payment completed (Apple Pay, Google Pay, PayPal)
REDIRECT	Iframe requests a redirect (e.g., after successful payment)

Payment Result

{
  status: 'PAYMENT_SUCCESS' | 'PAYMENT_ERROR' | 'PAYMENT_CANCELLED';
  data?: string;    // Payment ID on success
  error?: {
    code: string;
    message: string;
  };
}

Iframe Attributes

Attribute	Value	Why
sandbox	allow-scripts allow-forms allow-popups allow-same-origin	Required for payment SDKs, 3DS verification, and OAuth flows
allow	payment *; clipboard-write	Enables Payment Request API and clipboard access

Cleanup

Remove the iframe and event listener when no longer needed:

iframe.remove();
window.removeEventListener('message', handleMessage);

Troubleshooting

Iframe not loading

• Verify https://pay.flintn.com/iframe/ is accessible

• Check browser console for CSP or sandbox errors

Config not received

• Ensure postMessage uses the correct origin (https://pay.flintn.com)

• Verify clientSessionId is valid

Payments failing

• Check that sandbox attribute includes all required values

• Ensure allow="payment *" is set for Payment Request API support

Next Steps

For a simpler integration, consider using the SDK Installation which handles iframe creation, messaging, and cleanup automatically.