Integrating a single payment gateway

To integrate a Payment Component into your checkout for a single payment method, 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 check 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 method is 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

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

PaymentComponent.init('payment', {
    container: '#MSPPayment',
    gateway: '<GATEWAY>',
    onLoad: state => {
        console.log('onLoad', state);
    onError: state => {
        console.log('onError', state);

Replace the <GATEWAY> placeholder with the relevant payment gateway code.

View gateway codes

Payment method Gateway code
Credit card CREDITCARD
Paysafecard ???
Request to Pay DBRTP
E-invoicing EINVOICE
in3 IN3
Pay After Delivery PAYAFTER

Create event handlers for the following events:

View events

Event Event handler
onError Called when an error occurs in the Payment Component
onLoad Called when the Payment Component UI is rendered

The PaymentComponent uses the following methods:

View methods

Method Description
getErrors Returns error details, like error messages or codes.
hasErrors Returns a boolean value depending on whether errors have been 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",
    "gateway": "<GATEWAY>",
    "currency": "EUR",
    "amount": "100",
    "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 the customer needs to perform additional actions, they are redirected, e.g. to the payment_url or 3D Secure. Then, if successful, they are redirected to the redirect_url.

  • If no further action is 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.