SolutionsSystem status
Documentation
Create accountContact

    Payment components: user guide

    MultiSafepay's Payment Component

    Our payment components lets you seamlessly embed your payment methods in your checkout.

    Single vs. Multiple payment components

    You can include one or multiple payment methods:

    • Single payment components: Renders one specific payment method in your checkout using the init(payment) property. This solution requires the GATEWAY to be included in the component.

    • Multiple payment components: Renders all available payment methods in a list using the init(dropin) method. The solution does not require you to provide the GATEWAY parameter. Our SDK automatically fetches the available payment methods retrieved from the payload and displays them in your checkout.

      Check our Github repository where you can find more examples for Multiple payment components:

    Check the samples below to see a preview:

    User guide

    1. Add the HTML elements

    Add the following elements to your checkout page:

    1. Add the component's CSS to the <head> of your checkout page:
    <link rel="stylesheet" href="https://testpay.multisafepay.com/sdk/components/v2/components.css">
    1. Add the component's script to the bottom of the <body> of your checkout page:
    <script src="https://testpay.multisafepay.com/sdk/components/v2/components.js"></script>
    1. Add the DOM element for the component's UI in the <body> of your checkout page:
    <div id="MultiSafepayPayment"></div>

    2. Initialize the component

    a. Generate an API token

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


    b. 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: 'de_De',
  	country: 'DE'
	}
};

    Properties

    KeyRequiredValue
    amountYesThe value of the order.
    Format: Number without decimal points, e.g. 100 euro is formatted as 10000
    currencyYesThe currency of the order.
    Format: ISO-4217 , e.g. EUR
    customer.countryNoThe customer's country code. Checks the availability of the payment method.
    Format: ISO-3166-1 alpha-2 , e.g. NL
    customer.localeNoThe customer's language. Sets the language of the payment component UI.
    Format: ISO 639 language codes and ISO 3166 country codes.
    Supported languages: en_EN, es_ES, fr_FR, it_IT, nl_NL
    recurring.modelYes, for recurring paymentsThe tokenization model.
    1. Construct a PaymentComponent object in the test environment using the order object and your API token:
    const PaymentComponent = new MultiSafepay({
    env: 'test',
    order: orderData,
    apiToken: apiToken,
    recurring: recurringData //only for recurring payments
});

    Recurring payments

    Recurring payments is a solution that lets you store a customer’s payment details as a secure, encrypted token.

    Upon subsequent payments, customers can select their stored payment details and pay with a single click.

    To use recurring payments in your payment components, initialize the component using the recurring object.

    How to process recurring payments in your payment component
    • Add your recurring model:
      • cardOnFile
      • subscription
      • unscheduled
    • Make List tokens request from your server and provide atokens. Check the example below:
      const orderData = {
    currency: 'EUR',
    amount: 10000,
    customer: {
        locale: 'en',
        country: 'NL'
    },
    template: {
        settings: {
            embed_mode: true
        }
    }
};

const recurringData = {
    model: "cardOnFile",
    tokens: [
        {
            token: "AvqeOjgdm8A",
            code: "IDEAL",
            display: "xxxxxxxxxNL81PSTB0000012345",
            bin: null,
            name_holder: "Schilder",
            expiry_date: "",
            expired: 0,
            last4: null,
            model: "cardOnFile"
        },
        {
            token: "BcEWsknWsYg",
            code: "MASTERCARD",
            display: "Card xxxx xxxx xxxx 4444",
            bin: 555555,
            name_holder: "Holder",
            expiry_date: 2412,
            expired: 0,
            last4: 4444,
            model: "cardOnFile"
        }
    ]
};


    c. Initialize the component

    1. Call the PaymentComponent.init() method and include the required container and gateway parameters:

      PaymentComponent.init('payment', {
    container: '#MultiSafepayPayment',
    gateway: '<GATEWAY>'
});

      Check the table below lo learn more about the components properties:

      PropertyTypeDescription
      init('payment')MethodThe method that initializes the core payment module and boots the necessary library dependencies
      containerParameterSpecifies the target DOM element where the component will be injected
      gatewayParameterDefines the payment method used for the transaction

    2. Replace the <GATEWAY> placeholder with the relevant payment gateway identifier.

      Payment methodGateway ID
      Bank transferBANKTRANS
      BancontactMISTERCASH
      Betaal per maandSANTANDER
      Card paymentsCREDITCARD
      Direct debitDIRDEB
      iDEALIDEAL
      In3IN3
      PayPalPAYPAL
      Google PayGOOGLEPAY
      Apple PayAPPLEPAY

    3. Define event handlers to respond to specific component actions:

      Event HandlerDescription
      onEventOccurs when there is a state change in the component (e.g., a successful payment).
      onGetQROccurs when the QR is rendered in the payment component.
      onErrorOccurs when there is an error in the payment component.
      onLoadOccurs when the payment component UI is rendered.
      onSelectOccurs when the customer selects an issuer with iDEAL.
      onValidationOccurs when form validation changes. Can be used to disable the payment button until all fields are validated.

      Example

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

    Wallet payment buttons

    Wallet payment buttons (such as Google Pay and Apple Pay) are independent from the regular Pay button in your webshop. The following onEvent handler serves as a trigger that detects when a wallet payment has been successfully authorized, sends the payment data to your backend to create or update the order, and then continues the flow by initiating a redirection:

    ...
