setting up an online e-commerce system - user · pdf filelist of slovenian online merchants...

Setting up an online e-commerce system

User guide

Setting up an online e-commerce system: User guide – Version 3.1 Author: Milan Čulibrk

2

Document history Date Person Description

15 February 2007

Matjaž Pahor - Preliminary versions of this document, Versions 1.0 to 1.4

14 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: 2.0

14 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 7.1.

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


22 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 5.3.



3

Notes

Symbols in document Text… Ordinary text PaymentInit Important words, definition of parameters, references, messages http://www.activa.si Hyperlinks Action=5 Program code

Other resources For additional information related to the content of this document, the following online resources are useful:

http://www.activa.si/e-trgovina.asp?content=prodajna_mesta Activa online shopping – Description for POS

http://www.activa.si/e-trgovina.asp?content=varnost Security recommendations for online merchants

http://www.activa.si/merchants.asp List of Slovenian online merchants participating in the MasterCard SecureCode and Verified by Visa programmes

http://www.pametna-kartica.si/securecode.asp Description of MasterCard SecureCode service

http://www.pametna-kartica.si/vbv.asp Description of Verified by Visa service

http://www.securecode.com MasterCard SecureCode (MasterCard’s pages on the SecureCode service) – in English

http://www.visaeurope.com/personal/onlineshopping/verifiedbyvisa/ Verified by VISA (Visa’s pages on the Verified by Visa service) – in English

http://www.activa.si/

http://www.activa.si/e-trgovina.asp?content=prodajna_mesta

http://www.activa.si/e-trgovina.asp?content=varnost

http://www.activa.si/merchants.asp

http://www.pametna-kartica.si/securecode.asp

http://www.pametna-kartica.si/vbv.asp

http://www.securecode.com/

http://www.visaeurope.com/personal/onlineshopping/verifiedbyvisa/


4

Contents Document history .................................................................................................................. 2 Notes ................................................................................................................................... 3 Symbols in document............................................................................................................. 3 Other resources .................................................................................................................... 3 Contents .............................................................................................................................. 4 1 INTRODUCTION .............................................................................................................. 5

1.1 Payment Gateway...................................................................................................... 5 1.2 Hosted Payment Page (HPP) ....................................................................................... 5

2 TRANSACTION PHASES ................................................................................................... 6 2.1 Consumer’s point of view ............................................................................................ 6 2.2 Merchant’s point of view ............................................................................................. 6 2.3 Payment Gateway system’s point of view ..................................................................... 6 2.4 Schematic illustration of exchange of information .......................................................... 7 2.5 Description of steps ................................................................................................... 8

3 INTEGRATION OF THE POS ............................................................................................. 10 3.1 Flow of transaction with list of messages used.............................................................. 10

3.1.1 Online phase ..................................................................................................... 10 3.1.2 Offline phases .................................................................................................... 10

3.2 Description of the transmission of messages between the merchant and the Payment Gateway system ....................................................................................................... 11

3.3 PaymentInit request ................................................................................................. 12 3.4 PaymentInit response ............................................................................................... 13 3.5 NotificationMessage .................................................................................................. 13 3.6 Merchant’s response ................................................................................................. 15 3.7 ErrorURL ................................................................................................................. 15 3.8 Payment request ...................................................................................................... 16 3.9 Payment response .................................................................................................... 16 3.10 Description of the e24PaymentPipe plug-in .................................................................. 17 3.11 Specification of a direct interface ................................................................................ 18 3.12 Demo ...................................................................................................................... 19

4 TEST ENVIRONMENT AND MODIFICATIONS ...................................................................... 20 4.1 Display of logos ........................................................................................................ 20 4.2 Modification of the HPP .............................................................................................. 23

5 BILLING OF TRANSACTIONS ........................................................................................... 26 5.1 Direct billing ............................................................................................................ 26 5.2 Delayed billing ......................................................................................................... 27 5.3 Repayment in instalments for American Express and Diners ........................................... 28

6 BASICS OF WORKING ON THE PAYMENT GATEWAY BACK-OFFICE PORTAL ............................ 30 6.1 Working with transactions ......................................................................................... 30 6.2 Terminology ............................................................................................................. 32

7 FAQs ............................................................................................................................ 34 7.1 Redirection to ErrorURL despite successful execution of the transaction ........................... 34 7.2 Transactions ............................................................................................................ 37

8 INSTALLATION OF DEMO PAGE........................................................................................ 39 APPENDIX 1: ERROR MESSAGES ............................................................................................ 40 APPENDIX 2: CERTIFICATION AUTHORITIES ............................................................................ 44 APPENDIX 3: ISO RESPONSE CODES ...................................................................................... 46


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.


6

2 TRANSACTION PHASES This section describes the individual steps in an electronic transaction via a Payment Gateway plug-in 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 (email) 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 (email) 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.


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.


8

2.5 Description of steps

The flow of a transaction is analysed in the table.

Consumer/cardholder’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)


9

