Single payment method

Technical manual for integrating a payment component using a single payment method.

This technical manual is for integrating a payment component using a single payment method.

1. Add the 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="">
  2. Add the component's script to the 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: 'Customer123'
        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. Optional.
    customer.localeThe customer's language. Sets the language of the payment component UI. Format: ISO-3166-1 alpha-2 , e.g. NL. Supported languages: EN, ES, FR, IT, NL. Optional.
    customer.referenceYour unique customer reference. Required for recurring payments.
    recurring.modelThe tokenization model. Required for recurring payments.
    template.settings.embed_modeA template designed to blend in seamlessly with your ecommerce platform. Format: Boolean. Optional.

    How to process recurring payments

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

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

    To process recurring payments in your payment component:

    • Add the cardOnFile recurring model

    • Provide the relevant customer.reference

      const orderData = {
          currency: 'EUR',
          amount: 10000,
          customer: {
              locale: 'en',
              country: 'NL',
              reference: 'Customer123'
          recurring: {
              model: 'cardOnFile'

    Recurring payments are supported for all credit card payments.

    Note: For test credit card details, see Test payment details – Credit and debit cards.

    To use recurring payments in your payment component, you need to enable recurring payments for your account. If you haven't already, email [email protected]

    Note: We use the orderData object to ensure the payment method is enabled and the currency, country, and transaction 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 ID
    Bank TransferBANKTRANS
    Credit cardsCREDITCARD
    SEPA Direct DebitDIRDEB
  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
    onSelectOccurs when the customer selects an issuer with iDEAL.
    onSubmitOccurs when the customer clicks the payment button (when using the button generated by the component).
    onValidationOccurs when form validation changes. Can be used to disable the payment button until all fields are validated.

    Note: 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
    getPaymentDataReturns a payment_data object with a payload containing the customer's payment details, used to create orders, and the gateway.
    getOrderDataReturns an object containing a payment_data object and the full order configuration.

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

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.

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. Handle the response:

    Bank Transfer payments

    In the gateway_info object, you receive the bank account details for the customer to wire the funds to.

    Render the account details in the interface for the customer with clear instructions. (MultiSafepay also emails these details to the customer.)

    Example gateway_info object

        "account_holder_name":"testperson-nl approved",
    Other payment methods

    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.
    • Not required, the customer is redirected to the redirect_url.

4. Go live

To test the payment method, use our Testing.

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

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

    <script src=""></script>

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

    <link rel="stylesheet" href="">
  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:



Email [email protected]

Top of page

Did this page help you?