NAV Navbar
Logo
http

Introduction

QuikWallet - Pay Securely

QuikWallet is a PCI-DSS Level-1 certified payment gateway, developed by LivQuik Technology (India) Pvt. Ltd. that enables users to transact with credit card, debit card, net banking and various other payment modes. Merchants can also host closed-loop prepaid cards on the QuikWallet platform and use QuikWallet as a secure card vault.

We are looking to provide you with a seamless and secure payment experience for all your platforms with customizations available for a host of use cases. For more on how you can customize your integration to your specific need, contact us at techsupport@livquik.com. click here.

What is a Self Checkout ?

Payment flow

The following steps will cover the entire payment flow

  1. Get your unique Partner ID (partnerid) and API key (secret) here
  2. Calculate your signature (covered here)
  3. Check for user’s available redemptions for the payment
  4. Collect the user’s payment instrument details - Select from cards stored by the user on QuikWallet or allow for entering details for a different card
  5. Generate a payment link
  6. Visit the generated link to complete the payment

Authentication

In this integration there will be two kinds of API calls you will make :-

  1. Server to Server (Querying for payment status, Refunding payments, and more)
    • API’s will be of the form : https://uat.quikwallet.com/api/partner/<partnerid>/<routeName>
    • Authentication will be done by the partnerid and secret provided to you.
  2. Client to Server (Loading stored cards, Payment link generation)
    • API’s will be of the form : https://uat.quikwallet.com/api/user/<routeName>
    • Authentication will be done by partnerid, the user’s mobile number and signature. This signature will have to be calculated by you for every mobile number on your platform.

Signature calculation logic

You will generate the signature using the secret key provided to you, the user’s authenticated 10 digit mobile number and HMAC-SHA256 as shown here

Signature = HMAC-SHA256 (users mobile number, secret key)

Conduct a payment

Check for redemptions

For every payment made via QuikWallet, there can be multiple redemptions available to the user.

These include, but are not limited to :-

To facilitate this, it is imperative to integrate the following API into the payment flow.

Check for the user’s available redemptions

POST /api/user/howtopay HTTP/1.1
User-Agent: MyClient/1.0.0
Host: uat.quikwallet.com
Content-Type: application/json
{
    "mobile":"6432949000",
    "signature":"82335083d7fa9dc3dab475b66fb07f55d41fea15a8bd719246be7d0c8c86dadd",
    "partnerid":"1",
    "amount":"2000"
}

Success case

HTTP/1.1 200 OK
Content-Type: application/json
 {  
        "status":"success",
        "data":{  
            "howtopay":[  
                {
                    "method":"offer",
                    "payload":[  
                        {
                        "amount":"100"
                        }
                    ]
                },
                {
                    "method":"credit",
                    "payload":[
                        {
                        "amount":"200"
                        }
                    ]
                 },
                 {
                    "method":"prepaid",
                    "payload":[
                        {
                        "amount":"500"
                      }
                    ]
                 }  
              ],
              "fulfilled":false,
              "topay":"1200"
        }
    }

Failure case

HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "failed",
  "message":  "Reason for failure"
}

HTTP Request

POST https://uat.quikwallet.com/api/user/howtopay

POST data

Field Required Description
signature true Your calculated signature
mobile true The customer’s mobile number
amount true The amount for the payment to be created
partnerid true Your unique partnerid

Response data

Field Type Description
status string Will be success or failed
data.howtopay JSON array An array comtaining the list of redemptions available to the user for the current payment
data.fulfilled boolean Is this payment fulfilled completely by the user’s redemptions (no further payment instrument is required)
data.topay string Balance amount to be paid (using a payment instrument) after redemptions are applied

Once the redemptions available have been ascertained, the user will be able to choose what mode of payment to proceed with.

The options available are :-

HTTP Request

POST https://uat.quikwallet.com.in/api/user/pay

CASE 1 : Fulfilled payments

