Setting up an online e-commerce system. User guide

Transcription

1 Setting up an online e-commerce system User guide

2 Document history Date Person Description 15 February 2007 Matjaž Pahor - Preliminary versions of this document, Versions 1.0 to July 2008 Milan Čulibrk - Corrections and additions to text of whole document, new document structure, notes added, history, additional references, numbering and contents of document. - American Express and Diners payment in instalments functionality added. - Merchants FAQs during implementation of online shopping added. - Section related to Payment Gateway system s Back-Office portal added. - Document version: July 2011 Milan Čulibrk - Corrections and additions to text of whole document / change in graphics. - Sections/subsections 3 and 4: Corrections and additions to test environment parameters. Tables with detailed descriptions of all request/response parameters for PaymentInit, Payment and NotificationMessage added. Links for downloading files with examples/graphics to aid implementation added. - Correction in Section 5.3 with regard to administration of Diners instalment payments. - Addition to Section 6.1: Review of details for an individual transaction - Addition of explanation of connection to ErrorURL despite successful transaction in Section Additions to Section 8: Demo pages, existing text corrected, explanations for JSP and PHP examples added. - Addition to Appendix 2: Possibility of downloading whole list of supported CAs from Activa website. - Appendix 3: ISO Response Codes added. - Document version: November 2011 Milan Čulibrk - Minor corrections and additions to contents of whole document. - Acceptance of American Express card product enabled: minor corrections in text of whole document. - Payment in instalments with American Express cards added in Section Document version: 3.1 2

3 Notes Symbols in document Text PaymentInit Action=5 Ordinary text Important words, definition of parameters, references, messages Hyperlinks Program code Other resources For additional information related to the content of this document, the following online resources are useful: Activa online shopping Description for POS Security recommendations for online merchants List of Slovenian online merchants participating in the MasterCard SecureCode and Verified by Visa programmes Description of MasterCard SecureCode service Description of Verified by Visa service MasterCard SecureCode (MasterCard s pages on the SecureCode service) in English Verified by VISA (Visa s pages on the Verified by Visa service) in English 3

4 Contents Document history... 2 Notes... 3 Symbols in document... 3 Other resources... 3 Contents INTRODUCTION Payment Gateway Hosted Payment Page (HPP) TRANSACTION PHASES Consumer s point of view Merchant s point of view Payment Gateway system s point of view Schematic illustration of exchange of information Description of steps INTEGRATION OF THE POS Flow of transaction with list of messages used Online phase Offline phases Description of the transmission of messages between the merchant and the Payment Gateway system PaymentInit request PaymentInit response NotificationMessage Merchant s response ErrorURL Payment request Payment response Description of the e24paymentpipe plug-in Specification of a direct interface Demo TEST ENVIRONMENT AND MODIFICATIONS Display of logos Modification of the HPP BILLING OF TRANSACTIONS Direct billing Delayed billing Repayment in instalments for American Express and Diners BASICS OF WORKING ON THE PAYMENT GATEWAY BACK-OFFICE PORTAL Working with transactions Terminology FAQs Redirection to ErrorURL despite successful execution of the transaction Transactions INSTALLATION OF DEMO PAGE APPENDIX 1: ERROR MESSAGES APPENDIX 2: CERTIFICATION AUTHORITIES APPENDIX 3: ISO RESPONSE CODES

5 1 INTRODUCTION 1.1 Payment Gateway The Activa system s Payment Gateway service has the role of intermediary between consumers, merchants, banks and external card associations between which financial transactions are conducted. The Activa system offers merchants that already have their own website the chance to use a comprehensive electronic transaction solution (using credit and debit cards). Online authorisation: safe execution of purchases in all phases of the transaction. Offline administration: access to the web interface in which administrative viewing can be conducted, transaction status checked, voids and reversals made, financial debiting procedures executed, and reports of executed payments generated. 1.2 Hosted Payment Page (HPP) During the execution of an electronic credit or debit card transaction, the merchant redirects the consumer to a bank page, where the secure entry of the card information is executed. In this way the following objectives are achieved: The merchant does not have the card information at its disposal, and is thus relieved of the burden of complying with the security requirements (secure connections and secure data storage) that have previously been a prerequisite for such transactions. The bank allows merchants to use the services and protocols with regard to their needs and requirements. The merchant can partly modify the appearance of the HPP (in agreement with the bank). The page to which the consumer is redirected during the execution of payment is called a Hosted Payment Page (HPP), and provides for payment methods activated for the merchant by the bank. The bank itself will adapt the HPP to any changes or new services, thus relieving merchants of the burden of developing and adapting to new standards. 5