11. Completes the requisite information and confirms payment by clicking on the button

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

13. The authorisation system processes the request received, and returns the result to the Payment Gateway

14. Sends the POST request to the merchant with a message about 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 email to the consumer

16. Redirects the browser (consumer) to the URL received

17. Calls/requests the merchant’s URL

18. Receives the request and returns the page with result of the transaction

19. Displays the merchant’s page with the result of the transaction


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

3.1.1 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 email 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.

3.1.2 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


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: http://www.activa.si/test/

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: http://www.activa.si/test/

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-to-server). 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.

http://www.activa.si/test/



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 length

Description

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.


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





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

3.4 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

length Description

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


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

length Description

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


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

length Description

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=http://www.vasa-trgovina.si/result.asp?paymentID=123456 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 email, 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.


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 server-to-server messages. The fields used in such requests are as follows: Element Mandatory? Max

length Description

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

length Description

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)


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.

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


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: https://test4.constriv.com/cg301/servlet/PaymentInitHTTPServlet for Payment: https://test4.constriv.com/cg301/servlet/PaymentTranHTTPServlet 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=978&amt=amount&responseURL=www.merchant.com/response&errorURL=www.merchant.com/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&paymentid=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

https://test4.constriv.com/cg301/servlet/PaymentInitHTTPServlet

https://test4.constriv.com/cg301/servlet/PaymentTranHTTPServlet


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

3.12 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: http://www.activa.si/test/.



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 email]

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

https://test4.constriv.com/cg301/servlet/PaymentInitHTTPServlet (for PaymentInit messages);

https://test4.constriv.com/cg301/servlet/PaymentTranHTTPServlet (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):

https://test4.constriv.com/cg301/servlet/PaymentInitHTTPServlet

https://test4.constriv.com/cg301/servlet/PaymentTranHTTPServlet


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: http://www.activa.si/test/.

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 SecureCode1 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 http://www.pametna-kartica.si/securecode.asp Link to Verified by Visa http://www.pametna-kartica.si/vbv.asp


http://www.pametna-kartica.si/securecode.asp

http://www.pametna-kartica.si/vbv.asp


22

Example of layout of logos during viewing of article:

Example of layout of logos during selection of payment:


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.


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


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:

i. Modify the appearance and content under the conditions imposed by the bank.

ii. Save the changes in the file entitled “header.html”.

b. Style:

i. Modify the content between <STYLE> </STYLE> tags.

ii. Save the changes in the file entitled “style.css”.

c. Footer:

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 email 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: http://www.activa.si/test/.



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: 1 2 2 2 Scheme 3: Operation: Purchase Void Purchase Action: 1 3


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: 4 5 2 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: 4 5 2 2 Scheme 3: Operation: Authorization Void Authorization Action: 4 9


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 1 40 000000000XX

where XX is the number of instalments.

- Example for three instalments: udf1=B24POSKPI 1 40 00000000003 Example for 12 instalments: udf1=B24POSKPI 1 40 00000000012

- Detailed overview of the format of the udf1 field: Positions 1 – 9: B24POSKPI Position 10: <interval> Position 11: 1


29

Positions 12 – 13: <2 intervals> Positions 14 – 15: 40 Positions 16 – 20: <5 intervals> Positions 21 – 29: 000000000 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.


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 http://www.activa.si/test.

6.1 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:

http://www.activa.si/test


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”).


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


33

transactions, etc.). When there is a transaction using a card or at a POS in this list, the result of the transaction is designated DENIED BY RISK.

UNKNOWN - The result of the transaction could not be determined. In the event of this result, contact the bank.

HOST TIMEOUT - This occurs when the authorisation system is unable to return a response to the Payment Gateway system in the specified time interval.


34

7 FAQs

7.1 Redirection to ErrorURL despite successful execution of the transaction

There are several possible reasons for a redirection to the ErrorURL despite the successful execution of the transaction, but in any case it involves an error in the implementation of the online shop itself. Irrespective of whether the transaction was successful or failed, the Payment Gateway always redirects to the ResponseURL page, on which the result of the transaction is displayed. The ErrorURL is used only in cases when various complications arise in the communications or operation of the system, e.g. when the Payment Gateway cannot access your ResponseURL page. One such reason is that the ResponseURL page is not accessible by the Payment Gateway system, which would otherwise be sending information about the success of the transaction to the ResponseURL. This could be because of various security systems, e.g. a firewall or similar systems. The ResponseURL page must therefore always be accessible to the Payment Gateway. Another (most common) error is an error in the actual code of the interface. Often during implementation merchants forget a specific step in the process of closing a transaction, and thus fail to obtain a result, irrespective of whether the transaction itself was successful. In general, the reasons for redirection to the ErrorURL and thus for the transaction to lack Order Notify status can be as follows:

