Multiple payment methods

Technical manual for integrating a payment component using multiple payment methods.

This technical manual is for integrating a payment component using multiple payment methods.

1. Add the elements

  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">
    
  2. 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>
    
  3. Add the DOM element for the component's UI in the <body> of your checkout page:

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

Choose your payment button

Decide if you want to:

  • Generate a button with the component (see Step 2 below). Recommended.

  • Use an existing button, e.g. if your checkout already includes one.

  • Create your own button:

    <button id="payment-button"></button>
    

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'
        },    
        payment_options: {
            settings: {
                connect: {
                    group_cards: true
                }
            }
        },
        template : {
            settings: {
                embed_mode: true
            }
        }
    };
    
    Properties
    KeyValue
    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. Used to validate 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 recurring model. Required for recurring payments.
    template.settings.embed_modeA template designed to blend in seamlessly with your ecommerce platform. Format: Boolean. Optional.
    payment_options.settings.connect.group_cardsGroups all credit card payment methods as a single option in the list of payment methods. Format: Boolean. Optional. Default: false.

    How to process recurring payments

    Recurring payments is a feature 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 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 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 component

Initialize the component using:

Payment component button
PaymentComponent.init('dropin', {
    container : '#MultiSafepayPayment',
    onSelect : state => {
        console.log('onSelect', state);
    }, 
    onError : state => {
        console.log('onError', state);
    },
    onLoad : state => {
        console.log('onLoad', state);
    },
    onSubmit : state => {
        if(PaymentComponent.hasErrors()) {
            let errors = PaymentComponent.getErrors();
            console.log(errors);
            return;
        }

        // Send state.paymentData to your server (createOrder)
        // Create an order from your server
        // Return the response from your server to the client-side
        // With the response, redirect the customer or log an error

        createOrder(PaymentComponent.getPaymentData()).then(response => {
            console.log(response);
            if(response.success) {
                PaymentComponent.init('redirection', {
                    order: response.data
                });
            }
        });
    }
});
Own or existing button
PaymentComponent.init('dropin', {
    container : '#MultiSafepayPayment',
    onSelect : state => {
        console.log('onSelect', state);
    }, 
    onError : state => {
        console.log('onError', state);
    },
    onLoad : state => {
        console.log('onLoad', state);
    }
});

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

Events
EventEvent handler
onLoadOccurs when the payment component UI is rendered.
onErrorOccurs when an error occurs in the payment component.
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.

The PaymentComponent has the following methods:

Methods
MethodDescription
getErrorsReturns error messages or codes
hasErrorsReturns a boolean value about whether errors were 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

Handle the interaction

Tip! This step only applies if using your own or an existing payment button.

  1. Assign the button element to a variable:

    const paymentButton = document.querySelector('#payment-button');
    
  2. Create an event handler for the payment button:

    • When the customer clicks the payment button, call the getPaymentData() method.
    • Send the response to your server and create an order.
    • Return the reponse from your server to the client-side to redirect the customer.

    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.removeAttribute('disabled');
                console.log(response);
            } else {
                PaymentComponent.init('redirection', {
                    order: response.data
                });
            }
        });
    });
    

Avoid duplicate orders

When using your own payment button, if the customer clicks it again during the latency before redirection, this creates duplicate orders.

To avoid duplicate orders, disable the button until you have attempted to create an order.
Then, check response.success:

  • If true, don't re-enable the button and proceed to the redirect.

  • If false, re-enable the button for the customer to try again.

    Redirect to 3D authentication

    The init('redirection') method redirects customers paying by credit card to the relevant page.

    If 3D Secure authentication is:

    • Required, the customer is first directed to 3D Secure. If successful, they are then redirected to the redirect_url.

    • Not required, the customer is redirected to the redirect_url.

    Redirect 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

    {
    "gateway_info":{
        "mtpinfo":"NL25DEUT7351811717",
        "reference":"9202124254788300",
        "issuer_name":"Sofortbank",
        "destination_account_id":"003001380000",
        "destination_holder_name":"MultiSafepay",
        "destination_holder_city":"Zurich",
        "destination_holder_country":"CH",
        "destination_holder_iban":"NL25DEUT7351811717",
        "destination_holder_swift":"DEUTCHZZ",
        "account_holder_name":"testperson-nl approved",
        "account_holder_city":"gravenhage",
        "account_holder_coutry":"NL"
    }
    }
    

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.

4. Go live

To test the payment methods, 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="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]fepay.com

Top of page


Did this page help you?