Knoma SDK

Introduction

The "Pay with Knoma" button allows your applicants to quickly secure funding for any course. Our product allows the applicant to better manage their cash flow by allowing them to spread out the cost of the course (max. 12 months repayment duration) without incurring any interest or fees. Knoma allows the applicant to learn now, pay later.

With our lightweight (27kb) Javascript web SDK, you can easily add the Knoma checkout solution with just one line of code which, once added, never needs to be updated or maintained - we take care of all of this!

In addition to the checkout functionality, our SDK makes it super quick and easy to add more information about Knoma to your website - a crucial step for improving the application funnel, as it informs the applicant that another solution is available if they are unable to pay the price upfront.

Prerequisites

In order to add the "Pay with Knoma" button, your organisation must be an approved Knoma Partner and must have a Partner ID to identify and authorise your organisation within our systems. If you have not yet applied, but wish to use the "Pay with Knoma" offering, you can do so here.

You will need writable access to your website. If you do not have writable access, please contact your system administrator.

Getting Started

Installing the Knoma SDK (v2.1) on your website is very easy. We designed the Knoma SDK so anyone with basic web development skills can use it! The SDK is more than just the "Pay with Knoma" button so we encourage you to add the launcher-min.js script across your entire site. The launcher-min.js script must be added, at a minimum, in all your course pages and at checkout.

You will need to add our Javascript Library and CSS style guide as well. Simply copy and paste the following code between <head> and </head> across your website.

Adding the k-about to an id attribute in any DOM node is a very quick way of adding this functionality. Adding the id to an existing DOM node and embedding content within makes all the content clickable.

Upon clicking any content wrapped with the k-about attribute, the applicant is presented with a contextual modal window with more information about Knoma.

You can see a live example here.

As a Knoma partner, you can access the Knoma press kit, which provides the full range of Knoma assets that you can use when designing your page.

Additionally, you can leave the k-about DOM node empty which results in auto-populated content about Knoma.

"Pay with Knoma" Checkout Action

The "Pay with Knoma" button should be installed at the point where you wish to accept payment; this can be put on the course information page. However, we suggest the button is added to a dedicated checkout page, where applicants accepted to the course can be directed to. We have an example of how this can look here. This example can be downloaded from GitHub here and used as is, or fully customised to fit your brand!

When the "Pay with Knoma" button is clicked the Knoma Loan Application will launch right within your website in a stylish window. You can see a demo of the Knoma Loan Application process here.

Before adding the "Pay with Knoma" button to your site you will need to locate your k-provider-id and the k-course-id.

The k-provider-id can be found in your welcome email or within the Partner Portal. Please contact us if you cannot find this.

The k-course-id is a unique key or reference for the course. Please note, the k-course-id should be provided by you, the education provider. This should be a value that does not change.

Note: The "Pay with Knoma" button can only be rendered once per page, this is to avoid causing confusion to the applicant as to which option to click.

The Code

<div id="k-paywith-action" k-provider-id="[Knoma Provider ID]" k-course-id="[Unique Course ID]"></div>

Dynamic Pages

As discussed, there can only be one "Pay with Knoma" checkout button rendered on each page. This means that for every course there needs to be a subsequent checkout page. We highly suggest doing this dynamically - meaning that you create one checkout which populates page contents and the "Pay with Knoma" checkout button based on a parameter sent within the URL.

Start Date

It is recommended you add a start date for the course. The start date, if passed, will show up in the Knoma Partner Portal if the applicant is approved by Knoma, giving more contextual information to the applicant which makes reconciliation easier.

In addition to providing additional information in the Partner Portal, the start date will be added to course information within the Knoma Marketplace, and courses with an up-and-coming start date will be promoted under the 'Starting Soon...' section.

You can add the next start date by simply passing the date to the k-commencing attribute. Additionally, if the date is reoccurring, then you can specify this by also passing the value weeklybiweeklymonthly, or yearly after the date value.

Note: A start date is required when adding a reoccurring value. If a start date is set in the past, then we will use the next reoccurring date.

// Next date will be Friday 23rd July\
// Next date will be Saturday 17th October\
// Next date will be 11th November 2022 ### Auto-loading In addition to the Knoma Loan Application being triggered when the applicant interacts with the "Pay with Knoma" button, it can also be set to automatically fire once the page loads. This can be set by passing the `k-autoload` attribute. **Note:** This will fire once the necessary checks are passed, not when the page has loaded.

