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-3.0.0.js'></script>
  <!-- OR the live SDK -->
  <script type='text/javascript' src='https://cdn.zlick.it/zlick-3.0.0.js'></script>
</head>

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

Important Note About JWT tokens

Many of the methods below use JWT tokens as function inputs. Instructions to generate these JWT tokens can be found here.

How your end product will look like?

Vist our Demo website.

SDK functions

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

Note: For identifyClient response. Only if the returned response has a non null userId only then jwtToken will contain the payload of the response otherwise jwtToken will return back the provided token value to the identifyClient function.

Also See standard response for case when user is authenticated. If the browser has a stored cookie for a returning user.

Examples

When user is not found
{
  phone: null,
  userId: null,
  contentId: null,
  hasAccessRights: false,
  allowedMethods: {
    smsAuth: true
  },
  // for identifyClient function below is same as param JWT Token provided containg the purchase payload or subscription payload
  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

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
}

Constants and Enums

AUTH_TYPES

Authentication types. Used to check which flow to go

Values

Errors

Error status codes

When a zlick method fails it throws an error with serveral properties. One being the statusCode, this will follow the standard HTTP error codes. Usually status codes reflect a general or broader category of the error. To identify more specific reasons for the failure, please check the additional property zlickErrorCode.

Zlick error codes

When purchase fails due to infufficent funds or for some other reason Zlick will always return the error with a unique zlickErrorCode. Please see below what each code implies.

We try to deliver more context of the exact error and so we will always try to summarize the error with a descriptive reason in the message property of the error.

SDK Demo

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