• The ResponseURL page is not properly formed The ResponseURL page is erroneously formed, and the Payment Gateway does not understand it. The ResponseURL page must receive data on the result of the transaction from the Payment Gateway, and must form the URL to which the Payment Gateway redirects the user. If you are calling the ResponseURL page via an ordinary browser, you should obtain a result similar to the following: REDIRECT=http://www.YourDomain.com/YourFinalPage.asp?PaymentID=&TransID=&TrackID=&postdate=&resultcode=&auth=

• The ResponseURL page is not accessible to the Payment Gateway system The page can be inaccessible because of the rules of the firewall or a similar system. If for example you are testing implementation on a workstation on which access from the internet is disabled, this can yield this result. It could also merely be a temporary loss of internet connection.

• The ResponseURL page is protected by (SSL) certificate If your ResponseURL page is protected by certificate, it must be issued by a certification authority licensed to issue digital certificates for servers. The Payment Gateway must send information about the completion of the transaction to your ResponseURL page, and must therefore trust the certificate on the page. If you use a self-issued certificate, an expired certificate, a certificate that does not match the domain name or a certificate issued by an unlicensed authority, the Payment Gateway will be unable to connect and send the information about the completion of the transaction. Websites protected by SSL certificate 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.


35

• The ResponseURL is located on a website accessible via ports other than 80 or 443 Connections to the Payment Gateway are via Ports 80 and 443 alone. For example, if you cite “http://www.YourDomain.com:9999/Response.asp” as the ResponseURL, the connection will fail.

A brief explanation of the essential pages in the payment process on an ASP platform is illustrated below: After the entry of all the requisite information on the pages of your online shop and the clicking of the “payment” button, it is necessary to transfer the parameters related to the payment (price, etc.) to another page as illustrated in the case below (buy.asp). < Buy.asp START > <%Dim MyObj Set MyObj = Server.CreateObject("e24PaymentPipe.e24PaymentPipe.1") MyObj.WebAddress = "www.constriv.com" MyObj.PortStr = "443" MyObj.Context = "/cg" MyObj.ID = "XXXXXXXXX" 'TranPortal ID MyObj.Password = "XXXXXXXX" 'TranPortal PWD MyObj.Action = "4" 'type of payment MyObj.Amt = Request.form("PRICE") 'amount of payment MyObj.Currency = "978" ‘currency, 978 = EURO MyObj.Language = "SLO" ‘language for display of HPP ' Enter the URL of your server MyObj.ResponseURL = "http://www.your-server.com/response.asp" ' The Payment Gateway sends the information about the result of the transaction to this address MyObj.ErrorURL = http://www.your-server.com/error.asp ' In the event of system or communication errors redirection to this page is effected. randomize Ord_id = cstr(clng(rnd(50) * 1000000)) MyObj.TrackId = "Order-" & Ord_id ‘transaction ID code MyObj.Udf1 = Request.form("ime") MyObj.Udf2 = Request.form("naslov") MyObj.Udf3 = Request.form("posta") MyObj.Udf4 = Request.form("kraj") MyObj.Udf5 = Request.form("e-mail") ' execution of transaction Dim TransVal, varPaymentId, varPaymentPage, varErrorMsg, varRawResponse, varRedirectURL TransVal = MyObj.PerformInitTransaction ‘returns 0 for successful, -1 for failed varRawResponse = MyObj.RawResponse varPaymentId = MyObj.PaymentId varPaymentPage = MyObj.PaymentPage varErrorMsg = MyObj.ErrorMsg varRedirectURL = varPaymentPage & "?PaymentID=" & varPaymentId Response.Redirect varRedirectURL


36

< Buy.asp END > The ResponseURL page (“www.your-server.com/response.asp” in the above example) must accept the parameters sent by the Payment Gateway and must then form the address (ReceiptURL) on which the result of the transaction is to be displayed. This step is often missed by merchants and their software developers during implementation, resulting in an error in redirection. < ResponseURL START > <% Dim PayID, TransID, ResCode, AutCode, PosDate, TrckID, UD1, UD2, UD3, UD4, UD5, ReceiptURL PayID = Request.Form("paymentid") TransID= Request.Form("tranid") ResCode = Request.Form("result") AutCode = Request.Form("auth") PosDate = Request.Form("postdate") TrckID = Request.Form("trackid") UD1 = Request.Form("udf1") UD2 = Request.Form("udf2") UD3 = Request.Form("udf3") UD4 = Request.Form("udf4") UD5 = Request.Form("udf5") ' In the URL below enter the exact address of your server, for example: ReceiptURL = "REDIRECT=http://www.your-server.com/finish.asp?PaymentID=" & PayID & "&TransID=" & TransID & "&TrackID=" & TrckID & "&postdate=" & PosDate & "&resultcode=" & ResCode & "&auth=" & AutCode%> <%=ReceiptURL%> < ResponseURL END > On the final page (“www.your-server.com/finish.asp” in the above example) display the final report of the transaction, for example: < ReceiptURL START > <% ' get Merchant Notification parameters Dim payID payID = request.Querystring("PaymentID") if IsEmpty(payID) Then response.Redirect("error.asp") end if if ( request.Querystring("resultcode")="CAPTURED" or _ request.Querystring("resultcode")="APPROVED" ) Then%> <FONT color="GREEN" face="Verdana" style="font-size: 12px"> Transaction approved. Thank you for your order. </FONT>


