Payment Gateway Services Bank Hosted Card Page Hashing Integration Universal Merchant Integration Guide Version 4.0

Transcription

1 Bank Hosted Card Page Hashing Integration Universal Merchant Integration Guide Version 4.0 December 13, 2012 Financial Software & Systems Pvt. Ltd G4, PLOT No G-4, 1st Cross Road, Rajiv Gandhi Salai (OMR) Sipcot IT Park, Sirurseri Navallur Post, Chennai Tamil Nadu, India Telephone : Website:

2 Copyright Information/Disclaimer All information contained in this documentation is confidential and proprietary to Financial Software & Systems Private Ltd (FSS), and has been delivered for use pursuant to the current Hosted Payment Gateway Services agreement with Bank. No part of this documentation may be photocopied, electronically transferred, modified, or reproduced in any manner that is contrary to the agreement, without the prior written consent of FSS. 13-Dec-2012 FSSNeT PGS MID HUMI BHP V4.0 Page 2

3 Index Section (a) FSSNeT Hosted Payment Gateway Services... 4 (b) This Document... 4 (c) Relevance... 4 (d) Prerequisites... 4 (e) Hardware Prerequisites... 4 (f) Software Prerequisites... 5 (g) Security Configuration... 5 Section (a) Bank Hosted Card Page - Transaction Flow... 6 Section (a) Transactions... 9 (b) Purchase Transactions (c) Auth Transactions (d) Support Transactions (e) Transaction Initial Request to Payment Gateway (f) Payment Gateway Initial Request Response (g) Payment Gateway Transaction Response Parameters (h) Transaction Result / Error Definitions Section Section (a) Important Notes and Information (b) Essentials Section (a) Frequently Asked Queries (General) (b) Best Practices Dec-2012 FSSNeT PGS MID HUMI BHP V4.0 Page 3

4 Section 1 (a) FSSNeT Hosted Payment Gateway Services FSS is a global provider of electronic payment and transaction processing solutions and services for the banking and financial services industry. Established in 1991, FSS is a unique combination of payments technology solutions and payment infrastructure businesses. FSSNeT provides hosted payment solution and the Payment Gateway Services is one such hosted solution. (b) This Document The Payment Gateway follows industry standards and norms as prescribed by MasterCard and Visa International as well in conformity with Payment Card Industry Data Security Standards commonly referred to as PCI DSS. In order that the Bank s merchants are integrated in a secure and mandated manner, this reference document is being shared. The expectation being that the merchant s system integrator or auditor is able to refer to a document while progressing the integration as well as post integration. It contains the technical integration details including message formats to be used in communicating to the Payment Gateway irrespective of the merchant platform being used. The document also shares the best practices and recommendations the merchant should follow for integration and transaction handling and ensure an error free integration (c) Relevance The FSSNeT Payment Gateway Bank Hosted Integration Guide Version 4.1 is relevant to Merchant Developers/Integrators who intend to integrate with the FSSNeT Payment Gateway and forward the transaction data to Payment Gateway for Payment Processing where the card related sensitive information is captured by the Payment Gateway from the Card Holder / Customer. (d) Prerequisites Readers of this user guide should be familiar with basic either of the languages JSP, ASP, ASP.NET, PHP, Perl terminology (e) Hardware Prerequisites Merchants can use their existing hardware for transaction processing via Payment Gateway. 13-Dec-2012 FSSNeT PGS MID HUMI BHP V4.0 Page 4

5 Merchants may have a variety of arrangements for hosting their websites and thus have relevant security mandates for internet access controls and checks. This may include utilization of a Proxy Server which presents informed challenges. It is recommended that the merchant use a Public IP during the integration testing for transaction processing to the Payment Gateway. The merchant should ensure the Payment Gateway Domain and IP address is enabled at the firewall for both incoming and outgoing request/response (f) Software Prerequisites The merchant should have the requisite software for connecting to the Payment Gateway depending on the merchant application environment. The merchant may use combinations of OS/Web Server/ Application server whilst setting up and operating the website. Standard Software options are listed below, this list is for reference use only Operating Systems - Windows 2000/ 2003 / 2008 Server, Linux, Sun Solaris, IBM AIX Web/Application Servers - Web/Application Server that support JSP / ASP /.NET / PHP. The current version with all required patches is recommended to ensure success. Software Installation Basic software that are required for Web/Application server should be installed at the merchant site. (Java/JDK for JSP integration is essential; similarly.net frame work is essential for ASP.NET integration) (g) Security Configuration The UMI approach facilitates merchant developers to integrate with the Payment Gateway using a variety of software options, Web Sites, server software, and client software across the Internet. The UMI approach is a set of communication protocols, transaction transmit formats, transaction response formats, and error messages that can be used to develop an interface or object that provides the developer with a set of simple tools for communicating with the Payment Gateway. The merchant s developer / integrator should ensure that the communication protocol used for transmitting the request to the Payment Gateway is vide SSL (https). It should also be ensured that the required SSL protocols functions are called each time, when communication is made with the Payment Gateway. The merchant SHOULD ensure that top 10 Application Security Risks listed under are taken care for their web based applications. 13-Dec-2012 FSSNeT PGS MID HUMI BHP V4.0 Page 5