POST /api/user/pay HTTP/1.1
User-Agent: MyClient/1.0.0
Host: uat.quikwallet.com
Content-Type: application/json
{
    "mobile":"6432949000",
    "signature":"82335083d7fa9dc3dab475b66fb07f55d41fea15a8bd719246be7d0c8c86dadd",
    "partnerid":"1",
    "amount":"2000",
    "billnumbers":"Unique order id generated at your end",
    "udf1"  : "BillNumber-1352",
    "udf2"  : "Something relevant",
    "udf3"  : "SKU-4321",
    "udf4"  : "Men'sFootwear",
    "udf5"  : "Something else relevant"
}

A payment is fulfilled if the response from https://uat.quikwallet.com/api/user/howtopay has the fulfilled key as true. In this case, no further mode of payment (netbanking, paymentcard) is required to complete the payment.

POST data

Field Required Description
signature true Your calculated signature
mobile true The customer’s mobile number
amount true The amount for the payment to be created
partnerid true Your unique partnerid
billnumbers true This field can be used to query our server for payment status. MUST be unique.
udf1 - udf5 false Use all udf fields as you please. These values will be returned to you as-is when we post payment updates to your callback (webhook) url

CASE 2 : Pay using saved cards

POST /api/user/pay HTTP/1.1
User-Agent: MyClient/1.0.0
Host: uat.quikwallet.com
Content-Type: application/json
{
    "mobile":"6432949000",
    "signature":"82335083d7fa9dc3dab475b66fb07f55d41fea15a8bd719246be7d0c8c86dadd",
    "partnerid":"1",
    "amount":"2000",
    "billnumbers":"Unique order id generated at your end",
    "cardid":"1219",
    "cvv":"121",
    "paymentmode":"paymentcard",
    "redirecturl" : 'http://redirect.to.this/url',
    "udf1"  : "BillNumber-1352",
    "udf2"  : "Something relevant",
    "udf3"  : "SKU-4321",
    "udf4"  : "Men'sFootwear",
    "udf5"  : "Something else relevant"
}

This mode is possible if :-

  1. The payment is not fullfilled:true
  2. The user has cards saved at QuikWallet. To get the user’s saved cards check out our section on Using QuikWallet as a Card Vault

POST data

Field Required Description
partnerid true Your unique partnerid
signature true Your calculated signature
mobile true The customer’s mobile number
amount true The amount for the payment to be created
billnumbers true This field can be used to query our server for payment status. MUST be unique.
cardid true The id for the user’s saved cards. To get a list of the user’s stored cards, checkout our section on Using QuikWallet as a Card Vault
cvv true The CVV number for the user’s selected card
paymentmode true Has the value paymentcard for all card payments
redirecturl false if configured with us beforehand, else true Once the payment is complete we will redirect to your custom url as specified by this field
udf1 - udf5 false Use all udf fields as you please. These values will be returned to you as-is when we post payment updates to your callback (webhook) url

CASE 3 : Pay using a new card

POST /api/user/pay HTTP/1.1
User-Agent: MyClient/1.0.0
Host: uat.quikwallet.com
Content-Type: application/json
{
    "mobile":"6432949000",
    "signature":"82335083d7fa9dc3dab475b66fb07f55d41fea15a8bd719246be7d0c8c86dadd",
    "partnerid":"1",
    "amount":"2000",
    "billnumbers":"Unique order id generated at your end",
    "paymentmode":"paymentcard",
    "ccno":"5148346584434657",
    "expmm":"05",
    "expyyyy":"2022",
    "name":"Pinay Vinto",
    "cvv":"245",
    "redirecturl" : 'http://redirect.to.this/url',
    "udf1"  : "BillNumber-1352",
    "udf2"  : "Something relevant",
    "udf3"  : "SKU-4321",
    "udf4"  : "Men'sFootwear",
    "udf5"  : "Something else relevant"
}

This mode is possible if :-

  1. The payment is not fullfilled:true
  2. The user wants to enter a new card with the following details :-
    • cardnumber
    • cvv
    • expmm (Expiry month)
    • expyyyy (Expiry year)
    • name (Card holder’s name)

POST data

