Getting started

Request your development account and development SDK by emailing to support@zlick.it

Installation

Add zlick.js script to your webpage:

<head>
  <script type='text/javascript' src='path/to/your/javascript/files/index.js'></script>
  <script type='text/javascript' src='https://cdn.zlick.it/zlick-latest-sdk-verion'></script>
</head>

then in index.js (in our example, it might be different for you) you are able to access zlick methods by referring to zlick.methodName(). Example: How to identifyClient on window.onload:

window.onload =  async function () {
  await zlick.identifyClient(token);
}

Usage

JWT and token signing

Zlick requires jwt token as one of the function inputs. We do that to be able to verify the source of requests. More info about web tokens can be found at jwt.io. The secret for signing the JWT together with client token will be provided by the Zlick team. The JWT must be generated and signed on your server each time the user requests the page.

JWT header

The header of the web token must be:

{
  "alg": "HS256",
  "typ": "JWT"
}

JWT Payload

JWT payload depends on purchase type - single payment / purchase or subscription:

JWT token payload example when making a purchase:

{
  "contentId": "123", // your content ID
  "amount": 20, // how much purchase costs in change (cents, cross, pennies etc. )
  "token": "Token", // token provided by Zlick
}

JWT token payload example when making a subscription:

{
  "productName": "123", // name of product that is configured on Zlick
  "token": "Token", // token provided by Zlick
}

Function Response

Zlick function with return either response in JSON format or Error

Successful response

{
  userId: "123456abcdef", // String, UserID
  jwtToken: "xxxxxxx.xxxxxxxxxx.xxxxxxx", // Same reponse in JWT format, signed with apiClient secret
  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 smsStart
  hasAccessRights: "true", // Boolean. Shows if he or she has access to content
  allowedMethods: {
    refundPurchase: true
  }, // object describing next allowed methods
}

Error response

{
  statusCode: "401", // error Status Code
  message: "Failed to verify JWT token", // error message
  zlickErrorCode: "ZLICK01", // zlick error code. Only in case of purchase / subscribe
}

Error status codes

When function fails it returns error with statusCode and message. The status codes follow 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

Creating jwt token

Sample javascript function for creating JWT token

const jwt = require('jsonwebtoken')

window.onload =  async function () {
  try {
    const token = signJwtToken();
    const response = await zlick.identifyClient(token);
    // response is JSON Object
  } catch (error) {
    console.log(error); // ..or better error handling :) 
  }
}

// This is just example. For security reasons we advise you to sign your tokens on server side.
// You have to use this token as input to all functions
function signJwtToken () {
  const payload = {
    amount: 'your amount in change',
    contentId: 'your contnetId',
    token: process.env.ZLICK_TOKEN
  }
  return jwt.sign(payload, process.env.ZLICK_SECRET)
}

The Documentation of the methods with examples

We have published our exposed methods, clientside demo application and commented client-side implementation. Feel free to use them as examples. Implementation can be found:

The full demo solution is over here and the full demo javascript implementation over here.