Web

📘

Prerequisites:

• You have retrieved your Ivy API Secrets
• You have created a new Checkout Session and have the redirectUrl

JavaScript Library

Installation

Include the Ivy script for integrating the Ivy Button on each page of your site. It must always be loaded directly from https://cdn.getivy.de, rather than included in a bundle or hosted yourself.

<script src="https://cdn.getivy.de/button.js"></script>

Start Flow

First, you must create a data or a checkout session by calling the Ivy API directly. You will be returned a redirectUrl, which you need to start the flow.

When you have created the session and received the redirectUrl successfully, call the startIvyCheckout() function.

After calling the function, the Ivy flow will open in a modal popup or a redirect, depending on whether it is in mobile or desktop web view.

End of Flow

When the user finishes the flow, the SDK will send them back automatically to either the errorCallbackUrl or successCallbackUrl specified in the request to create the session.

Embed as iFrame

Configure URL

Append the URL parameter &iframe=true to the redirectUrl . This will make sure that the callbacks are sent via postMessage to the parent window.

// data is the response payload of /checkout/session/create
const newUrl = data.redirectUrl + '&iframe=true'

Add URL to an iframe element

Add the adapted redirectUrl as the src parameter of an <iframe> HTML element.

<iframe src=newUrl />

To allow the iframe to seamlessly adapt its size to the containing element, make sure to apply appropriate sizing either by css or inline-styles. Using the width attribute will give the iframe a static width, which is not recommended when targeting mobile devices.

<!–– ❌ not recommended for mobile devices ––>
<iframe src=newUrl width="400" />

<!–– ✅ adapt to the size of the parent element ––>
<iframe src=newUrl style="width:100%;" />

❗️

Note

If you are using sandboxing, you need to at minimum add the following flags allow-scripts, allow-same-origin, allow-popups, allow-forms, allow-popups-to-escape-sandbox, and allow-top-navigation

Add a listener to your app

All communication between an iframed Ivy Checkout and the parent host is done via postMessage. Register a listener to start receiving messages. How you do this is up to you, but the code below shows the basics.

window.addEventListener('message', receiveMessage, false);

function receiveMessage(event) {
  
  const { source, type, value, redirectUrl, referenceId } = JSON.parse(event.data);
  
  if (source !== 'ivy' || type !== 'iframe') {
    return;
  }
  
  if (value === 'success') {
    // Handle success response
    // Use the referenceId to retrieve any more specific results with a server to server call
    console.log("User paid successfully", referenceId, redirectUrl);
  } else if (value === 'error') {
    // Handle error response
    console.log("User closed Ivy Checkout");
  } else {
    // Something went wrong
  }
}

Callback body

The postMessage has the below format:

{
  source: 'ivy',
  type: 'iframe',
  value: 'success' | 'error', 
  redirectUrl: 'redirectUrl', // The redirectUrl according to the settings of the Checkout
  referenceId?: 'referenceId', // The referenceId passed when creating a Checkout
}

UI Components

Installation

Include the Ivy script for integrating the Ivy Button on each page of your site. It must always be loaded directly from https://cdn.getivy.de, rather than included in a bundle or hosted yourself.

<script src="https://cdn.getivy.de/banner.js"></script>

Integration

Embed the UI Banner on your page simply with this HTML component. You can adapt the component to your needs by setting the parameters data-locale and data-market:

<div 
	class="ivy-banner"
	data-variant="shopify-payment"
	data-locale="locale"
	data-market="market"
></div>

You can re-initialize the component by calling window.initIvy() .