Strictly Confidential

BillDesk Payment Gateway

-- Technical Interface Document v2.0

Merchant

IndiaIdeas.com Limited
E 510, Crystal Plaza, New Link Road
Andheri (W) Mumbai 400 053
Tel: 4092 0000, Fax: 4092 0002

This document contains confidential material proprietary to IndiaIdeas.com Limited (IndiaIdeas). The information, processes, ideas and concepts
contained herein in this document shall not be duplicated, used or disclosed to anyone outside, in whole or in part, except for the express purpose
of evaluating this proposal or implementing the same with IndiaIdeas. Should the client decide to not partner with IndiaIdeas, please return this
document along with an assurance that no photocopies have been taken and this document has not been distributed to or shared with other parties,
either in whole or in part.
 Table of Contents

1. Background ........................................................................................ 3

2. BillDesk Payment Gateway Service ........................................................ 3

3. Process Flow ....................................................................................... 3

4. Technical Integration with BillDesk......................................................... 4

5. Merchant TID Report ............................................................................ 7

6. Refund Processing ............................................................................... 8

7. Key Points for a Successful Integration ................................................... 9

8. Next Steps ........................................................................................ 10

9. Contact Persons ................................................................................ 10

ANNEXURE I – Checksum calculation.............................................................. 11

ANNEXURE II – Transaction Status Check API ( Query API ) .............................. 12

Strictly Confidential Page 2 of 13 IndiaIdeas.com Limited

1. Background

This note briefly describes the mode/manner of technical integration between BillDesk
Payment Gateway and Merchant website in respect of powering online transactions.

2. BillDesk Payment Gateway Service

BillDesk offers electronic payment gateway services to merchant organizations through its
partnerships with various banks and card companies. BillDesk would facilitate the payment
gateway integration at Merchant website to enable electronic commerce transactions.

3. Process Flow

This section briefly details the overall customer transaction flow, and the related
reconciliation and reporting processes.

Transaction Process

 Customer logs-in at the ‘Merchant’ website.

 Customer then decides to pay; clicks on ‘Pay’.

 Merchant website will log the order by generating a unique Order Number; and establish
a connection with the BillDesk Payment Gateway Interface [refer the section on Payment
Request].

 At the BillDesk Payment Gateway; the customer is displayed various ‘payment options’
that the customer can use for e.g. Credit Cards / Debit Cards / Online Netbanking / Cash
Cards.

 Customer chooses the payment option at BillDesk Payment Gateway, and is taken to the
page of that specific bank. Customer then enters the relevant authentication details [i.e.
User ID/ Card Number/ Password] at the bank’s website; and then is requested to
confirm the payment amount.

 Customer’s account is debited and the Customer is then directed back to the designated
Return URL [RU] at Merchant website.

 The BillDesk Payment Gateway will provide the return response to the designated
Merchant return URL received in the initial transaction request. Merchant can use this
response to update its system and display to the customer that the payment process
was successful.

 BillDesk payment gateway also generates a unique Transaction ID against each order
number that is received – this could be displayed to the customer; and used for any
queries relating to the transaction.

Strictly Confidential Page 3 of 13 IndiaIdeas.com Limited

Reconciliation Process [at BillDesk]

 On the next day, BillDesk will reconcile the online transactions with the credits received
based on the batch files received from the bank(s).

 After reconciling, BillDesk will generate an MIS report – that will include the Order
Number; and the Transaction ID generated by BillDesk.

 This report will contain the successful transactions; and the refunds that would have
been initiated by Merchant for specific transactions.

 Net amount [of BillDesk Charges] will be provided to Merchant with an MIS Report
[‘Merchant TID Report’].

4. Technical Integration with BillDesk

Key aspects of the integration between Merchant website and BillDesk are described in the
paragraphs below.

Payment Request

 Merchant website constructs a pipe separated message all values including but not
limited to:
o Order Number – is unique reference generated by Merchant for each transaction
initiated by Merchant
o Amount – is the transaction amount
o Unique Customer Reference Number
o Payment Option
o Return Response URL

 For the constructed pipe separated message, Merchant website computes a checksum
