Recipients embedded experience

Mangopay provides a pre-built UI component that you can integrate to allow users to securely register their bank account details directly with Mangopay as a Recipient.

Mangopay’s embedded Recipients experience:

• Accelerates your integration by taking care of fronted interactions and the necessary API calls
• Leverages Mangopay’s data validation features in real time to ensure the user’s data conforms to the expected local bank account format
• Integrates SCA redirection to allow the user to authenticate the account registration
• Performs Verification of Payee checks for EUR local accounts in the SEPA zone and warns the user in case the account name and IBAN don’t match

Key concepts

The Recipients feature is built around key concepts relating to bank account registration.

Each Recipient can be used for one combination of Currency, Country of registration, and PayoutMethodType, which together determine the account details required from the user.

The PayoutMethodType can be either InternationalBankTransfer or LocalBankTransfer, which determines whether payouts to the account will be attempted using the SWIFT international messaging system to the account’s IBAN, or via local rails to the local account format.

Independent of these values, the Recipient can also have one of two RecipientType values: Individual if registered to a private individual (first name and last name), or Business if registered to a legal entity (using the business name).

Note that the Recipients embedded experience can only be used to register bank accounts that are usable for payouts and therefore must be authenticated using Mangopay’s SCA feature. This means that the Natural User or Legal User must have the UserCategory of OWNER to be able to complete the session. The Recipient created via the embedded experience can also be used for pay-in use cases (read more about Recipient scopes).

User experience

The Recipients experience present the user with an easy-to-complete form:

The form is dynamic depending on the Recipient type, currency, and country. Any data format issues are presented to the user before submission thanks to regexes. After submission, the validity of the data is also checked thanks to Mangopay’s POST Validate data for a Recipient endpoint, with any issues again presented to the user.

Once the data satisfies these checks and is submitted, the SDK also performs a Verification of Payee check if the account is in EUR and in the SEPA zone. If the account name and IBAN don’t match, the SDK warns the user and gives the option to modify the data or confirm the account creation.

Once the form is complete, the experience redirects the User to Mangopay’s SCA session to authenticate the account registration.

Authentication

Before integrating the Recipients experience in your frontend app, you end to integrate an authentication step from your server.

The Recipients experience requires an access token (clientToken) to authenticate the API calls from your frontend app to Mangopay’s servers.

The clientToken:

• Is specific to the UserId
• Is valid for 15 minutes
• Must be generated using OAuth 2.0 authentication

To generate the clientToken using OAuth 2.0 authentication, the steps are as follows:

1. Generate OAuth bearer token with your dedicated API key

To create the clientToken, you need a specific API key that has the required permissions for embedded experiences – if you don’t have one already, contact Mangopay via the Dashboard.

You need to encode the dedicated API key in the usual way for OAuth 2.0, by combining it with the Client ID separated by a colon (ClientId:ApiKey), and then encoding that string using Base64 (see the OAuth 2.0 authentication guide for details).

Once encoded, call the POST Create OAuth bearer token endpoint using Basic authentication (in the Authorization HTTP header, set the value to Basic followed by a space followed by your encoded string).

In the API response, you receive an access_token, which is valid for 1 hour (as shown by the expires_in value).

Use the token for its full lifetime to avoid overuse of the OAuth bearer token endpoint.

2. Obtain client token for the user’s Recipients session

Use your bearer token to call the POST Create an access token for Recipients endpoint, by setting the Authorization HTTP header value to Bearer following by a space followed by the bearer token obtained in Step 1.

When you call this endpoint, you also need to specify the UserId of the Natural User or Legal User that the Recipient is being created for.

$
curl -X POST 'https://api.sandbox.mangopay.com/v2.01/oauth/token/embedded/recipient' \
>
     -H 'Content-Type: application/json' \
>
     -H 'Authorization: Bearer ab08691f2ef34733a8451ed3742d4204' \
>
     -d '{
>
    "clientId": "your-mangopay-client-id",
>
    "claims": {
>
        "userId": "user_m_01JP2X1PK52W8PYD99Q3CXDMAP"
>
    }
>
}'

In response, the API returns an access_token which you need to use later as the clientToken during initialization.

As shown by the expires_in value, the clientToken is valid for 15 minutes, which means the user must complete the Recipients registration session within this time.

1
{
2
    "access_token": "rec_019bb6b1683d7251b29e56524bcc551e",
3
    "token_type": "Bearer",
4
    "expires_in": 900,
5
    "scope": "bankaccounts:r bankaccounts:w"
6
}

Now that you have your Recipients access token (clientToken), you can use it to initialize Mangopay Elements.

Installation

The Recipients experience relies on the Mangopay Elements package.

Install the package in your project using your preferred package manager:

1
npm install @mangopay/mangopay-elements
2
# or
3
yarn add @mangopay/mangopay-elements
4
# or
5
pnpm add @mangopay/mangopay-elements

Integration

To integrate Mangopay Elements in your frontend app, using the clientToken generated by your server during authentication, the steps are as follows:

1. Import the SDK

Import the library into your JavaScript or TypeScript file:

