Custom Checkout (Client To Server) Integration

Description

The purpose of this API is to enable websites to do online payment transactions using Zaakpay Payment Gateway. Mobile Integration: For Zaakpay Payment Gateway integration on mobile, parameters show Mobile must be set to true. Everything else is the same for desktop and mobile integration.

Here are two flows in this section:

PCI-DSS certified merchants

In this case, the Transact URL will be as mentioned below.

Method: POST
Staging Server: https://zaakstaging.zaakpay.com/transactD?v=5 / http://zaakpay-stagapi1.mbkinternal.in/transactD?v=5
Live Server:https://api.zaakpay.com/transactD?v=5

Here the card details will be encrypted on the merchant’s server using RSA encryption.

PCI-DSS non-certified merchants

In this case, the Transact URL will be as mentioned below.

Method: POST
Staging Server: https://zaakstaging.zaakpay.com/transactD?v=8 / http://zaakpay-stagapi1.mbkinternal.in/transactD?v=8
Live Server:https://api.zaakpay.com/transactD?v=8

Here the card details will be encrypted on Zaakpay Payment Gateway’s server using a js file.

Use zaakpay.js to generate the key, which will be used to encrypt the card details. Encryption is to be done on the front end only.

Staging Server:https://zaakstaging.zaakpay.com/zaakpay.js / http://zaakpay-stagapi1.mbkinternal.in/zaakpay.js
Live Server:https://api.zaakpay.com/zaakpay.js

Sample Encrypt function:

function encrypt(cardValue) {
        var out = '';
        for (var i = 0; i < cardValue.length; i++) {
            out += cardValue.charAt(i).charCodeAt()+ key.charAt(i%key.length).charCodeAt()+",";
        }
        return out;
}

Checksum Calculation

  • Create a list of all parameters which you’re passing to the API. Parameters used in checksum calculation are (in particular order):

    • merchant Identifier
    • orderid
    • mode
    • currency
    • amount
    • merchant Ip Address
    • txnDate
  • Create a concatenated string of all data value sin your list,with single quotes around each item.e.g. 'merchantIdentifier''orderId''mode''currency''amount''merchantIpAddress''txnDate'

  • The empty parameters are not to be used in checksum calculation string.

  • Calculate the checksum using the HMACSHA-256 algorithm, the concatenated string as data and your generated secret key.

  • The resulting checksum calculated should be posted to the Zaakpay API along with other data.For example: Let’s suppose we need to post the following data to the API. We calculate"checksum"
    only with the parameters mentioned below and the order of the parameters must remain intact when calculating "checksum".

    • merchantIdentifier-b19e8f103bce406cbd
    • orderId–223453
    • mode-1
    • currency -INR
    • amount -200
    • merchantIpAddress–10.45.46.127
    • txnDate –2014-09-22
  • Now, we have to create a concatenated string of all the values, in the order in which they’ll be sent to the API, with single quotes around each item. The string therefore will be:
    'b19e8f103bce406cbd''223453''1''INR''200''10.45.46.127''2014-09-22'

  • Now you can calculate the checksum based on this concatenated string and the secret key generated in your account under the URLs & Keys tab.

Request Parameters

These Parameters are mentioned in the same order in which MobiKwik Payment Gateway calculates the checksum (Excluding checksum) ie. order for parameters and checksum string must be the same.

Parameter

Type

Optional O /MandatoryM

Validation

Allowed Values

merchant Identifier

String

M

alphanumeric

MobiKwik Payment Gateway’s unique identifier for your website

orderId

String

M

max 40 alphanumeric,must be unique per website, we do not accept duplicate

  • *Advice: Orderid should be an alphanumeric value eg.
    ZAAK20170421

Your unique transaction identifier.

returnUrl

String

O

This must be the domain(or sub-domain of it) you saved under MyAccount -- >
Integration

Url where you want MobiKwik Payment
Gateway to post the
response

buyerEmail

String

M

valid email address of
the buyer

eg.prasang.misra@mo
bikwik.com

buyerFirstName

String

M

Max 30 alphanumeric characters, no special characters or dashes.
First Name on card

Prasang

buyerLastName

String

M

Max 30 alphanumeric characters, no special characters or dashes.
Firstname And Lastname cannot be the same. Last Name on
card.

Mishra

buyerAddress

String

M

100 alphanumeric Street address of the buyer.(Part Of Billing Address)

B-34, Priyadarshini Society,Dumma
Road

buyerCity

String

M

30 alphabet, minimum 3 (Part Of Billing address)

Jabalpur

buyerState

String

M

Country of the buyer

India

buyerPincode

String

M

Buyer’s pin/zipcode.
Can have Numbers, Spaces and Hyphens (-)only(Part Of Billing address)

210301

buyerPhoneNumber

String

M