37

<% else %> <FONT color="RED" face="Verdana" style="font-size: 12px"> Transaction not approved. Please try again. If the problem persists, please contact your bank. </FONT> <% end if %> < ReceiptURL END > On the final page you can also display information about the transaction, for example: Information about the purchase: <br> Track ID: <%=request.Querystring("TrackID")%><br> Auth Code: <%=request.Querystring("auth")%><br> Post Date: <%=request.Querystring("postdate")%><br> Result Code: <%=request.Querystring("resultcode")%><br> Payment ID: <%=request.Querystring("PaymentID")%><br> Transaction ID: <%=request.Querystring("TransID")%>

7.2 Transactions

Some FAQs in relation to the results of transactions and their review in the Payment Gateway system’s Back-Office portal are described below. Q: Given that the payment process takes place on your server, do we receive feedback if the customer closes the browser at that moment and does not complete the payment? Do we have to release stocks if the customer cuts off the payment? A: If the user cuts off the transaction on the page requiring the entry of the card information, you simply receive data on the initialisation of the transaction with the status PRESENTED, while if no card information entry window was displayed the transaction has the status INITIALIZED. If the user closes the browser after clicking on the payment button, i.e. during the actual processing of the transaction, he/she will not obtain information about the result of the transaction, and the transaction may have been approved or not. In any case, the information about the result of the transaction is available via the Payment Gateway Back-Office portal. Q: After receiving statistics and information on turnover at our POS, we notice an exceptionally large number of failed transactions with the results PRESENTED or INITALIZED. A: These problems do not arise from the malfunctioning of the payment system, but are actually conditioned by the nature of the website (particularly a website with large numbers of visitors). The majority of transactions are merely initialised, which means that the visitor genuinely reached the window for entering payment card information through clicking, but then left the page without entering any information. There are many such initialised transactions, and it is far from surprising, if we consider that a website is visited daily by a large number of users, some of whom reach the payment page merely out of curiosity. Q: Please check what is happening, whether there are any errors or why transactions are failing. We have noticed that some users have had difficulties with card payments.


38

A: Usually the reasons for the failure of certain transactions are completely normal. For example, often the wrong card number is entered, or a non-existent card number and similar combinations of this and other numbers (wrong CVC/CVV, wrong expiration date), which result in a payment authorisation failure. There are also many cardholders who enter Maestro card numbers, even though their cards do not support online payment. Online payments can only be made with a Maestro card when the card is registered in the MasterCard SecureCode programme. Only banks in the Activa system currently issue such Maestro cards in Slovenia. Q: What is the authorisation procedure for Maestro payment cards? A: Payments can only be made with a Maestro card when the cardholder’s bank issues cards that support MasterCard SecureCode services. All the banks in the Activa system currently issue such Maestro cards in Slovenia. The authorisation procedure is no different from the authorisation of other card products.


39

8 INSTALLATION OF DEMO PAGE DLL registration (for ASP and JSP)

Unpack the Plugin301.zip file (located on the Payment Gateway portal), and save to a folder named “C:\e24plugin”. The e24PaymentPipe plug-in is in the file, with examples of implementation that can be downloaded from the Activa website at http://www.activa.si/test/.

In the DOS command prompt navigate to the subfolder entitled “C:\e24plugin\DLL\Release”.

Enter the following command: “regsvr32 e24PaymentPipe.dll”.

A message on successful installation should appear. Confirm by clicking “OK”.

In the event of an error, try launching the “regsvr32 e24PaymentPipe.dll” command from the folder entitled “C:\e24plugin\DLL\Debug”.

Installation of ASP page

Check whether the Microsoft IIS (Internet Information Services) server is installed and launched. Install if necessary.

Copy the contents of the folder entitled “demo-asp” to a new folder created in the IIS wwwroot folder, for example “C:\inetpub\wwwroot\demo”.

Make a new page in IIS, for example “MerchantDemo”, which points to the folder created in the previous step (Execute Permissions: “Scripts only”).

Relaunch IIS.

Check operation in the browser: http://localhost/demo/index.asp.

Installation of JSP page

Copy the contents of the folder entitled “demo-jsp” to the “webpass” folder (or the equivalent basic folder for web applications) on the application server.

Relaunch the application server.

Check operation in the browser: http://localhost/demo-jsp/index.jsp.

Installation of PHP page

Copy the contents of the folder entitled “demo-php” to the folder where the PHP applications are installed.

Create the website, e.g. “demo-php”, in the web server supported by PHP script.

Relaunch the web server.

Check operation in the browser: http://localhost/demo-php/index.php.


http://localhost/demo/index.asp

http://localhost/demo-jsp/index.jsp

