NAV Navbar
javascript php python

Introduction

Welcome to the Montonio API Developer Documentation. This docs provides an overview of our application flow. See the examples, requests & implementations below.

If you have any questions regarding the docs, please contact our software development team member Henrik Rank at henrik@montonio.com.

To sign up or test our service, please contact our sales team member Karel Nappus at karel@montonio.com.

API Keys

Montonio uses API keys to allow access to the API. The keys can be acquired for 2 environments: Sandbox and Production.
Sandbox (used for testing and development) - Get the keys from Montonio Sandbox Partner System
Production (used for production with real offers) - Get the keys from Montonio Partner System

When generating new keys, the old ones will get invalidated.

API Environments and Specs

Montonio has a RESTful API, which inputs and outputs JSON data.
Here are the API URLs for our environments:

Generating the X-Signature Header

const crypto = require('crypto');
const secretKey = '2lJ64EFaIXaLhBnx6EQYiq1702YxL2DgWEJ9FqWJ77WP';

function createSignature($body, $secretKey) {
    try {

        let hmac = crypto.createHmac('sha256', $secretKey);
        hmac.update(JSON.stringify($body));
        let signature = hmac.digest('hex');

        return signature

    } catch (error) {
        console.log(error)
        // ...
        return null
    }
}

let body = {
    "origin":"online",
    "merchant_reference":"O036869",
    "customer_first_name":"John",
    "customer_last_name":"Smith",
    "customer_email":"info@montonio.com",
    "customer_phone":"5555555",
    "customer_city":"Tallinn",
    "customer_address":"Telliskivi 60a",
    "customer_postal_code":"10412",
    "products":[
        {
            "product_name":"Shiny New Computer T490s",
            "product_price":1578.85,
            "quantity":2
        },
        {
            "product_name":"Standard delivery charges",
            "product_price":5,
            "quantity":1
        }
    ]
}

let xSignature = createSignature(body, secretKey);
console.log(xSignature);
// 5de3c8c592a4aa9b0bf1e459fc31d2ffbccb22cc8bca93fd7051a18fdfed7414
<?php
function _generateSignature($secretKey, $data)
{
    return hash_hmac('sha256', $data, $secretKey);
}

$xSignature = _generateSignature("2lJ64EFaIXaLhBnx6EQYiq1702YxL2DgWEJ9FqWJ77WP", '{"origin":"online","merchant_reference":"O036869","customer_first_name":"John","customer_last_name":"Smith","customer_email":"info@montonio.com","customer_phone":"5555555","customer_city":"Tallinn","customer_address":"Telliskivi 60a","customer_postal_code":"10412","products":[{"product_name":"Shiny New Computer T490s","product_price":1578.85,"quantity":2},{"product_name":"Standard delivery charges","product_price":5,"quantity":1}]}');

echo $xSignature;
// 5de3c8c592a4aa9b0bf1e459fc31d2ffbccb22cc8bca93fd7051a18fdfed7414

?>
# import crypto dependencies
import hmac
import hashlib

def _generate_signature(secret_key, data):
    ''' Method for generating HMAC-SHA256 signatures for requests. '''
    sha_signature = \
        hmac.new(str.encode(secret_key), str.encode(
            data), hashlib.sha256).hexdigest()
    return sha_signature

_x_signature = _generate_signature("2lJ64EFaIXaLhBnx6EQYiq1702YxL2DgWEJ9FqWJ77WP", '{"origin":"online","merchant_reference":"O036869","customer_first_name":"John","customer_last_name":"Smith","customer_email":"info@montonio.com","customer_phone":"5555555","customer_city":"Tallinn","customer_address":"Telliskivi 60a","customer_postal_code":"10412","products":[{"product_name":"Shiny New Computer T490s","product_price":1578.85,"quantity":2},{"product_name":"Standard delivery charges","product_price":5,"quantity":1}]}')
print(_x_signature) 
# 5de3c8c592a4aa9b0bf1e459fc31d2ffbccb22cc8bca93fd7051a18fdfed7414

The X-Signature header guarantees us that API calls are initiated by you.

We use HMAC-SHA256 for the signature. The key for HMAC is the API Secret Key obtained from the partner system. The message for HMAC depends on the request method.

