- Document version: 3.0 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.
- Document version: 3.1
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
Contents
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
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.
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.
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.
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
4. Prepares an HTTP request for request, data on the transaction is stored on the system, where a PaymentID code is created and the URL to which the
9. Calls the HPP 10. After verification
of the PaymentID
11. Completes the request to the bank authorisation system page with the result of the transaction,
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
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
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.
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
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.
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 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
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
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
The consumer is redirected to the ErrorURL, where static information about the error is