and appends it as the last value of the pipe separated string.

 Merchant website then redirects the payment request to the payment gateway at a
specified URL with the parameter ‘msg’ containing the pipe separated string.

After the customer clicks on PAY [within Merchant website], a request needs to be generated
by Merchant to a designated BillDesk URL for each payment:

https://uat.billdesk.com/pgidsk/PGIMerchantPayment
[The above URL is for illustration purpose only –the actual URL to be provided after integration development is
completed at BillDesk]

MERCHANT
Parameter Sample Value Description
MerchantID BDSKUATY To be provided after setup
UniqueTxnID ARP10234 Merchant’s Txn Reference
Number
TxnAmount 2.00 Transaction Amount
CurrencyType INR Fixed Value (max length 3)

Strictly Confidential Page 4 of 13 IndiaIdeas.com Limited

 TypeField1 R Fixed Value (max length 1)
SecurityID bdskuaty To be provided after setup
TypeField2 F Fixed Value (max length 1)
RU http://www.merchantwebsite.com/resp Return URL where the
onse.jsp payment gateway response is
to be received by Merchant

Note: The pipe separate message to be constructed must be in line with the message
description provided below. Only the key fields have been described in the table above. For
some fields which are fixed as NA refer the ‘Message description’ below in the Payment
Request section.

Payment Request

Message description

MerchantID|UniqueTxnID|NA|TxnAmount|NA|NA|NA|CurrencyType|NA|TypeField1|SecurityID|NA|N
A|TypeField2|txtadditional1|txtadditional2|txtadditional3|txtadditional4|txtadditional5|txtadditional6
|txtadditional7|RU

Parameters in RED should never be modified under any circumstances once it is defined in system.
Parameters in BLUE are variables that you pass uniquely for each transaction.
Parameters in BLUE and yellow highlight are variables that you pass uniquely for each transaction, but
their positions should not interchanged within 1&7 and remain as per the defined headings.

Most important: When you have no values to pass in txtaddtional1 to 7, then you must pass NA, and do
not leave it blank or pass any other random characters/dummy text.

Sample message for checksum value generation

BDSKUATY|ARP10234|NA|2.00|NA|NA|NA|INR|NA|R|bdskuaty|NA|NA|F|NA|NA|NA|NA|NA|N
A|NA|http://www.domain.com/response.jsp

Assume the checksum value/HASH generated was as shown below

38CA6911C1D490870DC35ADDC2BE1AEFC8792800CE5DF0A15B45349BBB5E01B3

Sample Txn Initiation Message to be sent to BillDesk URL as parameter ‘msg’

BDSKUATY|ARP10234|NA|2.00|NA|NA|NA|INR|NA|R|bdskuaty|NA|NA|F|NA|NA|NA|NA|NA|N
A|NA|http://www.domain.com/response.jsp|38CA6911C1D490870DC35ADDC2BE1AEFC879
2800CE5DF0A15B45349BBB5E01B3

Payment Response

The payment response is sent to the Return URL [RU] specified dynamically by merchant for
each transaction.

This response is a browser response and the message will be posted to the merchant’s
Return URL as a parameter - msg

Strictly Confidential Page 5 of 13 IndiaIdeas.com Limited

Response Message description:

MerchantID|UniqueTxnID|TxnReferenceNo|BankReferenceNo|TxnAmount|BankID|BIN|TxnT
ype|CurrencyName|ItemCode|SecurityType|SecurityID|SecurityPassword|TxnDate|AuthStat
us|SettlementType|AdditionalInfo1|AdditionalInfo2|AdditionalInfo3|AdditionalInfo4|Addition
alInfo5|AdditionalInfo6|AdditionalInfo7|ErrorStatus|ErrorDescription|CheckSum

Sample Response Message

BDSKUATY|ARP10234|MCIT0412001668|NA|00000002.00|CIT|443725|01|INR|NA|NA|NA|N
A|12-12-2004 16:08:56|0300|NA|300.00|15.00|NA|NA|NA|NA|NA|NA|NA|3734835

