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:
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.2.3.min.js'></script>
<!-- OR the live SDK -->
<script type='text/javascript' src='https://cdn.zlick.it/zlick-2.2.3.min.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.
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.
API
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
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
identifyClientcall.
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
identifyClientcall.
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): zlick userId provided as response from the
identifyClientcall.
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
sendPinCodeSMSmethod.
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
purchasemethod. - refundReason (string): challengeId returned from the response of
sendPinCodeSMSmethod.
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
subscribemethod.
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
setCookiemethod and it should be done before calling theidentifyClientmethod.
Parameters
- cookieObject: Object containing the following properties:
- userIdToken (string): Token returned from the response of
POST /my-api/getcookiecall.
- userIdToken (string): Token returned from the response of
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
}
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.