6 Section 2 (a) Bank Hosted Card Page - Transaction Flow The Bank Hosted Page works within a transaction path that is illustrated in the following diagram (Note the transaction flow is as per current mandates and for representation purposes only) 1. The merchant s customer logs into the merchant s website and selects product/services of his choice and proceeds for payment 2. The merchant initiates a Payment Request to the Payment Gateway (as per the specified UMI format), comprising Merchant Track Id, Transaction Amount, Merchant Response URL, Merchant Error URL and other parameters in User Defined Field (UDF) to the Payment Gateway. Before sending the request, merchant system generates a hash value of important parameters (listed in detail below) and passes the hash value in UDF5. 3. The Payment Gateway authenticates the merchant basis the credentials present in the merchant request. Payment Gateway also validates the hash value received and post successful validation, A Payment ID is generated by the Payment Gateway on successful 13-Dec-2012 FSSNeT PGS MID HUMI BHP V4.0 Page 6

7 validation of the merchant. The Payment Gateway response includes the Payment ID and Payment Gateway Card Page URL for redirecting the customer browser from the merchant website to the Payment Gateway Card Page. The Payment Gateway responds with the appropriate error code in case the merchant authentication fails. (Note: The steps 2 & 3 mentioned above are a server-to-server [TCPIP] call; the merchant should ensure that the Payment Gateway IP address is enabled for two-way communication at merchant firewall/proxy servers, the transaction is in Initialized state on Payment Gateway) 4. The merchant receives the Payment ID and Card Page URL from the Payment Gateway. Merchant now maps the Payment ID, Track ID and Amount with other transaction details in merchant back-end system (database) after which the merchant redirects the customer browser to the Card Page with the Payment ID. 5. The Payment Gateway presents the Card Page to the customer to enter the card related sensitive information like Card Number, Card CVV2/CVC2, Card Expiry Date, Card Holder Name etc. The transaction is with status as PRESENTED on Payment Gateway 6. The Payment Gateway sends the Card Enrollment Verification request to the Card Issuing Bank via the Interchange Directory Server and on receiving successful enrollment status customer browser is redirected from Payment Gateway to respective Issuing Bank Access Control Server (ACS). 7. The Issuing Bank ACS presents a Secure Page to enable the Customer enter the 3D Secure Authentication password on the ACS page. Customer provides the 3 D Secure password on the ACS page. The ACS authenticates the password and sends a good response back to the Payment Gateway 8. On successful ACS authentication of the customer, the Payment Gateway routes the transaction for Authorization to Acquiring Bank Switch, through the interchange and onto the Issuing Bank Card Host 9. The transaction is authorized by the respective issuing bank host via interchange and the response is sent back to Acquiring Bank Switch and from there back to Payment Gateway. 10. The Payment Gateway logs the response from the Acquiring Bank Switch and sends response back to the merchant s Response URL. The transaction status is PROCESSED at Payment Gateway. While sending response back to merchant, Payment Gateway generates a hash value using the response parameters (listed below in detail) 11. On receipt of response from Payment Gateway, the merchant first generates hash value using the response parameters and validates the generated hash value with the hash value received from Payment Gateway. If value matches then, merchant proceeds further for payment status update at his back-end system. 12. While updating the merchant back-end system, merchant MUST validate the Track Id, Payment Id and Transaction Amount against the original request sent and mapping done in the merchant database. If the validation is successful, the merchant proceeds basis the transaction status received. 13-Dec-2012 FSSNeT PGS MID HUMI BHP V4.0 Page 7

8 13. The merchant stores the transaction status and other parameters from the Response Url page in the database and redirects the customer browser to the appropriate result page. During the redirection merchant pass his required parameters to the result page to show appropriate message to the customer. 13-Dec-2012 FSSNeT PGS MID HUMI BHP V4.0 Page 8

9 Section 3 (a) Transactions This section provides an insight into transaction processing for developers, in order that they may focus their attentions on creating transactional objects as required. The transaction logic should be implemented as mentioned below by the merchant, and the information helps provide an understanding as to how and what actually happens before, during, and after a transaction. Transaction Processing The Bank Hosted Card Page integration module has 4 base steps as mentioned below - Transaction Initialization - Redirecting Customer Browser on Bank Hosted Card Page - Payment Processing by Payment Gateway - Response Management of response from Bank Payment Gateway Transaction Initialization Transaction Initialization refers to sending the initial payment request to the Payment Gateway for processing the transaction using the Bank Hosted Card Page option. To perform a transaction initiation, the required input data (request parameters/hashing) are captured in Section 3 (e) and Section 4 of this document. On receipt of transaction initialization request from the merchant, Payment Gateway verifies the merchant with the credential provided and the hash value in the request by the merchant. Once the merchant verification is successful, the Payment Gateway generates unique Payment Id for the order request and sends the Payment Id and Card Page URL in a response to the merchant. If the merchant verification or hash value mis-matches/fails or any error during verification then, Payment Gateway sends an error response to the merchant. The merchant should handle the error response appropriately and show appropriate message to customer. (Note: Merchant should ensure that initial request is initiated is a server-to-server call and the parameters set in request to gateway are from merchant backend system and not customer browser) Redirecting Customer Browser to Bank Hosted Card Page Once the merchant receives the Payment ID and Card Page URL from the Payment Gateway, the merchant redirects the customer to the Payment Gateway Card Page URL with Payment ID Payment Processing by Payment Gateway The Payment Gateway presents a Card Pay Page to customer, to collect card related information from the customer; Payment Gateway then performs Authentication and Authorization request for the card and finally completes the transaction processing. 13-Dec-2012 FSSNeT PGS MID HUMI BHP V4.0 Page 9