Please note – MERCHANTID and the CHECKSUM KEY would be provided at the time of
integration. Refer ANNEXURE I for a detailed description of the Checksum Key and related
process.

Bin Number : This will be mentioned in BankMerchantID field in the above response string.
The BIN number will be shared only for Card transactions. For Netbanking and other
payment options, NA will be the value shared in BankMerchantID field

Transaction Type : this will be mentioned in TxnType field in the above response string

Transaction Transaction
Code Type Transaction Code Transaction Type
01 Netbanking 06 IMPS
02 Credit Card 07 Reward Points
03 Debit Card 08 Rupay
04 Cash Card 09 Others
05 Mobile Wallet 10 UPI

Server to Server Direct Response

Browser based transaction status response porting to Merchant has a dependency on the
user’s internet connectivity for if there is an internet connectivity drop at the user’s end or if
the user browser shuts before the status has been posted to Merchant through the browser,
it will cause the transaction status to not reach Merchant for updating their systems in real
time.

In an effort to ensure that once the user is redirected from the bank to the BillDesk
Payment Gateway the transaction status is not dependent on the user’s browser, the ‘Server
to Server’ direct response mode would be setup between BillDesk and Merchant.

Thus, in addition to the browser response, BillDesk will also send a ‘Server to Server’
response to Merchant in the same format (‘msg’ as a parameter) as is being sent in the
browser response mode.

Strictly Confidential Page 6 of 13 IndiaIdeas.com Limited

Payment Updation process at Merchant end

The following process should be followed at Merchant end for receiving and processing the
payment response:

(a) Receive and Read the Payment Response message – msg at the Return URL
(b) Generate the ‘checksum value’ for the Payment Response and validate it with the
‘checksum value’ received in the Payment Response. If they match; proceed to step (c)
below; else display a Payment Rejection message to the customer.
(c) Update the original record in the merchant system based on the ‘AuthStatus’ field
received in the Payment Response. Refer the table below for various values that are
received in the AuthStatus field, and the related Transaction Status. The updation to
the original record must be done as follows:

Successful transaction [AuthStatus – 0300]

Update <record> set STATUS = ‘SUCCESS’ where ORIGINALSTATUS=’PENDING’ and ORDERNUMBER=’
1073234’ and TRANSACTIONAMOUNT=’100.00’

Failure transaction [AuthStatus – other than 0300]

Update <record> set STATUS = ‘FAILURE’ where ORIGINALSTATUS=’PENDING’ and ORDERNUMBER=’
1073234’ and TRANSACTIONAMOUNT=’100.00’

(d) The above updation process ensures the following:

 Only the original record is updated [through the Unique Order Number]
 The record is updated only once [for original status=PENDING]
 The record is updated for the same ‘Transaction Amount’ that was initiated by the
merchant.

Authorization status

Proposed Transaction
AuthStatus Status Reason
Status
“0300” Success Successful Transaction
“0399” Invalid Authentication at Bank Failure Transaction
“NA” Invalid Input in the Request Message Failure Transaction
“0002” BillDesk is waiting for Response from Bank Pending Transaction
“0001” Error at BillDesk Failure Transaction

For all AuthStatus that is not a Success, an ErrorDescription would be provided in the
Payment Response.

5. Merchant TID Report

The merchant will be able to login to the Merchant Interface and download a daily Merchant
TID Report. This report provides a summary of:

 Settled Transactions
 Refund Transactions
 Chargeback Transactions

In addition to providing details as mentioned above, the Merchant TID Report gives an
overall summary with respect to the ‘Net Credit’ amount.

Strictly Confidential Page 7 of 13 IndiaIdeas.com Limited

6. Refund Processing

The merchant administrator can initiate a refund for a transaction through the BillDesk
Merchant Interface. The Transaction Refund requests can be initiated through the upload of
a Refund File into the BillDesk Merchant Interface.

Refund process workflow

The following process should be followed at the merchant end for processing refunds:

(a) Create a file in the standard format [refer format below] and upload into the ‘Upload
Refund/Cancellation File’ option in the BillDesk Merchant Interface
(b) BillDesk Payment Gateway processes the uploaded refund file on a batch basis; and
provides a Validation Report that can be downloaded by the merchant through the
‘Download Validation Report’ option.
(c) Refunds that are successfully received are then processed with each of the banks as per
the workflow defined with the banks.

Refund – a transaction that is already settled for the merchant. Part of the transaction
amount can also be refunded by the merchant.

Cancellation – a transaction that is not settled for the merchant. Only the entire
transaction amount can be cancelled by the merchant.

(d) Refunds made by the merchant can be viewed through the ‘Refund Report’ option.
(e) Refunds successfully processed will be displayed as a deduction in the next ‘Merchant
TID Report’ that is generated for the merchant.

Format of the refund file will be as follows:

txn_id,txn_date,uniquetxn_id,txn_amount(Paise format),refund_amount(Paise format)

Field Name Notes

txn_id BillDesk Transaction ID received in the Payment Response
txn_date Transaction Date in YYYYMMDD format
uniquetxn_id Will be the value set in ‘txtUniqueTxnID’ in the Payment Request
txn_amount Transaction Amount; in paise format [for e.g. 100.00 will be 10000]
refund_amount Amount to be refunded; in paise format

For example:
MUTI0803612345,20080731,6012345,100000,100000

Sample Refund File Naming Convention: MerchantID_Refund_yyyymmddhhmmss.txt

Notes:
 File is to be uploaded as a .txt file
 Values should be separated with ‘comma’ delimiter
 The refund file must not contain any column headers
 All fields are mandatory in the refund file
 Refund File Name can take maximum of 50 characters without spaces

Strictly Confidential Page 8 of 13 IndiaIdeas.com Limited

 7. Key Points for a Successful Integration

Payment Request

No Area Description
1. Secure BillDesk URL Always use “https” for the BillDesk URL where the request will
be posted.

2. POST method * Always Use “POST” method

* Variables must be sent as HIDDEN values

3. Referral URL Always call the BillDesk production URL from the Referral URL
only; which needs be shared at the time of integration.

4. Length of parameters Each parameter field should not be more than 120 characters.
A ‘NULL’ value will not be accepted for any parameter.

5. Allowed characters Only the following characters are allowed in the parameters
that are sent to BillDesk:
. , @ - (period, comma, at, hyphen)

If any special characters are required for a parameter, they

have to be specifically requested to be enabled.
6. Transaction Amount Ensure the format is Rupee.Paise ( 2.00 ).

7. Return URL Always pass valid return URL where you want the response to
be posted and page redirected. Ensure it is in the 22nd
position.

8. All parameters Ensure all the parameters are passed at the exact same
Mandatory positions as specified above. No parameter should be omitted
because value is unavailable or NULL or unnecessary.
9. Checksum Value Checksum Value has to be always in UPPER CASE, and
generated using the correct algorithm specified by Billdesk. i.e
HMAC SHA256

Payment Response

No Area Description
1. Checksum Validation Always validate the checksum before updating the transaction
response

2. Verify whether the  Only the original record is updated [through the Unique
updation is as per the Order Number]
process specified in  The record is updated only once [for original
the interface status=PENDING]
document  The record is updated for the same ‘Transaction Amount’
that was initiated by the merchant.

Strictly Confidential Page 9 of 13 IndiaIdeas.com Limited

8. Next Steps

In order to get the service live, the following next steps are required:

 Merchant to confirm the integration process and discuss any clarifications required.
 Merchant to confirm their tech platform; parameters for the integration along with
validation information.
 Merchant to confirm the Referral URL to be used for the test phase.
 Merchant to provide Nodal Bank Letter for payout related setup.
 BillDesk to initiate the technical integration development at its end.
 BillDesk to share the URL for testing/UAT post completion of the development.
 Merchant to test all use cases thoroughly to fullest satisfaction.
 While testing in UAT Merchant to prefix the UniqueTxnID with the code provided by