6 2 TRANSACTION PHASES This section describes the individual steps in an electronic transaction via a Payment Gateway plugin and an HPP. 2.1 Consumer s point of view The cardholder (consumer) makes a purchase on the merchant s website via the following steps: The consumer selects the item. He/she enters the requisite delivery data and confirms by clicking on the Buy button. The consumer is automatically redirected to the HPP (the browser must include JavaScript functionality for the HPP to work properly). The consumer selects the method of payment, enters the payment card information and clicks on the Payment button. The browser again automatically redirects to the merchant s page, where the result of the transaction is displayed. Eventually the consumer receives a message from the merchant ( ) with the payment data (a virtual receipt). 2.2 Merchant s point of view The merchant receives an order/purchase from the consumer: The merchant sends a PaymentInit message to the Payment Gateway system. It receives a PaymentID and the URL of the HPP in response. The consumer is redirected to the URL of the HPP, the purchase data and the PaymentID attached. The Payment Gateway sends a response on the successful execution of the transaction. Eventually the merchant sends a message to the consumer ( ) with the payment data, which the consumer can use as confirmation (a virtual receipt). Merchants that so decide can develop this service themselves. The merchant sends the Payment Gateway a URL, where the consumer is redirected for the result of transaction to be displayed. The result of the transaction is displayed for the consumer. 2.3 Payment Gateway system s point of view The Payment Gateway system receives a PaymentInit message from the merchant: It responds with the URL of the HPP and a PaymentID. The HPP is displayed for the consumer (insofar as it is not specifically modified by the merchant, the preset bank page is used). The Payment Gateway receives all the card information entered by the consumer on the HPP. The Payment Gateway processes the transaction, and sends it to the bank authorisation system for processing. The Payment Gateway waits for the authorisation system s response. The Payment Gateway sends the merchant a message on the result of the transaction. 6

7 In response the Payment Gateway receives the URL to which the consumer is to be redirected. The Payment Gateway redirects the consumer to the URL received. 2.4 Schematic illustration of exchange of information A schematic illustration of the flow of a transaction between the pages involved is given below. Each step is explained in detail. 7

8 2.5 Description of steps The flow of a transaction is analysed in the table. Consumer/cardhol der s browser Merchant s website Payment Gateway Bank authorisation system 1. Adds products to the basket 2. Prepares and displays the purchase page 3. Completes the requisite delivery data and confirms the purchase by clicking on the button 4. Prepares an HTTP request for PaymentInit with all details of the purchase 5. Sends a POST request to the Payment Gateway 6. After verification of the received request, data on the transaction is stored on the system, where a PaymentID code is created and the URL to which the consumer is to be redirected is prepared 7. Responds to the merchant with the URL and PaymentID 8. Stores the PaymentID with other data on the transaction and returns the redirection to the Payment Gateway address (with the PaymentID added) to the browser (consumer) 9. Calls the HPP 10. After verification of the PaymentID received, a payment page is generated with the options supported by the merchant and returned to the browser (consumer) 8

9 11. Completes the requisite information and confirms payment by clicking on the button 17. Calls/requests the merchant s URL 19. Displays the merchant s page with the result of the transaction 15. Receives the message and updates the transaction status with the result received Returns the URL for redirecting the browser (consumer) to the page with the result of the transaction, and eventually sends an to the consumer 18. Receives the request and returns the page with result of the transaction 12. The consumer s data and the merchant s data are combined, and sent in the form of a request to the bank authorisation system 14. Sends the POST request to the merchant with a message about the result of the transaction 16. Redirects the browser (consumer) to the URL received 13. The authorisation system processes the request received, and returns the result to the Payment Gateway 9

10 3 INTEGRATION OF THE POS The Payment Gateway platform envisages direct communication with a merchant s server for conducting electronic transactions. The merchant can upgrade the exchange of messages in two ways. Merchants are recommended to use the plug-in method. Merchants can also produce their own communication interface if so desired. The e24paymentpipe plug-in: the advantage of using this method is simple integration into the merchant s system, and support for the Java, C/C++, ColdFusion, ActiveX/COM, VB and ASP development environments. Production of an in-house communication interface: the method for producing an in-house communication interface for cases when the plug-in is not compatible with the platform hosting the merchant s website (PHP) is defined below. 3.1 Flow of transaction with list of messages used Online phase The cardholder fills a basket, completes the personal information (address, etc.) and clicks on the Buy button. The merchant sends the PaymentInit message with the order data to the Payment Gateway. The merchant forwards a parameter on the type of transaction (the Action parameter) with the message. - Action=1: Transaction type Purchase : if the transaction is successful, the cardholder s card is debited immediately. - Action=4: Transaction type Authorization : the card limit is reduced by the amount of the purchase, and the actual debiting occurs only when the merchant confirms the purchase (usually when the goods are dispatched). The merchant obtains a URL for the HPP and the PaymentID identifying the transaction in response. The merchant redirects the consumer to the HPP, attaching the PaymentID as a parameter. After payment is completed, the Payment Gateway sends a message on the result (NotificationMessage) to the URL prepared in advance by the merchant (ResponseURL) and cited in the PaymentInit message sent to the Payment Gateway. The merchant can send the consumer an on the transaction just completed (virtual receipt). The merchant responds to the received NotificationMessage with the URL to which the consumer s browser is to be redirected. The Payment Gateway redirects the consumer to the URL received. The merchant displays the result of the transaction to the consumer Offline phases Confirmation transaction (accreditation) After successful online authorisation, the merchant can initiate the process of dispatching the goods. In Purchase transactions, debiting occurs simultaneously with authorisation. Authorization 10

