This document details the ZipDial To Verify API. If you need to understand how to setup your  ZipDial To Verify account, refer this page.

You can sign up for ZipDial To Verify product by registering on http://www.zipdial.com/selfreg/users/register.

Once you register for the product, you should have a customerToken and z2vToken, which is required for API Integration. While registering, a Call Back URL(to be provided by the you) has to be configured with the account. Rest of the document is focused on the integration.

Important taxonomy before you read ahead:

• Client – A client of ZipDial or the system where ZipDial is being integrated.
• customerToken – Provided by ZipDial to the client during registration. This is unique for every client.
• z2vToken  – Provided by ZipDial to the client during registration. This is unique for every Callback URL.
• Call Back URL – The URL on the client’s end that ZipDial would invoke to inform that a given transaction is successful.  Hence it can be considered as verified.
• Transaction – Each verification process is referred to as a transaction throughout this document.
• ZipDial Number – The number that user needs to dial for verification.

System Flow:

The integration flow can be summarized in the following steps:

1. End Consumer enters a mobile number on the client application, which has to be verified. Client application invokes ZipDial startTransaction API, which returns the ZipDial Number to be displayed to the user, and also a transaction token to identify the transaction.

API:

http://www.zipdial.com/z2v/startTransaction.action?customerToken=<CUSTOMER TOKEN>&clientTransactionId=7161680&callerid=<Mobile Number>&duration=180&countryCode=91&z2vToken=<Z2VTOKEN>

Parameters

• customerToken (mandatory) – Customer Token shared at registration time
• clientTransactionId(mandatory) – Transaction identifier on client application
• callerid (mandatory) – end consumer mobile number for verification
• duration (optional) – number of seconds for which the verification request has to be live on ZipDial. By default its 180 secs. Max 1 hour or 3600 secs.
• countryCode(optional) – Country Code for the verification request. By default, its 91. We support the following country codes:
  •  91 (for India 1800 ZipDial numbers),
  • Country code (for India +91 numbers. non 1800 ZipDial numbers). Country code should be used for verifying International dialers. Eg. 1 for US.
• z2vToken (mandatory) – Token to identify a given instance of verification account. A customer, depending on the commercial package chosen, can configure multiple instances under a verification account. A verification account is identified based on the CALLBACK_URL at client’s end to be invoked by ZipDial after a successful verification. A client application has to use different z2vtokens for different instances. This is usually helpful for Staging and Production environment.  Please ensure that Callback URLs are public URLs and not behind any firewall.

Response

• JSON response is returned for a successful request. Or else appropriate error messages are shared. If message =ok, then it’s a successful request.

{“message”:”ok”,”client_transaction_id”:”7161680″,”transaction_token”:”19c7006363bafeeaa3c2877501c013866a6a1134″,”status”:”1″,”img”:”http://www.zipdial.com/zip2auth/images/access/19c7006363bafeeaa3c2877501c013866a6a1134″}

• message: indicates status. ok means successful
• transaction_token : transaction identifier for the verification request. This is generated by ZipDial and is unique to every transaction.
• status : 1 (indicates an active verification request. 0 indicates an either verified verification request or an expired verification request.)
• img: returns the image URL for display of the ZipDial Number.

To display the ZipDial number, insert the image URL on the page that user is viewing.

Error Codes

 

• ERRO1: Insufficient information to process Z2V Request. Pls refer Z2V API docs à implies some of the mandatory parameters are missing
• ERRO3: Invalid Customer Credentials. Pls contact ZipDial Support (support@zipdial.com) à implies customer credentials is Invalid (customerToken or z2vToken)
• ERRO4: Invalid CallerID for verification. For any issues, pls contact ZipDial Support (support@zipdial.com) à implies the callerid is not a valid number

2. The client application would display the ZipDial number to the end consumer on the browser (or any client interface) and request the user to make a ZipDial (or a Missed Call) to the ZipDial number, from the mobile number entered on the screen.

3. Once the user ZipDials or gives a Missed Call, ZipDial would notify the client application on the CALLBACK URL, and pass the transaction_token.

After the verification the client application can implement the end consumer flows.

4. Optional Step For Status Check

The client can verify the transaction details by invoking pollTransaction API.

http://www.zipdial.com/z2v/pollTransaction.action?transactionToken=<transaction token>&customerToken=<customer token>

This would return a JSON object. Please note all timestamp information is in GMT.

{“message”:”Transaction verified”,”status”:1,”ivr”:”918039193919″,”transaction_time”:”2011-01-30 11:52:31″,”customer_call_time”:”2011-01-30 11:52:42″,”mobile_no_1″:”XXXXXXXXX”,”transaction_id”:”1296388351″}

The transaction_id here is the same clientTransactionId provided by client through startTransaction API in step 1.

Example of implementation of CALLBACK URL functionality

This is only a sample illustration of the implementation. Client may decide to make any desirable changes on its end.

1. Client application should create a z2v_transactions table. The structure of the table could be similar to as follows (assuming MYSQL database)

CREATE TABLE `z2v_transactions` (

`id` int(11) NOT NULL AUTO_INCREMENT,

`client_transaction_id` varchar(20) NOT NULL,

`transaction_token` varchar(50) DEFAULT NULL,

`mobile` varchar(15) DEFAULT NULL,

`verified` tinyint(4) NOT NULL DEFAULT ’0′,

`created` datetime NOT NULL,

`modified` datetime NOT NULL,

PRIMARY KEY (`id`)

) ENGINE=InnoDB;

2. Client application should generate an unique client_transaction_id and pass it onto the START VERIFICATION APIs.

3. Assuming that the url is http://www.clientexample.com/zipdial/notify_transaction, ZipDial would notify the client application by calling the above URL, along with a transaction token. Within the URL implementation, the following steps need to be done

a. Using  the transaction token, invoke the POLL TRANSACTION API to get the client transaction id.

b. The specific transaction should be updated (sample query as below)

update z2v_transactions set verified=1 where transaction_token=? and client_transaction_id=?