Integrating multiple payment methods

To integrate a Payment Component into your checkout for multiple payment methods, follow these steps:

Step 1: Install

Generate an API token

Payment Components require a MultiSafepay API token. See API Reference - Generate an API token.

Note: To keep your API key private, request the token from your own server.

Add elements to your checkout page

1. Add the Payment Component CSS to the <head> of your checkout page:

link rel="stylesheet" href="">

2. Add the Payment Component script to the bottom of the <body> of your checkout page:

<script src=""></script>

Note: If you choose to host the Payment Component library on your own server, MultiSafepay is no longer responsible for PCI DSS compliance.

3. Add the DOM element for the Payment Component UI in the <body> of your checkout page:

<div id="MSPPayment"></div>

Step 2: Initialize

Construct the Payment Component object

1. Initialize an orderData object containing information about the customer’s order collected during the checkout process:

const orderData = {
    currency: 'EUR',
    amount: 10000,
    customer: {
        locale: 'EN',
        country: 'NL',
        reference: 'Customer123'
    template : {
        settings: {
            embed_mode: true
View properties

Key Value
currency Currency of the order. Format: ISO-4217, e.g. EUR. Required.
amount Value of the order. Format: Number without decimal points, e.g. 100 euro is formatted as 10000. Required. Customer’s country code. Used to validate the availability of the payment method. Format: ISO-3166-1 alpha-2, e.g. NL. Required.
customer.locale Customer’s language. Used to set the language of the Payment Component UI. Format: ISO-3166-1 alpha-2, e.g. NL. Supported languages: EN, ES, FR, IT, NL. Optional.
template.settings.embed_mode A template designed to blend in seamlessly with your ecommerce platform. Format: Boolean. Optional.

Note: We use the orderData object to ensure the payment methods are enabled, e.g. for the currency, country, and transaction value.

2. Construct a PaymentComponent object in the test environment using the orderData object and your API token:

PaymentComponent = new MultiSafepay({
    env: 'test',
    apiToken: apiToken,
    order: orderData

Initialize the Payment Component

1. To retrieve a list of available payment gateways, make a /connect/payments/methods request from your server, specifying the country, currency, and amount of the order:

curl -X GET "" \
-H "accept: application/json" \
-H "Authentication: Bearer <your-website-API-key>" \
-d ' \
  "country": "NL",
  "currency": "EUR",
  "amount": "10000"

From your server, pass the gateways_response to the request to the customer’s device.

2. Call the PaymentComponent.init() method with the following arguments:

PaymentComponent.init('dropin', {
    container: '#MSPPayment',
    gateways: gateways_response,
    onLoad: state => {
        console.log('onLoad', state);
    onError: state => {
        console.log('onError', state);

In the method call, create event handlers for the following events:

View events

Event Event handler
onError Called when an error occurs in the Payment Component
onSubmit Called when the customer selects a payment method
onLoad Called when the Payment Component UI is rendered

The PaymentComponent uses the following methods:

View methods

Method Description
getErrors Returns error messages or codes.
hasErrors Returns a boolean value about whether errors were registered.
getPaymentData Creates a payload object with the customer’s payment details. Used to create orders.

Step 3: Redirect to pay

Collect payment data

1. To collect the customer’s payment details from the Payment Component UI, call the PaymentComponent.getPaymentData() method:


2. Pass the payment_data to your server.

Create an order

Make a POST /orders request from your server:

  • Append the payment_data collected from the Payment Component UI to the orderData collected during the checkout process.
  • Replace the <GATEWAY> placeholder with the relevant gateway code, see Step 2: Initialize the Payment Component.
curl -X POST "" \
-H "accept: application/json" \
-H "Content-Type: application/json" \
-H "Authentication: Bearer <your-website-API-key>" \
-d " \
    "type": "direct",
    "order_id": "my-order-id-1",
    "currency": "EUR",
    "amount": "10000",
    "description": "Test Order Description",
    "payment_data": {
       "payload": "{secure_payload}"

Redirect the customer

1. From your server, pass the response to the POST /orders request to the customer’s device.

2. Check that response.success is true.

3. Call the PaymentComponent.init() method using the following arguments:

PaymentComponent.init('redirection', {
  • If 3D Secure verification is required, the customer is first directed to 3D Secure. If successful, the customer is then redirected to the redirect_url.

  • If 3D Secure is not required, the customer is redirected to the redirect_url.

Step 4: Go live

When you’re ready to process real payments, make the following changes:

1. In Step 2: Construct the Payment Component object, change the environment from test to live:

PaymentComponent = new MultiSafepay({
    env: 'live',
    apiToken: apiToken,
    order: orderData

2. In Step 3: Create an order, change the test endpoint to the live endpoint:

Next steps


Our documentation is open source.

Create issue in GitHub

Other languages

For an explanation in another language, contact your account manager.