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

You can generate the keys under the Integrations page of the 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:

Sandbox environment: https://sandbox-api.montonio.com
Production environment: https://api.montonio.com

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:

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.
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

Send callback_url with the draft data when you want to redirect the customer to Montonio to fill in the financing application. The callback_url will be used to redirect the customer back to your store after finishing the application.

Additionally, use the notification_url to receive a POST request when a loan agreement has been signed, in case the customer does not redirect back to your store.

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

Please make sure that the product_price is the price of the product for a quantity of 1. Montonio API will multiply the individual product's price by the product's quantity in the server.

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:

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

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

When using Montonio as a redirect-based gateway, please make sure to provide callback_url in your draft data when fetching your access_token. This is necessary to redirect the customer back to your store after completing the financing application.

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.

See how to get the access_token from the previous section. To make it available in your JavaScript file, consider passing it as a data-attribute to your script. See the demo for examples.

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.

window.updateMerchantSystem()

This is called when a decision on an application has been reached. This can happen for the following reasons:
1) The applicant successfully signed an offer.
2) The applicant was unable to get any offers from the lenders.
3) It was impossible to request financing for the purchase. (for example, in Lithuania, no loan applications can be made during the night)
This request should make an AJAX call to the merchant's system that makes a validation request to the Montonio API as described in the next section called "Validating Application Status".
This AJAX request could, for example, return a new location to redirect the client to, such as a "Thank You" page or "Order Cancelled" page.
window.userClosedGateway()

This is called when the user closes the gateway before a decision has been reached.
The normal behaviour should be just to implement the Montonio.removeBackdrop() method as the SDK removes the iframe element itself.
At this stage, the customer should be able to open the gateway again. For example, this could be done by binding an EventListener to a button, which calls Montonio.addBackdrop() and Montonio.openModal() when clicked.
window.completedFunction()

This method gets called after the user presses the "Return to Merchant" button in the iframe, after a decision has been reached. By that time, the merchant system should have updated the order status according to the application status in Montonio API. The user should be redirected to a Success/Failure/Thankyou page.

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.

This endpoint should be used to update the order status in the merchant's own system. It is advised to make a controller that implements this request, updates the order status, and then returns an URL to redirect the user to when window.completedFunction() is called, as shown in the previous section.

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

When developing a custom integration, you should only consider an order paid for when the application status is signed. Other statuses imply the flow has not been successfully completed and the order should not be accepted.

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.

The webhook's body is signed with your secret key using HMAC-SHA256. The signature is included in the X-Montonio-Signature header. Make sure to validate the signature when receiving this webhook.

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.

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

If you provide data-access-key and data-environment to the script, it will automatically update its UI when you have an ongoing campaign.


<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

Introduction

API Keys

API Environments and Specs

Generating the X-Signature Header

Integrating with Montonio

The Complete Flowchart

Starting the Flow: Creating an Application Draft

HTTP Request

Headers

Post Data

Post Data: Products

Redirect flow

Iframe flow

Montonio JS SDK

Setting up the gateway

Window functions

Validating Application Status

HTTP Request

Generating the X-Signature

Headers

Query Parameters

Response: Application Status

Signed Application Webhook Notification

Headers

Request Body

Widgets

Loan Calculator Widget

Monthly Estimate Widget

Downloads

Demo

JavaScript SDK

PHP Library

Python Library