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¤cy=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
Updated about 3 years ago