http://localhost/demo-php/index.php


40

APPENDIX 1: ERROR MESSAGES

GW00100-Institution ID required.

GW00101-Brand ID required.

GW00102-Brand Description required.

GW00150-Missing required data.

GW00151-Invalid Action type

GW00152-Invalid Transaction Amount.

GW00153-Invalid Transaction ID.

GW00154-Invalid Terminal ID.

GW00155-Invalid Batch Track ID.

GW00156-Batch track ID not unique.

GW00157-Invalid Payment Instrument.

GW00158-Card Number Not Numeric.

GW00159-Card Number Missing.

GW00160-Invalid Brand.

GW00161-Invalid Card/Member Name data.

GW00162-Invalid User Defined data.

GW00163-Invalid Address data.

GW00164-Invalid Zip Code data.

GW00165-Invalid Track ID data.

GW00166-Invalid Card Number data.

GW00167-Invalid Currency Code data.

GW00168-Institution ID mismatch.

GW00169-Merchant ID mismatch.

GW00170-Terminal ID mismatch.

GW00171-Payment Instrument mismatch.

GW00172-Card Verification Code Mismatch.

GW00173-Currency Code mismatch.

GW00174-Card Number mismatch.

GW00175-Invalid Result Code.

GW00176-Failed Previous Captures check.

GW00177-Failed Capture Greater Than Auth check.

GW00178-Void Greater Than Original Amount check.

GW00179-Failed Previous Voids check.

GW00180-Failed Previous Credits check.

GW00181-Failed Credit Greater Than Capture check.

GW00200-Address verification failed.

GW00201-Transaction not found.

GW00203-Invalid access: Must use POST method.

GW00205-Invalid Original Transaction ID.

GW00250-Transaction denied: Negative Card

GW00251-Maximum transaction count exceeded.

GW00252-Maximun transaction volume exceeded.

GW00253-Maximum credit volume exceeded.

GW00254-Maximum card debit volume exceeded.

GW00255-Maximum card credit volume exceeded.

GW00256-Maximum card transaction count exceeded.

GW00257-Maximum transaction amount exceeded.

GW00258-Transaction denied: Negative BIN.

GW00259-Transaction denied: Declined Card.

GW00260-Transaction denied: Credits exceed Captures.

GW00261-Trans. denied: Captures exceed Authorizations


GW00302-Currency code required.

GW00350-Merchant has terminals.

GW00351-Merchant ID required.


GW00353-Invalid Login.


GW00355-New password mismatch.

GW00356-New password same as old.

GW00357-Console password required.


GW00359-ISO Country code is invalid.

GW00360-Website address in invalid.

GW00361-Console Password Confirmation required.

GW00362-Console Password Confirmation invalid.

GW00363-Password Confirmation mismatch.

GW00364-Name is invalid.

GW00378-Currency Code is invalid.

GW00380-Merchant ID not numeric.

GW00381-Merchant Password data invalid.

GW00383-Merchant Password Confirmation invalid.

GW00384-Merchant New Password invalid.

GW00385-Merchant New Password is required.

GW00386-Merchant New Confirm Password is required.

GW00387-Merchant User Password is expired.

GW00388-Merchant User Name is required.

GW00389-Merchant User Pswd Confirmation is required.

GW00390-Password and Confirmation mismatch.

GW00391-Merchant User password length is too short.

GW00392-Merchant User Status is required.

GW00478-Invalid Terminal Card Acceptor ID.

GW00479-Invalid Terminal Card Acceptor Terminal ID.

GW00480-Invalid Terminal Acquirer Institution.


41

GW00393-Merchant User Status is invalid.

GW00394-Merchant User Password is required.

GW00395-Merchant User Password mismatch.

GW00396-Merchant User new password same as old.

GW00397-Merchant User inactive.

GW00398-Merchant User Password length too long.

GW00399-Merchant User ID is invalid.

GW00400-Merchant User Password is invalid.

GW00401-Merchant New Password is invalid.

GW00402-Merchant User Name is invalid.

GW00403-Merchant Password Expire Code is invalid.

GW00404-Merchant Password Expires Date is invalid.

GW00405-Merchant exists with this Merchanat Category.

GW00420-Currency Code data in not available.

GW00421-Currency Code minor digits is invalid.



GW00452-Terminal ID required.

GW00453-TranPortal ID required.

GW00454-TranPortal password required.

GW00455-TranPortal ID not unique.

GW00456-Invalid TranPortal ID.

GW00457-Action not supported.

GW00458-Invalid Transaction Attempt.

GW00459-Terminal not active.

GW00460-TranPortal ID required.

GW00461-Invalid Transaction amount.

GW00462-Invalid Tranportal Password.

GW00463-Invalid Terminal Institution ID.

GW00464-Invalid Terminal Merchant ID.

GW00465-Invalid Terminal Termainl ID.

GW00466-Invalid Terminal Description.

GW00467-Invalid Terminal External Connection ID.

