- Generation of the payment link using CreatePayInit
- 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.
- The authorisation response (including the authorisation data) is digitally signed. This signature is then verified using VerifyPayConfirm to ensure that the response is authentic.
- Finally, the transaction is captured using PayComplete.
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 (PSD2) 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 PSD2-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 by all online merchants.
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.
How do I know which interface I am using?
Under Online Support / Interface Usage you can see which interfaces were last used to access Saferpay.
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 |
IMPORTANT:
Please note that with more complex systems different interfaces might be used for communicating with Saferpay. The frontend (website, web shop or app) might already be integrated with the JSON API, whereas the downstream management system (e.g. ERP or PMS tools) might still use the older interfaces. It is therefore important to check all relevant transactions to ensure that no old interfaces are being used.
I already use the JSON API. Do I have to do anything?
No, you do not have to do anything. 3-D Secure 2 is currently being rolled out as a pilot and will soon be available to you automatically.
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 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. |
PLEASE NOTE:
With the old interfaces, it was possible to provide an expiry date with authorisation selection (execute). This would then override the expiry date saved for the transaction with the alias in the Secure Card Data (SCD) database. The JSON API no longer provides this option. Here, the expiry dates in the SCD database can be adjusted by the alias/update request if required. If you are using SCD with the old interfaces and have previously provided the expiry date with the execute request, this should be taken into account in your new implementation.
Basic description of the processes
Payment Page
Old interface
Further information on the old interfaces is available at:
- PDF documentation: PaymentPage
JSON API
- Generation of the payment link using PaymentPage/Initialize
- 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 - The call-up of the SuccessUrl or NotifyUrl address indicates a successful authorisation.
- The authorisation data are then returned as a response to the PaymentPage/Assert request.
- 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 interface
- 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.
- After registration, the 3-D Secure process was started via VerifyEnrollment.
- 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:
- PDF documentation: Authorization Interface
- PDF documentation: Merchant Plug-In
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.