.Net Integration with Bill Desk Payment Gateway

Introduction:

Now-a-days online shopping websites has become very popular, and to handle the secure Payment transactions, these are relying on popular third part Payment gateways like Billdesk, paypal etc.

BillDesk is the Payment Transaction Interface which allows the secure payment through Credit card/Online  Banking transaction.

Step-by-step Transaction Process:

a.       Customer logs-in at the merchant website, chooses the product/service that he intends to purchase.

b.      Customer then decides to make payment at merchant’s website.

c.       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].

d.      At the BillDesk Payment Gateway; the customer is displayed with various ‘payment options’ that the customer can use. These would include – Credit Card; Online Net Banking.

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

If the customer chooses to pay using Credit card then a payment page with the look and feel of the merchant is displayed for the user to make a payment.

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

g.       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.

h.       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.

Payment Request:

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

https://www.billdesk.com/pgidsk/pgijsp/MerchantPaymentoption.jsp

[The above URL is for example purpose only. And will be unique for each Merchant.]

A brief explanation of these parameters is below:

Parameter Name	Description	Sample Value
txtCustomerID	Order Number	1073234
txtTxnAmount	Total value of Transaction Rs.Ps.	2400.30
txtAdditionalInfo1	Source	Identity of Merchant website with Billdesk
txtAdditionalInfo2	Currency	INR or USD or GBP or EUR
txtAdditionalInfo3	Homestays	Kerela Backwaters
txtAdditionalInfo4	Arrival Date	25-Sep-09
txtAdditionalInfo5	Depature Date	28-Sep-09
txtAdditionalInfo6	Guests	2
txtAdditionalInfo7	Rooms	1
RU	Return URL – this dynamic return URL of the merchant where the online return response has to be received for that transaction	Https://payment.merchant.com (sample)

Note: Parameters are case sensitive.

Example:

<form name=’abc’ method='POST'  

action='https://www.billdesk.com/pgidsk/pgijsp/MerchantPaymentoption.jsp'>

  <input type='hidden' name='txtCustomerID' value='1073234'>

  <input type='hidden' name='txtTxnAmount' value='2400.30'>

  <input type='hidden' name=' txtAdditionalInfo1' value='  

    Identity of Merchant website with Billdesk '>

  <input type='hidden' name=' txtAdditionalInfo2' 

    value='USD'>

  <input type='hidden' name=' txtAdditionalInfo3'      

    value='Kerala Backwaters'>

  <input type='hidden' name=' txtAdditionalInfo4' value='25-

    Sep-08'>

  <input type='hidden' name=' txtAdditionalInfo5' value='28-

    Sep-08'>

  <input type='hidden' name=' txtAdditionalInfo6' value='2'>

  <input type='hidden' name=' txtAdditionalInfo7' value='1'>

  <input type='hidden' name='RU' 

    value='https://payment.merchant.com'>

     form>

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	Disallowed characters	Special characters are disallowed in the parameters that are sent to BillDesk. For example: <  >  % ; ' " ^ ` $
6	Transaction Amount	During the test phase of the integration, only Rs. 2 can be used as a transaction amount.
7	Parameter Name	Parameter names (sent to BillDesk) are case-sensitive

Payment Response

Once the Payment transaction is done in the Billdesk website, the payment response is sent to the Return URL [RU] specified dynamically by Merchant for each transaction.

This response is the “Form submit” and can be retrieved by – Request.Form[“msg”]

Response Message description:

MerchantID|CustomerID|TxnReferenceNo|BankReferenceNo|TxnAmount|BankID|BankMerchantID|TxnType|CurrencyName|ItemCode|SecurityType|SecurityID|SecurityPassword|TxnDate|AuthStatus|SettlementType|AdditionalInfo1|AdditionalInfo2|AdditionalInfo3|AdditionalInfo4|AdditionalInfo5|AdditionalInfo6|AdditionalInfo7|ErrorStatus|ErrorDescription|CheckSum

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

MAHINDRAID|c7b9b0|MEPG9999999999|200911106652263|7800.00|EPG|NA|NA|INR|DIRECT|NA|NA|NA|10-11-2009 11:00:56|0300|NA|HOMESTAYS|INR|BBEstate-Coorg-Karnataka|17-Nov-09|20-Nov-09|3|1|NA|Transaction Successful|717696825

Please note – MERCHANTID and the CHECKSUM KEY would be provided at the time of

integration.

Payment updation process at Merchant end

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

