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.

Mobile Phone Number - 00000010
Pin Code - 5544

`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

token (string): JWT Token containing the purchase payload or subscription payload

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

params: An object containing following properties:
- token (string): JWT Token containing the purchase payload
- userId (string): zlick userId provided as response from the identifyClient call.

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

params: An object containing following properties:
- token (string): JWT Token containing the subscription payload
- userId (string): zlick userId provided as response from the identifyClient call.

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

params: An object containing following properties:
- token (string): JWT Token containing one of the standard payloads
- mobilePhoneNumber (string): Customer's mobile number to receive a pincode via SMS.

Response

See standard response

`verifyPinCode(params)`

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

Parameters

params: An object containing following properties:
- token (string): JWT Token containing one of the standard payloads
- confirmationCode (string): 4 digit confirmation code sent to customer's mobile number via SMS.
- challengeId (string): challengeId returned from the response of sendPinCodeSMS method.

Response

See standard response

`refundPurchase(params)`

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

Parameters

params: An object containing following properties:
- token (string): JWT Token containing the purchase payload
- transactionId (string): Transaction ID returned by the purchase method.
- refundReason (string): Reason to refund the purchase.

Response

See standard response

`unsubscribe(params)`

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

Parameters

params: An object containing following properties:
- token (string): JWT Token containing the subscription payload
- subscriptionId (string): Subscription ID returned by the subscribe method.

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)

Now it is possible to override the cookie with setCookie method and it should be done before calling the identifyClient method.

Parameters

cookieObject: Object containing the following properties:
- userIdToken (string): Token returned from the response of POST /my-api/getcookie call.

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:

400 - bad request. Most probably validation error
401 - unauthorized. Wrong PIN code in authentication, wrong token, secret, etc.
403 - Forbidden. User and / or apiClient disabled
422 - Unprocessable Entity. See Zlick Error code
429 - Too many attempts. Too many tries on SMS authentication
500 - Server Error. Something bad happened in Zlick

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

ZLICK01 - User has insufficient credit for the transaction
ZLICK02 - Phone is either moved to another / unknown telco or closed
ZLICK03 - Exceeds allowed monthly / daily limit
ZLICK04 - Payments not permitted, premium services not allowed
ZLICK05 - Failed payment (other reason)
ZLICK06 - Transaction failed. Technical error. Usually caused by an unexpected response from the carrier
ZLICK07 - Zlick was unable to get a response from the service provider

SDK Demo

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

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search