Billdesk.
 Merchant to provide a UAT signoff and request for live credentials.
 Merchant to confirm their Referral URL to be setup for production phase.
 Merchant to provide Operations Contact Matrix for the process.
 Merchant to provide Administrator Details for setting up Billdesk Dashboard access.
 BillDesk to initiate the technical integration development for production Merchant ID.
 BillDesk to share live URL and Merchant details post completion of the live setup.
 Merchant to configure/update Billdesk production details at their end.
 While in production Merchant to omit prefix used in UAT for UniqueTxnID.
 Merchant to conduct live business using the live credentials provided by Billdesk.
 Merchant agrees to bear transaction charges for all testing activity conducted using the
live credentials and agrees to receive the funds in the account already configured in
Billdesk.
 Merchant also is aware that Billdesk UAT will continue to be available for all future
testing purposes

9. Contact Persons

Saviour Raj C IndiaIdeas.com Limited

No.203, 2nd Floor, Brigade Garden,
saviour.raj@billdesk.com Church Street, Bangalore 5600 01

Strictly Confidential Page 10 of 13 IndiaIdeas.com Limited

ANNEXURE I – Checksum calculation

The checksum is an important part while receiving messages from BillDesk. When the
merchant receives the response from BillDesk, a new checksum is generated at the
merchant site to verify the received one. Any differences in the checksum imply that the
messages have been modified or received erroneously.

BillDesk will provide a checksum component to the merchant to generate the checksum.
The Checksum component will require a message string and common string, i.e. password
(BillDesk and the merchant would share a common password to generate the checksum) to
generate checksum.

msg – Checksum will be required for this message and has to be validated by the
merchant.

Payment Response string

MerchantID|UniqueTxnID|TxnReferenceNo|BankReferenceNo|TxnAmount|BankID|BIN|TxnT
ype|CurrencyName|ItemCode|SecurityType|SecurityID|SecurityPassword|TxnDate|AuthStat
us|SettlementType|AdditionalInfo1|AdditionalInfo2|AdditionalInfo3|AdditionalInfo4|Addition
alInfo5|AdditionalInfo6|AdditionalInfo7|ErrorStatus|ErrorDescription|CheckSum

Checksum will be calculated for the string -

MerchantID|UniqueTxnID|TxnReferenceNo|BankReferenceNo|TxnAmount|BankID|BIN|TxnT
ype|CurrencyName|ItemCode|SecurityType|SecurityID|SecurityPassword|TxnDate|AuthStat
us|SettlementType|AdditionalInfo1|AdditionalInfo2|AdditionalInfo3|AdditionalInfo4|Addition
alInfo5|AdditionalInfo6|AdditionalInfo7|ErrorStatus|ErrorDescription

For example, suppose the Response message for a particular transaction is as follows:

BDSKUATY|1073234|MSBI0412001234|NA|00002400.30|SBI|22230123|NA|INR|NA|NA|NA
|NA|12-12-
200416:08:56|0300|abcd123|NA|NA|NA|NA|NA|NA|NA|NA|NA|92BX6955B5D490270DB95
XDDB2BE5XEFB2792200BE5DF0X55B45949BBB5E05B9

Following checksum string will be passed to checksum component with checksum key

BDSKUATY|1073234|MSBI0412001234|NA|00002400.30|SBI|22230123|NA|INR|NA|NA|NA
|NA|12-12-200416:08:56|0300|abcd123|NA|NA|NA|NA|NA|NA|NA|NA|NA|checksumkey

Calculated checksum value at the merchant end should be 3734835005 as in response

message. This should be matched and then the transaction should be taken for further
processing at the merchant’s end.

Strictly Confidential Page 11 of 13 IndiaIdeas.com Limited

ANNEXURE II – Transaction Status Check API ( Query API )

Merchant can query the BillDesk Payment Gateway using the Transaction Query API for the
transaction status. This request is a server to server request and the message should be
posted to a designated BillDesk URL as a parameter ‘msg’ in a pipe separated message
format.