buyer's landline or mobile
phone number, numeric only,no dashes,no spaces

eg.123456778

txnType

String

M

Numeric:MobiKwikPayment Gateway will show the tab on the payment page which corresponds to the txnType
you provide

1-ALL
11-CARD
12-NETBANKING
WALLETS
UPI15-CCONLY-Only
allow Credit Cards
15- CCONLY- Only allow Credit Cards
16- DCONLY - Only
allow Debit Cards 17-EZEClick
-ATM+PIN
-MasterPass
20 -EMI

zpPayOption

String

M

Which MobiKwik Payment Gateway option have you used for this transaction. 1digit only, numeric Default
value is 1.

0=onzaakpay, 1=button
redirect, 2=widget_
redirect, 3=api

mode

String

M

1 digit only, numeric

1=Domaincheck,0=Domain
checkskip

currency

String

M

Values defined by
MobiKwik Payment Gateway

INR

amount

String

M

Value in paisa.Min 100 paisa Max 10000000. Amount limit saved under Transaction Limit
in your Zaakpay panel.

merchantIpAddress

String

M

buyer’s IP address as recorded by your website.

127.0.0.1

txnDate

String

M

Transaction date in
yyyy-mm-dd format
Transaction date in
yyyy-mm-dd format

2016-08-11

purpose

String

M

Min and Max numeric 1 digit. You must specify the purpose of the transaction

0=Service
1=Good
2=Auction
3=Other

productDescription

String

M

Text description of what you are selling At Least one product description is mandatory to show in the bill on the payment page.
free text al- phanumeric 100 max

Text description of what you are selling At Least one product

product1Description

String

O

free text alphanumeric 100
max

product2Description

String

O

free text alphanumeric 100
max

product3Description

String

O

free text alphanumeric 100
max

product4Description

String

O

free text alphanumeric 100
max

shipToAddress

String

O

You may specify this
only when the buyer's address is different from the shipping address. 30 alphanumeric

Flat 1A, Sector7, Defence
Colony

shipToCity

String

O

Shipping address city.
30 alphabet, minimum 3

Jabalpur

shipToState

String

O

Shipping address state

MP

shipToCountry

String

O

Shipping address country

India

shipToPincode

String

O

Shipping address pin/zip code. 2 to 12 digits Can have Numbers, Spaces and Hyphens (-)only

210301

shipToPhoneNumber

String

O

Shipping address landline or mobile or phone number numeric only, no dashes,no spaces

e.g 12345678

shipToFirstname

String

O

max 30 alphanumeric characters, no special characters or dashes

Prasang

shipToLastname

String

O

max 30 alphanumeric characters,no special
characters or dashes

Mishra

showMobile

String

O

false:We show the full-fledged version unconditionally.

DETECT:We
do detection of the user Agent of the browser from which the request is sent & route accordingly.

true: We show the mobile page unconditionally.
missing/not

sent: Same as DETECT (i.e. We do detection at our
end ).

Only allowed value is “true” if you want MobiKwik Payment Gateway to represent mobile view

debitorcredit

String

M

Possible Values:debit,
credit, netbanking, upi or wallet

bankid

String

M (for Net Banking
and UPI)

For Net Banking, ID of selected bank, For Upi pass the user’s VPA

eg. SBI and For UPI:
eg.9864567456@ikwik

encrypted_pan

String

M (for Card txn)

Encrypted Card Number

card

String

O

Card Type

eg.VISA,MasterCard

nameoncard

String

M(for Card txn)

Card Holder Name

encryptedcvv

String

M(for Card txn)

Encrypted CVV of card

encrypted_expiry_month

String