10 The Payment Gateway sends the transaction response details to the merchant response URL, Payment Gateway also sends the hash value in response to merchant. Transaction Response Management at Merchant Web Environment If the transaction result is successful then, merchants will perform Hashing Validation, in hashing validation; merchant collects the mandatory hashing parameters from response received and generates hash value. Merchant checks the generated hash value against the hash value received from Gateway. If both hash value matches, merchant proceeds further with the transaction. If hash value mis-matches, merchant drops the transaction and treats the transaction as failure transaction. For more information on Hashing Validation, Response Handling, Parameter Validations refer Section 6 of this document Before redirecting customer to any other page from Response URL or Error URL, merchant should ensure that merchant database record is updated with the status / result received from Payment Gateway. Before updating the record in database merchant must ensure that merchant validates the response with the Track ID, Amount and Payment ID received in response against the request and then checks whether transaction is successful or failed. - If transaction is failed merchant updates his database with the transaction result as FAIL and redirects the customer on the failure transaction receipt/result page. - If transaction is successful then merchant updates his database with the transaction result as SUCCESS and redirects the customer on the respective receipt/result page (b) Purchase Transactions Purchase Transactions refers to those transactions, whereby the merchant processes both the Authorization as well as the Card Account Debit upon successful customer authentication in a single leg. The funds of such successful Purchase Transactions are transferred into the merchant account after the Interchange Settlement between the Acquiring bank and Card Issuing Bank is complete. Purchase transaction will be shown in the customer's card used statement. To perform a Purchase Transaction request, the merchant must provide the required input data in the pre-specified format as specified in Section 3 (e) and Section 4 of this document (c) Auth Transactions Auth (Authorization) transactions are those where the transaction amount of the goods and services is sent to the Issuing Bank to verify funds availability in the customer card account and to block the funds until the Capture Transaction is initiated by the merchant. The Capture transaction refers to the merchant confirmation that the transaction value is to be debited to the card account against supply of goods/services as specified by the customer through the 13-Dec-2012 FSSNeT PGS MID HUMI BHP V4.0 Page 10

11 merchant s website. The Auth transaction blocks the Open To Buy (OTB) funds in the card account for a predetermined period of time as determined by the Issuing Bank.. To perform an Auth Transaction, the merchant provides the required input data as specified in Section 3(e) and Section 4 of this document. The Auth Transaction should be followed by the Capture transaction separately. The Capture Transaction refers to the initial Auth Transactions and confirms to the Issuing Bank to transfer funds from customer card to the merchant account. (d) Support Transactions For every Authorized transaction, there may be a number of associated Support financial transactions, for example Void, Refunds (Partial or Full) for Purchase Transactions and Capture (Partial or Full), for Auth Transactions. These associated transactions are also referred to as Support Transactions. The TranPortal (Merchant Hosted) Non 3 D Secure Integration Guide Version 3.0 or higher version covers the Support Transaction processing using Payment Gateway. Merchants are requested to contact their Bank for more information on Support Transaction (e) Transaction Initial Request to Payment Gateway Important: The message formats for the Purchase/Auth and Support Transactions differ from each other, hence the merchant should ensure that the message format is adhered to correctly for each transaction type Sr No 01 Field Details id Tran Portal Identification Number. The Payment Gateway Bank administrator issues the Tran Portal ID to identify the merchant and terminal for transaction processing. This parameter is used for hashing. Mandatory [M] /Optional [O] M Min / Max Length/ Fixed Value Min 1 - Max 10 ME password 13-Dec-2012 FSSNeT PGS MID HUMI BHP V4.0 Page 11

12 Tran Portal Password. The Payment Gateway Bank administrator issues the Tran Portal password to authenticate the merchant and terminal. Merchant data will be encrypted and password securely hidden as long as the merchant is issuing an https post for transmitting the data to Payment Gateway Mandatory [M] /Optional [O] M Min / Max Length/ Fixed Value Min 1 Max 50 merchantdemo123 action Transaction Action Type, "1" for Purchase and 4 for Authorization. This parameter is used for hashing. Mandatory [M] /Optional [O] M Numeric Min / Max Length/ Fixed Value Fixed Value "1" OR "4" 1 Mandatory [M] /Optional [O] Min / Max Length/ Fixed Value amt Transaction Amount, the amount should not contain thousands separators or currency symbols. This parameter is used for hashing. M Numeric Mandatory [M] /Optional [O] Numeric Min / Max Length/ Fixed Value Min/Max 3 Min 1 - Max 10 (including decimal) currencycode The currency code of the transaction. This parameter is used for hashing M 356 Mandatory [M] /Optional [O] trackid A unique tracking id isused by the merchant's system which is stored with the transaction. (Avoid spaces and extended characters. FSS recommends merchant to use numeric format). This parameter is used for hashing O 13-Dec-2012 FSSNeT PGS MID HUMI BHP V4.0 Page 12

13 Min / Max Length/ Fixed Value Max 40 Mandatory [M] /Optional [O] Min / Max Length/ Fixed Value Mandatory [M] /Optional [O] TRC langid The language in which Payment Page has to be presented. Currently only USA is supported M Alpha Fixed Value USA USA responseurl The merchant URL where Payment Gateway send the authorization response. URL must not have special characters like?. The or is mandatory in merchant response URL. M Min / Max Length/ Fixed Value Min 1 / Max et Mandatory [M] /Optional [O] Min / Max Length/ Fixed Value Min 1 / Max 255 errorurl The merchant URL where Payment Gateway send the response in case any error while processing the transaction. URL must not have special characters like?. The or is mandatory in merchant response URL M udf1 The user (merchant) defines these fields. The field data is passed along with a transaction request and then returned in the transaction response. Merchant should ensure that field is left blank when no data is need to be passed. These fields are for merchant to pass additional transaction related information like customer id, contact number etc 13-Dec-2012 FSSNeT PGS MID HUMI BHP V4.0 Page 13

