​
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

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 });
      }}
    />
  )
}
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;
  }
}

​
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

​
Need Help?

SettlementsOne-time payments