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