14 Mandatory [M] /Optional [O] O Min / Max Length/ Fixed Value Max Mandatory [M] /Optional [O] customer@ id.com udf2 The user (merchant) defines these fields. The field data is passed along with a transaction request and then returned in the transaction response. Merchant should ensure that field is left blank when no data is need to be passed. These fields are for merchant to pass additional transaction related information like customer id, contact number etc O Min / Max Length/ Fixed Value Max Address 1 Mandatory [M] /Optional [O] udf3 The user (merchant) defines these fields. The field data is passed along with a transaction request and then returned in the transaction response. Merchant should ensure that field is left blank when no data is need to be passed. These fields are for merchant to pass additional transaction related information like customer id, contact number etc O Min / Max Length/ Fixed Value Max Address 2 Mandatory [M] /Optional [O] udf4 The user (merchant) defines these fields. The field data is passed along with a transaction request and then returned in the transaction response. Merchant should ensure that field is left blank when no data is need to be passed. These fields are for merchant to pass additional transaction related information like customer id, contact number etc O Min / Max Length/ Fixed Value Max Dec-2012 FSSNeT PGS MID HUMI BHP V4.0 Page 14

15 City udf5 14 Mandatory [M] /Optional [O] Min / Max Length/ Fixed Value 255 Merchant to pass the hash value calculated by merchant. Merchant should not pass any other value in this field. M 1472f342b20be3745b7b1a4d368e3d786 80ab4dad57c82057e900f11fe481783& Note 1. Merchant should ensure that UDF fields are left blank if not utilized by merchant. Merchant need not send UDF tags in request to Payment Gateway is merchant is not utilizing UDF values Request Format (Via HTTPS Post (TCPIP socket-to-socket connection) from merchant servlet/back-end system to Payment Gateway) Please note this is a single string to be posted on Payment Gateway - id=me &password=merchantdemo123&action=1&langid=usa&currencycod e=356&amt=1.00&responseurl= orurl= est1&udf2=test2&udf3=test3&udf4=test4&udf5=1472f342b20be3745b7b1a4d368 e3d78680ab4dad57c82057e900f11fe (f) Payment Gateway Initial Request Response Sr No Field Details paymentid Unique Id generated by Payment Gateway. Merchant MUST map this payment ID with merchant track Id and transaction amount for 01 future transaction reference Mandatory [M] /Optional [O] M Numeric Min / Max Length/ Fixed Value Max paymentpage The Payment Gateway URL on to redirect the consumer browser to enter payment details 02 Mandatory [M] /Optional [O] M Min / Max Length/ Fixed Value Max Note: 1. In case of any error payment Id and payment page will not be provided, error will be 13-Dec-2012 FSSNeT PGS MID HUMI BHP V4.0 Page 15

16 provided. Merchant to collect the error and do appropriate exceptional handling, the error will start with text ERROR Response Format (TCPIP response from Payment Gateway to Merchant) : payment.jsp Note: Merchant will receive response from Payment Gateway with Payment ID and Pay Page URL, both this fields will be separated by :. Merchant should collect the Payment ID and Payment Page URL and create a URL as below and redirect the customer on the URL (g) Payment Gateway Transaction Response Parameters Sr No Field Details paymentid Unique Id generated by Payment Gateway, this is the same ID that Payment Gateway had provided along with the PaymentPage URL for the initial request. This parameter is used for hashing Mandatory [M] /Optional [O] M Numeric Min / Max Length/Fixed Value Max result Transaction response, merchant to evaluate the transaction result and take further action accordingly. Please refer Section 3.h to identify the transaction result i.e. Success/Failure. This parameter is used for hashing Mandatory [M] /Optional [O] M Alpha Min / Max Length/Fixed Value Max 100 CAPTURED auth The resulting authorization number of the transaction from the issuing bank. This number or series of letters is used for referential purposes by some acquiring/issuing bank/institutions and should be stored properly. This parameter is used for hashing Mandatory [M] /Optional [O] M 13-Dec-2012 FSSNeT PGS MID HUMI BHP V4.0 Page 16

17 Min / Max Length/Fixed Value Max amt Transaction Amount as sent by merchant in the request. This parameter is used for hashing Mandatory [M] /Optional [O] M Numeric Min / Max Length/Fixed Value Max ref The resulting reference number of the transaction. This number or series of letters is used for referential purposes by some acquiring/issuing bank/institutions and should be stored properly. This parameter is used for hashing Mandatory [M] /Optional [O] M Min / Max Length/Fixed Value Max postdate Transaction Date in the format of the authorization system, Post Date is business logic date of respective issuing bank and may not be same as the actual transaction date Mandatory [M] /Optional [O] O Numeric Min / Max Length/Fixed Value Max trackid Track ID value that was sent by merchant in the transaction request. This parameter is used for hashing Mandatory [M] /Optional [O] M Min / Max Length/Fixed Value Max - 40 TRC tranid Unique Transaction ID generated by Payment Gateway, this transaction ID is required for any future support/subsequent transaction (Refund/Void/Capture) to be performed by merchant on Payment Gateway, merchant should store this parameter properly. This parameter is used for hashing 13-Dec-2012 FSSNeT PGS MID HUMI BHP V4.0 Page 17

