Swedbank Payment Portal Implementation

Overview

Product: Hosted Pages

Region: Baltics

September 2015

Version 1.0

Contents

1. Introduction 1

1.1. Audience 1

1.2. Hosted Page Service Features 1

1.3. Key Benefits 1

2. Business and integration 2

2.1. Typical steps in integrating with the Payment Portal – services 2

2.2. Technical prerequisites 2

2.3. Basic business scope 2

3. Service Summary 4

3.1. Service Configuration 4

3.2. How does the service work? 4

4. Payment Gateway Production Connectivity 5

4.1. SSL Technology 5

4.2. Payment Gateway Authentication 5

4.3. Hosted Page Sets 5

5. Performing Transactions 6

6. Query Transaction 7

7. Repeat Payments 8

8. Basics on Card transaction 9

8.1. Introduction to card payments 9

8.2. What is e-commerce card payments 9

8.3. What is 3-D Secure 10

Page 1

1. Introduction The Hosted Page Service (HPS) allows the capture and subsequent authorization of Credit and Debit cards via a page hosted by the Payment Gateway. A merchant no longer has to store or transmit the sensitive card details meaning the Payment Gateway can help lower PCI requirements and responsibilities. Hosted Page Service (HPS) is a product which combines the flexibility of an API driven system with the security benefit of not handling or transmitting any sensitive card details. The Payment Gateway hosts a card capture page which is recommended to be used as a full redirect. The cardholder is presented with a page which captures sensitive card data before automatically passing the card data to the Payment Gateway for authorisation. Once complete, the cardholder is re-directed back to the merchant’s website.

1.1. Audience

This document is intended to assist developers with the technical integration and implementation to the payment gateway.

1.2. Hosted Page Service Features

Hosted Page Service is a feature rich hosted product that includes the following features:

Customisable elements including Merchant Logo, Links and Name.

Ability to capture just Card Security Code (CSC) for repeat customer payments.

3-D Secure

Tokenization

Fraud and Risk Screening

Refunds and Cancelations

1.3. Key Benefits

Hosted Page Service brings the merchant real benefits over and above a traditional API approach where card details are stored and transmitted from your own environment.

Secure collection and transmission of card data

Reduces the PCI requirements of the merchant as data is stored by the Payment Gateway

Authorisation and 3-D Secure process managed by the Payment Gateway

Simple integration model

Managed 3-D Secure through interaction with the Payment Gateway

Page 2

2. Business and integration The technical integration to the Payment Gateway depends on your business scope. Complex business scenarios can be achieved but would likely require a more involved integration. The Payment Gateway provides an API for access to payment products and services. The API is a proprirety XML-structured message that is sent over HTTPS to the Payment Gateway with a different XML-structure returned in the HTTPS response.

Figure 1 - Solution Overview – Merchant connects to Payment Gateway via API over the Internet

2.1. Typical steps in integrating with the Payment Portal – services

In order to start accepting payments via the Payment Portal typically a merchant will need to undertake the following steps:

1. Understand the correct API calls required for each payment type by reading this document and the additional Payment Portal documentation.

2. Test account details are required (id = vTID and password for the API) and details to access the Reporting Portal.

3. Undertake the technical integration by linking your ecommerce system with the Payment Portal. Use the “magic“ card numbers to process test transactions and then view your transactions in the Reporting portal.

4. When you are happy with your test transactions. Contact your Payment Portal support representative who will provide the access details for the Production systems.

5. Update your ecommerce system with the Production access details. 6. Perform final live verification and check the outcome in the Reporting Portal

2.2. Technical prerequisites

You will typically need the following: 1. An ecommerce platform or shopping software that is typically integrated with an order system. 2. A webserver and possibly ideally with a seperate test environment. 3. A fixed IP-address from where the API calls are initiated. 4. A SSL certificate provisioned from a trusted provider (see section 4.1) 5. Access to programming tools and libraries that can assist in the construction of the XML

messages.. 6. Access and connection details from your Payment Portal representative: merchant ID (vTID),

password, testing API URL.

2.3. Basic business scope

There are a lot of features provided by the API and you need to decide on what services that suit your business needs. This is normally decided in an early stage and in cooperation with your Payment Portal representative. This document focuses on a basic business scope that will cover the most common ecommerce scenarios and designed to get you up and running very quickly.