11 transactions must be subsequently confirmed by the merchant using the Capture option. This can happen in two ways: 1. The merchant registers on the Payment Gateway portal, where enquiries regarding completed transactions can be made and the tools and functionality provided by the Payment Gateway portal can be used via the interface. In this case the merchant selects the Capture option, which causes the transaction to be processed. - Access point to the test portal: 2. The merchant sends the Payment message to the Payment Gateway. The data from the original transaction is used in the message, and the Action parameter is set to 5 (Action=5). NB: The confirmation transaction is unique to an individual authorisation. The amount must be equal to or less than the amount of the authorisation. Reversal transaction In the event of the return of the goods (in full or in part), the merchant can reverse the amount in full or in part. This causes the merchant to be debited and the cardholder to be credited. The procedure can be undertaken in two ways: 1. The merchant registers on the Payment Gateway portal, where enquiries regarding completed transactions can be made and the tools and functionality provided by the Payment Gateway portal can be used via the interface. In this case the merchant selects the Credit option (the Reversal option if the goods are yet to be dispatched). - Access point to the test portal: 2. The merchant sends the Payment message directly to the Payment Gateway. The data from the original transaction is used in the message, and the Action parameter is set to 2 (Action=2). Several small reversals can be executed for a particular transaction, the sum of the individual void transactions thereby not exceeding the amount of the original authorisation. 3.2 Description of the transmission of messages between the merchant and the Payment Gateway system There are three types of messages between the merchant and the Payment Gateway (server-toserver). Each type consists of a request and a response. PaymentInit: The initial message of a transaction sent by the merchant to the Payment Gateway. The latter responds with the URL of the HPP and adds the PaymentID. NotificationMessage: A message on the result of the transaction sent by the Payment Gateway to the merchant. The latter responds with the URL to which the consumer s browser is to be redirected. Payment: A message for booking or voiding transactions executed previously, which the merchant sends to the Payment Gateway. The latter responds with the result of the transaction. The PaymentInit and Payment messages are generated on the merchant s page, and require the e24paymentpipe plug-in or a similar interface to work. 11

12 The NotificationMessage is generated by the Payment Gateway, and the merchant must prepare a dynamic page that can accept the parameters from the message and send the redirection URL for the consumer s browser in response. 3.3 PaymentInit request The message is created by the merchant, and is sent to the Payment Gateway system for each new payment transaction. The following elements are used in the message: Element Mandatory? Max Description length id YES 8 Merchant s unique identification code assigned upon activation in the system. password YES 8 Password assigned to the merchant upon activation in the system. action YES 1 Transaction type: 1 = Purchase 4 = Authorisation amt YES 10 Transaction amount (format NNNNN.NN). currencycode YES 3 ISO currency code: 978 = Euro. langid YES 3 Code of the language to be used to display the HPP. The following languages are supported: SLO = Slovene USA = English SRB = Serbian ITA = Italian FRA = French DEU = German ESP = Spanish responseurl YES 256 URL to be used for forwarding the result of the transaction via the NotificationMessage. Notes: - Only Port 80 and Port 443 can be used. - Websites protected by SSL certification must use certificates issued by approved issuers (certification authorities) listed in Appendix 2 of this document. Otherwise the merchant must submit a digital CA certificate used to sign its server certificate. errorurl YES 256 The URL to which the Payment Gateway will redirect the consumer in the event of system or communication errors. trackid YES 256 Transaction identification code. Ordinarily, this is the unique code of the order in the merchant s system. udf1 NO 256 A field available to the merchant for any additional information that it wishes to enter in the message. This information is sent directly, unmodified, to the merchant in the NotificationMessage. 12

13 Special values: - SHA1 : the value dictates to the Payment Gateway system the return of the hash value of the consumer s payment card (calculated using the sha-1 algorithm) in the udf1 field of the NotificationMessage. - The udf1 field can also be used to set payment by instalments using Diners cards (for more information, see Section 5.3). udf2 NO 256 A field available to the merchant for any additional information that it wishes to enter in the message. This information is sent directly, unmodified, to the merchant in the NotificationMessage. udf3 NO 256 A field available to the merchant for any additional information that it wishes to enter in the message. This information is sent directly, unmodified, to the merchant in the NotificationMessage. udf4 NO 256 A field available to the merchant for any additional information that it wishes to enter in the message. This information is sent directly, unmodified, to the merchant in the NotificationMessage. udf5 NO 256 A field available to the merchant for any additional information that it wishes to enter in the message. This information is sent directly, unmodified, to the merchant in the NotificationMessage. Special values: - If a field begins with HPP_TIMEOUT=<XX>, the Payment Gateway will set a time limit of XX minutes for entering the data on the HPP page. If the cardholder remains on the HPP for longer than the set time, after the payment button is clicked the Payment Gateway will not process the transaction, but will instead send the merchant a specific NotificationMessage containing Error Code CT PaymentInit response Is the response returned to the merchant by the Payment Gateway after the PaymentInit request has been received (after verification of the message received). It contains the following fields: Element Max Description length PaymentID 20 Unique purchase code that the merchant uses in subsequent messages to identify the transaction. PaymentURL 256 URL of the HPP to which the merchant redirects the consumer to continue the payment process. 3.5 NotificationMessage 13