For GET requests, see the components for the HMAC-SHA256 message on a per-endpoint basis.

For POST requests, the message is the stringified HTTP request body.

The exact implementation of how to generate these hashes varies by programming language and you can see some examples on the code panel. Don't forget to choose your language of choice! 🙂

Integrating with Montonio

There are 2 main methods of integrating your site with Montonio:

  1. Redirect: The recommended method is to redirect the customer to Montonio to fill in the loan application, and redirect back to your store for verification after the loan agreement has been signed.
  2. Iframe: You can also open our application in an iframe. Integrating is only a matter of importing our Montonio JS SDK and implementing some methods. See details on how to use Montonio in an iframe in the corresponding section below.

The Complete Flowchart

Here is a flowchart describing how communication between Montonio and your webstore looks like.
Don't worry, we will break it down for you 🙈.

alt text

Starting the Flow: Creating an Application Draft

This endpoint submits checkout data to the API. An access_token is returned.

Headers for the request:

  Content-Type: application/json
  X-Access-Key: 3d5c50ef-06a5-4156-9688-f6d0056e9135
  X-Signature: 96e5460184e7dfed795b18c2aa1e33da0b4b749b1236a15a4bc70a2883a4b186

Example post data:

{
    "origin":"online",
    "merchant_reference":"O036869",
    "customer_first_name":"John",
    "customer_last_name":"Smith",
    "customer_email":"info@montonio.com",
    "customer_phone":"5555555",
    "customer_city":"Tallinn",
    "customer_address":"Telliskivi 60a",
    "customer_postal_code":"10412",
    "callback_url": "https://mystore.com/montonio/payment/return?orderId=O036869",
    "notification_url": "https://mystore.com/montonio/payment/webhook?orderId=O036869",
    "products":[
        {
            "product_name":"Shiny New Computer T490s",
            "product_price":1578.85,
            "quantity":2
        },
        {
            "product_name":"Standard delivery charges",
            "product_price":5,
            "quantity":1
        }
    ],
    "timestamp": "2019-10-31T12:00:57+0200"
}

Example response:

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6ImFjY2VzcyJ9.eyJzZXNzaW9uSWQiOiI5OTdlZjFmOS04OTU1LTQyMTYtYTliZi00MzZiMzFmZTAyMDIiLCJpYXQiOjE1NzAxODY1MTUsImV4cCI6MTU3MDQ0NTcxNSwiYXVkIjoiaHR0cDovL2xvY2FsaG9zdCIsImlzcyI6ImZlYXRoZXJzIiwic3ViIjoiYW5vbnltb3VzIiwianRpIjoiYmJlMjJiMDMtYTA0ZS00YzBiLWFiZmMtZGNmZGY4OGRiYWM0In0.bOSUBA5jUd96XqBocspCHlYcoRXwt3Q6HbzsY4mabQc"
}

HTTP Request

POST [API_URL]/applications

Headers

Key Required Value Description
Content-Type yes application/json Set the content type
X-Access-Key yes UUIDv4 The Access Key from Partner System
X-Signature yes Hash HMAC-SHA256(Post Data, Secret Key)

Post Data

Key Required Type Description
origin yes string Origin must be the string "online"
merchant_reference yes string The order reference in the merchant system
customer_first_name no string The first name of the customer
customer_last_name no string The last name of the customer
customer_email no string The email of the customer
customer_phone no string The phone number of the customer
customer_city no string The city of the customer address
customer_address no string The address of the customer
customer_postal_code no string The postal code (zip) of the customer
callback_url no string The URL to redirect back to from Montonio application
notification_url no string The URL to send a webhook notification to once a loan agreement has been signed. See below for details
products yes array Array of products, see below
timestamp yes string ISO 8601 timestamp of current time

Post Data: Products

Key Required Type Description
product_name yes string The product's name
product_price yes float %.2f The product's sale price (tax included)
quantity yes integer Quantity of this product

Redirect flow

An easy way to integrate with Montonio is to redirect the customer from your store to Montonio Application URL.
Append the access_token as a query parameter.

The Montonio Application URLs for the two environments are:

  1. Sandbox: https://sandbox-application.montonio.com
  2. Production: https://application.montonio.com