onEvent: function (state) {
  if (state) {
            try {
                if (state.type == 'payment' && state.success && state.data.paymentData) {
                    setOrder(PaymentComponent.getOrderData 
                        ? PaymentComponent.getOrderData() 
                        : PaymentComponent.getPaymentData()
                        ).then(response => {
                        if (response.success) {
                            PaymentComponent.init('redirection', {
                                order: response.data,
                                settings: redirectSettings.settings
                              });
                          }
                      });
                  }
              } catch (e) {
                  console.log(e);
              }
          }
},
...

    The state of the wallet button can be controlled using setState. For example, you can disable the button until a condition is met, such as the customer accepting your Terms & Conditions. This allows you to establish prerequisites before the payment flow is started, even though the wallet button itself is managed by the SDK.

    PaymentComponent.setState({
    payment_button: {
        enabled: 0 | 1
    }
})

    Methods

    The PaymentComponent has the following methods:

    MethodDescription
    getErrorsReturns error messages or codes.
    hasErrorsReturns a boolean value indicating whether errors were registered.
    getOrderDataReturns an object containing a payment_data object and the full order configuration.
    getPaymentDataReturns a payment_data object with a payload containing the customer's payment details, used to create orders, and the gateway.
    setQR()Returns a boolean to set up the QR code. Requires argument orderData.
    If orderData is not sent, the payment will not be associated with the order.
    setStateAllows you to control the state of payment buttons rendered by the wallet, such as enabling or disabling them.
    getStateReturns the current state of the payment component or buttons.

    3. Create the order

    Handle the interaction

    1. Assign the button element to a variable:
     const paymentButton = document.querySelector('#payment-button');
    1. When the customer clicks the button, call getPaymentData() to retrieve the necessary encrypted payload to send to your server.

    Payment data parameters:

    KeyRequiredDescription
    gatewayYesThe unique gateway_id to redirect the customer to the specific payment method.
    payloadYesInformation required to process the payment.
    ⚠️ Note: Do not edit or modify the payload or otherwise the payment fails.
    tokenizeOptionalFor
    1. Create an event handler for the payment button:
    • When the customer clicks the payment button, call the component's getPaymentData() method.
    • Send the response to your server and create an order.
    • Return the response from your server to the client-side to redirect the customer.

    4. Complete the order

    Once the customer initiates the payment, your integration must handle two critical tasks: preventing duplicate transactions and managing the post-order redirection.

    a. Handle the submission

    To ensure a correct payment flow, disable your payment button upon clicking. This prevents order duplications in our system.

    • If response.success is false, re-enable the button so the customer can correct their details or try again.
    • If response.success is true, disable the button and proceed to the redirection handler.

    b. Redirect the customer

    By passing your server's response to init('redirection'), the component automatically determines the next step based on the payment method:

    • Authentication: Automatically redirects to 3D Secure (Cards) or Issuer pages (iDEAL).
    • Frictionless: Redirects directly to your defined redirect_url (Success page).
    • Information Display: Renders Bank Transfer details or QR Codes directly within the component container if applicable.

    Implementation example

    paymentButton.addEventListener('click', e => {
      paymentButton.addAttribute('disabled');
      if (PaymentComponent.hasErrors()) {
          let errors = PaymentComponent.getErrors();
          console.log(errors);
          return false;
      }
      createOrder(PaymentComponent.getPaymentData()).then(response => {
          if(!response || !response.success) {
              paymentButton.disabled = false;
              console.log(response);
          } else {
              PaymentComponent.init('redirection', {
                  order: response.data
              });
          }
      });
  });

    c. Create an order

    Create an order from your server, appending the payment_data collected from the payment component UI to the order data.

    See API reference – Create order > Payment component.


    5. Go live

    To test the payment methods, see Testing payment methods.

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

    1. In Step 1: Add the elements, replace the test JavaScript library with the live JavaScript library:

      <script src="https://pay.multisafepay.com/sdk/components/v2/components.js"></script>

      Next, replace the test CSS file with the live CSS file:

      <link rel="stylesheet" href="https://pay.multisafepay.com/sdk/components/v2/components.css">

    2. In Step 2: Construct the component object, change the environment from test to live:

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

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

      https://api.multisafepay.com/v1/json/orders

    💬

    Support

    Email [email protected]

    Updated 5 days ago