Page 3

1. Support for basic card based authorizations (reservation of funds on the cardholder account).

2. Support for automatic “capture”. The actual transfer of money from the cardholder account. This

is also referred to as “one-stage authorisation”

3. Support for 3D Secure – identification of cardholder

4. Support for refund (on return of goods or similar, the merchant may refund the payment back to the cardholder).

Page 4

3. Service Summary

3.1. Service Configuration

The Hosted Page Service requires configuration on the Payment Gateway. The merchant must request service enablement (please consult the specific setup process for your service provider). A merchant must have the following available in order to use the service

A Client ID

The Payment Gateway Password

A Page Set ID

3.2. How does the service work?

The hosted page service provides a simple integration model for the processing of credit and debit card transactions.

1. Merchant submits a “SETUP” request to the Payment Gateway 2. Payment Gateway returns a redirect URL and Session ID. 3. Merchant redirects cardholder to hosted page 4. Payment Gateway undertakes authentication and authorization processing 5. Cardholder is returned to merchant website 6. Merchant submits QUERY request to Payment Gateway for detailed transaction information

Page 5

4. Payment Gateway Production Connectivity The Payment Gateway has dual ISP Internet routes (via different suppliers). Under normal operating situations the Primary Route into the Payment Gateway should be used. If you are unable to connect to the Payment Gateway via the Primary Route, you should switch to the Secondary Route. The Secondary Route is available at all times. It is recommended that you do not use the Secondary route under normal operating conditions and should only be used in the event of connectivity issues via the Primary. For example, you may consider switching routes if an excessive number of timeouts or an inability to establish a connection is experienced. It is recommended to connecting using the DNS domain name, rather than the IP address. By using DNS, should there be an issue with the Primary Data Centre, traffic will automatically fail over to the Secondary Data Centre and your transactions will automatically switch without requiring additional action on your part. To facilitate automatic failover, a merchant must ensure they can send and receive traffic to all of the following end points. It is recommended traffic is allowed to pass to and from IP Set 1 and IP Set 2. The payment gateway test connectivity details will be provided by Payment Gateway Technical Support team.

4.1. SSL Technology

A merchant who collects and transmits cardholder and transaction data via a website application must securely protect that information as it moves between the cardholder’s browser, the merchant’s application, and the Payment Server. A merchant application must use Secure Sockets Layer (SSL) technology to provide the necessary security and encryption for transmitting sensitive cardholder and transaction information. It is also recommended that a merchant uses a secure method when collecting cardholder data. The Payment Server uses SSL to encrypt cardholder and other sensitive transaction details and provide a secure transmission with the cardholder where merchants use the Server Hosted integration method. When the cardholder’s browser connects to the merchant application using SSL the website address prefix changes to https:// and an indication appears in the browser address bar to indicate that the communication is encrypted and secure.

4.2. Payment Gateway Authentication

Each merchant will be allocated one or more Client ID’s, this uniquely identifies a merchant’s account and is used when submitting a transaction to the Payment Gateway, it is sent within the client element. Payment Gateway Technical Support will generate and provide Client Id(s) and Client Password(s) during the merchant on-boarding process. These details will be different for production and test environments.

4.3. Hosted Page Sets

Payment Gateway Technical Support will also provide the Hosted Page Set IDs that have been allocated with the merchant profile during the merchant on-boarding process. Page Set IDs are used by the merchant in session requests and allows to merchant to present the selected hosted capture pages to their buyers, e.g. pages localized in preferred language. It should be noted Page Set IDs will be different for production and test environments.

Page 6

5. Performing Transactions The first API call a merchant must make to the Payment Gateway is a “Setup” request. The setup request informs the Payment Gateway of the necessary details required to process the transaction. These details include:

A unique reference number generated by the merchants system - to allow the transactions to be distinguished from each other. Commonly this is an order or invoice number.

The value and currency of the transaction. Supported currency is EUR.

The transaction type. Each transaction will contain a transaction type which informs the type of transaction to be carried out

details about which of the payment page is to be presented to the customer

3-D Secure authentication requirement

The merchant also needs to include additional information to use additional services and trigger or

enhance various fraud and risk screening techniques:

Additional customer and order information for Fraud and Risk screening

Address details