18 Mandatory [M] /Optional [O] M Numeric Min / Max Length/ Fixed Value Max udf1 Same udf1 value that merchant has sent in the initial transaction request to Payment Gateway Mandatory [M] /Optional [O] O Min / Max Length/Fixed Value Max 255 ID udf2 Same udf2 value that merchant has sent in the initial transaction request to Payment Gateway Mandatory [M] /Optional [O] O Min / Max Length/Fixed Value Max 255 Address 1 udf3 Same udf3 value that merchant has sent in the initial transaction request to Payment Gateway Mandatory [M] /Optional [O] O Min / Max Length/Fixed Value Max 255 Address 2 udf4 Same udf4 value that merchant has sent in the initial transaction request to Payment Gateway Mandatory [M] /Optional [O] O Min / Max Length/Fixed Value Max 255 City udf5 Payment Gateway will generate a hash value of response parameters and will set the hash value in UDF5. Mandatory [M] /Optional [O] M Min / Max Length/Fixed Value Max 255 Country avr Address verification response Mandatory [M] /Optional [O] O Min / Max Length/Fixed Value 3 13-Dec-2012 FSSNeT PGS MID HUMI BHP V4.0 Page 18

19 15 16 Payment Gateway Services A errortext Error text in case of any error while processing transaction Mandatory [M] /Optional [O] O Min / Max Length/Fixed Value Max 255 GV00004 Pares Not Successful ErrorNo Error Number in case of any error while processing transaction. Note, in case of error in processing txn then only error text will be returned Mandatory [M] /Optional [O] O Min / Max Length/Fixed Value Max 255 GV00004 Note: 1. Fields marked as M (mandatory) will be received in case transaction is successful, in case fail or error in transaction the mandatory fields may or may not be available Response from Payment Gateway on Merchant responseurl paymentid= &result=captured&auth=999999&avr=n&ref= &tranid= &postdate=1019&udf1=Test1&udf2=Test2&udf3=Test3&udf 4=Test4&udf5= ecc ea9b06145b96d3c607b20556e24d2360f917ec856bd49f f&trackid= &amt=1.0 Response from Payment Gateway on Merchant errorurl (in case of error) paymentid= &error=py20006&errortext=py Invalid+Brand.&udf1=Test1&udf2=Test2&udf3=Test3&udf4=Test4&udf5=093dc34e6ebc 7fd5dd963221d0a95fc1a95af2fde0df774fa3b5c02c e&trackid= &amt=1.0 (h) Transaction Result / Error Definitions Result The result parameter in the Payment Gateway transaction response helps the merchant to determine the transaction status. The merchant should first check for any error received; if no error received, check for the result parameter and basis the same, determine whether the transaction is successful or failed. Mentioned below are the values that could be sent in the response by the Payment Gateway in the result parameter to the merchant response URL CAPTURED - Transaction was captured (successful) (For Action Code 1 ) APPROVED - Transaction was approved (successful) (For Action Code 4 ) 13-Dec-2012 FSSNeT PGS MID HUMI BHP V4.0 Page 19

20 Error NOT CAPTURED - Transaction was not captured (failed) (For Action Code 1 ) NOT APPROVED - Transaction was not approved (failed) (For Action Code 4 ) DENIED BY RISK - Risk denied the transaction HOST TIMEOUT - The authorization system did not respond within the Time Limit when the transaction is sent to Bank for authorization If an error occurs during the processing of the transaction, then the response format will contain a single string indicating that an error occurred. All Response Error Messages begin with a!error! Identifier. Therefore, it is important for the developer to first look at the actual response message string to determine if an error occurred. The sample error codes are listed below Error Code GW00150 GW00151 GW00152 GW00153 GW00154 GW00155 GW00156 GW00157 GW00165 GW00166 GW00167 GW00168 GW00169 GW00170 GW00171 GW00160 GW00161 GW00162 GW00163 GW00164 GW00183 GW00201 GW00258 GW00259 GV00004 FSS0001 GV00007 GV00005 GV00006 Error Description GW00150-Missing required data. GW00151-Invalid Action type GW00152-Invalid Transaction Amount GW00153-Invalid Transaction ID GW00154-Invalid Terminal ID GW00155-Invalid Batch Track ID GW00156-Batch track ID not unique GW00157-Invalid Payment Instrument GW00165-Invalid Track ID data GW00166-Invalid Card Number data GW00167-Invalid Currency Code data GW00168-Institution ID mismatch GW00169-Merchant ID mismatch. GW00170-Terminal ID mismatch GW00171-Payment Instrument mismatch GW00160-Invalid Brand. GW00161-Invalid Card/Member Name data GW00162-Invalid User Defined data GW00163-Invalid Address data GW00164-Invalid Zip Code data GW00183-Card Verification Digit Required GW00201-Transaction not found. GW00258-Transaction denied: Negative BIN GW00259-Transaction denied: Declined Card GV00004-PARes status not successful FSS0001-Authentication Not Available GV00007-Signature validation failed GV00005-Certificate chain validation failed GV00006-Certificate chain validation error 13-Dec-2012 FSSNeT PGS MID HUMI BHP V4.0 Page 20

21 GV00011 PY20006 PY20001 PY20002 FSS1001 GV00011-Invalid expiration date PY20006-Invalid Brand PY20001-Invalid Action Type PY20002-Invalid amount Transaction denied UDF5 Data Mismatch 13-Dec-2012 FSSNeT PGS MID HUMI BHP V4.0 Page 21

