Previous release

Technical manual for integrating the previous release of the payment component.

This technical manual is for integrating the previous release of the payment component.

1. Add the elements

  1. Add the component's CSS to the <head> of your checkout page:

    <link rel="stylesheet" href="">
  2. Add the component's script tothe bottom of the <body> of your checkout page:

    <script src=""></script>
  3. Add the DOM element for the component's UI in the <body> of your checkout page:

    <div id="MultiSafepayPayment"></div>

2. Initialize the component

Generate an API token

Payment Components require a MultiSafepay API token. See API reference – Generate an API token.

✅   Tip! To keep your API key private, request the token from your own server.

Construct the 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: 's9Q8ikjFJBCX'
       template : {
           settings: {
               embed_mode: true
    currencyThe currency of the order. Format: ISO-4217 , e.g. EUR. Required.
    amountThe value of the order. Format: Number without decimal points, e.g. 100 euro is formatted as 10000. Required.
    customer.countryThe customer's country code. Checks the availability of the payment method. Format: ISO-3166-1 alpha-2 , e.g. NL. Required.
    customer.localeThe customer's language. Sets the language of the payment component UI.
    Format: ISO 639
    Supported languages: en, es, fr, it, nl. Optional.
    template.settings.embed_modeA 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 and the currency, country, and order amount are supported.

  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 component

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

    PaymentComponent.init('payment', {
        container: '#MultiSafepayPayment',
        gateway: '<GATEWAY>',
        onLoad: state => {
            console.log('onLoad', state);
        onError: state => {
            console.log('onError', state);
  2. Replace the <GATEWAY> placeholder with the relevant payment gateway identifier.

    Gateway IDs
    Payment methodGateway IDs
    Card paymentsCREDITCARD
  3. Create event handlers for the following events:

    EventEvent handler
    onErrorCalled when an error occurs in the payment component
    onLoadCalled when the payment component UI is rendered

    The PaymentComponent uses the following methods:

    getErrorsReturns error details, e.g. error messages or codes.
    hasErrorsReturns a boolean value depending on whether errors have been registered.
    getPaymentDataCreates a payload object with the customer's payment details, used to create orders

3. Create an order

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 Create order > Payment component 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 identifier, see Step 2: Initialize the component.

    curl -X POST "" \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "api_key: <your-website-API-key>" \
    --data-raw '{
        "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 create order 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 to the relevant page, e.g. 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.

4. Go live

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

  1. In Step 2: Construct the 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:



Email [email protected]

Top of page