14 The Payment Gateway sends the NotificationMessage to the merchant as the result of the transaction. The merchant has at its disposal a dynamic page, via which it accepts and processes the received message. The merchant cites the page in the PaymentInit message (the ResponseURL field). The Payment Gateway uses a POST method to send messages. The structure of the message can vary, depending on the success of the transaction: For a successful transaction, the merchant analyses and stores information on the transaction, in particular the ResultCode variable (to determine the result). For failed transactions, the reason for the error is examined. Several NotificationMessages can be sent. This occurs when the consumer erroneously returns to the payment page (BACK navigation). The Payment Gateway denies such a transaction (because of the use of the same PaymentID), and sends a NotificationMessage. Only the first NotificationMessage should be taken into consideration for updating the transaction status in the internal database (to avoid overwriting the result of the transaction with subsequent attempts). Example: Successful transaction Element Max Description length paymentid 20 Unique purchase identification code. tranid 20 Unique transaction identification code. result 20 Result of the transaction, which can be: APPROVED = Successful authorisation NOT APPROVED = Failed authorisation CAPTURED = Successful authorisation and settlement NOT CAPTURED = Failed authorisation DENIED BY RISK = Transaction blocked because of security parameters set by the bank. HOST TIMEOUT = Transaction unprocessed because of technical or communication problems in connecting with the authorisation system. auth 9 Authorisation code in the event of the successful authorisation of the transaction. postdate 4 Transaction date (format MMDD). trackid 256 Transaction identification code assigned by the merchant. ref 20 Transaction code assigned by the bank. udf1 udf5 256 Unchanged values of fields defined by the merchant in the PaymentInit message. cardtype 10 Type of card used for the transaction: VISA = Visa and Visa Electron MC = MasterCard MAES = Maestro ACTIVA = Activa Card AMEX = American Express DINERS = Diners Club 14

15 payinst 10 Designates the use of a security protocol during purchase: - VPAS = A transaction executed by means of the 3DSecure security protocol (Verified by Visa or MasterCard SecureCode), using a card included in one of the programmes (Visa, MasterCard, Maestro), - CC = A transaction executed by means of the SSL or 3DSecure security protocols using a card (Visa, MasterCard, Maestro) that is not included in a secure online shopping programme. liability 1 Liability shift protects the merchant. Example: Failed transaction Element Max Description length paymentid 20 Unique purchase identification code. Error 10 Error code. ErrorText 256 Error description. 3.6 Merchant s response In the response to the NotificationMessage the merchant reports the URL of the final page to which it intends to redirect the consumer (i.e. the page to which the Payment Gateway redirects the consumer s browser and on which the result of the transaction is displayed). The URL must host a dynamic page whose only output is a text string with the following structure: REDIRECT= + URL of the final page Example: REDIRECT= In the event of technical problems the browser does not display an address with the result of the transaction; it can happen that the consumer repeats a transaction despite the previous transaction being successful. It is recommended that the display or successful visualisation of the page be verified. In the event of an error: the consumer is notified of the result of the transaction by , or the transaction is automatically voided in online fashion. This procedure is designed for Purchase transactions (Action = 1). 3.7 ErrorURL In the event of errors during the exchange of NotificationMessages, the Payment Gateway redirects the consumer s browser to the ErrorURL, as a result of which the following may apply: The transaction may have been successful, despite the displayed error. The merchant does not receive notification, and thus loses oversight of the transaction. The consumer is redirected to the ErrorURL, where static information about the error is displayed (the merchant does not know the result). The consumer attempts to execute the transaction again. 15

16 For this reason it is important that the merchant prepare an ErrorURL in a manner that thus obtains as much useful information as possible for further enquiries. It is recommended that an identification parameter (e.g. TrackID) that the merchant recognises at the beginning of the transaction be used during display. 3.8 Payment request The merchant can also execute credit and reverse transactions (offline) via the exchange of serverto-server messages. The fields used in such requests are as follows: Element Mandatory? Max Description length paymentid YES 20 Unique purchase identification code. The Payment Gateway generates and sends this code in response to the PaymentInit request. tranid YES 20 Unique payment transaction identification code. It is assigned by the Payment Gateway in response to the NotificationMessage. id YES 8 Merchant s unique identification code assigned upon activation in the system. password YES 8 Password assigned to the merchant upon activation in the system. action YES 1 Type of operation: 2 = Credit 3 = Reversal 5 = Capture 9 = Void amt YES 9 Transaction amount (format NNNNN.NN). trackid YES 256 Transaction identification code. Ordinarily, this is the unique code of the order in the merchant s system. currencycode YES 3 ISO currency code: 978 = Euro. udf1 udf5 NO 256 Fields available to the merchant for any additional information that it wishes to enter in the message. This information is sent unchanged in the response to the merchant. 3.9 Payment response This is the response that the Payment Gateway returns to the merchant after receiving the Payment request (after validation of the message received). It contains the following fields: Element Max Description length Result 20 Result of the operation, which can be: CAPTURED = Credited to the merchant s account (for Action = 5) CAPTURED = Refunded to the consumer s card account (for Action = 2) 16