GW00468-Invalid Terminal Risk Profile.

GW00469-Invalid Terminal Currency Code List.

GW00470-Invalid Terminal Action Code List.

GW00471-Invalid Terminal Payment Instrument List.

GW00472-Invalid Terminal Brand List.

GW00473-Invalid Terminal Option Code List.

GW00474-Invalid Terminal Risk Flag.

GW00475-Invalid Terminal Address Verification List.

GW00476-Invalid Terminal Tranportal ID.

GW00477-Invalid Terminal Status.

GW00481-Invalid Terminal Base24 Terminal Data.

GW00482-Invalid Terminal Retailer ID.

GW00483-Invalid Terminal Retailer Group ID.

GW00484-Invalid Terminal Retailer Region ID.

GW00485-Invalid Terminal Cutover Hour.

GW00486-Invalid Terminal Cutover Minute.

GW00550-Category Code missing or invalid.

GW00600-Card number required.

GW00601-Card BIN required.

GW00602-Invalid BIN length.



GW00605-Terminal ID required.

GW00606-Card number required.

GW00607-Invalid Card Number.

GW00608-Invalid Currency Code.

GW00609-Invalid Decline Reason.


GW00611-Invalid Negative Reason.

GW00612-Invalid Card Bin.

GW00613-Invalid Negative Reason.

GW00614-Please click correct button or tab.

GW00700-No processes available.

GW00701-Batch not processed.

GW00702-Batch could not be started.


GW00704-Batch ID not numeric.

GW00705-Batch ID required.

GW00706-Invalid Batch Response File Name

GW00750-Error hashing card number.


GW00851-Invalid Action Type.



GW00854-Invalid Expiration Date.

GW00856-Invalid Card Verification Code.


GW00876-Invalid Action Type.



GW00879-Invalid Expiration Date.

GW00880-Invalid Card Verification Code.

GW00881-Card Type unknown

GW00950-Batch Upload Directory Required. GW01072-Merchant exists with this Currency Code.


42

GW00951-Batch Download Directory Required.

GW00952-Batch Archive Directory Required.

GW00953-Access Log Retention Days Required.

GW00954-Transaction Log Retention Days Required.

GW00955-Declined Card Retention Minutes Required.

GW00956-Declined Card Maximum Count Required.

GW00957-Access Log Retention Days Invalid.

GW00958-Transaction Log Retention Days Invalid.

GW00959-Declined Card Retention Minutes Invalid.

GW00960-Declined Card Maximum Count Invalid.

GW00961-Multiple Capture Flag Invalid.

GW00962-Multiple Capture Amount Flag Invalid.

GW00963-Multiple Void Flag Invalid.

GW00964-Compare Void Amount Flag Invalid.

GW00965-Multiple Credit Debit Flag Invalid.

GW00966-Compare Credit Debit Amount Flag Invalid.

GW00967-Batch Upload Directory Invalid.

GW00968-Batch Download Directory Invalid.

GW00969-Batch Archive Directory Invalid.

GW00970-Invalid Terminal Cutover Hour.

GW00971-Invalid Terminal Cutover Minute.

GW00975-FAQ Question ID required.

GW00976-Invalid Language ID.

GW00977-Invalid Question ID.

GW00978-Invalid Question content.

GW00979-Invalid Answer content.

GW00990-Card Number Encryption Failure.

GW01020-Invalid Languange ID.

GW01021-Invalid System News Header.

GW01022-Invalid System News Body.

GW01040-Invalid Languange ID.

GW01041-Invalid Merchant Guideline Header.

GW01042-Invalid Merchant Guideline Body.

GW01060-Currency Code Required.

GW01061-Institution ID Required.

GW01062-Ivalid Minor Digits Range.

GW01063-Currency Code Not Numeric.

GW01064-Currency Code Not Valid ISO Code.

GW01065-Invalid Minor Digits.

GW01066-Invalid Amount.

GW01067-Invalid Currency Code Data.

GW01068-Invalid Currency Description Data.

GW01069-Invalid Minor Digits Data.

GW01070-Invalid Currency Symbol Data.

GW01180-Hex required.

GW01181-Invalid Key length.

GW01182-Key encryption failed.

CM00001-External message timeout.

CM00002-External message system error.

CM00026-External connection ID required.

CM00027-External connection description required.

CM00028-External connection Protocol code required.

CM00029-External connection Formatter class name invalid.

CM00030-External connection Protocol not supported.

CM00051-Institution ID required.

CM00052-Invalid Institution Data Encryption Key Name.

CM00053-Missing Institution Data Encryption Key.

CM00054-Institution Data Encryption Key does not exist.

CM00055-Missing Institution Data Encryption Key.

CM00056-Institution Data Encryption Key does not exist.

CM90000-Database error.

CM90001-Database configuration error.

CM90002-Data format error.

CM90003-No Records Found.

CM90004-Duplicate found error.

CM90005-TimeStamp Mismatch error.

CM90100-Message formatter class failure.