M(for Card txn

Encrypted Expiry Month of card

encrypted_expiry_year

String

M(for Card txn

Encrypted Expiry Year of card

checksum

String

M

To be calculated on above parameters using HMAC SHA 256

Note:
For UPI specifically if the merchant wants to use zaakpay’s timer page then consider the above request. Else, refer to Transact UPI API request of transact-U document.Once the transaction is successful we will send a notification to return url as well as real time notification URL. Merchants can also check the status of transactions using check txn api which is present in this document itself.
The card details need to be encrypted and sent across the https POST parameters. This encryption can be done by the help of RSA encryption. Example: Since you are sending payment information to Zaakpay, you need to per-fill form parameters as hidden fields as a part of a form. Here is an example of what a form sending information to Zaakpay looks like.

Sample Request

<form action = " https://api.zaakpay.com/transactD?v=8 "method= " post ">
<input type="hidden" name="merchantIdentifier" value=" b19e8f103bce406cbd">
<input type="hidden" name="orderId" value="444221414">
<input type="hidden" name="returnUrl" value="">
<input type="hidden name="buyerEmail"value="[email protected]">
<input type="hidden name="buyerFirstName"value="Prasang">
<input type="hidden" name="buyerLastName" value="Misra">
<input type="hidden" name="buyerAddress" value="jbp">
<input type="hidden" name="buyerCity" value="Jabalpur">
<input type="hidden" name="buyerState" value="M.P.">
<input type="hidden" name="buyerCountry" value="India">
<input type="hidden" name="buyerPincode" value="482001">
<input type="hidden" name="buyerPhoneNumber" value="7698189874">
<input type="hidden" name="txnType" value="1">
<input type="hidden" name="zpPayOption" value="1">
<input type="hidden" name="mode" value="1">
<input type="hidden" name="currency" value="rupee">
<input type="hidden" name="amount" value="200000">
<input type="hidden" name="merchantIpAddress" value="127.0.0.1">
<input type="hidden" name="purpose" value="1">
<input type="hidden" name="productDescription" value="testproduct">
<input type="hidden" name="product1Description"value="">
<input type="hidden" name="product2Description" value="">
<input type="hidden" name="product3Description" value="">
<input type="hidden" name="product4Description"value="">
<input type="hidden" name="shipToAddress" value="">
<input type="hidden" name="shipToCity" value="">
<input type="hidden" name="shipToState" value="">
<input type="hidden" name="shipToCountry" value="">
<input type="hidden" name="shipToPincode" value="">
<input type="hidden" name="shipToPhoneNumber" value="">
<input type="hidden" name="shipToFirstname"value="">
<input type="hidden" name="shipToLastname"value="">
<input type="hidden" name="txnDate" value="2011−08−30">
<input type="hidden" name="debitorcredit" value="wallet"/>
<input type="hidden" name="encrypted_pan" value=""/>
<input type="hidden" name="card"value=""/>
<input type="hidden" name="nameoncard"value=""/>
<input type="hidden" name="encryptedcvv" value=""/>
<input type="hidden" name="encrypted_expiry_month" value=""/>
<input type="hidden" name="encrypted_expiry_year" value=""/>
<input type="hidden" name="checksum"
value="796d672eb63e1dfa4a0bc844e8d3468ebcd6d612dc39588814b7b00ce669c1c2">
< / form>

Response Parameters

These Parameters are used in the same sequence in checksum calculation.

Parameters

Description

orderId

Order Id as per the request

responseCode

Refer to Table 9: Transact-API Responses Codes

responseDescription

Refer to Table 9: Transact-API Responses Codes

checksum

Checksum calculated byMobiKwik Payment
Gateway on all above response parameters

amount

amount Txn amount in paisa, Integer

doRedirect

True or False

paymentMode

Mode of Payment eg. "Credit Card"

cardId

Unique number generated for card (to fetch the stored card)

cardScheme

Main Issuer e.g. Visa,MasterCard

cardToken

First four and last four digits of card number

bankid

for Net Banking, ID of selected bank

paymentmethod

Defined below

cardhashId

Unique number generated for card (same for all devices)

productDescription

As Received with the Request eg. testProduct

product1Description

As Received with the Request

product2Description

As Received with the Request

product3Description

As Received with the Request

product4Description

As Received with the Request

pgTransId

Txn ID from MobikwikPG

pgTransTime

Txn Date & Time

Sample Response

orderId                 ZPLive1509350715217
responseCode            100
responseDescription     The transaction was completed successfully.
checksum              13a09f5fc5dc4f6f6b25fe384f5f3f106f9aabff10f4aed02511b8b2392fa9  
amount                  1000
doRedirect              false
paymentMode             DebitCard
cardId              ba58e263f0f89f87080ac95ee46eea90389d1b29e9b5364b531d08a5e400175c~366
cardScheme              Visa
cardToken               4000 XXXX XXXX0002
bank                    4000 XXXX XXXX0002
bankid                  AXIS BANK LTD
paymentMethod           NA
cardhashid              400000CH466 
productDescription      NA
product1Description     NA
product2Description     NA 
product3Description     NA
product4Description     NA
pgTransId               ZP55cbfff01a00d
pgTransTime             10/30/201714:40:25

Sample Response Checksum String

amount=1000&bank=AXIS BANK LTD.&bankid=NA&cardId=2ba58e263f0f89f87080ac95ee46eea90389d1b29e9b5364b531d08a5e401 75c~366&cardScheme=Visa&cardToken=4000 XXXX XXXX0002&cardhashid=CH466&doRedirect=false&orderId=ZPLive1509350715217&paymentMethod=400000&paymentMode=Debit Card&responseCode=100&responseDescription=The transaction was completed successfully.&productDescription=NA&product1Description=NA&product2Description=NA&product3Description=NA&product4Description=NA&pgTransId=ZP55cbfff01a00d&pgTransTime=10/30/2017 14:40:25&

paymentMethod

This parameter helps in determining the mode of payment. This parameter returns a unique id which is mapped to different cards/banks. For example, if the value of this parameter is N1001, payment was made using HDFC NetBanking. If the value is C4300, payment was made using Axis VISA Debit Card. In the case of Mobikwik Wallet, the value of this parameter isN1053.

cardhashid

This is a one to one mapping with a card number. It is a unique value generated per card and will remain the same for all transactions made using the same card. This can help a merchant to extract information like how many transactions and of how much worth were made using a card. Merchants can also set up some fraud checks and limits per card using this parameter. In the case of NetBanking and MobiKwik Wallet, the value of this parameter isNA.

checksum

Similar to request checksum, response checksum must be calculated on all response parameters by merchant and matched with the checksum sent by MobiKwik Payment Gateway in response. Sample code to calculate response checksum has been given in file test_merchant_output.jsp

Secret: 0678056d96914a8583fb518caf42828a

<form action="https://zaakstaging.zaakpay.com/transactD?v=8" method="post"><br />
<input type="hidden" name="merchantIdentifier"
value="b19e8f103bce406cbd3476431b6b7973"><br />
<input type="hidden" name="orderId" value= "ZPtest_transaction">OrderId<br />
<input type="hidden" name="mode" value="0">mode<br />
<input type="hidden" name="currency" value="INR">currency<br />
<input type="hidden" name="amount" value="100"> amount<br />
<input type="hidden" name="merchantIpAddress" value="175.101.156.22">buyerPhoneNumber<br />
<input type="hidden" name="txnDate" value="2021-05-06">txnDate<br />
<input type="hidden" name="buyerEmail" value="[email protected]">buyerEmail<br />
<input type="hidden" name="buyerFirstName" value="John">buyerFirstName<br />
<input type="hidden" name="buyerLastName" value="sdsds">buyerLastName<br />
<input type="hidden" name="buyerAddress" value="SCO-123, sector- 58 ">buyerAddress<br />
<input type="hidden" name="buyerCity" value="Gurgaon">buyerCity<br />
<input type="hidden" name="buyerState" value="Haryana">buyerState<br />
<input type="hidden" name="buyerCountry" value="India">buyerCountry<br />
<input type="hidden" name="buyerPincode" value="sdsds">buyerPincode<br />
<input type="hidden" name="buyerPhoneNumber" value="sddsds">buyerPhoneNumber<br />
<input type="hidden" name="merchantIpAddress" value="175.101.156.22">buyerPhoneNumber<br />
<input type="hidden" name="txnDate" value="2021-05-06">txnDate<br />
<input type="hidden" name="purpose" value="1">purpose<br />
<input type="hidden" name="debitorcredit" value="wallet">wallet<br />d
<input type="hidden" name="bankid" value="MW">MW<br />
<input type="hidden" name="showMobile" value="true">showMobile<br />
<input type="hidden" name="zpPayOption" value="1">zpPayOption<br />
<input type="hidden" name="productDescription" value="PRN">productDescription<br />
<input type="hidden" name="txnType" value="1">Txntype <br/>
<input type="hidden" name="checksum" value="38334a0c81c2f8afc131ee87610add41a4b2aa4909b807cca4fcdd04cfc47ead"><br />
<input type="submit">	
< /form>
'b19e8f103bce406cbd3476431b6b7973''ZPtest_transaction''0''INR''100''175.101.156.22''2021-05-06'
a3e436305aa9d78cd4a7219a4ddaf3151a4f7c0e171e66d2bcc8e8e908bf9300
curl -X POST \
  'https://zaakstaging.zaakpay.com/transactD?v=8&merchantIdentifier=b19e8f103bce406cbd3476431b6b7973&orderId=ZP-TEST-1591597360707&returnUrl=http://zaakpaystaging.centralindia.cloudapp.azure.com:8080/merchant/test_merchant_output.jsp&[email protected]&buyerFirstName=Neeraj&buyerLastName=Kumar&buyerAddress=123,%20Sector%2045&buyerCity=Gurgaon&buyerState=Haryana&buyerCountry=India&buyerPincode=122011&txnType=12&zpPayOption=1&mode=0&amount=100&merchantIpAddress=172.14.19.138&txnDate=2019-06-24&purpose=1&productDescription=Testing%20Transact%20D&debitorcredit=wallet&checksum=00ce413c9699023cef93c7d39e76b73c61031e561caae2c791ad9a843846b33a&currency=INR&buyerPhoneNumber=9812547130&bankid=MW' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Postman-Token: 21d2ebd0-fbdd-4f05-b24c-28efb76d3a35'
'b19e8f103bce406cbd3476431b6b7973''ZP-TEST-1591597360707''0''100''172.14.19.138''2019-06-24''INR'
00ce413c9699023cef93c7d39e76b73c61031e561caae2c791ad9a843846b33a