Introduction

When interacting with Qonto Embed, there are some actions that are considered sensitive. In order to perform them securely and not force Qonto Embed partners to be compliant with applicable laws, those actions are performed by Qonto on behalf of the partner. This delegation happens through an iframe that is opened in the partner’s platform.

This documentation describes how a partner can integrate with Qonto Embed’s iframe by explaining all the available actions that can be directed through it and how the communication between the iframe and the partner’s website happens.

Communication

Once the partner initiates the sensitive action by calling the Qonto Embed API, it will get a response specifying that the operation is sensitive. This means the operation will have to be done through the iframe so the partner will have to render it on their side with the appropriate URL.

Once the iframe is rendered, the system uses post messages for communication between the parent window and the iframe, ensuring type-safe data transmission and handling.

Each sensitive action expects a different payload to be sent from the parent to the iframe, in the later sections of this document a description of each action can be found.

Getting Started

Prerequisites

• The partner’s domain must be allowlisted to communicate with the Qonto Embed iframe.
• The partner needs a valid Oauth token.
• The iframe must be properly loaded in the partner’s application:
  • The iframe route that listens to post messages is /connect#access_token=xxxxx where the access_token parameter is an Oauth token obtained previously.
• Once the iframe loads successfully, it will post a qonto.ready message to the parent to signal it is ready to operate. The partner will have to subscribe to the message event to be able to capture it:

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

Communication Flow

Diagram showing an example of communication with the Qonto API through the Qonto Embed Iframe

1. Initial Ready Event coming from the iframe When the iframe is loaded, it sends a qonto.ready message to the parent window, indicating it's ready to receive commands. The ready event can be listened for as follows:

   // Wait for iframe ready signal
   window.addEventListener('message', (event) => {
     if (event.data.eventId === 'qonto.ready') {
       // Iframe is ready to receive commands
     }
   });
   

2. Sending Commands from the partner The parent window can send commands to the iframe using the following message structure:

   interface MessageData {
     actionId: string;                     // The action to perform
     actionData: Record<string, unknown>   // Action-specific data
   }