PY20000-Missing required data.

PY20001-Invalid Action Type.

PY20002-Invalid amount.

PY20003-Invalid Order Status.

PY20004-Non Numeric Card Number.

PY20005-Missing Card Number.

PY20006-Invalid Brand.

PY20007-Invalid Order Status.

PY20008-Invalid Currency Code.

PY20009-Transaction Not Found.

PY20010-Invalid Merchant URL.

PY20011-Invalid Merchant Error URL.

PY20012-Invalid Track ID.

PY20013-Invalid Language Code.

PY20014-Invalid User Defined Field.


43

GW01071-Terminal exists with this Currency Code.

PY20015-Invalid Card Name.

PY20016-Invalid Card Address.

PY20017-Invalid Zip Code.

PY20018-Invalid Card Verification Code.

PY20019-Invalid Transaction ID.

PY20080-Invalid Payment Page Style File.

PY20081-Invalid Payment Page Header File.

PY20082-Invalid Payment Page Footer File.

PY20050-Card Number Encryption Failure.

ERROR 3-D Secure

GV00001-Unknown VPAS version

GV00002-Cardholder not enrolled

GV00003-Not a VPAS Card

GV00004-PARes status not sucessful

GV00005-Certificate chain validation failed

GV00006-Certificate chain validation error

GV00007-Signature validation failed

GV00008-Signature validation error

GV00009-Invalid root certificate

GV00010-Missing data type

GV00011-Invalid expiration date

GV00012-Invalid action type

GV00013-Invalid Payment ID

ERROR plug-in 3-D Secure

GV00100-Invalid action type

GV00101-Missing data type

GV00102-Invalid Amount

GV00103-Invalid Brand

GV00104-Payment ID not numeric


44

APPENDIX 2: CERTIFICATION AUTHORITIES Websites protected by SSL certification must use certificates issued by approved issuers (certification authorities). Otherwise the merchant must submit a digital CA certificate used to sign its server certificate. A list of the certification authorities most commonly used for issuing server certification that are already supported in the Payment Gateway system follows.

For the full list of supported certification authorities, download the file on the Activa website at http://www.activa.si/test/.

Verisign Root CA Creation date: Tue Feb 03 10:01:08 CET 2004 Owner: OU=Class 3 Public Primary Certification Authority, O="VeriSign, Inc.", C=US Issuer: OU=Class 3 Public Primary Certification Authority, O="VeriSign, Inc.", C=US Serial number: 70bae41d10d92934b638ca7b03ccbabf Valid from: Mon Jan 29 01:00:00 CET 1996 until: Wed Aug 02 01:59:59 CEST 2028 Certificate fingerprints: MD5: 10:FC:63:5D:F6:26:3E:0D:F3:25:BE:5F:79:CD:67:67 SHA1: 74:2C:31:92:E6:07:E4:24:EB:45:49:54:2B:E1:BB:C5:3E:61:74:E2 Verisign Intermediate CA Creation date: Tue Feb 03 10:25:45 CET 2004 Owner: OU=www.verisign.com/CPS Incorp.by Ref. LIABILITY LTD.(c)97 VeriSign, OU=VeriSign International Server CA - Class 3, OU="VeriSign, Inc.", O=VeriSign Trust Network Issuer: OU=Class 3 Public Primary Certification Authority, O="VeriSign, Inc.", C=US Serial number: 78ee48de185b2071c9c9c3b51d7bddc1 Valid from: Thu Apr 17 02:00:00 CEST 1997 until: Tue Oct 25 01:59:59 CEST 2011 Certificate fingerprints: MD5: 81:C8:88:53:0A:FC:AD:91:6F:BE:71:D9:41:7B:F1:0C SHA1: DE:0F:3A:63:CA:D1:38:41:E9:B6:2C:94:50:2C:B1:89:D7:66:1E:49 Thawte Creation date: Tue Feb 03 09:13:17 CET 2004 Owner: [email protected], CN=Thawte Server CA, OU=Certification Services Division, O=Thawte Consulting cc, L=Cape Town, ST=Western Cape, C=ZA Issuer: [email protected], CN=Thawte Server CA, OU=Certification Services Division, O=Thawte Consulting cc, L=Cape Town, ST=Western Cape, C=ZA Serial number: 1 Valid from: Thu Aug 01 02:00:00 CEST 1996 until: Fri Jan 01 00:59:59 CET 2021 Certificate fingerprints: MD5: C5:70:C4:A2:ED:53:78:0C:C8:10:53:81:64:CB:D0:1D SHA1: 23:E5:94:94:51:95:F2:41:48:03:B4:D5:64:D2:A3:A3:F5:D8:8B:8C Equifax Creation date: Tue Jan 27 13:21:15 CET 2004 Owner: OU=Equifax Secure Certificate Authority, O=Equifax, C=US Issuer: OU=Equifax Secure Certificate Authority, O=Equifax, C=US Serial number: 35def4cf Valid from: Sat Aug 22 18:41:51 CEST 1998 until: Wed Aug 22 18:41:51 CEST 2018 Certificate fingerprints: MD5: 67:CB:9D:C0:13:24:8A:82:9B:B2:17:1E:D1:1B:EC:D4



