An overview of how to integrate Divido as a payment option to any webshop.
This document assumes you are developing a reusable plugin to a shop system and it will guide through creating your own integration to any platform. If you are adding Divido to a custom-built webshop or as a one-off integration, some of the sections, such as the settings, might not apply to your case.
We also have pre-built plugins for many top e-commerce systems.
We are actively developing additional plugins and if your system is not in this list contact us to find out if we can add yours.
An overview of the steps a customer goes through when checking out using Divido as the payment method:
| # | Where | Webhook | What's Happening |
|---|---|---|---|
| 1 | Merchant | N | Choose Divido as payment method, Select financing plan and deposit percentage |
| 2 | Merchant | N | Confirm, redirections to ... |
| 3 | Divido | Y | Start of Divido application process |
| 4 | Divido | Y | Enter personal and banking info |
| 5 | Divido | Y | Pay deposit |
| 6 | Divido | Y | Sign Contract |
| 7 | Divido | N | Thank you page, redirection to ... |
| 8 | Merchant | N | Success Page |
At https://demo.divido.com/ you can find an example of a Shopify site that is integrated with Divido and see a standard customer journey.
To provide the merchant with the possibilites to customise their Divido integration in a way that it suits their business, you need to add a list of options to the payments section of the webshop settings.
Below is a list of what should minimally be included in this list. More options are discussed under the section limiting available payment plans
Please note that the names of the options are only guidelines and can be changed to suit the shop's platform.
Type: String
Example: sandbox_ccdc53735.b04d5a8270cf7cf8d24238e5a2a5fe4f Contains the API key necessary for communication with Divido's services.
Type: Bool
Quickly enables/disables the Divido payment option and product page calculator.
Type: String
Lets the customer pick their own title for the payment option at checkout.
Type: Bool
Toggles the product page widget.
Type: Order status
Provides a list of possible/applicable order statuses, so that the merchant can choose what status an order created by Divido gets.
Type: String
Possible values: ACCEPTED, SIGNED, READY
Lets the merchant choose when in the Divido process an order is created/escalated. The recommended value is 'READY' as a customer has checked out successfully only after they have signed and thus their application is ready to be fulfilled.
Type: Bool Toggles whether or not the plugin sends an automatic update call to Divido when a Divido order reaches the 'READY' status.
Type: Order status If "Send automatic fulfilment update" is True, this is the order status it would react to.
Type: Float Lets the merchant define an amount, under which a cart is not eligible to be paid for with Divido.
Options: All products, Products above specified price
Above is the two required options, see more under limiting available payment plans
Type: Float
If "Product selection" is set to "Products above specified price", this is the price limit against which products are checked.
For every customer, Divido provides javascript generated specifically for them by adding their API key.
This javascript contains functionality for showing dynamic calculators and widgets, as well as info about available financing products. Since this script is regenerated when the customers plans are updated, it should not be hosted locally, but sourced from Dividos CDN.
The URL of the script follows this pattern: //cdn.divido.com/calculator/[API KEY].js The [API KEY] placeholder is replaced by the part of the API key up to the period.
So if the API key is sandbox_ccdc53735.b04d5a8270cf7cf8d24238e5a2a5fe4f
The part we use for the javascript URL is sandbox_ccdc53735
Example: //cdn.divido.com/calculator/sandbox_ccdc53735.js
This script must be included on the product page and the checkout page and anywhere else you want to display a Divido calculator or widget.
The Divido product page widget is the Divido calculator which pops up after clicking on the instalment amount that should be displayed close to the product price. It allows the customer to get a quick overview of what financing options are available on that specific product, the cost break-down for each option and how different levels of deposit will affect this cost break-down.
In its most basic form, it looks like this:
<div
data-divido-widget
data-divido-mode="popup"
data-divido-prefix="finance for"
data-divido-suffix="with"
data-divido-title-logo
data-divido-amount="2000"
data-divido-apply="true"
data-divido-apply-label=“Apply Now"
data-divido-plans
>
</div>
We suggest you place it directly under the price on the product page. Don't forget to take the values of the "Product selection" and "Product price limit" into account when deciding whether or not to show it!
It's only the tag that's needed, the Divido javascript will take care of the rest.
When the customer has chosen Divido as their payment option, you need to provide them with a form where they can choose the finance product and set a deposit amount. Our Calculator Widget provides an interactive user-friendly form.
Here is the code you need to install the Calculator Widget:
Include this javascript on the page: https://cdn.divido.com/calculator/v2.1/production/js/template.divido.js
In the head of the page add in your sandbox key as a global js variable.
Javascript
<script>
var dividoKey = "<YOUR KEY HERE>";
window.DIVIDO_WIDGET = {
deposit: 20
}
</script>
Create a div with the options adjusted to your requirements. Put this div inside the <form> element of the checkout -
It adds two hidden fields for you
divido_deposit
divido_plan
html
<div
data-divido-widget
data-divido-prefix="finance for"
data-divido-suffix="with"
data-divido-title-logo
data-divido-amount="2000"
data-divido-apply="true"
data-divido-apply-label=“Apply Now"
data-divido-plans
>
</div>
If the html is loaded before the javascript is run, you can run the following to reset the widget
TemplateCalculator.reload() The Divido javascript will take care of making this interactive. When the customer has chosen the finance plan and deposit, you need to collect that data and send it, along with additional information about the order and the customer, to make a credit request.
The first step in a credit application starts with a credit request. It is simply an HTTP POST call to our web service, containing customer and order data that is used as the basis for the credit application.
See Create Application
You can see the full documentation for this call in the credit request section of our API documentation. Please note that the host name differs depending on whether you're using a live or sandbox key, see API endpoints - it will either be http://merchant-api.dev.divido.net
If the call is correctly done, the response will contain a field named "url". To start the credit application, redirect the user to that URL.
The customer has now left the merchants shop and is walked through a series of steps in the Divido credit application process. Each of those steps results in an update call back to your server, Webhooks.
Whenever the customer completes a step in the credit application process, an HTTP POST call is sent to the URL specified in the credit request field "response_url".
These are the events we send updates for, and a list of their possible statuses:
-
Basic application is finished
- ACCEPTED
- REFERRED
- DECLINED
-
Basic application has been cancelled by customer
- CANCELLED
-
Deposit has been paid
- DEPOSIT-PAID
-
Contracts have been signed
- SIGNED
- READY
-
Merchant marks order as fulfilled
- ACTION-LENDER
When the application is done, the information is sent to the underwriter for review. This is for the most part an automated process and the application gets accepted or declined directly.
In some cases, however, the underwriter will have to do a manual review of the application and its status is set to "referred". This will pause the application process and the customer will be given the choice to wait for the approval process to finish or return to the merchant.
When referred, the approval process takes up to 3 days and when it is done, the customer gets an email with a link that places them right where they left off in the application process.
Here's an example of the payload:
{
"application": 'C84047A6D-89B2-FECF-D2B4-168444F5178C',
"reference": 100024,
"status": 'SIGNED',
"live": true,
"metadata": {
"Invoice Number":"844001",
"Order Number":"100019"
}
}Field for field, these are the contents:
application: The ID of the Application, we recommend you save this for further reference.
reference: Third part reference, if sent with credit request status: This is the actual status update!
live: Whether or not this comes from our live environment (false = sandbox environment)
metadata: This contains whatever you sent us in the metadata field when you did the credit request.
To make sure no one is falsely sending you status updates, you need to verify that the updates are actually from us and that they refer to actual orders. To acheive this, we usually create a unique salt. Store it together with the order id, create a hash based on the salted order ID and send the hash and the order ID in the credit request metadata. When the status update comes back, we salt the order ID, hash it and check it against the hash that is in the metadata.
Merchants sometimes need to tailor the list of available finance plans to suit their business needs. To allow this you need to provide a way to limit the overall available finance plans and often more granualar settings targeting categories, brands or individual products.
What's needed really comes down to the individual merchant. Here we will detail the solution we ship with our generic Magento plugin.
Shown plans Options: All plans, Selected plans
Type: List of strings
Offers multiple-select boxes or a list of checkboxes with the result from a call to our API (http://developer.divido.com/#resources-finances). Dependencies: Only shown if Shown plans is set to "Selected plans"
Extra option: Selected products When this is option is chosen, a product is only available on finance if it has specifically been enabled. Used in combination with Shown plans set to "Selected plans".
Options: Default settings, Selected plans
Type: List of strings Offers multiple-select boxes or a list of checkboxes with the result from a call to our API getFinances Dependencies: Only shown if Available on finance is set to "Selected plans".
You need to calculate the available financing plans on both the product page and the checkout page. How you do it on the checkout page will depend on your use case, but here we show how we do it in our generic plugins as an example.
Naive pseudo code:
If global setting "Product selection" is "Selected products"
If product setting "Available plans" is "Default settings"
Let Plans be global setting "Available plans"
Else
Let Plans be product setting "Available plans"
Let Plans be global setting "Available plans"
Return Plans that has a minimum price lower than the product price
The code added to the webshop's cart to incorporate finance purchases on finance
This naive pseudo code will help you build the code for your checkout page:
For each product in the cart
Collect all plans for the product
Return all plans that has a minimum price lower than the full order value
Else