1
// Optional: Import types for TypeScript
2
import type { RecipientElementInstance } from '@mangopay/mangopay-elements';

2. Fetch your access token from server

Before initializing the package, fetch the clientToken from your server that you generated during authentication:

1
// Initialize Mangopay SDK
2
await Mangopay.init({
3
  locale: 'en',
4
  env: 'sandbox',
5
  clientId: 'YOUR_CLIENT_ID',
6
  userId: userId,
7
  clientToken: clientToken,
8
});

3. Initialize the package

Use the clientToken to initialize the Mangopay Elements package:

1
// Initialize Mangopay SDK
2
await Mangopay.init({
3
  locale: 'en',
4
  env: 'sandbox',
5
  clientId: 'YOUR_CLIENT_ID',
6
  userId: userId,
7
  clientToken: clientToken,
8
});

4. Create the Recipients element

Define the default values for the user and customize your theme:

1
const recipientElement = Mangopay.createElement('recipient', {
2
  defaultValues: {
3
    currency: 'EUR',
4
    country: 'FR',
5
    recipientType: 'Individual',
6
    payoutMethodType: 'LocalBankTransfer',
7
  },
8
  appearance: {
9
    theme: {
10
	    
11
    },
12
  },
13
});

5. Set up event listeners

Mangopay’s solution provides event listeners that you can use to insert the experience into your wider user journey. You need to set these up in your app like the example below – see the event handling section for details.

1
recipientElement.on('ready', data => {
2
  console.log('Element ready:', data.elementId);
3
});
4
5
recipientElement.on('submit', data => {
6
  console.log('Form submitted:', data.formData);
7
});
8
9
recipientElement.on('success', data => {
10
  console.log('Recipient created:', data);
11
});
12
13
recipientElement.on('error', data => {
14
  console.error('Error:', data.message);
15
});

6. Insert the container in to your HTML

Ensure your Recipients container is present in your DOM before mounting the element:

1
<div id="recipient-container"></div>

7. Mount the element

1
await recipientElement.mount('#recipient-container');

Examples

See below for more complete examples you can adapt to your integration.

HTML

1
<!DOCTYPE html>
2
<html lang="en">
3
  <head>
4
    <meta charset="UTF-8" />
5
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
6
    <title>Add Recipient</title>
7
    <style>
8
      #recipient-container {
9
        min-height: 500px;
10
        border: 1px solid #e0e0e0;
11
        border-radius: 8px;
12
        padding: 20px;
13
      }
14
      .loading {
15
        text-align: center;
16
        padding: 40px;
17
        color: #666;
18
      }
19
    </style>
20
  </head>
21
  <body>
22
    <h1>Add a Recipient</h1>
23
    <div id="recipient-container">
24
      <div class="loading">Loading...</div>
25
    </div>
26
27
    <script type="module" src="/app.js"></script>
28
  </body>
29
</html>

JavaScript

1
async function initializeRecipientForm() {
2
  try {
3
    const tokenResponse = await fetch('/api/generate-token', {
4
      method: 'POST',
5
      headers: { 'Content-Type': 'application/json' },
6
      body: JSON.stringify({ userId: 'user_m_123456' }),
7
    });
8
9
    if (!tokenResponse.ok) throw new Error('Failed to generate token');
10
11
    const { clientToken, userId } = await tokenResponse.json();
12
13
    await Mangopay.init({
14
      locale: 'en',
15
      env: 'sandbox',
16
      clientId: 'your_mangopay_client_id',
17
      userId: userId,
18
      clientToken: clientToken,
19
    });
20
21
    const recipientElement = Mangopay.createElement('recipient', {
22
      defaultValues: {
23
        currency: 'EUR',
24
        country: 'FR',
25
      },
26
    });
27
28
    recipientElement.on('ready', () => console.log('✅ Recipient form is ready'));
29
    recipientElement.on('submit', data => console.log('📤 Form submitted:', data.formData));
30
    recipientElement.on('success', data => {
31
      console.log('✅ Recipient created successfully:', data);
32
      alert('Recipient added successfully!');
33
    });
34
    recipientElement.on('error', data => {
35
      console.error('❌ Error:', data.message);
36
      alert(`Error: ${data.message}`);
37
    });
38
39
    await recipientElement.mount('#recipient-container');
40
  } catch (error) {
41
    console.error('Failed to initialize recipient form:', error);
42
    document.getElementById('recipient-container').innerHTML =
43
      `<p style="color: red;">Failed to load form. Please try again.</p>`;
44
  }
45
}
46
47
document.addEventListener('DOMContentLoaded', initializeRecipientForm);

TypeScript