22 Section 4 (a) Payment Gateway Request Parameter List for Hashing Methodology In order to generate the hash values in request from Merchant Site/Server to Payment Gateway, standard SHA256 algorithm has been used. The key to the algorithm is the merchant Tranportal ID and the password. The parameters listed below are dynamic parameters for each transaction generated by merchant system/server/site as request to Payment Gateway Merchant Track Id - This is mandatory field but the value present or not is based on the request sent by the merchant. This is merchant reference number generated by merchant system for each transaction request sent to Gateway. If merchant has send any value in this parameter then Payment Gateway will return the same value in response in this field. Merchant SHOULD use this field for verification and validation of the transaction. We highly recommend merchant use pass unique value for each transaction in merchant track ID field. Transaction Amount - This is mandatory field, merchant will send to the Payment Gateway in the initial request. The parameters listed below are static parameters for each transaction generated by merchant system/server/site as request to Payment Gateway Tranportal ID - Tranportal ID is the key value for generating hash values; merchant should ensure these values are stored securely in merchant environment. Currency Code - The currency code of the transaction which will be enable for respective merchant / Bank. Action Code - The transaction Action Type, "1" for Purchase and 4 for Authorization which will be enable for respective merchant/terminal. Merchant has to generate hash value using the above dynamic and static values and then send the request to Payment Gateway with requisite parameters including the hash value in UDF5. (This is server to server call) 13-Dec-2012 FSSNeT PGS MID HUMI BHP V4.0 Page 22

23 (b) Payment Gateway Response Parameter List for Hashing Methodology On successful payment by customer, Payment Gateway will provide below listed parameters in response. Merchant SHOULD verify that for each successful transaction merchant is receiving all the mandatory parameters in response from Payment Gateway with values. This verification of parameters is MANDATORY. If merchant has not received these mandatory parameters from Payment Gateway and has received transaction status as successful than, merchant SHOULD decline the transaction processing and inform Bank on such transactions with transaction details and logs. In order to generate the hash values using the parameters from Payment Gateway to Merchant, standard hashing method i.e. SHA256 algorithm has been used. Tranportal ID Payment Gateway uses the respective merchant Tranportal ID for generating the hash value in addition to other response parameters. The Tranportal ID is not passed in response to merchant, hence merchant to use the Tranportal ID provided by Bank. Payment Id This is mandatory parameter in case transaction is successful or failed. This is the same payment Id that merchant has received in the initial handshake request with Payment Gateway of the transaction. Merchant should decline the response if merchant does not receives this parameter in response from Payment Gateway with value. Result This is mandatory parameter in case transaction is successful, this parameter contains the status of the transaction i.e. CAPTURED or APPROVED if transaction is successful. Any other value in this parameter means transaction is failed. Failure values are NOT CAPTURED, NOT APPROVED, DENIED BY RISK, HOT TIMEOUT, CANCELED. Merchant should verify that this parameter is received from Payment Gateway with value if transaction is successful. Auth Code This is mandatory field, this is authorization code generated by the Card Issuing Bank for the respective transaction Reference Id This is mandatory field if transaction is successful, this is Payment Gateway and Bank reference number for the transaction Transaction ID This is mandatory field if transaction is successful. This is unique value generated by Payment Gateway for each transaction when processing of the transaction is completed. Track Id This is mandatory field but the value present or not is based on the request sent by the merchant. This is merchant reference number field that merchant has generated and send to Payment Gateway in the request. If merchant has send any value in this parameter then Payment Gateway will return the same value in response in this field. Merchant SHOULD use this field for verification and validation of the transaction. Amount This is mandatory field, Payment Gateway will send the transaction amount that merchant has sent in the initial request. 13-Dec-2012 FSSNeT PGS MID HUMI BHP V4.0 Page 23

24 (c) Transaction Steps including hashing Payment Gateway Services Merchant muse secure the Merchant Request internally in the Merchant System/Server/Site before submitting to secure data to Payment Gateway Step 1: Merchant sends the request to Payment Gateway; merchant will generates a single Hash Value using the mandatory transaction parameters like, Tranportal ID, Merchant Track Id, Transaction Amount, Currency Code, and Action Code. Step 2: Once the hash value is generated for the mandatory fields, merchant has to set the hash value in UDF5 field and then send the request to Payment Gateway with requisite parameters including the hash value in UDF5. (This is server to server call) Step 3: On receipt of request from merchant, Payment Gateway will use the Tranportal ID configured on the Gateway by the Bank, payment gateway will take the Tranportal ID, merchant track id, transaction amount, currency code, action code received from the merchant and will generate hash value. Payment Gateway then compares the hash value generated by merchant in UDF5 against the hash value generated by Payment Gateway. Step 4: If hash value sent by merchant matches with the hash value generated by Payment Gateway, then Payment Gateway generates Payment ID and Pay Page URL and provides the same back to merchant in response. If the hash values mis-matches, Payment Gateway, sends hash value mismatch error back to merchant and transaction is ended here. Step 5: Once merchant receives Payment Id and Pay page url from Payment Gateway, merchant redirects the customer to Payment Gateway page, post mapping of Track ID / Amount and Payment ID on merchant back-end system. Step 6: A Payment Page will be shown to customer by Payment Gateway, and then the card details will be provided by the customer and submits the request. Step 7: Once the authorization is successful at the Transaction Switch response will be sent back to Payment Gateway. Step 9: Payment Gateway will hash the entire response data using parameters like Tranportal Id, Merchant Track ID, Transaction Amount, Result, Payment Id, Reference Number, Auth Code, and Transaction ID and will set the hashed value in the UDF5 field and send response to merchant (server-to-server call) to the merchant. (Note Tranportal Id will not be sent by Payment Gateway to merchant) Step 10: Merchant will collect Tranportal Id,Merchant Track ID, Transaction Amount, Result, Payment Id, Reference Number, Auth Code, Transaction ID and perform hashing If the hash value generated by merchant and hash value received from Payment Gateway to merchant matches, then, merchant updates his back end system and redirects customer browser respective result page. 13-Dec-2012 FSSNeT PGS MID HUMI BHP V4.0 Page 24