45

SHA1: D2:32:09:AD:23:D3:14:23:21:74:E4:0D:7F:9D:62:13:97:86:63:3A


46

APPENDIX 3: ISO RESPONSE CODES Informative overview of responses to requests for transaction authorisation according to the ISO standard.

ISO code Description

00 Approved or completed successfully

01 Refer to card issuer

02 Refer to card issuer’s special conditions

03 Invalid merchant

04 Pick-up card

05 Do not honor

06 Error

07 Pick-up card, special condition

08 Honor with identification

09 Request in progress

11 Approved (VIP)

12 Invalid transaction

13 Invalid amount

14 Invalid card number (no such number)

15 No such issuer

30 Format error

31 Bank not supported by switch

33 Expired card

34 Suspected fraud

35 Card acceptor contact acquirer

36 Restricted card

37 Card acceptor call acquirer security

38 Allowable PIN tries exceeded

39 No credit account

41 Lost card

43 Stolen card, pick-up

51 Not sufficient funds

54 Expired card

55 Incorrect personal identification number

56 No card record

57 Transaction not permitted to cardholder

58 Transaction not permitted to terminal

61 Exceeds withdrawal amount limit

62 Restricted card


47

65 Exceeds withdrawal frequency limit

68 Response received too late / Timeout

75 Allowable number of PIN tries exceeded

76 Reserved for private use






82 Reserved for private use / No security module

83 Reserved for private use / No accounts




87 Reserved for private use / Bad track data



90 Cutoff is in process (switch ending a day’s business and starting the next. Transaction can be sent again in a few minutes) / Unable to authorize

91 Issuer or switch is inoperative / Unable to authorize

92 Financial institution or intermediate network facility cannot be found for routing / Decline

94 Duplicate transmission

96 System malfunction

N0 Reserved for private use / Unable to authorize

N1 Reserved for private use / Invalid PAN length

N2 Reserved for private use / Preauthorization full

N3 Reserved for private use / Maximum online refund reached

N4 Reserved for private use / Maximum offline refund reached

N5 Reserved for private use / Maximum credit per refund

N6 Reserved for private use / Maximum refund credit reached

N7 Reserved for private use / Customer selected negative file reason

N8 Reserved for private use / Over floor limit

N9 Reserved for private use / Maximum number refund credits

O0 Reserved for private use / Referral file full

O1 Reserved for private use / NEG file problem

O2 Reserved for private use / Advance less than minimum

O3 Reserved for private use / Delinquent

O4 Reserved for private use / Over limit table

O5 Reserved for private use / PIN required


48

O6 Reserved for private use / Mod 10 check

O7 Reserved for private use



P0 Reserved for private use

P1 Reserved for private use / Over daily limit

P2 Reserved for private use

P3 Reserved for private use / Advance less than minimum

P4 Reserved for private use / Number of times used

P5 Reserved for private use / Delinquent

P6 Reserved for private use / Over limit table

P7 Reserved for private use / Advance less than minimum

P8 Reserved for private use / Administrative card needed

P9 Reserved for private use / Enter lesser amount

Q0 Reserved for private use / Invalid transaction date

Q1 Reserved for private use / Invalid expiration date

Q2 Reserved for private use / Invalid transaction code

Q3 Reserved for private use / Advance less than minimum

Q4 Reserved for private use / Number of times used

Q5 Reserved for private use / Delinquent

Q6 Reserved for private use / Over limit table

Q7 Reserved for private use / Amount over maximum

Q8 Reserved for private use / Administrative card not found

Q9 Reserved for private use / Administrative card not allowed

R0 Reserved for private use








R8 Reserved for private use / Card on national negative file

S4 PTLF full

S5 Reserved for private use




S9 Reserved for private use / Unable to validate PIN; security module is down

T1 Reserved for private use / Invalid credit card advance amount


49

T2 Reserved for private use / Invalid transaction date

T3 Reserved for private use / Card not supported

T4 Reserved for private use / Amount over maximum

T5 Reserved for private use

T6 Reserved for private use

T7 Reserved for private use / Cash back exceeds daily limit

T8 Reserved for private use / Invalid account

U0 ARQC Failure Decline

U1 Security Module Parameter Error

U2 Security Module Failure

U3 KEYI Record Not Found

U4 ATC Check Failure

U5 CVR Decline

U6 TVR Decline

U7 Reason Online Code Decline

U8 Fallback Decline

V0 ARQC Failure Referral

V1 CVR Referral

V2 TVR Referral

V3 Reason Online Code Referral

V4 Fallback Referral

V7 ARQC Failure Capture

V8 CVR Capture

V9 TVR Capture

setting up an online e-commerce system - user · pdf filelist of slovenian online merchants...

Documents