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 reffering 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. Secret for signing the JWT together with client token will be provided by Zlick team. The JWT must be generated and signed on your server each time the user requests the page.

JWT header

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 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 subscription:

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

Function Response

Zlick function withh return eiter 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 return error with statusCode and message. StatusCodes follow http error code standard:

  • 400 - bad request. Most probably validation error
  • 401 - unauthorized. Wrong PIN code in authentication, wrong token, secret etc.
  • 403 - Forbiden. 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 resons Zlick will return error with StatusCode 422 with specific Zlick error code

  • ZLICK01 - User has insufficient credit for transaction
  • ZLICK02 - Phone is either moved to another / unkown telco or closed
  • ZLICK03 - Exceeds allowed montly / daily limit
  • ZLICK04 - Payments not permitted, premium services not allowed
  • ZLICK05 - Failed payment (other reason)
  • ZLICK06 - Transaction failed due to technical error
  • ZLICK07 - TelcoTimeoutError: no response from telco

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)
}

Examples and methods documentation

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:

Full demo solution is over here.
Full demo javascript implementation over here.


TODO

  • Make zlick available via NPM
  • Release source code to github