25 If the hash value generated by merchant and hash value received from Payment Gateway to merchant does not matches, then, merchant should treat transaction as failure and should not provide good/services to customer and displays appropriate message to customer (Note Tranportal ID will be stored at merchant end, merchant has to collect from his system / server, rest other values will be received from Payment Gateway in response) (d) Communication Protocol Specifications Protocol: http Port: 443 VeriSign 3.0 SSL Certificate Payment Gateway Transaction Initialization URL: For Purchase / Auth transaction (Production URL will be provided during production movement by Bank) Method: POST Content Type: URL Encoded for Purchase / Auth Transaction: application/x-wwwform-urlencoded for purchase and auth transaction. Application/xml for Dual Verification request. Note:- Character set to be used is charset=utf- 8 Transmit Data Format: URL Encoded Response Data Format: URL Encoded Encryption Level: SSL Version 3.0 (e) Payment Gateway IP Address Domain Information Test Environment Details: Domain Name: securepgtest.fssnet.co.in Public IP Address Please contact Bank Payment Gateway Team for the Payment Gateway Test set-up Public IP Addresses Production Environnent Details: 13-Dec-2012 FSSNeT PGS MID HUMI BHP V4.0 Page 25

26 Domain Name: securepg.fssnet.co.in Public IP Address Please contact Bank Payment Gateway Team for the Payment Gateway Production set-up Public IP Addresses 13-Dec-2012 FSSNeT PGS MID HUMI BHP V4.0 Page 26

27 Section 5 (a) Important Notes and Information In order to commence the test implementation, the merchant should ensure the information captured below is available Merchant Console :- The Payment Gateway provides a web based Merchant Console for merchants from where a merchant can download the resource file, ID, password and transaction reports. Bank provides the Merchant Console login credentials to the merchant in order to start integration Test Integration and UAT Environment :- The merchant should enable port 443 for communicating with the Payment Gateway. The request send by merchant to Payment Gateway is via port 443 and hence the same is required to be open for two-way communication. For the FSSNeT Payment Gateway Test Environment IP Addresses merchant should contact bank team. The merchant should ensure that the firewall is configured for both the IP Addresses. The domain for the test environment is Response URL :- Response URL is URL where Payment Gateway sends the transaction response to merchant, the response URL is merchant page located in merchant environment and Payment Gateway sends response on this page. All transaction response validations like hashing value checks and other validations that merchant would like to perform and transaction payment status update in backend (like database) MUST be implemented on Response URL ONLY. Response URL is merchant web page or servlet and merchant SHOULD ensure that security measures are implemented to ensure transaction security is intact at merchant web environment. Merchant should use best security policies to ensure the data is not editable by end user or third party within the once the response is received in the merchant environment. Merchant can use firewall / proxy server rules where the Response URL and Error URL are only accessible to Payment Gateway IP addresses or domain, this ensures that the response is always received from Payment Gateway and not for third party. Once the merchant has updated the records in the database and is ready to redirect the user on the result / success or failure page, merchant should ensure limited or required information is passed from response URL to result / success / failure pages. Post receiving response from payment gateway, successful validations and update of records in database merchants can use their own logics / methods for passing the value from response URL to result / success / failure page. 13-Dec-2012 FSSNeT PGS MID HUMI BHP V4.0 Page 27

