UI widgets

Here, you can find all the available widgets that can be used to develop your store's checkout.

Montonio Checkout

This checkout widget only displays the banks for the paymentInitiation method. For other methods (cards, BLIK, financing, etc.) you should use your own UI elements.

Montonio checkout is a JavaScript SDK that provides an easy way for e-commerce stores to display a selection of bank logos to their customers during the checkout process. The SDK generates the bank logos, along with a regions dropdown and two hidden input elements - one for the chosen provider and one for the chosen region. When the user selects a bank, the value of the hidden input element is set to the identifier of the chosen bank, which you can then pass to Montonio when creating an order.

Below is an example of a checkout that utilises the SDK. Please note that the SDK solely loads the bank selection component, not the entire page displayed below.

Complete example

This is a complete example of how you could include the SDK in your stores checkout.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Montonio SDK</title>
</head>
<body>
    <form id="my-checkout" novalidate>
        <input id="montonio-checkout-user" name="montonio-checkout-user" type="text" placeholder="User" value="User" />
        <!-- This is the target div -->
        <div id="montonio-checkout"></div>
        <button type="submit">Submit</button>
    </form>

    <script>
        // Make sure to wrap your code in the window.onMontonioLoaded function
        window.onMontonioLoaded = function() {
            var checkout = Montonio.Checkout.PaymentInitiation.create({
                accessKey: 'YOUR_ACCESS_KEY',
                // The JSON string obtained from the HTTP request GET /stores/payment-methods from your backend.
                storeSetupData: 'RESULT_FROM_THE_API_CALL_IN_THE_BACKEND',
                currency: 'EUR',
                targetId: 'montonio-checkout',
                defaultRegion: 'PL',
                inputName: 'preferred-bank',
                regionInputName: 'preferred-region'
            })
            checkout.init();
        }
        // You can then listen to the submit button and get the values of the input values. 
        // The bank identifier and preferred region will appear under your specified name.
        var form = document.getElementById('my-checkout');
        form.addEventListener("submit", (e) => {
            e.preventDefault();
            var formData = form.elements;
            var output = {
                "User": form.elements['montonio-checkout-user'].value,
                "Preferred region": form.elements['preferred-region'].value,
                "Preferred provider": form.elements['preferred-bank'].value,
            }
            alert(JSON.stringify(output, null, 2))
        })
    </script>
    <!-- Don't forget to include the script tag -->
    <script src="https://public.montonio.com/assets/montonio-js/1.x/montonio.bundle.js"></script>
</body>
</html>

storeSetupData is the JSON string that is returned from the /stores/payment-methods request. You should fetch the data from this endpoint on the backend and pass it to the front-end. Read more here.

Including the SDK

The SDK can be included in your HTML file with a script tag. The script tag should be included in the very bottom of the body.

Methods

create()

Before creating an instance for your checkout, you must create a div element and assign it an ID. Once this is done, you can use the create method provided by Montonio.Checkout.PaymentInitiation. To ensure proper functionality, the code has to be wrapped in a window.onMontonioLoaded function.

createOptions

The following table describes the fields that can be used to create a checkout instance.

Key	Type	Description	Default value
storeSetupData*	`string`	The JSON string obtained from the HTTP request GET /stores/payment-methods. Read more here.	Providing storeSetupData is mandatory and does not have a default value.
accessKey	`string`	Your Access Key obtained from the Partner System.	-
targetId	`string`	This refers to the ID of the div element where the payment methods will be displayed.	`montonio-payment-choices-container`
target	`HTMLElement`	The target div element can be used as an alternative to the `targetId` parameter.	-
shouldAllowDeselection	`boolean`	When this is set to `true`, banks can be toggled between selected and unselected.	`false`
shouldInjectCSS	`boolean`	If this is set to `false` then CSS doesn't get injected by the SDK. You can include the stylesheet yourself by liknking it from here.	`true`
currency	`EUR, PLN`	The currency that your store operates in. This will be used to only load the banks that support your provided currency.	`EUR`
description	`string`	You can insert a description that will appear between the `select` element and the bank logos.	-
defaultRegion	`EE, LV, LT, DE, FI, PL`	This refers to the default region of banks that you want to be displayed on your checkout page.	`EE`
regions	`[EE, LV, LT, DE, FI, PL]`	This refers to the available regions of banks for the checkout process.	`[EE, LV, LT, DE, FI, PL]`
regionNames	`{"EE" : "Eesti"}`	Translations for country dropdown in a key value pair. The available regions are defined in the regions property.	-
inputName	`string`	This is the name of the hidden input element created by the SDK that that contains the code of the selected bank.	`montonio-payment-initiation-preferred-provider`
regionInputName	`string`	This is the name of the hidden input element created by the SDK that contains the value of the preferred region.	`montonio-preferred-region`
onRegionSelectorChange	`Function`	This is a function that will be called every time the user changes the selector option.	-
onProviderClick	`Function`	This is a function that will be called every time the user clicks on a bank.	-
onLoaded	`Function`	This is a function that will be called once the bank logos are successfully loaded.	-