REQUEST
Following are values that need to be sent pipe delimited as parameter ‘msg’ using the HTTP
POST method to a designated BillDesk URL:
REQUEST
Parameter Sample Value Description
RequestType 0122 Fixed value
Merchant ID BDSKUATY Fixed Value (as provided by BillDesk)
UniqueTxnID ARP10234 This is unique ID that was sent in
‘UniqueTxnID’ in the Payment Request by
BDSKUATY
Current Date/ 20130325182510 Current Date/Time stamp at the time of
Time stamp initiating the query request
[yyyymmdd24hhmmss]
Checksum 455057528 Checksum computed by BDSKUATY

For example – the ‘msg’ parameter would contain the following value:
0122|BDSKUATY|ARP10234|20130325182510|455057528

RESPONSE
Following is the response received as an output from BillDesk Payment Gateway.
RESPONSE
Parameter Sample Value Description
RequestType 0130 Fixed value
MerchantID BDSKUATY Fixed Value
UniqueTxnID ARP10234 This is Unique Transaction Reference
Number/Order Number.
TxnReferenceNo MSBI0412001668 BillDesk Payment Gateway Transaction
Reference Number
TxnAmount 94.00 Original TxnAmount
AuthStatus 0300 Successful Transaction
[Refer table below to understand the various Auth
Status values]
Filler1 NA Filler field
Refund Status 0699 0699 – Cancellation
0799 – Refund
NA – Refund Not Available for this request
TotalRefundAmount 50.00 Total Refund Amount for this transaction
LastRefundDate 20130320 Last Refund Date in YYYYMMDD format
LastRefundRefNo MSBI04120016681 BillDesk Payment Gateway Refund ID
QueryStatus Y Y – Request Successfully Processed
N- Invalid Request / Parameters
Checksum 3789267470 Checksum value

Strictly Confidential Page 12 of 13 IndiaIdeas.com Limited

Note: Only the key fields have been described in the table above. Refer the ‘Message
description’ below for response message construct.

RequestType|MerchantID|UniqueTxnID|TxnReferenceNo|BankReferenceNo|TxnAmount|Ban
kID|BankMerchantID|TxnType|CurrencyName|ItemCode|SecurityType|SecurityID|SecurityP
assword|TxnDate|AuthStatus|SettlementType|AdditionalInfo1|AdditionalInfo2|AdditionalInf
o3|AdditionalInfo4|AdditionalInfo5|AdditionalInfo6|AdditionalInfo7|ErrorStatus|ErrorDescrip
tion|Filler1|RefundStatus|TotalRefundAmount|LastRefundDate|LastRefundRefNo|QueryStatu
s|CheckSum

For Example:
0130|BDSKUATY|ARP10234|MSBI0412001668|NA|94.00|SPD|22270726|NA|INR|DIRECT|N
A|NA|NA|22-03-2013 16:08:56|0300|NA|NA|NA|NA|NA|NA|NA|NA|NA|NA|NA|0699|50.0
0|20130320|MSBI04120016681|Y|378926747

Notes:
1. Initiate the Query to the BillDesk platform at least 30 minutes after the transaction
initiation.

2. Always refer combination of “Auth Status” and “Refund Status” [from the Query API
response message] to determine whether the transaction is

(a) Successful
(b) It has been cancelled / refunded [i.e. processed for a refund back to the
customer].

3. Your public IP address must be whitelisted at BillDesk in order to be able to initiate

Query API requests to BillDesk

Status Map to be referred for understanding the status of a transaction:

Sr. Auth Refund Description

No Status Status
1 0300 0699 Payment status (0300) is success but it has been process for
cancellation (0699) i.e. refunded back to customer

2 0300 0799 Payment status (0300) is success and a refund [either

partial/full] was initiated for this transaction

3 0300 NA Payment status (0300) is success and is currently not

refunded or cancelled.

4 0300 0899 Payment status (0300) is success but it has been processed
for Chargeback (0899) i.e. Returned back to customer via
Chargeback

BILLDESK QUERY API URL:

https://uat.billdesk.com/pgidsk/PGIQueryController

Strictly Confidential Page 13 of 13 IndiaIdeas.com Limited