Field Required Description
partnerid true Your unique partnerid
signature true Your calculated signature
mobile true The customer’s mobile number
amount true The amount for the payment to be created
billnumbers true This field can be used to query our server for payment status. MUST be unique.
cardnumber true The number on the user’s cards
expmm true The 2 digit expiry month on the user’s card
expyyyy true The 4 digit expiry year on the user’s card
name true The card holder’s name as per the user’s card
cvv true The CVV number for the user’s card
paymentmode true Has the value paymentcard for all card payments
redirecturl false if configured with us beforehand, else true Once the payment is complete we will redirect to your custom url as specified by this field
udf1 - udf5 false Use all udf fields as you please. These values will be returned to you as-is when we post payment updates to your callback (webhook) url

CASE 4 : Pay using netbanking

POST /api/user/pay HTTP/1.1
User-Agent: MyClient/1.0.0
Host: uat.quikwallet.com
Content-Type: application/json
{
    "mobile":"6432949000",
    "signature":"82335083d7fa9dc3dab475b66fb07f55d41fea15a8bd719246be7d0c8c86dadd",
    "partnerid":"1",
    "amount":"2000",
    "billnumbers":"Unique order id generated at your end",
    "cardid":"1219",
    "cvv":"121",
    "paymentmode":"netbanking",
    "netbankingcode":"AXIB",
    "redirecturl" : 'http://redirect.to.this/url',
    "udf1"  : "BillNumber-1352",
    "udf2"  : "Something relevant",
    "udf3"  : "SKU-4321",
    "udf4"  : "Men'sFootwear",
    "udf5"  : "Something else relevant"
}

This mode is possible if :-

  1. The payment is not fullfilled:true
  2. The user wants to complete the payment using Netbanking

POST data

Field Required Description
partnerid true Your unique partnerid
signature true Your calculated signature
mobile true The customer’s mobile number
amount true The amount for the payment to be created
billnumbers true This field can be used to query our server for payment status. MUST be unique.
netbankingcode true This is a code that denotes which bank the user wants to complete the payment with. The complete mapping of this field to our supported banks is covered here.
paymentmode true Has the value netbanking for netbanking payments
redirecturl false if configured with us beforehand, else true Once the payment is complete we will redirect to your custom url as specified by this field
udf1 - udf5 false Use all udf fields as you please. These values will be returned to you as-is when we post payment updates to your callback (webhook) url

Response data

Success case

HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "success",
  "data": {
    "paymentid": "P-534671",
    "twofactor": "https://uat.quikwallet.com/2fr/req/VrRYyff"
  }
}

Failure case

HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "failed",
  "message":  "Reason for failure"
}

Field Type Description
status string Will be success or failed
data.paymentid string This id will be your reference to the payment created. Store this to query us for payment status and initiate refunds.
data.twofactor string

Get payment status

When the payment processing is complete at our end, we will redirect you back to your custom redirecturl as discussed in the previous section.

Following are the ways to ascertain the status of the payment.

Redirect URL Query Parameters

There will be additional query parameters that we will append to the redirect url. For eg:-

http://redirect.to.this/url?state=paid&id=567&billnumbers=114242&checksum=03b3ed7d716dcd10e012

where :

  1. state can be paid or failed and is indicative of the success of the payment attempt.
  2. id is the unique id for the payment.
  3. checksum - This field is to be verified before trusting the received values of state and id. This step is critical to ensure the authenticity of the data received, and therefore is a mandatory step.
  4. billnumbers - Unique order id generated at your end

Computing HMAC and confirming authenticity of data received in query parameters

SET:

Message : state=paid&id=567&billnumbers=114242

i.e. all parameters up until checksum

SecretKey : secret assigned to you

For example - oXPpwQRrUL9WSaA0K0aE240k46gR868G

and then compute the value of

checksum = HMAC(Message, SecretKey) using SHA-256

You will get the value : 03b3ed7d716dcd10e012

Now compare to see if the HMAC computed is the same as the value of the checksum field sent as part of the query parameters.

Payment status API

At any time after a payment is initiated (id for the payment is available to you), you can retrieve the current status of the payment via the following API.

HTTP Request

Check payment status by API

