Swedbank Payment Portal Implementation
Overview
Product: Hosted Pages
Region: Baltics
September 2015
Version 1.0
Contents
1.
Introduction
1.1.
1.2.
1.3.
2.
Business and integration
2.1.
2.2.
2.3.
3.
Typical steps in integrating with the Payment Portal – services
Technical prerequisites
Basic business scope
Service Summary
3.1.
3.2.
4.
Audience
Hosted Page Service Features
Key Benefits
Service Configuration
How does the service work?
Payment Gateway Production Connectivity
4.1.
4.2.
4.3.
SSL Technology
Payment Gateway Authentication
Hosted Page Sets
1
1
1
1
2
2
2
2
4
4
4
5
5
5
5
5.
Performing Transactions
6
6.
Query Transaction
7
7.
Repeat Payments
8
8.
Basics on Card transaction
9
8.1.
8.2.
8.3.
Introduction to card payments
What is e-commerce card payments
What is 3-D Secure
9
9
10
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 redirected 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 1
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 2
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 3
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.
2.
3.
4.
5.
6.
Merchant submits a “SETUP” request to the Payment Gateway
Payment Gateway returns a redirect URL and Session ID.
Merchant redirects cardholder to hosted page
Payment Gateway undertakes authentication and authorization processing
Cardholder is returned to merchant website
Merchant submits QUERY request to Payment Gateway for detailed transaction information
Page 4
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 5
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 6
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 7
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 8
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 authorisation 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 purchase. 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 9
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.
Page 10