17 NOT CAPTURED = Failed confirmation / failed reversal VOIDED = Authorisation voided REVERSED = Transaction reversed DENIED BY RISK = Transaction blocked because of security parameters set by the bank. HOST TIMEOUT = Transaction unprocessed because of technical or communication problems in connecting with the authorisation system. Auth 9 Authorisation code from the card issuer. Ref 20 Operation reference code assigned by the card issuer. Avr 1 Not used. postdate 4 Operation date (format MMDD). tranid 20 Unique operation identification code. It is assigned by the Payment Gateway. trackid 256 Transaction identification code assigned by the merchant. udf1 udf5 256 Unchanged values of fields defined by the merchant in the Payment message Description of the e24paymentpipe plug-in Upon the merchant s activation in the test environment, the merchant receives the e24paymentpipe plug-in, which can be used on various platforms: Java ASP ActiveX/COM ColdFusion The basic features of the aforementioned platforms are described below. Java The e24paymentpipe Java class object is independent of the platform, and can therefore be used in various environments. Developers can use the e24paymentpipe component to execute transactions in their own systems. An example is included on the Payment Gateway portal. Active Server Pages The same object can also be used in the ASP environment via an interface. (ASP does not support asynchronous communication, for which reason e24paymentpipe will not return message status). An example of use in an ASP environment is included on the Payment Gateway portal. ActiveX/COM The e24paymentpipe ActiveX/COM object supports various methods for executing secure transactions via the internet in real time. It can be used in desktop applications, CGI, API web servers, ASPs and others. An example of use in Visual Basic is included on the Payment Gateway portal. 17

18 3.11 Specification of a direct interface When the merchant does not have a suitable platform for using the plug-in (e.g. a PHP platform), it can produce its own interface. The communication protocol, the format for sending and receiving messages, the variable fields and the error messages are described below. The e24paymentpipe plug-in was produced according to the same specifications, and provides for simple use and fast integration. Specification of communication protocol Protocol: https in test environment https in production environment Port: 443 Target (action): Test environment for PaymentInit: for Payment: Production environment for PaymentInit: to be reported to the merchant before the changeover to production for Payment: to be reported to the merchant before the changeover to production Method: POST Content-type: application/www-form-urlencoded or application/x-www-form-urlencoded Data sending format: URL encoded Data receiving format: single text string formed from fields ( : as separator) Encryption level: SSL3 Data sending format All data sent in URL encoded format, consisting of field name and field value. PaymentInit message: id=tranportalid&password=password&action=action&langid=language&currencycode=97 8&amt=amount&responseURL= om/error &trackid=unique tracking id&udf1=user Defined Field 1&udf2=User Defined Field 2&udf3=User Defined Field 3&udf4=User Defined Field 4&udf5=User Defined Field 5 Payment message: id=tranportalid&password=password&action=action&currencycode=978&amt=amount&p aymentid=paymentid&transid=transid&trackid=trackid&udf1=user Defined Field 1&udf2=User Defined Field 2&udf3=User Defined Field 3&udf4=User Defined Field 4&udf5=User Defined Field 5 18

19 Data receiving format: The response sent by the Payment Gateway has the form of a text string containing the values of the variable fields (unnamed) in a defined structure. The merchant must mine the requisite data from the message: - PaymentInit Response: PaymentID:PaymentURL - Payment Response: Result:Auth:Ref:AVR:Date:TransId:TrackId:UDF1:UDF2:UDF3:UDF4:UDF5 Error messages In the event of an error between the preparation of a message for the Payment Gateway (PaymentInit or Payment), the response begins!error!, followed by the error code and a description. It is important that the merchant verify the presence of the aforementioned ERROR field for each message (response) received. A list of errors is given in Appendix Demo In addition to instructions, the package received by the merchant when opening a test POS contains examples of online shops produced on ASP, PHP and JSP platforms. The examples illustrate the method for connecting with and using the Payment Gateway system by means of the e24paymentpipe plug-in (DLL version), or without it. The examples cover the following pages: Index : the first page displays the product for which purchase has been designated. Details : a control page where the contents of the basket and other purchase data can be verified. Purchase is confirmed by pressing the Buy button. Buy : (ASP and JSP version) the page is activated by the Buy button (a plug-in is used in this phase). The plug-in prepares the PaymentInit message and sends it to the Payment Gateway, which redirects the browser to the HPP in response. Pure-Buy : (ASP and JSP version) an example of a page not using a plug-in (the parameters in Details.asp need to be corrected for proper functioning). Receipt : after a successful transaction, a NotificationMessage is sent to the Notify URL. Result : the merchant s URL where the result of the transaction is displayed. Error : this page is displayed in the event of an error. Examples of the implementation of the payment interface in various programming languages are available for download on the Activa system website: 19