1
import {
2
  Mangopay,
3
  RecipientElementInstance,
4
  RecipientOptions,
5
  RecipientFormData,
6
  RecipientEvents,
7
  MangopayInitOptions,bi
8
} from '@mangopay/mangopay-elements';
9
10
async function createRecipient(): Promise<void> {
11
  const initOptions: MangopayInitOptions = {
12
    locale: 'en',
13
    env: 'sandbox',
14
    clientId: 'your_client_id',
15
    userId: 'user_123',
16
    clientToken: 'token_xyz',
17
    debug: true
18
  };
19
20
  await Mangopay.init(initOptions);
21
22
  const options: RecipientOptions = {
23
    defaultValues: {
24
      currency: 'EUR',
25
      country: 'FR',
26
      recipientType: 'Individual',
27
    },
28
  };
29
30
  const element: RecipientElementInstance = Mangopay.createElement('recipient', options);
31
32
  element.on('ready', data => console.log(data.elementId));
33
  element.on('submit', data => console.log(data.formData));
34
  element.on('success', data => console.log('Success:', data));
35
  element.on('error', data => console.log(data.message));
36
37
  await element.mount('#recipient-container');
38
}

Configuration reference

Initialization options

1
interface MangopayInitOptions {
2
  locale: string;
3
  env: 'sandbox' | 'production';
4
  clientId: string;
5
  userId: string;
6
  clientToken: string;
7
  debug?: boolean;
8
}

Theme

You can customize the colors and font:

1
export interface ThemeColors {
2
  primary?: string;
3
  secondary?: string;
4
  background?: string;
5
  surface?: string;
6
  border?: string;
7
  text?: string;
8
  error?: string;
9
  success?: string;
10
  warning?: string;
11
}
12
13
export interface ThemeFonts {
14
  family?: string;
15
  size?: {
16
    small?: string;
17
    medium?: string;
18
    large?: string;
19
  };
20
  weight?: {
21
    normal?: string;
22
    medium?: string;
23
    bold?: string;
24
  };
25
}
26
27
export interface Theme {
28
  colors?: ThemeColors;
29
  fonts?: ThemeFonts;
30
  borderRadius?: string;
31
  spacing?: {
32
    small?: string;
33
    medium?: string;
34
    large?: string;
35
  };
36
}

Recipient element options

You can use the Theme and RecipientOptions interfaces to customize the appearance and default values of the experience.

Supported currencies

The currencies supported by the experience are:

1
type CurrencyCode =
2
  | 'AED' | 'AUD' | 'CAD' | 'CHF' | 'CNH' | 'CZK' | 'DKK' | 'EUR'
3
  | 'GBP' | 'HKD' | 'HUF' | 'ILS' | 'JPY' | 'MXN' | 'NOK' | 'NZD'
4
  | 'PLN' | 'RON' | 'SAR' | 'SEK' | 'SGD' | 'TRY' | 'USD' | 'ZAR';

Event handling

The Mangopay Elements package provides the following events that your application can rely on to manage the user’s experience.

Ready

The ready event is triggered when the form is fully loaded and interactive.

1
recipientElement.on('ready', data => {
2
  console.log('Element ID:', data.elementId);
3
});

Event data

1
interface RecipientReadyEvent {
2
  elementId: string;
3
}

Submit

The submit event is triggered when the user has filled out the form and clicks the submit button.

1
recipientElement.on('submit', data => {
2
  console.log('Form data:', data.formData);
3
});

Event data

1
interface RecipientSubmitEvent {
2
  formData: RecipientFormData;
3
}

Success

The success event is triggered when the Recipient is successfully created in Mangopay’s system:

1
recipientElement.on('success', data => {
2
  console.log('Recipient created:', data);
3
});

Event data

The success event returns the unique identifier of the Recipient (RecipientId) that you can store and use to request the User’s payouts.

1
interface RecipientSuccessEvent {
2
  [key: string]: unknown;
3
}

Error

The error event is triggered if the Recipient data is not valid after submission or if the Recipient is not created successfully.

1
recipientElement.on('error', data => {
2
  console.error('Error message:', data.message);
3
  console.error('Error details:', data.details);
4
});

Event data

1
interface RecipientErrorEvent {
2
  message: string;
3
  details?: Record<string, unknown>;
4
}

Element lifecycle methods

Troubleshooting

SDK must be initialized before creating elements

If you attempt to create an element before initialization, the SDK will throw an error.

To fix this error, ensure you call Mangopay.init() before Mangopay.createElement()

1
// ❌ Wrong
2
const element = Mangopay.createElement('recipient');
3
await Mangopay.init({});
4
5
// ✅ Correct
6
await Mangopay.init({});
7
const element = Mangopay.createElement('recipient');

Debugging

Set the debug property to true when calling MangopayInitOptions to see logs in the browser console:

1
// pass debug: true
2
// Check DevTools Console for logs, e.g:
3
// "Mangopay SDK: Initialization complete"
4
// "RecipientElement: Received message: { type: 'ready', ... }"

Verifying the element’s state

You can add these logs to your integration script to track the lifecycle of the Element in the browser’s console:

1
const element = Mangopay.createElement('recipient');
2
// 1. Verify the SDK is ready to create elements
3
console.log('SDK initialized:', Mangopay.isInitialized());
4
// 2. Trace the lifecycle of the form
5
element.on('ready', () => console.log('✅ Element ready'));
6
element.on('submit', d => console.log('📤 Submit:', d));
7
element.on('success', d => console.log('✅ Success:', d));
8
element.on('error', d => console.error('❌ Error:', d));
9
10
// 3. Attempt to mount the element
11
await element.mount('#container');