28 (b) Essentials a) The merchant should ensure that any sensitive transaction information like transaction amount, merchant track id should not be passed through the customer browser to the merchant system/database as these can be intercepted and modified by the customer or even by third party to fraudulently alter the transaction data. b) Any transaction information displayed to a customer, such as amount, merchant transaction id (track id) should be passed only for display and information purposes to the customer on browser. It is imperative that the actual transactional data should be retrieved EXCLUSIVELY from the database/server and at the final stage of processing the transaction to Payment Gateway. In case where merchant is providing multiple services or products to customer in the same shopping cart or session and allows customer to make one single payment in such cases merchant should ensure the total price of all product / services are done at server side and the total amount sent to Payment Gateway is either the total done on the server side or from merchant database. c) ALL transaction data input from the customer should ONLY be accepted once from a browser at the point of input, and then inserted and stored in a way that does not allow vulnerability or access to others to modify details (e.g. database, server session, etc.) d) Merchant should ensure that parameters posted to the Payment Gateway are solely from secure source and not from the customer s browser. e) The merchant should ensure that the merchant code/page that forwards the transaction request to the Payment Gateway is secure and should not be vulnerable for alteration/modification f) The merchant should ensure that each parameter is validated before sending request to Payment Gateway (example amount should be numeric, junk characters should not be passed in any of the input parameters). g) Characters like ~ `! # $ % ^ = + \\ : ' \ ", ; are treated as hack characters and should not be passed in any parameters by the merchant. Merchant should also ensure that reutn carriage is not passed to Payment Gateway in any of the input parameter specially the UDF values. The return carriage leads to improper formatting of the reports in Payment Gateway which may lead to reconciliation issues at merchant level at later stage. h) The request sent from the merchant to the Payment Gateway can be a simple merchant servlet also that manages request/response handling and does not interact directly with the customer browser. i) THE PAGES PROVIDED WITH THIS GUIDE CAN BE USED BY MERCHANT FOR NTEGRATION WITH GATEWAY, THE PAGES DEVELOPED AR BASED ON THE MINIMUM REQUIRMENT, MERCHANT TO ADD THE ADDITIONAL SECURITY AS REQURIED. MERCHANT SHOULD ENSURE REQUIRED CHECKS AND BALANCES ARE DEPLOYED IN PRODUCTION ENVIRONMENT TO ENSURE TRANSACTION SECURITY. 13-Dec-2012 FSSNeT PGS MID HUMI BHP V4.0 Page 28

29 j) Sensitive details of merchant like ID, Password,, should be encrypted and the same be stored it in the database and retrieve each time, decrypted and used 13-Dec-2012 FSSNeT PGS MID HUMI BHP V4.0 Page 29

30 Section 6 (a) Frequently Asked Queries (General) 1. Not able to connect to payment gateway The following options can help to solve the problem- Initiate an nslookup command from the merchant server Run the nslookup command from merchant server and check for successful connection establishment. The correct command is: nslookup securepgtest.fssnet.co.in The expected result of nslookup is the Payment Gateway IP Address of the Web Server The merchant logs into the site, this will help to identify whether there is any restrictions in the network to open the page Confirm that port 80 and 443 are open for the Payment Gateway messaging Please collect Payment Gateway Test and Production IP Address from the Bank Team 2. Some time Merchant gets Denied By Risk as the response The merchant gets this message in response when any transaction on the merchant terminal cross the threshold transaction amount limit defined by Bank for the merchant/terminal. The merchant needs to contact bank on this error 3. GW00456-Invalid TranPortal ID. When the merchant ID sent by merchant and the ID SET by the bank does not matches. Merchant should re-login and verify the correct ID from Payment Gateway Merchant Console from View Plugin Information option for the specific merchant terminal ID. 4. GW00457-Action not supported When the merchant is not allowed to perform specified Action by Bank, the merchant should contact Bank for this problem 5. GW00875-Missing required data. The merchant will get this error if the merchant has not passed the mandatory fields required for the transaction to be completed. The basic parameters are: 13-Dec-2012 FSSNeT PGS MID HUMI BHP V4.0 Page 30

31 Action Code Amount Response URL Error URL For more parameters kindly refer input parameter section mentioned above in this document. 6. The ID and Password differs from terminal to terminal, a merchant can have single or multiple terminal with the same Bank. Merchant should ensure proper ID and password is used for respective terminal transactions. 7. Incase the merchant is redirecting the response from the Payment Gateway to ports other than 80/443, the merchant should inform the Payment Gateway helpdesk team so that they can open the respective port for response handling 8. What are the browsers supported by Payment Gateway in Hosted Page environment? Payment Gateway Bank Hosted Page is best viewed in Internet Explorer 5.5 and above. Payment Gateway Bank Hosted page supports below versions of different browsers - Internet Explorer 5.5 and above - Mozilla Firefox 1.6 and above The other browsers are supported but limited to difference in look and feel could appear 9. What needs to be done by merchant developer for integrating? a. Merchant developer takes all required parameters mentioned above and formulates a string from all the parameters as per sample provided below. String id= &password=password123&action=1&langid=usa&currencycod e=356&amt=1.00&responseurl= t&errorurl= 456&udf1=Test1&udf2=Test2&udf3=Test3&udf4=Test4&udf5=1472f342b20b e3745b7b1a4d368e3d78680ab4dad57c82057e900f11fe481783& b. Merchant now POST the above string on the Payment Gateway URL using HTTPs port (443 port) TCP IP Payment Gateway Test Environment URL c. Payment Gateway gives response back after validating parameters and merchant credentials 13-Dec-2012 FSSNeT PGS MID HUMI BHP V4.0 Page 31

32 Response if ERROR!ERROR!-GW00456-Invalid TranPortal ID Response if merchant is validated successfully : way/payment/payment.jsp d. If error is received merchant gives appropriate response to customer. If merchant receives Payment Id and Pay URL then merchant redirects the customer browser on the Pay URL with Payment ID string generated by merchant for redirection /payment.jsp?paymentid= e. Now customer browser is redirected, customer provides required details to Payment Gateway and Payment Gateway processing the transactions and give response back to Merchant ResponseURL or merchant errorurl depending on transaction status response from Payment Gateway on Merchant responseurl paymentid= &result=captured&auth=999999&avr=n&ref= &tranid= &postdate=1019&udf1=Test1&udf 2=Test2&udf3=Test3&udf4=Test4&udf5= ecc ea9b06145b96d 3c607b20556e24d2360f917ec856bd49ff&trackid= &amt=1.0 response from Payment Gateway on Merchant errorurl paymentid= &error=py20006&errortext=py Invalid+Brand.&udf1=Test1&udf2=Test2&udf3=Test3&udf4=Test4&udf5=0 93dc34e6ebc7fd5dd963221d0a95fc1a95af2fde0df774fa3b5c02c e&t rackid= &amt= Error Page handling There can be a scenario where merchant response URL may not be available to Payment Gateway for example merchant has given incorrect response URL etc. In such cases, Payment Gateway will redirect the customer browser to merchant error URL with out any parameter values. Merchant should ensure such conditions / scenarios are handled appropriately at merchant end. 13-Dec-2012 FSSNeT PGS MID HUMI BHP V4.0 Page 32