init()

Once the init() method is called, payment methods will be generated on your site. It's important to note that all configuration should be completed before calling the init() method. The init() method does not require any parameters.

getPreferredProvider()

This method returns the preferred provider as a string. This enable you to use the SDK outside of a form element.

getPreferredRegion()

This method returns the preferred region.

update(options)

This method enables you to update the SDK. You can provide the options you want to change in the parameters of this method.

setPreferredRegion(region, shouldUpdateSessionStorage: `boolean`)

When this method is called, the user will be shown the banks of the region provided in the parameters. When shouldUpdateSessionStorage is set to false, the method doesn't overwrite the users sessionStoraga. By default, when calling the method, the region that is saved in the user's sessionStorage gets overwriten.

setPreferredProvider(code, shouldUpdateSessionStorage: `boolean`)

When this method is called, the bank with the given code will be preselected for the user. By default, this method also overwrites the provider the user has saved in their sessionStorage. If shouldUpdateSessionStorage is set to false, the sessionStorage does not get updated. Please note that unless setProvider() is used in combination with setRegion(), the bank will be chosen from the region that the user is currenly viewing, if such bank exists.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Montonio SDK</title>
</head>
<body>
        <!-- This is the target div -->
        <div id="montonio-checkout"></div>
    <script>
        var alertPreferences = function() {
            var output = {
                "Preferred region": window.checkoutInstance.getPreferredRegion(),
                "Preferred provider": window.checkoutInstance.getPreferredProvider(),
            };
            alert(JSON.stringify(output, null, 2));
        }
        var selectorChange = function() {
            var newRegion = this.getPreferredRegion()
            if (newRegion == 'PL') {
                this.update({
                    currency: 'PLN'
                })
            }
        }
        // Make sure to wrap your code in the window.onMontonioLoaded function
        window.onMontonioLoaded = function() {
            checkout = Montonio.Checkout.PaymentInitiation.create({
                accessKey: 'YOUR_ACCESS_KEY',
                // The JSON string obtained from the HTTP request GET /stores/payment-methods from your backend.
                storeSetupData: 'RESULT_FROM_THE_API_CALL_IN_THE_BACKEND',
                targetId: 'montonio-checkout',
                onProviderClick: alertPreferences,
                onRegionSelectorChange: selectorChange,
                onLoaded: function() {
                    alert('SDK loaded')
                }
            })
            checkout.init();
            window.checkoutInstance = checkout;
        }
    </script>
    <script src="https://public.montonio.com/assets/montonio-js/1.x/montonio.bundle.js"></script>
</body>
</html>

Creating multiple instances

The Montonio Checkout SDK allows for the creation of multiple instances of the bank selection feature. There are several ways to achieve this, one of which is demonstrated below as an example.

Please note that it is important that all the target containers have unique ids.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Montonio SDK</title>
</head>
<body>
    <div class="montonio-checkout" id="montonio-checkout-1"></div>
    <div class="montonio-checkout" id="montonio-checkout-2"></div>
    <div class="montonio-checkout" id="montonio-checkout-3"></div>
    <script>
        window.onMontonioLoaded = function() {
            var checkoutTargets = document.querySelectorAll('.montonio-checkout');
            var checkoutInstances = [];
            for (var i = 0; i < checkoutTargets.length; i++) {
                checkoutInstances.push(Montonio.Checkout.PaymentInitiation.create({
                    accessKey: 'YOUR_ACCESS_KEY',
                    // The JSON string obtained from the HTTP request GET /stores/payment-methods from your backend.
                    storeSetupData: 'RESULT_FROM_THE_API_CALL_IN_THE_BACKEND',
                    target: checkoutTargets[i],
                    defaultRegion: 'EE'
                }))

                checkoutInstances[i].init();
            }
        }
    </script>
    <script src="https://public.montonio.com/assets/montonio-js/1.x/montonio.bundle.js"></script>
</body>
</html>

UI widgets

Montonio Checkout

This could be your checkout!

Choose your bank:

Complete example

Including the SDK

Methods

create()

createOptions

init()

getPreferredProvider()

getPreferredRegion()

update(options)

setPreferredRegion(region, shouldUpdateSessionStorage: `boolean`)

setPreferredProvider(code, shouldUpdateSessionStorage: `boolean`)

Creating multiple instances

Montonio Checkout​

This could be your checkout!

Choose your bank:

Complete example​

Including the SDK​

Methods​

create()​

createOptions​

init()​

getPreferredProvider()​

getPreferredRegion()​

update(options)​

setPreferredRegion(region, shouldUpdateSessionStorage: boolean)​

setPreferredProvider(code, shouldUpdateSessionStorage: boolean)​

Creating multiple instances​

Montonio Checkout

Complete example

Including the SDK

Methods

create()

createOptions

init()

getPreferredProvider()

getPreferredRegion()

update(options)

setPreferredRegion(region, shouldUpdateSessionStorage: `boolean`)

setPreferredProvider(code, shouldUpdateSessionStorage: `boolean`)

Creating multiple instances