Zlick SDK Integration Guide

Zlick SDK offers marketplaces, newspapers and other commerce platforms a powerful and flexible mobile payment solution.

Getting Started

To get started, request your development account and development SDK by emailing to support@zlick.it. You will receive your client token and client secret which will be needed to integrate Zlick SDK on your website.

Integration Flow

Here is a basic overview of how you can use Zlick SDK to control paid access to content in your site:

Zlick Integration Flow

Add the SDK to your website

Add Zlick SDK to your website after your own scripts.

<head>
  <script type='text/javascript' src='path/to/your/javascript/files/index.js'></script>
  <!-- Dev SDK -->
  <script type='text/javascript' src='https://cdn.zlick.it/zlick-dev-2.5.2.js'></script>
  <!-- OR the live SDK -->
  <script type='text/javascript' src='https://cdn.zlick.it/zlick-2.5.2.js'></script>
</head>

Once you've included the SDK, the SDK exposes a global variable called zlick. You will be abke to use this object to call zlick methods.

API

Standard Responses

All of the function calls to Zlick API will give out a same standard response. We have kept it standard to keep it simple. But do note that not all of the parameters in the response will be usefull for an API call. For instance a response to subscirbe API would have subscriptionId and transactionId both but only subscriptionId would be relevant here. Same goes for purchase API response, where transactionId would be relevant and not subscriptionId.

Authenticating APIs

There are two types of JWT tokens that are required by many of the methods below as function inputs. These JWT tokens contain the details of the content/product and client. More details and instructions to generate these JWT tokens can be found here.

Sandbox Authentication

One of the methods below use Phone Number to authenticate the user. Below details can be used for testing purposes.

identifyClient(token)

Before you do any kind of operation with Zlick SDK, you have to call the identifyClient method. This method attempts to authenticate the current user and returns information about the user that you will need for calling other methods later.

Parameters

Response

See standard response

Examples

When user is not found
{
  phone: null,
  userId: null,
  contentId: null,
  hasAccessRights: false,
  allowedMethods: {
    smsAuth: true
  },
  jwtToken: "xxxxxxx.xxxxxxxxxx.xxxxxxx"
}

purchase(params)

Initializes one time purchase. Returns success, failure or need for SMS authentication

Parameters

Response

See standard response

subscribe(params)

Subsribes to monthly / weekly / daily subscription. When you sign up as a client with Zlick, you have to pre-define your subscription plans with unique names. While calling this method with a subscribe JWT token, you have to reference the unique product name. Zlick will use additional information about that subscription product from its own database.

For more information about subscriptions, see subscriptions flow.

Parameters

Response

See standard response

sendPinCodeSMS(params)

Starts SMS authentication by sending SMS with a pin code to user. Use this when userId is returned as null from identifyClient call.

Parameters

Response

See standard response

verifyPinCode(params)

Completes SMS authentication flow and returns userId on success. Throws an error on failure. See Errors.

Parameters

Response

See standard response

refundPurchase(params)

Completes SMS authentication flow and returns userId on success. Throws an error on failure. See Errors.

Parameters

Response

See standard response

unsubscribe(params)

Completes SMS authentication flow and returns userId on success. Throws an error on failure. See Errors.

Parameters

Response

See standard response

setCookie(cookieObject)

This method sets zlick cookie in the browser. This is useful in some scenarios when moving from v1 SDK to v2 SDK while keeping existing users logged in.

If the v1 cookie is detected, the content provider can convert the v1 cookie to v2 on their server side, and after that they can set the cookie for v2 with this method.

So from the client perspective, the process is as follows: 1. In the browser app, you need to check if there exists a cookie named zlick with a value that contains userId 2. If the userId if found, you can generate the new userIdToken on your server side like so:

POST /my-api/getcookie with body userId
jwt.sign({
  "apiClientToken": "7390d36701b0c29d8f8d3016af707ce9",
  "userId": "708fe1fe-864a-4ef4-8dab-cbf930f7a545",
}, secret)
  1. Now it is possible to override the cookie with setCookie method and it should be done before calling the identifyClient method.

Parameters

Response

This function runs synchronously and returns undefined.


Standard Response

All Zlick methods return a Promise that resolves to the following object with some properties conditional on the method being called.

{
  userId: "123456abcdef", // zlick user id.
  phone: "1223774963",
  jwtToken: "xxxxxxx.xxxxxxxxxx.xxxxxxx",
  contentId: "123456abcdef", // purchased content or product name
  transactionId: "123456abcdef", // TransactionID, only present in case of transaction
  subscriptionId: "123456abcdef", //  subscriptionID, only present in case of subscription
  challengeId: "123456abcdef", //  challengeID, only present in case of sendPinCodeSMS
  hasAccessRights: "true", // Boolean. Shows if user has access to content
  allowedMethods: {
    refundPurchase: true
  } // object describing next allowed methods
}

Allowed Methods

Standard response has a json object with the names of the method that are relevant and are infact allowed to be called - in terms of access rights and integeration flow. For instance if you have unsubscribed from a subscribtion you would find subscribe in the allowed methods. Similarly if you have purchased a content then you would find refundPurchase in the allowed methods. This is to help the developers to follow the integeration flow and only way to know the rights of the user, at any point of time, from the zlick API.


Errors

Error status codes

When a zlick method fails it throws an error with additional property statusCode. statusCode follows the HTTP error code standard:

Zlick error codes

When purchase fails due to infufficent funds or other similar reasons Zlick will return error with StatusCode 422 with specific Zlick error code

SDK Demo

A demo solution is over here. You will not be charged for actions you perform there.