Merchant Developer Guide Date: 3 September 2013 Version: 3.3 Status: Release
Document Information Copyright TSYS 2013. All rights reserved. Copyright in the whole and every part of this document belongs to TSYS, with the exception of proprietary material and the brand or product names of other parties for which the rights in such material or trademarks remain with their respective owners. Names and data used in examples herein are fictitious unless otherwise noted. Disclaimer This document and the TSYS software it describes are furnished by TSYS under a Software Licensing Agreement, Consultancy Agreement, Variation Order or Confidentiality Agreement, and may be used or copied only in accordance with the terms of such Agreement. Neither this document nor the TSYS software it describes may be used, sold, transferred, copied, translated, reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, in whole or in part, other than in accordance with the terms of such Agreement, or otherwise without prior written consent of TSYS. This document describes a generic product or service and should be read in conjunction with other documents relevant to the configuration of any specific system. The licensee of TSYS software or user of TSYS services is responsible for ensuring that the product or service described herein meets its own requirements. The information contained in this document is subject to change without notice and should not be taken as a commitment by TSYS. TSYS assumes no responsibility for any errors that may appear in this document. Confidentiality The information contained herein is the property of TSYS. This document contains confidential information that is produced solely for the benefit of the receiving party named on the front page of this document. The recipient should keep all information contained herein confidential, and on no account should the information, in whole or in part, be used, sold, transferred, copied, translated, reproduced or transmitted in any form or by any means, electronic or mechanical, or disclosed or disseminated to any third party, without the express written permission of TSYS. Document Publication Details Area Description Title SENTRY Payment Gateway Subject Released Date 02/05/2011 Version 3.3 (Release) Author SENTRY Team Document Version Control Version Date Comments 3.0 04/07/2013 Update document layout, review content for clarifications and corrections, enhanced appendix B, added appendix E 3.2 17/7/2013 Update Appendix E for latest versions of IE10, Opera, Chrome & Firefox 3.3 03/09/13 Add error code & description for custom MCBA checkout page timeout Page 2 of 72
Contents Contents... 3 List of figures... 6 1. Introduction... 7 1.1 Purpose of the Developer s Guide... 7 1.2 Intended audience... 7 1.3 SENTRY Basics and Requirements... 7 1.3.1 What is SENTRY?... 7 1.3.2 What is Credit Card Processing?... 8 1.3.3 What is the 3-D Secure protocol?... 9 1.3.4 Processing your first Test Transaction... 12 1.3.5 Sample Checkout Page... 13 1.3.6 Mandatory Fields... 15 1.3.7 Basic submission of a Merchant Order... 16 1.4 Data Integrity and Security using a Hash Signature... 17 1.4.1 Example of order signature generation... 17 1.4.2 Merchant Response Page... 19 1.4.2.1 A simple Response listener example... 20 1.4.3 Conclusion... 21 2. Getting Started with Merchant Administration... 22 2.1 The Merchant Menu... 22 2.2 Merchant Account... 22 2.3 What s next?... 23 3. Processing Methods... 24 3.1 SENTRY PG Integration Methods... 24 3.2 Virtual POS and MOTO transactions... 25 3.3 Connecting with SENTRY PG... 25 3.3.1 Overview of SENTRY PG Handler Methods... 25 3.4 Choosing a method... 26 3.5 Overview of SENTRY Direct Link... 26 3.5.1 Example Minimum requirements for Direct Link Method... 27 3.5.1.1 Displaying the ACS authentication window... 31 3.6 Overview of SENTRY Redirect Link... 34 3.6.1 Example - Minimum Requirements for Redirect Link... 34 3.7 SENTRY Batch Transaction Processing... 37 3.7.1 Uploading batch files... 37 3.7.2 Data Validation... 37 3.7.3 Batch file processing... 37 3.7.4 Checking the status of an uploaded batch file... 37 3.8 File Format... 37 3.8.1 Sample Batch File... 38 Page 3 of 72
3.8.2 Merchant Details MDET... 38 3.8.3 Authorization Request AUTH... 38 3.8.4 Refund Request REF... 38 3.8.5 Reversal Request REV... 39 3.8.6 Capture CAPT... 39 3.8.7 Authorization Request/Capture AUTHC... 40 3.8.8 Instalments INST... 41 3.8.9 Sending Order Details with merchant request... 43 3.8.10 Sending Additional Order Details with merchant request... 44 3.8.11 Airline Ticket Order Updates... 44 3.8.12 Recurring Transactions... 44 3.8.13 Instalment Transactions... 45 3.8.14 Handler Details... 45 3.8.14.1 DirectAuthLink... 45 3.8.14.2 DirectAuthztpLink... 46 3.8.14.3 DirectAVSLink... 47 3.8.14.4 DirectAuthzLink... 47 3.8.14.5 RedirectLink... 48 3.8.14.6 FinancialLink... 48 3.8.15 Incoming/Outgoing Signature or Response Fields Customization... 48 4. Appendix A Transaction Fields... 50 4.1 Form Fields... 50 5. Appendix B Response Codes... 61 5.1 System Response Codes... 61 5.1.1 Data Sent with Response Codes... 61 5.2 Customized Incoming Signature Fields... 62 5.3 Customized Outgoing Signature Fields... 62 5.4 Customized Response Codes Fields... 63 5.5 System Response Codes... 63 5.6 System Response Reason Codes for Response Code 1... 63 5.7 System Response Reason Codes for Response Code 2... 64 5.8 System Response Reason Codes for Response Code 3... 64 5.9 System Response Reason Codes for 3D-Secure Errors... 65 5.10 System Response Reason Codes for Airline Data Update... 65 5.11 System Error Codes for Store Front Services... 66 6. Appendix C AVS Result Codes... 69 6.1 VISA Transactions... 69 6.2 MasterCard Transactions... 69 6.3 AMEX Transactions... 70 7. Appendix D CVV2 Result Codes... 71 8. Appendix E Browser Compatibility... 72 Page 4 of 72
8.1 Test platform... 72 8.2 Legend... 72 Page 5 of 72
List of figures Figure 1: BASE I overview... 9 Figure 2: Authentication and Authorization overview Verify Enrolment... 10 Figure 3: Authentication and Authorization overview Payment Authentication... 11 Figure 4: Authentication and Authorization overview Authorization... 12 Figure 5: SENTRY PG cycle overview... 13 Figure 6: Sample Merchant Checkout Page... 14 Figure 7: Sample SENTRY PG Checkout Page... 15 Page 6 of 72
1. Introduction The Internet represents a tremendous opportunity for business regardless of the size of an organization. But selling goods and services on the Internet presents its own set of challenges. How can a business set up and maintain a secure, reliable, cost-effective system for processing credit cards and managing transactions? You want to sell your products in an easy to use and secure method but do not want to bother with the complexities that are involved in the card processing business. The SENTRY Payment Gateway (SENTRY PG for short) is a platform built with the goal to remove the complexity and effort involved with conducting e-commerce business on the Internet. From a merchant s perspective, all that is needed to process and manage transactions over the World Wide Web is a merchant account with an Acquirer running SENTRY PG, and a computer with an Internet connection and a Web browser. 1.1 Purpose of the Developer s Guide This guide s purpose is to provide information that will enable merchant developers to understand the functionality offered by SENTRY Payment Gateway, and allow them to choose the right integration options to suit the merchant s technical capabilities and business environment. The guide does not dictate coding techniques for integration. It only provides guidelines to understanding the basics of integrating a web application with the SENTRY Payment Gateway. It does not provide a complete solution to merchant developers on how to build an ecommerce web site. 1.2 Intended audience This guide is addressed towards e-commerce Merchants and the web developers tasked with integrating the Merchant s website/checkout system with SENTRY PG and MPI. It is assumed that readers are familiar with web development, web application security and the technologies supporting the World Wide Web. In order to fully benefit from this document, readers should ideally possess a basic understanding of card payments processing and related infrastructure, as well as a basic understanding of the 3D-Secure authentication protocol. 1.3 SENTRY Basics and Requirements 1.3.1 What is SENTRY? SENTRY PG is a Web-facing, real-time transaction processing system that serves as a payment gateway switch, using a secure connection to a Web server on the Internet. Merchants with a valid, enabled merchant account can use the system to submit, authorize and capture card transactions without the need for a separate transaction terminal. In addition to the normal e-commerce functionality, SENTRY supports 3D-Secure transactions, file based batch transactions, web-service based transactions and several other mechanisms, utilities and applications to help you process and manage e-commerce transactions. SENTRY PG is made up of four main modules: the Checkout Application, the Merchant Plug-In, the Bank Administration application and the Merchant Administration application. The Checkout Application is the module responsible for e-commerce transaction processing. The Merchant Plug-In, or MPI for short, is fully integrated with the Checkout Application and is responsible for handling cardholder authentication (3-D Page 7 of 72
Secure). The Merchant Administration application is a Web-facing front-end application that provides a user friendly interface that can be used by Merchants to manage their transactions. Although processing credit cards can be a complex and error-prone exercise, the whole family of SENTRY products has been designed to provide a user-friendly experience to both the merchant and the Cardholder, and at the same time provide a highly secure and stable platform that ecommerce merchants can depend on to run their business. The following section explains the basic e-commerce processing flow. The section after that discusses the 3-D Secure protocol which is considered the most secure credit card authentication protocol for Internet transactions. If you are familiar with the methodology used for processing e-commerce transactions you can jump right to the Processing your First Test Transaction section which explains the easiest and fastest method of connecting your ecommerce web site with the SENTRY Payment Gateway. 1.3.2 What is Credit Card Processing? Credit card processing sounds and can be a relatively difficult process that can take a lot of effort and money if a merchant chooses to implement it independently. Thankfully SENTRY PG provides the means to process e-commerce transactions much easier. The following is an outline of the steps involved in processing a credit card transaction: 1. SENTRY takes over from the point where the customer is ready to checkout (and pay with the credit card). SENTRY PG provides the means for doing both the Authentication cycle (3-D Secure Protocol) and the Authorization cycle. 2. After securely providing the credit card details, an electronic request is submitted to the processing network for authorization and capture from the cardholder's credit card account for the amount of the purchase. In a brick and mortar merchant, one would submit this request by swiping a credit card through an electronic transaction terminal provided by the acquiring bank. This request is provided electronically to SENTRY Payment Gateway, which then routes the request to the Provider s Payment System Host. In case Authentication is required by the SENTRY provider before step 3 takes place (Authorization Cycle), SENTRY Payment Gateway will authenticate the cardholder using 3-D Secure protocol (Authentication Cycle). 3. The authorization cycle, via SENTRY and the provider s acquiring host, is passed through the credit card interchange system to the credit card issuer. The credit card issuer determines if the cardholder's account is valid and if the funds are available. If they are, the processing network returns an electronic response to your terminal or computer. This response is called an authorization code, and is your guaranteed authorization to capture the funds. Typically, this code is a six-digit number. The transaction and its associated authorization are stored in a batch, where other currently unsettled transactions for that day reside. This entire authorization process typically takes 3 to 4 seconds, but this can vary depending on network and payment system traffic. 4. At the end of the business day (scheduled by the SENTRY provider to a default time), the SENTRY server or the Acquirer s banking host automatically creates batch files of your transactions that were flagged as captured. This is called settlement or settling your batch. With a traditional physical credit card swipe terminal, this settlement process must be initiated manually. One of the key advantages of SENTRY PG is that this settlement process is initiated automatically every day. 5. The SENTRY Provider will transmit the transaction batches to the Credit Card Interchange System, which, in turn, passes the batch onto the Credit Card Issuer. A settlement report can be printed showing the grand totals by card type (Visa, MasterCard, American Express, etc.) for the settled batch. Note: any corrections to the merchant s batch, such as voiding a transaction, must be made prior to settlement. Page 8 of 72
6. Within 48 to 72 hours (usually), the funds associated with the batch settled will be deposited electronically into the merchant s bank account. 7. At the end of the month, your provider will mail a statement to the merchant, detailing the credit card activity for the month and the associated fees the merchant has been charged for. The following diagram shows the authorization cycle that occurs during the first part of the credit card processing (BASE I), which occurs from the point when the cardholder enters the card information to the point when a response is received from the card holder s Issuer. Figure 1: BASE I overview 1.3.3 What is the 3-D Secure protocol? Since the first e-commerce credit card processing it was apparent that the possibility of fraudulent transactions is much higher than the traditional POS model of processing. The Payment Systems have recognised this and they have jointly developed the 3-D Secure protocol which is a highly secure protocol that was designed from scratch with the purpose to reduce ecommerce fraud as much as possible. The protocol is called 3-D Secure because during its cycle it involves three Domains: the Acquirer (Merchant) Domain, the Interoperability Domain (Payment System) and the Issuer (Card Holder) Domain. The main premise of the protocol is to generate a digital signature which will otherwise be impossible to generate, unless all three parties are authenticated properly within the context of an individual transaction. This digital signature is generically called the Card Authentication and Verification Value (CAVV) and is generated by the Issuer only after the Card Holder enters a password or secret phrase, during the 3-D Secure cycle. This signature is included in the authorization message that will be sent by the Acquirer and at the end of the process it will be verified by the same Issuer. Page 9 of 72
In order to process credit cards using this protocol from beginning to end, all three parties must participate in the program. If the Merchant is 3-D Secure enabled, the processing cycle changes at the point where the Payment Gateway sends the request to the Acquirer. Before this step is taken the Payment Gateway will have to check if the transaction can be performed with 3-D Secure. To do that, the Payment Gateway (or the Merchant) will contact the MPI (Merchant Plug In) and inquire if this card holder s Issuer and the card itself support the protocol. The details of the protocol are explained in a later section but in simple words this is what happens: 1. The Payment Gateway will send the card number to the MPI to check if the card and the Issuer are both enrolled in this program. The MPI will send a request (VeReq, Verification of Enrolment Request), to the Payment System s Directory Server (VISA, MasterCard etc). 2. The Directory Server will respond to the MPI with a Y or N response indicating if the card and the Issuer are enrolled. 3. If the answer is Y then the MPI will inform the Payment Gateway that the card holder has to be redirected to his/hers Issuer s web site (PaReq, Payer Authentication Request). 4. The card holder will be redirected to the Issuer to enter their 3D Secure password for authentication. After this is done, the Issuer will send a response back to the MPI (PaRes, Payer Authentication Request). 5. If the password was correct, the MPI will receive a Y in the PaRes and the verification value (CAVV). 6. The Payment Gateway will take the CAVV and insert it into the authorization message that will be sent to the Acquirer. From there on, the cycle is the same, except that the Issuer before checking that there are enough funds in the card, it will check that the CAVV value is valid. The following diagrams show a simplified version of the Authorization cycle together with the Authentication Cycle (3-D Secure). Figure 2: Authentication and Authorization overview Verify Enrolment Page 10 of 72
The Credit Card Holder enters the card information, the Payment Gateway requests from the MPI to check if the card is enrolled from the Directory Server. The Directory Server will locate the Issuer and request this information and send the results back to the MPI. The MPI will inform the Payment Gateway of the status of the request. This all happens behind the scenes and is transparent to the cardholder. Figure 3: Authentication and Authorization overview Payment Authentication Page 11 of 72
Figure 4: Authentication and Authorization overview Authorization The Acquirer will send the transaction for authorization to the Credit Card s Issuer including the CAVV in the authorization request. The Issuer will receive the request, validate the CAVV, then check for funds availability and finally respond back to the Acquirer. The Acquirer will forward the response back to the Payment Gateway and from there the Merchant will receive the response and inform the Card Holder. 1.3.4 Processing your first Test Transaction Processing transactions using the SENTRY is easy. However, it is important that the developer assigned with the task of integrating the Merchant s Checkout system with SENTRY has basic knowledge of Internet technology (HTML, SSL, scripting etc). Let s go through a simple transaction flow and how you can start sending test transactions as soon as possible. The flow begins when a potential customer arrives at the merchant s web store. The customer will select which items he/she wants to purchase, prepare the shopping basket and proceed to checkout. The following diagram shows the customer selecting to proceed to the checkout and what happens from there. Page 12 of 72
Figure 5: SENTRY PG cycle overview 1. Merchant s web site will create the request a send it to SENTRY. 2. SENTRY will ask the cardholder to enter the card information. 3. The authorization will be sent to the cardholder s bank. 4. And finally a response will be sent to the merchant s Web Site informing them if the authorization was successful or not. From a merchant s perspective, the process is simple, despite the high amount of processing taking place behind the scenes. The benefit for merchants of using SENTRY is that as long as you have an account with an Acquirer, and you are set up correctly in SENTRY Payment Gateway, the merchant s part is trivial. The only thing that is needed is a way to program the merchant Checkout system in order to send order requests to SENTRY for processing. Let s see what is actually required from the merchant s side in order to accomplish this. 1.3.5 Sample Checkout Page The way SENTRY works is that it waits for the merchant to request a particular listener, and provide the required data. As soon as it receives a request for that listener SENTRY will validate the order data that the merchant provided, and will start processing the transaction. Below is a simple page that can be stored in your web server and when loaded will show only a checkout button. As soon as you press that button, the request will be sent to SENTRY and the processing will initiate (If you would like to experiment by using this example note that some of the fields values will have to change according to the data that your Acquirer will provide otherwise the request will be rejected. You will also need to calculate the signature correctly). Here is the HTML code of the web page: <HTML> <body> Page 13 of 72
<form id='frmhtmlcheckout' name='frmhtmlcheckout' action=''https://sentry_host/sentry/paymentgateway/application/redirectlink.aspx'' method='post'> <input id='version' type='hidden' name='version' value='1.0.0'> <input id='merid' type='hidden' value='0009999012' name='merid' > <input id='acqid' type='hidden' value='459889' name='acqid' > <input id='merrespurl' type='hidden' value='https://your_server.com/sentryresponse.aspx' name='merrespurl'> <input id='purchasecurrency' type='hidden' value='196' name='purchasecurrency'> <input id='purchasecurrencyexponent' type='hidden' value='2' name='purchasecurrencyexponent'> <input id='orderid' type='hidden' value='20050201162457147' name='orderid' > <input id='signaturemethod' type='hidden' value='sha1' name='signaturemethod'> <input id='purchaseamt' type='hidden' value='000000000075' name='purchaseamt'> <input id='signature' type='hidden' value='w25b1ism517imsnpuumfkweze9m=' name='signature'> <input style="z-index: 101; LEFT: 264px; POSITION: absolute; TOP: 152px" type="submit" action="https://sentry_host/sentry/paymentgateway/application/redirectlink.aspx" </HTML> </body> </form> value="submit"> The above rudimentary sample defines a form (FrmHtmlCheckout) containing the necessary order fields that are to be sent to the SENTRY PG listener. Notice the form method is set to post, indicating the sender must use HTTP POST to send the data to SENTRY. The MerRespURL field must be present otherwise SENTRY will reject the request. Figure 6: Sample Merchant Checkout Page Page 14 of 72
By pressing the Submit button, the request will be sent to SENTRY PG for authorization. In a few fractions of a second the checkout page (similar to the one below) will appear in the browser. After the card details have been entered, the transaction can be submitted for processing. Figure 7: Sample SENTRY PG Checkout Page In the next section we will go over the mandatory fields that the merchant is required to send, in order for the transaction to take place. We will also look at how to send our first test transaction. 1.3.6 Mandatory Fields As in most applications, certain fields are optional and others are mandatory. In the case of SENTRY PG there are only few mandatory fields that the system will expect to receive in order to continue the transaction. Most of these are fixed (per Merchant) and some depend on the transaction. In the sample Web Page above the following fields were used: 1. Version This is the version of the SENTRY PG - currently set to 1.0.0 2. MerID This is your Merchant ID as set in SENTRY (will be provided by your SENTRY Provider) 3. AcqID This is your Acquirer ID (will be provided by your SENTRY Provider) 4. MerRespURL This is the fully qualified URL of a Web Page on the merchant s server where the final response will be sent 5. PurchaseCurrency This is the standard ISO code of the currency used for this transaction 6. PurchaseCurrencyExponent This is the number of decimal places used in the amount (usually 2) Page 15 of 72
7. OrderID This is the Order ID that will be used to match a merchant s submitted Orders with SENTRY transactions. This Order ID must be a unique value. 8. SignatureMethod This is the signature method used to calculate the merchant order s signature (explained below) 9. PurchaseAmt This is the total amount of the purchase 10. Signature This is a digital signature that will verify that the contents of this Web Page have not been altered while in transit. (SENTRY will verify this signature) Most of the mandatory fields will always be the same or will rarely change. The only fields that will almost always change are the OrderID, PurchaseAmt and Signature. Note Note Note The Order ID MUST be a unique number because it will be easier for you to track the Orders that you have on the Web Site with the actual transactions in SENTRY. A unique order id will also guarantee that even if the cardholder presses the back or submit button several times the transaction will only be processed once. The PurchaseAmt is straight forward, it is basically the normal amount e.g. 134.78, but without the decimal place and left padded with zeros in order to make the number twelve characters long. Therefore the amount 134.78 should be 000000013478. The signature is a little more complicated and is discussed later on. 1.3.7 Basic submission of a Merchant Order The HTML page shown above has a single submit button, that when pressed will POST the HTTP form from section 1.2.5 to the URL defined in the Submit button s action tag. This basically instructs the Checkout page to redirect the browser to the action URL, sending all the data in the form fields with the request. When the SENTRY listener picks up this request, it will read all the data in the input fields, validate the data and process the request accordingly. There are several other options that can be used to submit the page for processing to SENTRY and one of them is by using some JavaScript. The page below uses a JavaScript function wired to the Submit button s onclick event (onclick ="Checkout"). The JavaScript function called Checkout() will do the same thing as before; that is it will POST the page and its form data to the SENTRY Web Server. <HTML> <body> <form id='frmhtmlcheckout' name='frmhtmlcheckout' action='' method='post'> <input id='version' type='hidden' name='version' value='1.0.0'> <input id='merid' type='hidden' value='0009999012' name='merid' > <input id='acqid' type='hidden' value='459889' name='acqid' > <input id='merrespurl' type='hidden' value='https://your_server.com/sentryresponse.aspx' name='merrespurl'> </form> <input id='purchasecurrency' type='hidden' value='196' name='purchasecurrency'> <input id='purchasecurrencyexponent' type='hidden' value='2' name='purchasecurrencyexponent'> <input id='orderid' type='hidden' value='20050201162457147' name='orderid' > <input id='signaturemethod' type='hidden' value='sha1' name='signaturemethod'> <input id='purchaseamt' type='hidden' value='000000000075' name='purchaseamt'> <input id='signature' type='hidden' value='w25b1ism517imsnpuumfkweze9m=' name='signature'> <input style="z-index: 101; LEFT: 264px; POSITION: absolute; TOP: 152px" type="submit" onclick ="Checkout" value="submit"> Page 16 of 72
<script language='javascript'> </body> </script> function CheckOut(){ document.frmhtmlcheckout.action = 'https://sentry_host/sentry/paymentgateway/application/redirectlink.aspx'; document.frmhtmlcheckout.submit(); } </HTML> In addition to these two samples shown above, merchant developers are free to use other programming approaches to collect and submit the data to SENTRY. Implementation is up to the merchant developer. 1.4 Data Integrity and Security using a Hash Signature A hash signature is required when using either of the methods. The MD5/SHA1 hash is a security feature that enables your script to identify that the results of a transaction are actually from the appropriate authorization source and also for the Payment Gateway Server to make sure the integrity of data received on a transaction request. Using either MD5 or SHA1 algorithm, a unique signature or fingerprint of the transaction can be created. The mathematical algorithm used to construct this signature is designed in such a way that any change to the information used in the calculation of the signature will cause a different signature to be created. The information used in the calculation of the signature cannot be discovered through any analysis of the signature itself. Signature calculation is done by using information from the merchant SENTRY account. Every transaction that is processed through the system has a corresponding hash signature, created during the transaction process. This signature must be computed and included in every submitted transaction. The signature for a request is a hash of the following six fields: 1. Password (This is the password included in the mailer that your provider supplied) 2. Merchant Id 3. Acquirer Id 4. Order Id (The unique Order Id that your system generates) 5. Purchase Amount 6. Purchase Currency The fields must be set in the following order, (Password & MerchantID & AcquirerID & OrderID & Purchase Amount & PurchaseCurrency) 1.4.1 Example of order signature generation If your password was "orange", your Merchant Id was "45877687", your Acquirer Id was 459999, the Order Id was "SENTRYORD01154321", the amount was "12.00", and Purchase Currency was 840. The request s hash would be calculated based on the following string: orange45877687459999sentryord01154321000000001200840 Page 17 of 72
The resulting hash signature value equals to (using SHA1 algorithm in this case) U50GMpLO3fQ764kYILbqIcV5uAg= If the authorization request is successful, SENTRY will create a second hashed signature using the SHA1 hashing algorithm, and include it in the response message. Therefore when you receive the response data you can verify that the values were not modified in transit. The hash signature for the response is a hash of the following fields: 1. Password (This is the password included in the mailer that your provider supplied) 2. Merchant Id 3. Acquirer Id 4. Order Id (The Order Id that you included in the request) The fields must be set in the following order, (Password & MerchantID & AcquirerID & OrderID) For example: If your password was "orange", your Merchant Id was "45877687", your Acquirer Id was 459999 and the Order Id was "SENTRYORD01154321". The response s hash would be calculated on the following string: orange45877687459999sentryord01154321 The resulting hash value equals to: (note that only SHA1 is currently supported for the response) WbwSWEBzPqgo9C4nZmGwHhd/FBQ= When SENTRY Payment Gateway receives the request of the merchant order, it will compute the Hash value and check if it matches the hash value you have included in your order request. When the merchant s checkout system receives the results of the transaction from SENTRY, it will compute the hash and compare it to the one sent by SENTRY, to be sure that both are the same. The merchant s system already knows the hash seed values (password, merchant ID, etc), and will receive back the order ID sent in the initial request to SENTRY. Please note that the Signature in the response will only be present if the transaction passed the order validation stage. Responses for transactions which do not pass the order validation stage, or suffer an error during validation processing will not carry a signature value. A developer would receive the results of the transaction AFTER it was returned to the merchant server, and run the hash algorithm on the fields mentioned above. The only way that the results of a developer s processing can match the signature included with the transaction results is if the password used in the hash on the developer s end MATCHES the one used to compute the hash of the initial order request. The SENTRY listener password is a shared secret between the merchant and the Acquirer or Processor, and is one of the key pieces of information in the hash. One can be assured that if the signature generated on the merchant end matches the one sent with the transaction, then the transaction has in fact been Page 18 of 72
processed by the legitimate system, and has not been posted back to the merchant s server from any other location. The SENTRY password is generated by SENTRY during merchant account creation, and is sent securely to the merchant. This is also used to authenticate your server to our server during transaction posting. It is only known by the merchant and the SENTRY system. All sensitive data and passwords are stored under AES encryption. Also note that the merchant has the ability to choose which hashing algorithm to use on every order request (MD5, SHA1). If no hashing algorithm is specified in the order request, SENTRY will default to SHA1 (recommended). More information about the SHA1 hash algorithm, including sample implementation code, can be found in RFC 3174 in The Internet Engineering Task Force web site. More information about the MD5 hash algorithm, including sample implementation code, can be found in RFC 1321 in The Internet Engineering Task Force web site. The following VB.NET sample shows how to use the.net libraries to perform signature computation. The key argument passed to the function is a concatenation of the mandatory fields illustrated above. Public Shared Function ComputeHash(ByVal Key As String) As String Dim objsha1 As New SHA1CryptoServiceProvider() objsha1.computehash(system.text.encoding.utf8.getbytes(key.tochararray)) Dim buffer() As Byte = objsha1.hash Dim HashValue As String = System.Convert.ToBase64String(buffer) Return HashValue End Function Apart from the hashing algorithm described above, there is an extra layer of security with the use of bitmaps. See section Incoming/ Outgoing Signature or Response field s customization. 1.4.2 Merchant Response Page By this point the merchant s web developer should have all the information needed to submit an order request to SENTRY PG. However, you need a way to catch SENTRY s response to your order submission. SENTRY expects a Response URL to be passed in the POSTed page, which will point to a web listener on the merchant s server. When the authorization request completes, SENTRY PG will send a response to this URL, in order for the merchant to parse and interpret the results of the order request. The SENTRY response is made of several parts. The first is the Response Code which is the most important part of the equation. This will equal to 1, 2 or 3. Response code Response code meaning 1 Transaction was approved 2 Transaction was declined Page 19 of 72
Response code Response code meaning 3 Error during transaction processing By reading this value you can determine whether the payment was accepted or not. There are several other values that can be returned when a transaction is completed, which include the Reason Code, which is a numeric value that maps to the reason why a particular transaction was declined. There is a Response Description which carries a textual description of the result of the transaction. There are also other response fields like the Authentication response, the AVS response codes etc, depending on the type of transaction requested and the acquiring host that responded. For a complete list of these values, readers should refer to Appendix B (Response Codes). Response codes are returned inside hidden form fields inside the HTML posted back to the merchant s Response URL. In order to receive the SENTRY response you will need the following: A simple Web Page that will show the response details to the card holder. A way to read the data from the response and use it to update the order of the customer. A simple Web Page that will accept the response from SENTRY Usually the first and last points are the same Web Page. This Web Page will read the response codes from the SENTRY response, and update the record of the order request. The merchant s response page can be developed to show a message indicating to the customer if the transaction was successful or not. The method used to update the order and display the information to the client is up to the merchant s developer and there are several methods of achieving this, which can range from very simple to very complex depending on how your business logic will be enforced and the complexity of your Web Site. 1.4.2.1 A simple Response listener example The following VB.Net snippet will simply read the values from the request page and display them on a placeholder (label) on the form that the customer will see. This method is usually too simple to be used in a Production environment but can nevertheless form the basis of a more complex one. Private Sub Page_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load If Page.IsPostBack = False Then Dim FormKey As String Dim FormValue As String lblallformitems.text = "" lblallformkeys.text = "" For Each FormKey In Request.Form Next End If End Sub FormValue = Request.Form.Item(FormKey) If FormValue <> String.Empty Then lblallformkeys.text &= "<br><b>" & FormKey & ": </b> " lblallformitems.text &= "<br>" & FormValue End If Page 20 of 72
When the SENTRY response arrives at the response URL, the page_load event is fired. The event handler extracts the HTML form from the returned HTTP response, iterates over the form fields and prints the response field names and their associated values inside a ASP.NET web forms Label control. 1.4.3 Conclusion Readers should now understand the basic concepts of how to submit a transaction to SENTRY PG. If developers already have a Merchant Account, they should be able to send test transaction requests successfully. In the following sections readers will find information on all the functionality of SENTRY, such as selecting and using Direct or Redirect method, passing Airline or Order Details data to SENTRY PG, performing AVS checking (only if supported by Acquiring Host), recurring transactions, instalments, submit batch files, etc. Page 21 of 72
2. Getting Started with Merchant Administration Every merchant has access to the Merchant Administration module of SENTRY PG that can be viewed and edited. The system designed for ease of use. Each merchant user that uses the system has a unique login id and password used to access the system. The merchant s Processor/Acquirer will provide the merchant with an administrative user login id and password once the merchant account has been created in SENTRY PG. Upon logging in for the first time, users are prompted to change their password to an alphanumeric value. Merchant users must keep the login ID and password in a secure place and refrain from distributing it to anyone who does not need access to the merchant account interface. To log in to the system, users must first have access to the World Wide Web on the Internet. Once a user is online, they can open their Internet browser and login to the Merchant Administration application by accessing the following URL: https://<your Provider URL>/SENTRY/PaymentGateway/Merchant/Administration The <your provider URL> is the fully qualified domain name of the merchant s Processor/Acquirer. The channel is secured using 128-bit encryption with HTTPS over TLS or SSL3. 2.1 The Merchant Menu The first time a users logs on to the system, they are be required to change your password from the one that the provider has given you. Once the user modifies the password, they will have full access to the system, which starts with the Merchant Menu. The Merchant Menu is the central area from which users can access the system s configuration, reporting, and processing features. Please refer to the Merchant Administration s User Guide available from your provider. This document contains all the information users need in order to understand the various options available inside the Merchant Administration application. The remainder of this document will be primarily concerned with technical implementation and integration of a merchant s Web site with the SENTRY PG system. 2.2 Merchant Account Note The terms and conditions of the Merchant Account must be kept strictly confidential between the merchant and the processor and they should be consulted for specific information related to the merchant s account. A Merchant Account is required to accept credit cards through the application. A Merchant Account is a special account with an Acquiring Institution (or Processor), which must be a member of the payment association (e.g. VISA, MasterCard) for which the merchant wishes to process transactions. The Acquiring Institution (or Processor) will: Assign the merchant a Merchant Account Number (Merchant Id) Set up the merchant s SENTRY account Assign the merchant an Administrator Login Id and password for the Merchant Administration Web application. Act as the merchant s main point of contact for issues regarding the Merchant Administration access, and SENTRY account. Work with the merchant to configure the merchant s account. Page 22 of 72
Once the Merchant s Account is set up and becomes live on the system, the merchant can begin to accept credit Production transactions from customers. 2.3 What s next? At this point, merchant developers should have: 1. A merchant account able to process test transactions (if you don t yet have a SENTRY account, contact your Acquirer/Processor). 2. Familiarity with how credit card processing works. 3. A basic understanding of SENTRY architecture. 4. Access to the Internet. The guide will help merchant developers determine how SENTRY can best be integrated into the merchant s checkout environment. Basically, if the merchant does not operate a web-based checkout from which users can purchase products, then they can use the Virtual POS or the Batch File options. If a merchant operates a website from which cardholders can purchase products, then developers are invited to use either SENTRY Direct Link or SENTRY Redirect Link methods, depending on the agreement the merchant has made with their Processor/Acquirer. Page 23 of 72
3. Processing Methods SENTRY PG offers a number of methods for integration with the merchant s checkout system. The method of integration depends on your developer(s) skills and environment you want to build. 3.1 SENTRY PG Integration Methods As was mentioned above SENTRY PG supports several methods of processing e-commerce transactions and for each method there are a number of optional fields that can be used to customize each request to your individual needs. The main transaction engine is made up of several request listeners, implemented as HTTP handlers within SENTRY Checkout Application. The application also supports other transaction entry points like Web Services, and batch files (plain text files that carry many transactions, processed as a batch). The supported interfaces are listed below. Virtual POS (Merchant Administration module web screens) HTTP Handlers (Handlers are explained in more detailed in Section Hander Details ) o Redirect Link (Authorization with 3D Secure (SENTRY MPI) or Authorization only. Depending whether merchant is enrolled for 3Dsecure). URL to post is RedirectLink.aspx o Direct Link with 3D Secure (SENTRY MPI). URL to post to is DirectAuthLink.aspx o Direct Link without 3D Secure (Authorization Only, no 3D Secure). Offers high-throughput, low latency processing. URL to post is DirectAuthzLink.aspx. o Direct Link with 3D Secure (using an external MPI). URL to post is DirectAuthztpLink.aspx o Financial Link handler. Offers an HTTP-based interface for merchants to submit reversals, refunds and captures for existing original transactions. URL to post is FinancialLink.aspx. Web Services o Available Store Front Services List transactions Refund transactions Reverse transactions Capture transactions Batch Files o Authorization o Capture o Authorization + Capture (single action) o Refund o Reversal o Installment o Recurring These methods can be used on their own or in combination. For example the merchant can use the Redirect Link for all your transactions, 3-D Secure or not. Alternatively you can use the Redirect Link to complete the 3-D Secure Authentication cycle and then depending on the response you can decide whether to send the authorization using the Direct Method. Another combination could be to use the Direct Link with 3-D Secure for authentication only and then follow with the Direct without 3-D Secure to do the authorization. Another approach for Merchants operating their own MPI is to send authorizations through one host but use another host for their 3-D Secure Authentication. This works by using an external MPI to perform the 3D-Secure Authentication, and Page 24 of 72
then use the Direct Link with external MPI handler to pass the authentication data (ECI, CAVV) to initiate the Authorization with SENTRY. The supported interfaces are detailed in the following sections. 3.2 Virtual POS and MOTO transactions The Virtual POS is used for manual key entry of transactions using the Merchant Administration web interface. The effect of the Virtual POS is similar to the normal Point of Sale of a Credit Card terminal. You might need to use the Virtual POS for cases such as if: You received an order by phone, fax, or mail and need to process the transaction. You previously received a voice authorization by phone and now need to submit the transaction for capture. This type of transaction is known as a Mail Order/Telephone Order transaction (MOTO). The Virtual POS allows the merchant to either authorize only and capture later, or to do a full authorization and funds capture with a single transaction. This option does not require the merchant to have a Web site to use Virtual POS. The merchant can log in to the Merchant Administration web site and choose MOTO option on the Merchant Menu. 3.3 Connecting with SENTRY PG 3.3.1 Overview of SENTRY PG Handler Methods Sending order requests to the SENTRY PG Checkout Application is done over two different types of connectivity; both types require familiarity with Web Programming: 1. Direct Link 2. Redirect Link The capabilities offered under each method are listed below: Channel 3D-Secure Authentication supported Plain Authorization supported 3D-Secure Authorization supported (using SENTRY MPI) 3D-Secure Authorization supported (using 3 rd party MPI) Direct Link Yes Yes Yes Yes Redirect Link Yes Yes Yes No Under the Direct Link, a customer's Web browser makes a secure connection to the merchant s server and transmits all of the information necessary to process the transaction (including credit card details) when the shopper is ready to checkout. The merchant s server connects securely to the SENTRY PG web server, and transmits all of the transaction information in a Web Request (via HTTPS) by POSTing an HTML form to the gateway for processing. The gateway server returns the results of the transaction processing to the merchant s server over a secure connection. The merchant can then determine an appropriate response to the customer by interpreting the results of the transaction. Under the Redirect Link, the customer's interaction takes place with the SENTRY Payment Gateway web server. The merchant s Web page initiates a transaction by posting an HTML form to the SENTRY PG server with the required transaction information (amount, currency, item description, and so on), but without any card details. The cardholder is presented with a Checkout Page, and provides card details (number, expiry date, CVV2) to the SENTRY Payment Gateway server. The SENTRY PG server processes the transaction, and then transmits the results of the transaction to the merchant s server over HTTPS. Page 25 of 72
3.4 Choosing a method Both methods provide ways for developers to integrate transaction processing into whatever programs or databases they desire. However, one method might be better suited for certain environments than another. The main factor that determines which method to use will be the merchant s ability to make secure encrypted connections, and to a lesser degree the security requirements of the Acquirer/Processor. The Direct Link method will generally be more suitable than the Redirect Link method because of the greater control it gives developers over the whole transaction process flow. However, a developer won't be able to implement the Direct Link method unless they can provide a secure server side connection and initiate a secure client side connection when they send the transaction information to the gateway server (mutual SSL). This connectivity type requires the merchant s web server to be configured with a server SSL certificate, in order to secure the channel between the cardholder s browser and the merchant s checkout page. Also, an outgoing request from the merchant s server needs to carry a client SSL certificate to establish mutual SSL with the SENTRY PG web server. Implementing client side secure connections is made easier by using some of the readily available tools and libraries for implementing protocols like SSL. However, if it's not possible to create a secure connection on both the server and client sides of the link, the Redirect Link method provides an alternative where sensitive data such as credit card numbers is only transmitted across the secure link between the SENTRY gateway server and the cardholder's browser. To summarize: 1. If you can write a script that can process information sent via an HTTP form POST, then you might want to consider using Redirect Link method. 2. If you can write a script that can process information sent via an HTTPS form POST, AND you can provide a secure server side connection and initiate a secure client side connection, then you might want to consider using Direct Link Response. Please note that the Acquirer/Processor may not allow you to use the Direct Link method. Also, in the case of 3-D Secure, the Redirect Link method is most likely going to be used. Before choosing an integration method, check with your Payment Provider. 3.5 Overview of SENTRY Direct Link The most flexible way to integrate the merchant s Web site with SENTRY PG is by using the Direct Link method. In order to integrate a merchant s checkout system with SENTRY PG using the Direct Link method, a developer must be able to provide server-side as well as client-side security for the connection. A developer would also need to be able to write scripts or develop programs for their Web server to provide the necessary integration. As seen from the Integration Methods Section, there are a number of different Direct Handlers for different operations. To implement the simplest of the Direct Link methods (authorization only, non-3ds): 1. A developer would design a checkout system that can securely obtain all of the information needed to process a transaction. 2. The developer would initiate a secure HTTPS form POST from their server to SENTRY Direct Link Web Handler (DirectAuthZLink.aspx). 3. The SENTRY Checkout Application would process the transaction and respond with the results to the merchant s checkout system, which will then display the appropriate results to the cardholder. The fields contained in the posted form would be all of the information necessary to process a transaction, plus a couple of additional fields. Page 26 of 72