20 4 TEST ENVIRONMENT AND MODIFICATIONS A test environment is available to merchants, where they can execute transactions and test their POS before the changeover to production. The test environment is constantly available to merchants (although unannounced interruptions are possible for maintenance work). List of variables used in the test environment: Use of e24paymentpipe plug-in address: test4.constriv.com context: /cg301 port: 443 SSL: 1 (parameter only used during use of Java Plug-In) id: [each merchant gets its own] password: [reported by ] action: 1 or 4 (2 or 5 for subsequent transactions) currencycode: 978 langid: USA or SLO (codes for supported languages are described in Section 3.3) The remaining data can be used freely. Direct connection (for PaymentInit messages); (for Payment messages). When the HPP is displayed, the following data on the test card can be used: Credit card number: xxxx xxxx xxxx xxxx (the test number will be sent upon the activation of the test ID) Expiration date: MM/YYYY 4.1 Display of logos During the testing period the merchant must report to the bank the address of its test page, where the appearance and layout of card and bank logos is verified. The merchant must make the consumer aware of the possibility of using trust mark secure payments ( Verified by Visa and MasterCard SecureCode ) as early as the phase of selecting the article or on the page for viewing the basket (the logos are positioned on the right or the lower part of the page). Separate from the aforementioned logos, another place is envisaged for the Activa system logo and the logo of the bank with which the agreement has been concluded (each bank supplies its own logo): 20

21 Later, other logos of supported card products are displayed on the page for selecting the payment method, with the Verified by Visa and MasterCard Secure Code logos again displayed at the bottom of the page, at a distance from the other logos of at least four times the width of the logos. The file with the card product logos is available for download on the Activa system website: There follows an example of the notification to cardholders with links to the Activa system website with a detailed description of secure online shopping. Reference example of the wording for display on the website: Payment cards (MasterCard, Maestro, Visa, Visa Electron, Activa) We are happy to inform you that with the new method for making online payments, there is no longer any need for concern about the security of your payment card information. The new online payment system allows the payment card information to be entered exclusively on the bank s secure pages. We as the merchant do not have access to or sight of the information. Should you select to pay with a payment card, you will therefore be redirected to secure pages administered by the Activa processing centre and a bank with which we have reached a card acceptance arrangement. A new feature is the secure online payment service for international Visa and MasterCard cards. The Verified by Visa and MasterCard SecureCode 1 trademarks displayed below allow each online purchase made with your payment card to receive additional protection via 3DSecure security protocols. In Slovenia the Verified by Visa and MasterCard SecureCode services are supported by all banks in the Activa system, and by certain other Slovenian banks. We currently offer cardholders the highest level of security in online shopping, irrespective of the type of card (credit or debit). You can pay with the following payment cards: MasterCard Maestro Visa Visa Electron 1 Links to useful information for cardholders about MasterCard SecureCode and Verified by Visa: Link to MasterCard SecureCode Link to Verified by Visa 21

22 Example of layout of logos during viewing of article: Example of layout of logos during selection of payment: 22

23 Example of a bank HPP: 4.2 Modification of the HPP The merchant has the option of modifying the graphical appearance of the HPP. The purpose of this option is that the consumer is unaware of the redirection to the HPP. Modification is only possible in the production environment. The merchant can prepare the following three files affecting the appearance of the HPP, otherwise the preset appearance defined by the bank will be used: Header.html: HTML code used to display the upper section of the page (above the fields for entering the card information). Footer.html: HTML code used to display the lower section of the page (below the fields for entering the card information). Style.css: a file used to define the style of the page and displaying the entry fields. The conditions that must be adhered to when personalising the HPP are given below. 23

24 Example of a modified HPP: Header.html Displays the upper section of the page. The tags <HTML>, <HEAD>, <BODY> and other metatags may not be present. The merchant can change the colour, and display the logos and the information related to the purchase. Links to external pages are not allowed; when additional in-house graphical elements are used these must be sent together with the other files. Advertising messages are not allowed: only information related to the merchant s own online shop can be used. Footer.html Displays the lower section of the page. In this case too the modifications are limited: The merchant can change the background colour. Here the bank will place its logos related to security protocols and card products supported by the online shop (the background colour may not adversely affect the display of the logos). 24