payment response:

                          I.      Receive and Read the Payment Response message – msg at the Return URL

                        II.      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.

                      III.      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 set STATUS = ‘SUCCESS’ where ORIGINALSTATUS=’PENDING’ and ORDERNUMBER=’

1073234’ and TRANSACTIONAMOUNT=’2400.30’

Failure transaction [AuthStatus – other than 0300]

Update set STATUS = ‘FAILURE’ where ORIGINALSTATUS=’PENDING’ and ORDERNUMBER=’

1073234’ and TRANSACTIONAMOUNT=’2400.30’

                      IV.      The above updation process ensures the following:

i)   Only the original record is updated [through the Unique Order 
Number]

ii)  The record is updated only once [for original status=PENDING]

iii) The record is updated for the same ‘Transaction Amount’ that was 
initiated by the merchant.

Authorization status:

AuthStatus	Status Reason	Proposed Transaction Status
0300	Success	Successful Transaction
0399	Invalid Authentication at Bank	Cancel Transaction
NA	Invalid Input in the Request Message	Cancel Transaction
0002	Billdesk waiting for the response from bank	Cancel Transaction
0001	Error at Billdesk	Cancel Transaction

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

No.	Area	Description
1	Checksum Validation	Always validate the checksum before updating the transaction Response
2	Verify whether the updation is as per the process specified in the interface document	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.

Sample Code:

In the Merchant website, the Page use the “Post method” to send the variables to the Billdesk website

<html>

<head id="Head1" runat="server">

    <title>Paymenttitle>

<script type="text/javascript">

    function myfunc ()

    {

    var frm = document.all("form2");

    frm.submit();

    }

    window.onload = myfunc;

script>

head>

<body>

    <form id="form2" method="post" action="https://www.billdesk.com/ Paymentoption.jsp" name="form2">

        <input type="hidden" name="txtCustomerID" 

               value="<%=Request("txtCustomerID")%>" />

        <input type="hidden" name="txtTxnAmount" 

               value="<%=Request("txtTxnAmount")%>" />

             <input type="hidden" name="txtAdditionalInfo1" 

                    value="<%=Request("txtAdditionalInfo1")%>" />

        <input type="hidden" name="txtAdditionalInfo2" 

               value="<%=Request("txtAdditionalInfo2")%>" />

        <input type="hidden" name="txtAdditionalInfo3" 

               value="<%=Request("txtAdditionalInfo3")%>" />

        <input type="hidden" name="txtAdditionalInfo4"                

               value="<%=Request("txtAdditionalInfo4")%>" />

        <input type="hidden" name="txtAdditionalInfo5" 

               value="<%=Request("txtAdditionalInfo5")%>" />

        <input type="hidden" name="txtAdditionalInfo6" 

               value="<%=Request("txtAdditionalInfo6")%>" />

        <input type="hidden" name="txtAdditionalInfo7" 

               value="<%=Request("txtAdditionalInfo7")%>" />

        <input type="hidden" name="RU"          value="http://www.mahindrahomestays.com/Pages/confirmation.aspx" />

     form>

body>

     html> 

  

Once the Payment is done, the Bill Desk webiste posts the Response string to the Merchant website, in the form of a variable ie; “msg”.

The following sample code to be written to receive the response variable from the Billdesk website.

string _paymentResp = Request.Form["msg"];                      

string[] arrResponse = _paymentResp.Split('|'); //PG

     string merchantId = arrResponse[0];

     string _customerId = arrResponse[1];

     string txnReferenceNo = arrResponse[2];

     string bankReferenceNo = arrResponse[3];

     string txnAmount = Convert.ToDecimal(arrResponse[4]);

     string bankId = arrResponse[5];

     string bankMerchantId = arrResponse[6];

     string txnType = arrResponse[7];

     string currency = arrResponse[8];

     string itemCode = arrResponse[9];

     string securityType = arrResponse[10];

     string securityId = arrResponse[11];

     string securityPassword = arrResponse[12];

     string txnDate = arrResponse[13]; //dd-mm-yyyy

     string authStatus = arrResponse[14];

     string settlementType = arrResponse[15];

     string additionalInfo1 = arrResponse[16];

     string additionalInfo2 = arrResponse[17];

     string additionalInfo3 = arrResponse[18];

     string additionalInfo4 = arrResponse[19];

     string additionalInfo5 = arrResponse[20];

     string additionalInfo6 = arrResponse[21];

     string additionalInfo7 = arrResponse[22];

     string errorStatus = arrResponse[23];

     string _errorDescription = arrResponse[24];