Example: https://application.montonio.com?access_token=eyJhbGciOiJIUzI1NiIsInR5cCI6ImFjY2VzcyJ9.eyJzZXNzaW9uSWQiOiI5OTdlZjFmOS04OTU1LTQyMTYtYTliZi00MzZiMzFmZTAyMDIiLCJpYXQiOjE1NzAxODY1MTUsImV4cCI6MTU3MDQ0NTcxNSwiYXVkIjoiaHR0cDovL2xvY2FsaG9zdCIsImlzcyI6ImZlYXRoZXJzIiwic3ViIjoiYW5vbnltb3VzIiwianRpIjoiYmJlMjJiMDMtYTA0ZS00YzBiLWFiZmMtZGNmZGY4OGRiYWM0In0.bOSUBA5jUd96XqBocspCHlYcoRXwt3Q6HbzsY4mabQc

Iframe flow

Montonio JS SDK

Use the HTML <script> tag to include our SDK.

<script type="text/javascript" src="https://public.montonio.com/assets/js/production/montonio-sdk.min.js"></script>

After successfully posting the checkout data and creating an application draft, as described the previous section, it is time to import our JavaScript SDK into your application and open the gateway.

The SDK location is the same for both environments and can be fetched from
https://public.montonio.com/assets/js/production/montonio-sdk.js
or
https://public.montonio.com/assets/js/production/montonio-sdk.min.js
for the minified version.

Setting up the gateway

var $environment = 'production' // or 'sandbox'
var $access_token = "eyJhbGciOiJIUzI1NiIsInR5cCI6ImFjY2VzcyJ9.eyJzZXNzaW9uSWQiOiI5OTdlZjFmOS04OTU1LTQyMTYtYTliZi00MzZiMzFmZTAyMDIiLCJpYXQiOjE1NzAxODY1MTUsImV4cCI6MTU3MDQ0NTcxNSwiYXVkIjoiaHR0cDovL2xvY2FsaG9zdCIsImlzcyI6ImZlYXRoZXJzIiwic3ViIjoiYW5vbnltb3VzIiwianRpIjoiYmJlMjJiMDMtYTA0ZS00YzBiLWFiZmMtZGNmZGY4OGRiYWM0In0.bOSUBA5jUd96XqBocspCHlYcoRXwt3Q6HbzsY4mabQc";

// A Montonio instance is already available after including the script
Montonio.init();
Montonio.setEnvironment($environment);
Montonio.prepareDraftToken($access_token);
Montonio.addBackdrop();
Montonio.openModal();

To initialize and open the gateway, run the sequence as shown on the code preview on the right:
Please note, that the Montonio.setEnvironment() function expects a string of either production or sandbox as parameter.

A Demo application of our gateway can be downloaded from here

Window functions

Example implementation of window functions using jQuery


// The url to redirect the user to 
// after the order status has been updated
window.montonio_complete_url = null;

// The method which calls for checking the application status in
// Montonio's API and returns a redirect url.
window.updateMerchantSystem  = function() {
    jQuery.post('https://mystore.com/montonio/validate', {order_id: $orderId}, function(response) {
        try {
            var parsed = JSON.parse(response);
            if (parsed.status == "OK") {
                window.montonio_complete_url = parsed.data;
            } else {
              // some error occurred while validating, redirect immediately
                window.location = parsed.data;
            }
        } catch(err) {
            // should not reach here, unable to parse JSON
            window.location = 'https://mystore.com/error';
        }
    })
}

// What to do when user closes the iframe 
// before a decision has been reached
window.userClosedGateway = function() {
    Montonio.removeBackdrop();
}

// What to do after the user presses
// "Return to merchant"
window.completedFunction = function() {
    if (window.montonio_complete_url) {
        window.location = window.montonio_complete_url;
    }
}

// register handle for reopening modal
jQuery(document).on('click', '#montonio-open-modal', function(e) {
    initMontonio();
})

// Check that Montonio SDK is loaded and init by default
if (Montonio) {
    initMontonio();
}
else throw new Error('Unable to load Montonio SDK');

// Function to init Montonio gateway
function initMontonio() {
    Montonio.init();
    Montonio.setEnvironment($env);
    Montonio.prepareDraftToken($draftToken);
    Montonio.addBackdrop();
    Montonio.openModal();
}