25 Style.css Is a file for defining the appearance of the page and the entry fields (the settings can also be applied to the header and footer sections of the page). The only modifications allowed are between tags: <STYLE> </STYLE> Instructions for preparing files 1. During the execution of transactions in the test environment, a copy of the HPP is saved to the local disc. 2. The file can be modified. When the desired appearance is achieved, the modifications are copied into the following files: a. Header: b. Style: c. Footer: i. Modify the appearance and content under the conditions imposed by the bank. ii. Save the changes in the file entitled header.html. i. Modify the content between <STYLE> </STYLE> tags. ii. Save the changes in the file entitled style.css. i. Modify the appearance and content under the conditions imposed by the bank. ii. Save the changes in the file entitled footer.html. 3. The three modified files (and any other files such as graphics, images, logos and backgrounds) must be sent to the bank (an address will be provided later), where they will be reviewed and transferred into the production environment for the POS. The modified HPP is also submitted, for a quick preview of the modifications. The bank has the right to reject the proposed modifications and to use the preset HPP. A merchant may send modified files for personalising the HPP no more than three times. After three modifications, further changes to the page by the merchant will be disabled. An example of a modified HPP is available for download on the Activa system website: 25

26 5 BILLING OF TRANSACTIONS Online purchases can be billed simultaneously with the execution of the transaction, or subsequently within the deadline envisaged by the bank (e.g. 15 days). The Payment Gateway system gives merchants the option of determining the billing method for each individual transaction. 5.1 Direct billing Direct billing of a transaction is triggered when the PaymentInit message contains the defined parameter Action=1. In this case the transaction is treated as a Purchase. Successfully authorised Purchase transactions are processed in ordinary daily processing, and have a purchase processing date that is the same as the authorisation date. NB: Direct billing is used in cases when the merchant provides services that the consumer can use immediately after execution of the transaction. When the consumer wishes to cancel the purchase for unknown reasons, the merchant can execute a Credit for the full amount or a partial amount, or a Void Purchase in the full amount. The reversal procedure can be undertaken in two ways: By means of the plug-in: the merchant sends a Payment message containing the parameter Action=2 or Action=3. Via the Payment Gateway portal: the procedure consists of the designation of a void transaction in the archive, the entry of the amount of the reversal and the confirmation of entry. (The sum of Credit1 + Credit2 + Credit3 + + CreditN is less than or equal to the original amount). Scheme 1: Operation: Purchase Credit Action: 1 2 Several Credit transactions can be executed for a single Purchase transaction (the sum of all Credit transactions is less than or equal to the original amount). Scheme 2: Operation: Purchase Credit #1 Credit #2 Credit #3 Action: Scheme 3: Operation: Purchase Void Purchase Action:

27 5.2 Delayed billing Delayed billing of a transaction is triggered when the PaymentInit message contains the defined parameter Action=4. In this case the transaction is treated as an Authorization. An approved transaction reduces the card limit by the authorised amount, and the transaction is only processed via the merchant s mediation. When the goods have been dispatched, the merchant confirms the transaction by means of the Capture function. The amount of the Capture function is less than or equal to the authorised amount. The merchant s transaction confirmation procedure can be undertaken in two ways: By means of the plug-in: the merchant sends a Payment message containing the parameter Action=5. Via the Payment Gateway portal: the procedure consists of the selection of the desired authorisation, the entry of the final amount and the confirmation of the Capture option (the amount is less than or equal to the amount of the authorisation). When the consumer wishes to return the goods received, the merchant can execute a Credit reversal in a full or partial amount. The reversal procedure can be undertaken in two ways: By means of the plug-in: the merchant sends a Payment message containing the parameter Action=2. Via the Payment Gateway portal: the procedure consists of the designation of a void transaction in the archive, the entry of the amount of the reversal and the confirmation of entry. (The sum of Credit1 + Credit2 + Credit3 + + CreditN is less than or equal to the original amount). Scheme 1: Operation: Authorization Capture Credit Action: Several Credit transactions can be executed for a single Capture transaction (the sum of all Credit transactions is less than or equal to the original amount). Scheme 2: Operation: Authorization Capture Credit #1 Credit #2... Action: Scheme 3: Operation: Authorization Void Authorization Action:

28 Values of the Action parameter: 1 = Purchase Direct billing 2 = Credit Credit (in part or in full) 3 = Void Purchase Reversal / void of full amount 4 = Authorization Authorisation 5 = Capture Confirmation of authorisation 9 = Void Authorization Void of authorisation 5.3 Repayment in instalments for American Express and Diners This section applies solely to merchants that accept American Express and Diners card products on their websites. With American Express and Diners cards cardholders can also pay for goods and services in instalments. A merchant that also wishes to offer payment in instalments on its website must follow these instructions: The cardholder selects the products that he/she wants to purchase, completes the personal information and clicks on the Buy button. The merchant verifies with which card payment means the cardholder wises to make the purchase. Example: If the cardholder selects an American Express or Diners card, the merchant first verifies whether the purchase satisfies the conditions for payment in instalments, and then offers the cardholder the option of payment in instalments. Example: The merchant sends a PaymentInit message to the Payment Gateway system as it does for all other card payments. Data on payment in instalments is sent via the udf1 parameter as follows: - The udf1 parameter must be sent as 31 characters, the number of instalments being defined from position 30 onwards. The field is formed as follows: udf1=b24poskpi XX where XX is the number of instalments. - Example for three instalments: udf1=b24poskpi Example for 12 instalments: udf1=b24poskpi Detailed overview of the format of the udf1 field: Positions 1 9: B24POSKPI Position 10: <interval> Position 11: 1 28