Customisation

The "Pay with Knoma" button can be set to either Blue, Green, White, or Navy (Blue). This can be adjusted by changing the k-custom attribute.

<div id="k-paywith-action" k-custom="green"></div>\ <div id="k-paywith-action" k-custom="blue"></div>\ <div id="k-paywith-action" k-custom="white"></div>\ <div id="k-paywith-action" k-custom="navy"></div>

In addition to changing the colour of the Pay with Knoma button, you can also remove the default shadow or change the rounding of the edges.

Changing or overwriting any other style attribute of the "Pay with Knoma" button is prohibited.

Data Attributes

When the "Pay with Knoma" button is installed correctly, the SDK will return information about the course such as the course price (as listed on the Knoma Marketplace).

You can query this information directly by retrieving the payload object sent via the pwk callback function. Alternatively, you can 'tag' a DOM element with the k-data attribute. The DOM elements' inner HTML will be populated with the relevant information if it can be retrieved.

As a fallback, if the course data cannot be found, the DOM element will be hidden. Adding the k-data-placeholder attribute to the same DOM will allow a fallback message to be populated instead.

Errors

Below is a list of all errors that may be returned. Errors will be printed out in the Browser debugger window. Accessing this on your browser can be found here. Additionally, if you have added the pwk callback method, you can retrieve them here as well.

5001 = Pay with Knoma DOM Element not found on Page.

5002 = Provider ID not Found.

5003 = Course ID not Found.

5004 = CSS Stylesheet Missing from Document.

5005 = There is more than one Pay with Knoma DOM Element found on Page. There can only be one.

5006 = UAT Mode Enabled.

5007 = Partner ID Missing.

5008 = Partner ID is Invalid.

5009 = Partner is not (yet) Approved.

5010 = Course ID Missing.

5011 = Course ID is Invalid.

5012 = Internal Course ID's Missing.

5013 = Portal JSON Payload is Malformed.

5014 = SDK Asset JSON Payload is Malformed.

5015 =Incorrect SDK Library Version Installed.

Callbacks

It is good practice to handle any errors or events that can occur. For this, we have built a simple callback function that will notify you when a defined event within the Knoma SDK occurs. This can be useful for redirecting the applicant or for capturing events for analytical purposes.

This function will return an event name (all are listed below) and a javascript object (payload). The payload contains information such as error messages and codes or types of the modal window.

knsdk.initialized = Called when the script is initialised on the page

knsdk.launched = Called when Knoma SDK opens a new modal window. The type (returned in the payload) can be:

portal = Presented the registration loan application view.

support = Presented the FAQ's and contact view.

about = Presented the 'About Knoma' view

knsdk.dismiss = Called when any of the SDK modal windows are dismissed. The user_triggered (returned in payload) will return a boolean value to state if this was triggered by the applicant or by the Knoma SDK.

knsdk.loading = Called when the Knoma SDK Loader is presented

knsdk.error = Called when the Knoma SDK receives or creates a new error. The error object will be returned in the payload.

More information in the Errors section (below).

knsdk.status = Called after the knsdk.dismiss has been called if the applicant has got the the final state of the application. The status (returned in the payload) can be:

approved = If the applicant's application has been automatically approved.

inreview = If the applicant's application requires manual review. This can take upto 48 hours.

declined = If the applicant's application has been automatically declined.

Functions

The following javascript functions can be called anywhere the launcher-min.js script is added. These allow for more granular control of the Knoma SDK but are not required.

Dismiss Modals

You can dismiss any of the active modals by calling the following function. You can find out if any modals are presented by using the callback method (above).

pwk_dismiss();

Course ID Update

If you need to update or replace the checkout Course ID k-course-id after the page is loaded, for example after the completion of an AJAX request, you can pass the new Course ID to the following function.

pwkcourseupdate([NEW COURSE ID]);

Install Validation

You can receive the install status of the Pay with Knoma checkout button by calling the following function. It will return a boolean (true or false) value to give you the state, and a payload object that contains additional information, such as errors and parameters.

let installed = pwk_installed(); if (installed.valid == true) { console.log("Pay with Knoma is Installed"); } else { console.warn("Pay with Knoma is NOT Installed", installed.payload); }

Course & Partner Data

let data = pwk_data(); console.log(data.partner); // Partner / School Object console.log(data.course); // Course Object, Including Price

For any questions concerning the installation and setup process, please contact us at [email protected].

white-high-right