​
Guide

This guide walks you through embedding Ivy Checkout directly in your website using our iframe and modal integration. You’ll create a seamless checkout experience where customers can complete their payment without leaving your site.

​
Step 1: Backend Setup

1

Install Dependencies

First, install our official Node SDK:
npm install @getivy/node-sdk
# or
yarn add @getivy/node-sdk
2

Create a Checkout Session

Create an endpoint on your server that initializes a checkout session:
server/routes/checkout.ts
import express from 'express';
import Ivy from '@getivy/node-sdk';
import { CheckoutsessionCreateParams } from '@getivy/node-sdk/resources/checkoutsession';

const router = express.Router();
const ivy = new Ivy('YOUR_API_KEY');

router.post('/api/checkout', async (req, res) => {
  try {
    const params: CheckoutsessionCreateParams = {
      referenceId: 'order_123', // Your internal unique order reference
      price: {
        total: req.body.amount,
        currency: req.body.currency || 'EUR',
      },
      locale: req.body.locale || 'en', // The language of the checkout. Customers can change this in the checkout as well
      errorCallbackUrl: "https://example.com/error",
      successCallbackUrl: "https://example.com/success",
      customer: {
        email: "john.doe@example.com",
      }
    };

    const session = await ivy.checkoutsession.create(params);
    res.json({ url: session.redirectUrl });
  } catch (error) {
    console.error("Failed to create checkout session", error);
    res.status(400).json({ error: 'Failed to create checkout session' });
  }
});

export default router;

​
Step 2: Frontend Implementation

Critical Implementation Requirements:
  • Iframe Parameter: Always append &iframe=true to the checkout URL when rendering in an iframe. The API doesn’t include this parameter by default since it doesn’t know your rendering method.
  • Mobile Web: For optimal UX on mobile web, redirect users to the Ivy checkout URL instead of using an iframe.
  • Native Apps: Always open Ivy checkout in the user’s default browser, not in a WebView. This is required for proper deep linking and app redirects.
Choose your preferred frontend implementation:
1

Install Dependencies

npm install @getivy/react-sdk
# or
yarn add @getivy/react-sdk
2

Create IvyCheckout Component

components/IvyCheckout.tsx
import { IvyCheckout } from '@getivy/react-sdk'

export function Checkout({
  amount,
  currency = 'EUR',
  locale = 'de',
  handleSuccess,
  handleCancel
}: {
  amount: number,
  currency?: string,
  locale?: string,
  handleSuccess: (data: { redirectUrl: string, referenceId: string }) => void,
  handleCancel: (data: { redirectUrl: string, referenceId: string }) => void
}) {

  const response = await fetch('/api/checkout', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      amount,
      currency,
      locale
    })
  })

  const { url } = await response.json();

  return (
    <IvyCheckout
      checkoutUrl={url}
      displayOptions={{
        type: "embedded", // or "modal"
      }}
      onSuccess={({ redirectUrl, referenceId }) => {
        handleSuccess({ redirectUrl, referenceId });
      }}
      onCancel={({ redirectUrl, referenceId }) => {
        handleCancel({ redirectUrl, referenceId });
      }}
    />
  )
}
The React SDK automatically handles the &iframe=true parameter for you when using embedded mode.
3

Add Styling

styles/ivy-checkout.css
import "@getivy/react-sdk/dist/index.css";

.ivy-embedded-checkout-screen {
  border: none;
  margin: 0;
  padding: 0;
  overflow: hidden;
  width: 100%;
  height: 100%;
}
.ivy-modal-content {
  position: fixed;
  z-index: 999999;
  inset: 0;
  color: #000;
  background-color: rgba(10, 10, 10, 0.25);
  display: -webkit-box;
  display: -ms-flexbox;
  display: flex;
  -webkit-box-orient: vertical;
  -webkit-box-direction: normal;
  -ms-flex-direction: column;
  flex-direction: column;
  -webkit-box-align: center;
  border: none;
  margin: 0;
  padding: 0;
  overflow: hidden;
  width: 100%;
  height: 100%;
}
.ivy-modal-content {
  position: fixed;
  z-index: 999999;
  inset: 0;
  color: #000;
  background-color: rgba(10, 10, 10, 0.25);
  display: -webkit-box;
  display: -ms-flexbox;
  display: flex;
  -webkit-box-orient: vertical;
  -webkit-box-direction: normal;
  -ms-flex-direction: column;
  flex-direction: column;
  -webkit-box-align: center;
  -ms-flex-align: center;
  align-items: center;
  -webkit-box-pack: center;
  -ms-flex-pack: center;
  justify-content: center;
}
.ivy-modal-content .ivy-modal-iframe-container {
  border: none;
  margin: 0;
  padding: 0;
  overflow: hidden;
  border-radius: 16px;
  transform: translateZ(0);
  width: 100%;
  height: 100%;
  background-color: transparent;
}
.ivy-modal-content .ivy-modal-checkout-screen {
  border: none;
  margin: 0;
  padding: 0;
  overflow: hidden;
  width: 100% !important;
  height: 100% !important;
}
@media (min-width: 450px) {
  .ivy-modal-content {
    padding: 16px 32px 32px;
  }
}
@media (max-width: 450px) {
  .ivy-modal-content .ivy-modal-iframe-container {
    border-radius: 0px;
    width: 100% !important;
    height: 100% !important;
    max-height: none !important;
  }
}

​
Step 3: Platform-Specific Considerations

Different platforms require different implementation approaches for optimal user experience and functionality.
1

Iframe Implementation

For desktop web applications, iframe integration provides the best user experience:
// Always append iframe=true parameter
const iframeUrl = checkoutUrl + '&iframe=true';

const iframe = document.createElement('iframe');
iframe.src = iframeUrl;
iframe.sandbox = 'allow-scripts allow-same-origin allow-popups allow-forms allow-popups-to-escape-sandbox allow-top-navigation';
iframe.allow = 'clipboard-write';
Desktop web is the ideal platform for iframe integration, providing seamless checkout without leaving your site.

​
Reference

​
React SDK

Check out the React SDK docs here

​
Plain HTML

Instead of redirecting to any callback URLs, the iframe communicates with the parent window via the postMessage API. The iframe will send a message to the parent window with the following fields:
​
source
string
required
Always equal to "ivy"
​
type
string
required
Always equal to "iframe"
​
value
string
required
Either "success" or "error"
​
referenceId
string
required
Your original checkoutSession field referenceId. Can also be used to fetch a order with the Retrieve an Order endpoint.

​
Security Considerations

The iframe sandbox attributes are crucial for security. Each attribute serves a specific purpose:
  • allow-scripts: Required for Ivy Checkout to function
  • allow-same-origin: Enables secure communication
  • allow-forms: Required for payment form input
  • allow-popups and allow-popups-to-escape-sandbox: Required for bank redirects
  • allow-top-navigation: Required for completion redirects For customers to be able to copy payment details with a button click we need clipboard access:
  • allow="clipboard-write": Required for Ivy Checkout to copy text into clipboard

​
Need Help?