Montonio Gateway's <iframe> uses the browser's window messages to communicate with the merchant system.

Consider implementing the following methods to react to events and changes in the application process.

Validating Application Status

Headers for the request:

  X-Access-Key: 3d5c50ef-06a5-4156-9688-f6d0056e9135
  X-Signature: 96e5460184e7dfed795b18c2aa1e33da0b4b749b1236a15a4bc70a2883a4b186

Example request

curl -X GET \
  '[API_URL]/applications?merchant_reference=140' \
  -H 'X-Access-Key: 3d5c50ef-06a5-4156-9688-f6d0056e9135' \
  -H 'X-Signature: 96e5460184e7dfed795b18c2aa1e33da0b4b749b1236a15a4bc70a2883a4b186' \

Example response:

{
    "merchant_reference": "140", 
    "loan_amount": "3162.70", 
    "status": "signed", 
    "currency_code": "EUR"
}

Montonio API provides an endpoint to check the financing application's status.

HTTP Request

GET [API_URL]/applications?merchant_reference=${MERCHANT_REFERENCE}

Generating the X-Signature

To generate the X-Signature header for this request, instead of a stringified Post Data (since there is none), the query string should be passed to the HMAC-SHA256 hashing algorithm instead, along with the Secret Key.

Example:
myCreateHmacSha256HashFunction('/applications?merchant_reference=140', 'mysecretkeyfrompartnersystem')

Headers

Key Required Value Description
Content-Type no application/json Set the content type
X-Access-Key yes UUIDv4 The Access Key from Partner System
X-Signature yes Hash The generated signature, see above

Query Parameters

Key Required Type Description
merchant_reference yes string The order reference in the merchant system

Response: Application Status

Case Description
signed Application has been signed through Montonio

Signed Application Webhook Notification

Example headers:

  X-Montonio-Access-Key: 3d5c50ef-06a5-4156-9688-f6d0056e9135
  X-Montonio-Signature: 2972d113ed24e36314f5ee8d024742c786da4d0061b378ae43b40243f1e3d47f
  Content-Type: application/json
  User-Agent: Montonio

Example request body:

{
    "merchant_reference": "O036869",
    "loan_amount": "3162.70",
    "currency_code": "EUR",
    "status": "signed",
    "timestamp": "2019-10-31T12:38:37.835Z",
}

Validating the signature:

const crypto = require('crypto');

let secretKey = 'your_secret_key'; // your secret key
let requestBody = req.rawBody; // raw JSON string from the request body

let hmac = crypto.createHmac('sha256', secretKey);
hmac.update(requestBody);
let signature = hmac.digest('hex');

if (signature === req.headers['x-montonio-signature']) {
    // webhook is valid!
}

If you provided the notification_url when creating an application, Montonio will send a POST request to that URL to notify you of a signed loan agreement. You can see the example request headers and body on the right.

The webhook is useful in case the customer does not redirect back to the store after signing the agreement. In that case your store will still get a notification about the signed agreement to mark the order as paid.

Headers

Key Value Description
X-Montonio-Access-Key UUIDv4 The merchant's Access Key
X-Montonio-Signature Hash The generated signature, see below
Content-Type application/json Media type of the resource
User-Agent Montonio Identity of the requesting user agent

Request Body

Key Type Description
merchant_reference string The order reference in the merchant's system
loan_amount string The total loan amount, equal to the total price of the order
currency_code string ISO 4217 alphabetic currency code
status string Loan application status. Only consider signed as a valid status to mark the order as paid.
timestamp string ISO 8601 timestamp of current time

Widgets

Montonio is actively developing and updating widgets for our partners to use in their webstores.

Loan Calculator Widget

Default configuration

<script src="https://public.montonio.com/assets/UI/calculator/index.js" data-product-price="399.99"></script>

A more customized calculator