POST /api/partner/1/paymentstatus HTTP/1.1
User-Agent: MyClient/1.0.0
Host: uat.quikwallet.com
Content-Type: application/json
{
  "secret" : "e0Q2GqsHchainQ32StV8aH8W9c3A17r7",
  "paymentid" : "P-534671"
}

Success case

HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "success",
  "data": {
    "paymentstatus":  "paid"
  }
}

Failure case

HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "failed",
  "message":  "Reason for failure"
}

POST https://uat.quikwallet.com/api/partner/<partnerid>/paymentstatus

where partnerid is your partner id provided by QuikWallet.

POST data

Field Required Description
secret true Your secret key
paymentid true The unique id for the payment returned to you during payment link generation

Response data

Field Description
status Will be success or failed
data.paymentstatus The current state of the payment

Preconfigured webhooks

{  
    "type":"payment",
    "data":{  
      "mobile":"9833955597",
      "amount":"1000.00",
      "state":"paid",
      "partnerid":"1",
      "id":"P-10047324234",
      "mode":"CREDIT",
      "billnumbers":null,
      "timestamp":1445928942,
      "udf1":"field1",
      "udf2":"field2",
      "udf3":"field3",
      "udf4":"field4",
      "udf5":"field5"
    }
}

When the user completes the payment, we will call a URL from your server (which you register with us ) and post details of the transaction there to notify your server in real time. Suppose you register the callback URL as:

http://www.yourserver.com/callback

Then, at the point of completion of 3DSecure, we will post JSON data to this URL.

Example POST you will receive is shown in the code block above

Initiate a refund

Refund payment by API

POST /api/partner/1/refundpayment HTTP/1.1
User-Agent: MyClient/1.0.0
Host: uat.quikwallet.com
Content-Type: application/json
{
  "secret" : "e0Q2GqsHchainQ32StV8aH8W9c3A17r7",
  "paymentid" : "P-534671"
}

Success case

HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "success"
}

Failure case

HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "failed",
  "message":  "Reason for failure"
}

The refund API is provided in cases where a payment processed via QuikWallet is required to be refunded to the account that this payment was debited from.

POST https://uat.quikwallet.com/api/partner/<partnerid>/refundpayment

where partnerid is your partner id provided by QuikWallet.

POST data

Field Required Description
secret true Your secret key
paymentid true The unique id for the payment returned to you during payment link generation

Response data

Field Description
status Will be success or failed

Netbanking codes

Each bank supported via netbanking is mapped to a code that will need to be sent in the netbankingcode field of the /pay API. These are as listed below.

Bank Name netbankingcode
“AXIS Bank NetBanking” “AXIB”
“Bank of India” “BOIB”
“Bank of Maharashtra” “BOMB”
“Central Bank Of India” “CBIB”
“Corporation Bank” “CRPB”
“Development Credit Bank” “DCBB”
“Federal Bank” “FEDB”
“HDFC Bank” “HDFB”
“ICICI Netbanking” “ICIB”
“Industrial Development Bank of India” “IDBB”
“Indian Bank” “INDB”
“Induslnd Bank” “INIB”
“Indian Overseas Bank” “INOB”
“Jammu and Kashmir Bank” “JAKB”
“Karnataka Bank” “KRKB”
“Karur Vysya” “KRVB”
“South Indian Bank” “SOIB”
“Union Bank of India” “UBIB”
“United Bank Of India” “UNIB”
“Vijaya Bank” “VJYB”
“Yes Bank” “YESB”
“CityUnion” “CUBB”
“Canara Bank” “CABB”
“Deutsche Bank” “DSHB”
“Kotak Bank” “162B”

QuikWallet as a Card Vault

This section describes how to use QuikWallet as a secure PCI-compliant card vault. The API calls are of the Client-to-Server type, so as to keep your server out of PCI scope.

Adding a card to our vault

Add a card to the vault

POST https://uat.quikwallet.com/api/user/addcard

POST /api/user/addcard HTTP/1.1
User-Agent: MyClient/1.0.0
Host: uat.quikwallet.com
Content-Type: application/json
{
    "mobile":"6432949000",
    "signature":"82335083d7fa9dc3dab475b66fb07f55d41fea15a8bd719246be7d0c8c86dadd",
    "partnerid":"1",
    "ccno":"5123456789012346",
    "expmm":"03",
    "expyyyy":"2015",
    "name":"Pinay Vinto"
}