Page 7

6. Query Transaction At any point between the merchant applications sending a redirect to the customer (shopper) and them subsequently returning to the merchant website there could be a failure in communications. For example, the customer may choose to go to a different website or the Internet connection may fail. This will lead to an ambiguous order state in the merchant‘s system. To address this scenario, the Payment Gateway provides a method by which merchants can determine the status of all orders. The query transaction should be used against all orders that have an incomplete state after a certain period of time. The transaction state should then be updated in accordance with the Query response from the Payment Gateway. Suggested timings are to query a transaction at 30 minutes* after the initial XML Request and then an hour later if required. If the transaction is still in an incomplete state 60 Minutes* after the initial authorization then a manual process is required to clean up the transaction (the manual process with depend on the merchants own business process). Depending on the merchant business it may also be necessary for an operator to be able to query on an ad hoc basis. * Times should be adjusted to align with merchants own business process

Page 8

7. Repeat Payments Once a transaction has been processed using the full card details a card token will have been generated and stored by the Payment Gateway. It is possible to process a payment without collecting the full card details from the customer again but only collecting the card security code (CSC). In order for repeat payments to function correctly a merchant must have the following:

- The Tokenization service needs to be enabled on the merchant setup - A CSC only capture page associated to a Card Capture Page set in order to use this

functionality. A repeat customer payment can be achieved in three easy steps:

1. QUERY a previous transaction to obtain the Token and card expiry date 2. Submit a SETUP request to the Payment Gateway including Token & card expiry 3. Capture Card Security Code (CSC) only from the customer

After the CSC is captured the Payment Gateway will process the transaction using the same process as if the full card details were captured that is described in chapter 5 of this document. The merchant may wish to consider storing the card expiry, masked card number and token against a customer profile on their system which would remove the need to query a transaction to obtain the token ,expiry date and masked card number (after these details are obtained at least once by using a query). The setup request for a repeat payment contains more information than a request than the initial request, namely the following:

Masked card number

Expiry month/year

Card Token

CVV/CSC only indicator

Page 9

8. Basics on Card transaction This section is intended to provide merchants who are new to accepting online payments a brief overview of card payments and associated authentication protocols.

8.1. Introduction to card payments

The stakeholders typically involved in the acceptance and processing of credit & debit cards are:

Card Issuer – is the entity (often a bank) that provides the actual card – normally a physical card to - its customers, the cardholder. Swedbank acts as Card Issuer.

The Card Scheme – is providing the infrastructure for transferring the card transactions and is also the regulator for the other involved parties (Issuer, Acquirer). Visa and MasterCard are typical card schemes.

Acquirer – is the entity (often a bank) that signs an acquiring agreement with a merchant. The acquiring agreement regulates how merchants may accept card payments. The acquirer is sometimes also providing some infrastructure – such as a credit card terminal to its merchants. Swedbank acts as an acquirer

The actual card payment is normally based on two steps: Authorization and settlement.

1. Authorization occurs as the cardholder gives payment for his purchase. The merchant will send an authorization message online to the Payment Portal which in turn will submit an author-isation message to the acquirer. The acquirer will contact the card issuer who ultimately gives approval for the transaction.

2. Settlement is the process by which the Payment Portal indicates to the acquirer that the funds are to be moved from the cardholder to the merchant for the amount specified in each pur-chase. The acquirer contacts each issuer via the card scheme infrastructure.

8.2. What is e-commerce card payments

Ecommerce is a common term for payments collected via a website or mobile device where the cardholder is not present.

Page 10

8.3. What is 3-D Secure

3D Secure stands for 3 Domain Server and is a technology that is used to authenticate the cardholder with the card issuer. There are 3 parties that are involved in the 3-D Secure process : The company the purchase is being made from. The Acquiring Bank (the bank of the company) VISA and MasterCard (the card issuers themselves) The main goal of 3-D Secure is to improve the security of the transaction by introducing an authentication of the cardholder before the transaction is sent on for authorization.

To use 3-D Secure a cardholder needs to enroll their card in the 3-D Secure scheme. This is typically performed via the card issuer. There are several steps that take place in an 3-D Secure transaction, the majority of which are handled by the Payment Portal. A cardholder will be presented with a 3-D Secure authentication process prior to the transaction being sent for authorization.