<script 
    src="https://public.montonio.com/assets/UI/calculator/index.js" 
    data-css=".calc-option2 .mon-loan-calculator{margin-top:1em;display:flex;flex-direction:row;height:125px;border-color:#fdd900}.calc-option2 .mon-head{background-color:#fdd900;border-bottom:none;flex-grow:0;width:100px}.calc-option2 #mon-head-title{margin-top:10px;font-size:10px;line-height:10px}.calc-option2 .mon-estimate{color:#000;font-size:11px}.calc-option2 #mon-loan-period-value{font-size:2em}.calc-option2 #mon-loan-period-value{line-height:1em}.calc-option2 #mon-loan-period-unit{font-size:1em}.calc-option2 #mlcd-logo,.calc-option2 #mon-logo{max-height:12px}.calc-option2 .mon-logo-wrapper span{line-height:12px}.calc-option2 .mon-body{font-size:12px;padding:12px;flex-grow:1;flex-shrink:0}.calc-option2 .mon-loan-period{padding:0;align-items:flex-end}.calc-option2 .mon-logo-wrapper{flex-wrap:wrap;align-items:flex-start}.calc-option2 .mlcd-head{background-color:#fdd900;border-bottom:none}.calc-option2 .mlcd-footer hr{background:#979797}.calc-option2 .mlc .noUi-connect{background:#fdd900}.calc-option2 .mlc .noUi-horizontal .noUi-handle{background:#fdd900}.calc-option2 .mlcd-icon{background:#fdd900}.calc-option2 .mon-estimate h2{color:#000}"
    data-name="Sample Store"
    data-class="calc-option2"
    data-locale="en"
    data-logo-url="https://upload.wikimedia.org/wikipedia/commons/d/d9/Sample_Store_Logo.png"
    data-target-id="myDiv"
    data-access-key="fed764c5-b7b9-4b0b-ac2d-45d378b35456"
    data-environment="sandbox"
    data-info-page-url="https://www.montonio.com"
    data-product-price="399.99">
</script>

The Montonio Loan Calculator is a widget which displays estimated monthly price for a given product and loan period. Having the calculator widget on your product page increases the chances of your customer considering Montonio as a financing solution at checkout.

Implementation is super simple and can minimally be done in one line of code 👌. However, the calculator is very flexible and can be customized to perfectly fit your needs.


Attribute Required Type Description
data-product-price yes float The initial product price of a given product
data-access-key no string Your Access Key
data-environment no string The string production or sandbox
data-name whitelabel string The name of Montonio at checkout
data-logo-url whitelabel string The logo in calculator
data-css no string A CSS string that will be appended to after the default stylesheet
data-class no string Add a class to the calculator
data-target-id no string The ID of the element to append the widget after
data-locale no string Supported: ee,en, lt,ru, defaults to ee
data-show-modal no boolean Show how to apply for financing modal?
data-info-page-url no string The URL with info about financing



Monthly Estimate Widget


<div 
montonio-monthly-estimate 
data-product-price="455"
data-widget-type="textonly"
></div>

<div 
montonio-monthly-estimate 
data-product-price="455"
></div>

<div 
montonio-monthly-estimate 
data-product-price="455"
data-widget-type="badge"
></div>

<div 
montonio-monthly-estimate 
data-product-price="455"
data-widget-type="badge"
data-class="montonio-colorscheme-default"
></div>

<div 
montonio-monthly-estimate 
data-product-price="455"
data-widget-type="badge"
data-class="montonio-colorscheme-pink"
></div>

<!-- Include the Script -->
<script 
src="https://public.montonio.com/assets/UI/widget-estimate/index.js"
type="text/javascript">
</script>


alt text

The Montonio Monthly Estimate Widget allows you to show an estimated monthly payment for a product or total. As with the Loan Calculator Widget, implementation is super simple. Just add an element with montonio-monthly-estimate where you want to display it and include the javascript in the footer.






Attribute Required Type Description
data-product-price yes float The initial product price of a given product
data-name whitelabel string The name of Montonio at checkout
data-logo-url whitelabel string The logo in calculator
data-css no string A CSS string that will be appended to after the default stylesheet
data-class no string Add a class to the widget
data-locale no string Supported: ee,en, lt,ru, defaults to ee
data-info-page-url no string The URL with info about financing

Downloads

Here you can find resources for custom integrations with Montonio

Demo

montonio-demo.zip

JavaScript SDK

montonio-sdk.js

montonio-sdk.min.js

PHP Library

MontonioAPI.php

Python Library

MontonioAPI.py

 

 

 

 

 

  Head back to Montonio