Success case

HTTP/1.1 200 OK
Content-Type: application/json
{
    "status":"success",
    "data":{
      "type":"CREDIT",
      "cardid":"3340",
      "network":"mastercard",
      "tail":"2346",
      "bank":"BANCO DEL PICHINCHA, C.A."
    },
    "message":"Card successfully added"
}

Failure case

HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "failed",
  "message": "Invalid card number",
}

In this request, all fields are mandatory.

The keys are as follows:

POST data

Field Required Description
partnerid true Your unique partnerid
signature true Your calculated signature
mobile true The customer’s verified 10 digit mobile number (without the ’+91’ prefix)
amount true The amount for the payment to be created
cardnumber true The number on the user’s cards
expmm true The 2 digit expiry month on the user’s card
expyyyy true The 4 digit expiry year on the user’s card
name true The card holder’s name as per the user’s card

For a succesful response we are sending back the following information which you can display in your UI:

Field Type Description
status string Will be success or failed
data.type string Whether payment card type is credit or debit.
data.cardid string id generated by us for the card which you can store at your end
data.network string the network the card belongs to i.e. Visa, MasterCard, Amex
data.tail string the last four digits of the card
data.bank string the issuing bank for the card

Listing all cards in the vault

List all cards in the vault

POST /api/user/cards HTTP/1.1
User-Agent: MyClient/1.0.0
Host: uat.quikwallet.com
Content-Type: application/json
{
    "mobile":"6432949000",
    "signature":"82335083d7fa9dc3dab475b66fb07f55d41fea15a8bd719246be7d0c8c86dadd",
    "partnerid":"1"
}

Success case

HTTP/1.1 200 OK
Content-Type: application/json
{
    "status":"success",
    "data":{
      "paymentcards":[
        {
          "type":"CREDIT",
          "cardid":"3340",
          "network":"MASTERCARD",
          "tail":"2346",
          "bank":"BANCO DEL PICHINCHA, C.A."
        },
        {
          "type":"DEBIT",
          "cardid":"3341",
          "network":"VISA",
          "tail":"2346",
          "bank":""
        }
      ],
      "prepaidcards":[
        {
          "prepaidid":"9999",
          "balance":"100"
        }
      ]
    }
}

Failure case

HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "failed",
  "message": "Reason for failure"
}

POST https://uat.quikwallet.com/api/user/cards

In this request, all fields are mandatory.

The keys are as follows:

POST data

Field Required Description
partnerid true Your unique partnerid
signature true Your calculated signature
mobile true The customer’s verified 10 digit mobile number (without the ’+91’ prefix)

For a succesful response we are sending back the following information for each payment card, which you can display in your UI:

Field Type Description
type string Whether payment card type is credit or debit.
cardid string id generated by us for the card which you can store at your end
network string the network the card belongs to i.e. Visa, MasterCard, Amex
tail string the last four digits of the card
bank string the issuing bank for the card

Deleting a card from the vault

Deleting a card from the vault

POST https://uat.quikwallet.com/api/user/deletecard

POST /api/user/deletecard HTTP/1.1
User-Agent: MyClient/1.0.0
Host: uat.quikwallet.com
Content-Type: application/json
{
    "mobile":"6432949000",
    "signature":"82335083d7fa9dc3dab475b66fb07f55d41fea15a8bd719246be7d0c8c86dadd",
    "partnerid":"1",
    "cardid":"3431"
}

Success case

HTTP/1.1 200 OK
Content-Type: application/json
{
    "status":"success",
    "message":"Card successfully added"
}

Failure case

HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "failed",
  "message": "Reason for failure"
}

In this request, all fields are mandatory.

The keys are as follows:

POST data

Field Required Description
partnerid true Your unique partnerid
signature true Your calculated signature
mobile true The customer’s verified 10 digit mobile number (without the ’+91’ prefix)
cardid string Unique id for the user’s card. This can be obtained by the /api/user/cards route.

Response data

Field Type Description
status string Will be success or failed