29 Positions 12 13: <2 intervals> Positions 14 15: 40 Positions 16 20: <5 intervals> Positions 21 29: Positions 30 31: <2 positions for the number of instalments, see above example> The consumer then enters the number of his/her American Express or Diners card on the HPP, and the payment information is then authorised at one of the issuers, the merchant receives the message about the success or failure of the transaction, and displays it to the consumer. All subsequent activities related to billing are carried out the same as for other card products. 29

30 6 BASICS OF WORKING ON THE PAYMENT GATEWAY BACK-OFFICE PORTAL All data for registering on the Payment Gateway Back-Office portal is received by merchants in a PDF document, either when test access is received, or when access to the production environment is received. The link for access to the test portal is Working with transactions Review of transactions In the Payment Gateway Back-Office portal, select Detail Report in the Orders menu. In the form displayed, select the time period and any other information about transactions that you wish to display. Press the Generate Report button. Review of details for an individual transaction In the list of transactions, click the Trans button next to the transaction whose details you wish to display. A list of all operations executed in the transaction is displayed, as for example: Click on the Detail button next to the individual operation for which you require detailed information. All the details of the selected operation are displayed, itemised into various categories, as for example: 30

31 The Transaction Data category also gives the Host Response, which represents the response according to the ISO standard for the result of the operation received from the issuer of the payment card used. For more information about possible responses see Appendix 3 of this document. Confirmation of authorisation When you are executing transactions with a parameter of Action=4 (authorisation) in an online shop, each authorisation also needs to be confirmed when the goods are dispatched. If there is no automatic confirmations capability or the confirmations are not made automatically, this can be done via the Payment Gateway Back-Office portal. In the list of transactions, click on the Trans button next to the authorisation that you want to confirm (these are transactions whose Result Code is given as APPROVED ). In the form displayed under Available Actions in the Capture Euros field, confirm the authorisation in an amount less than or equal to the authorised amount by clicking on the Proceed button. Void of authorisation Voiding an authorisation releases the held funds (limit) on the cardholder s card. In the list of transactions, click on the Trans button next to the authorisation that you want to void (these are transactions whose Result Code is given as APPROVED ). In the form displayed under Available Actions in the Void the transaction field, void the authorisation by clicking on the Proceed button. Reversal of financial transaction In the list of transactions, click on the Trans button next to the transaction that you want to reverse (these are transactions whose Result Code is given as CAPTURED ). 31

32 In the form displayed under Available Actions in the Reverse the transaction field, reverse the transaction by clicking on the Proceed button. Partial reversal of financial transaction In the list of transactions, click on the Trans button next to the transaction that you want to refund in part or full (these are transactions whose Result Code is given as CAPTURED ). In the form displayed under Available Actions in the Credit Euros field, confirm the reversal of the transaction in an amount less than or equal to the transaction amount by clicking on the Proceed button. 6.2 Terminology Order statuses The order statuses as seen in the Payment Gateway Back-Office portal under the Order status column are described here: AUTH ERROR - This error occurs most often when the cardholder enters erroneous or incomplete card information in the data entry window (e.g. a non-existent card number). INITIALIZED - This status means that the transaction has only been initialised, but there has been no call to display the window for entering the payment card information. PRESENTED - Means that the page for entering the payment card information has been displayed, but the user left the page at this point or closed the browser window without entering the card information. PROCESSED - The order has been successfully processed. This means that the Payment Gateway received a response on the success or failure of the authorisation or transaction. TIMEOUT - The order expired because no connection was established with the processing centre of the issuer of the cardholder s card. Result codes The possible responses to the execution of a transaction as seen in the Payment Gateway Back- Office portal in the Financial status column are described here: APPROVED - Authorisation successful. The actual debiting of funds can be executed by means of the CAPTURE function. The approved authorisation reduces the card limit by the authorised amount. When the goods have been dispatched, the merchant confirms the authorisation by means of the CAPTURE function. The amount of the CAPTURE transaction is less than or equal to the authorised amount. After confirmation of authorisation, the transaction is given the status of CAPTURED or NOT CAPTURED. NOT APPROVED - Authorisation failed. This happens whenever a card exceeds the period limit, has insufficient funds, is blocked or similar. CAPTURED - Debiting successful. After authorisation, the transaction needs to be confirmed. The CAPTURE function allows confirmation of an amount equal to or less than the authorisation amount. NOT CAPTURED - Unsuccessful confirmation of transaction. Debiting failed. DENIED BY RISK - Risk parameters can be set in the Payment Gateway system itself by the bank (numbers of cards used in suspicious transactions, POS with suspicious 32