Saferpay FAQ: Introduction of 3-D Secure 2.0

Saferpay FAQ: Introduction of 3-D Secure 2.0

Relevant information for developers

Summary

The Regulatory Technical Standards (RTS) under the Second EU Payment Services Directive (PSD 2) are due to take effect on 14 September 2019. They mainly require strong customer authentication (two-factor authentication) for online payments. To comply with this requirement, the card organisations Visa and Mastercard together with EMVCo have further developed the 3-D Secure security process: 3-D Secure 2.0 is PSD 2-compliant and is valid in EU countries as well as Switzerland. According to the requirements of the card organisations, 3DS 2.0 must be supported in the first European countries and Switzerland from April 2019.

Worldline always provides you with the latest version of 3-D for Saferpay. The current version used is 3-D Secure 2.1 (hereinafter referred to only as “3-D Secure 2”). 

 

Do I have to take immediate action regarding 3-D Secure 2?

This depends on whether you already use the current Saferpay JSON API or work with one of the old interfaces. The journal overview (https://www.saferpay.com/BO/Commerce/JournalOverview) within the Saferpay Backoffice, and the transaction details clearly indicate which interface was used to create the transaction.

The Transaction Journal in the Saferpay Backoffice features a column labeled "Application". The values in this column indicate which interface was used to create the concerned transaction.

 

The Transaction Details Page in the Saferpay Backoffice also shows the interface that was used to create, capture or cancel the transaction.

 

 

 

Relevant values for this field are as follows:

Abbreviation Long text Action required
AI Saferpay Client Application Interface Switch to JSON API
API JSON API NO
HI HTTPS Interface Switch to JSON API
PP/AI/HI Payment Page / Saferpay Client Application Interface / HTTPS Interface Switch to JSON API
PP/API Payment Page / JSON API NO
BO Saferpay Backoffice NO
BP Saferpay Backoffice Batch Processing NO

I already use the JSON API. Do I have to do anything?

No, you do not have to do anything. The migration will be fully automatic and will take place gradually from April 2019 ongoing.

 
 

I still use the old interface (https interface or Saferpay client). Do I have to do anything?

3-D Secure 2 is only supported with the JSON API. The old interfaces do not support the new standard and will be deactivated at the end of 2020. It is therefore important that you migrate to the JSON API, even if your system does not use 3-D Secure functionality. For more information on the migration, please refer to Migration to the JSON API.

 

I am a new customer. Do I have to do anything to use 3-D Secure 2?

As a new customer, you are already using the Saferpay JSON API Interface and you therefore do not have to do anything. The migration from 3-D Secure 1 to 3-D Secure 2 will take place automatically within Saferpay. For more information, please refer to our integration guide for getting started with your Integration Process.

 

Migrating to the Saferpay JSON API

Technology is changing in many ways and interfaces are no exception. If you operate a web shop and offer more than one means of payment, it is important that the interfaces also comply with the new requirements. By adapting your interface to the Saferpay JSON API, you are making sure that the payment authorizations between your system and the Worldline continue to work seamlessly in the future. In addition, you will benefit from additional security mechanisms, more means of payment and a simplified integration.

To migrate your interface, it is best that you contact the technical person in charge of your web shop or other applications that are connected to Saferpay.

If your shop uses a plug-in to connect to Saferpay, our partner Customweb offers the latest Saferpay modules for many shop systems at https://www.sellxed.com/shop/en/chf/extensions/module/payment-service-provider/saferpay.html.

If you have an individual implementation, you can find the general documentation for the Saferpay JSON API at https://saferpay.github.io/sndbx/index.html.

The technical documentation, including a structured listing of all requests, their containers and parameters as well as relevant example codes, is available at: http://saferpay.github.io/jsonapi/.

For all the necessary information on the Saferpay test environment (including the option to set up an individual test account), please visit the Saferpay test account support page.  

 

Comparison of functions and parameters

Our documentation contains all the information necessary for the implementation of the JSON API. However, for you to have better understanding of the JSON API and to assist you with the migration process, the following table shows a comparison between the old interfaces and the JSON API.

 
 
Old interface JSON API Comment
CreatePayInit PaymentPage/Initialize  
CreatePayInit (SCD) Alias/Insert  
CreatePayComplete (ACTION=Settlement) Transaction/Capture  
CreatePayComplete (ACTION=Cancel) Transaction/Cancel  
CreatePayComplete (ACTION=CloseBatch) Batch/Close  
ACCOUNTID=401860-17795278 CustomerId=401860
TerminalId=17795278
The ACCOUNTID consists of the CustomerId and TerminalId, separated by a hyphen.
Execute (ACTION=Debit) Transaction/Authorize or Transaction/AuthorizeDirect  
Execute (ACTION=Credit) Transaction/Refund or Transaction/RefundDirect  
CARDREFID Alias.Id  
Automatically generated aliases were numeric and incremented Aliases generated by Saferpay are alphanumeric. The definition of aliases (alphanumeric to 40 char. length) is the same. Aliases are valid across interfaces. Aliases generated with the old interfaces can be easily reused with the JSON API.
Authentication using SPPASSWORD Basic authentication or client certificate authentication  
CreatePayInit (including formatting of the payment page):
Parameter
BODYCOLOR,
BODYFONTCOLOR,
FAILCOLOR,
FOOTERFONTCOLOR,
HEADCOLOR,
HEADFONTACTIVECOLOR,
HEADFONTCOLOR,
HEADFONTINACTIVECOLOR,
HEADLINECOLOR,
LINKCOLOR,
MENUCOLOR,
MENUFONTCOLOR,
MERCHANTDETAILCOLOR,
ORDERCOLOR,
PAYMENTDETAILMOUSEOVERCOLOR,
SUCCESSCOLOR,
TITLECOLOR
PaymentPage/Initialize using the parameter CssUrl Alternatively, the design of the payment page can be configured in the Backoffice.
CreatePayInit (including the display of the acceptance of the terms and conditions on the payment page: Parameter TERMSCHECKBOXACTIVE,  TERMSURL) Not available The acceptance of terms and conditions is part of the purchasing process and should be carried out and logged on the website or in the web shop. This function is therefore no longer offered in the payment process.

Basic description of the processes

Payment Page

Old interface

  1. Generation of the payment link using CreatePayInit
  2. The shop redirects the buyer to the Saferpay payment page. In this step, Saferpay records the payment data and if necessary, carries out 3DS authentication, runs the DCC process and then authorizes the payment.
  3. The authorisation response (including the authorisation data) is digitally signed. This signature is then verified using VerifyPayConfirm to ensure that the response is authentic.
  4. Finally, the transaction is captured using PayComplete. 
 

Further information on the old interfaces is available at:

 

JSON API

  1. Generation of the payment link using PaymentPage/Initialize
  2. The shop redirects the buyer to the Saferpay payment page. In this step, Saferpay records the payment data and ifnecessary, carries out 3DS authentication, runs the DCC process and then authorizes the payment. For further options on how to manage the payment process, please refer to: 
    https://saferpay.github.io/sndbx/Integration_PP.html#pp-initialize
  3. The call-up of the SuccessUrl or NotifyUrl address indicates a successful authorisation.
  4. The authorisation data are then returned as a response to the PaymentPage/Assert request.
  5. Finally, the transaction is then captured using Transaction/Capture or cancelled using Transaction/Cancel.
 

For a detailed description of the process using the JSON API, please refer to: https://saferpay.github.io/sndbx/Integration_PP.html

 

Main differences

  • With the old interfaces, the call-up of the return addresses (Successlink and NotifyUrl) returns authorisation data. The JSON API does not return any data. The authorisation data are called using a separate request (PaymentPage/Assert).
  • The old interfaces use signature verification (using VerifyPayConfirm request) for security purposes. The JSON API uses basic authentication or client certificate authentication to securely verify each request.
 

Standard Business Flow

Old interfaces

  1. With the old interfaces, it was imperative to tokenise customer card data (storage in SCD) first. A CreatePayInit request with specific parameters was executed and the returned address then opened the registration form.
  2. After registration, the 3-D Secure process was started via VerifyEnrollment.
  3. Depending on the ECI value returned in the response, the system either forwarded the data to the authentication page of the card-issuing bank or executed the authorisation request directly via Execute.
 

Further information on the old interfaces is available at:

 

JSON API

The JSON API simplifies the process considerably without the need to store the card data first, while still providing the option to do so if required. Furthermore, it is no longer necessary to use the VerifyEnrollment request. The verification is done automatically by Saferpay.

For a detailed description of the process using the JSON API, please refer to: https://saferpay.github.io/sndbx/Integration_trx.html

 

Contact

Do you have any further questions regarding 3-D Secure 2 or the interface change? We are also happy to assist you with updating your Saferpay interface.