Introduction

WL Sips is a secure multi-channel e-commerce payment solution that complies with the PCI DSS standard. It allows you to accept and manage payment transactions by taking into account business rules related to your activity (payment upon shipping, deferred payment, recurring payment, payment in instalments, etc.).

This document aims to explain how to implement 3-D Secure for the CB, VISA, MASTERCARD and AMEX means of payment up to the production start.

Who does this document target?

This document is intended for merchants and their technical teams wishing to implement 3-D Secure on their e-commerce website, for the CB, VISA, MASTERCARD and AMEX means of payment.

To get an overview of the WL Sips solution, we advise you to consult the following documents:

Contacting the support

For any technical question or request for assistance, our services are available:

  • by telephone at: +33 (0) 811 10 70 33
  • by e-mail: sips@worldline.com

In order to facilitate the processing of your requests, please provide your merchantId (15-digit number).

General points

Principle

3-D Secure is an authentication protocol designed to reduce the risk of fraud associated with online payments. Its purpose is to ensure that the card is used by its true holder.

When making a 3-D Secure payment, there is an additional step of authenticating the cardholder.

Attention: as of the 31st of March 2020, the DSP2 regulation makes strong authentication mandatory for online payments, deadline from which the first issuer refusals will be applied to transactions not 3-D Secure authenticated ( acquirerResponseCode field = A1).

For more on this, please refer to our RTS-SCA announcement of the 16th of September 2019 .

Liability shift

In addition to enhanced security, 3-D Secure allows you to benefit from the liability shift to the card issuing bank. In the event of fraudulent payment, you are guaranteed to receive the funds, it is the cardholder's bank that bears this responsibility. In rare cases, the cardholder's bank may accept a request for authorisation but refuse this liability shift, in this case the payment is no longer guaranteed, and the holderAuthentRelegationCode field is set to Y.

These liability shift rules are issued by the CB, VISA and MASTERCARD schemes. For CB/VISA/MASTERCARD cards, if payment is guaranteed, the guaranteeIndicator field is set to Y.

New 3-D Secure 2.0 version

Despite obvious security benefits, 3-D Secure 1.0, deployed in France since 2007, does not provide an optimal user experience, and therefore has an impact on the conversion rate of online purchases.

To improve the user experience, the CB, VISA, MASTERCARD and AMEX networks now offer 3-D Secure 2.0 which provides a more optimal authentication system based on risk assessment and more suitable for smartphones.

Depending on the level of risk, issuing banks will decide whether or not to perform strong authentication of the client, this is an operating mode called "frictionless". The lower the risk, the higher the probability of obtaining a frictionless transaction.

Improvements made

Despite the obvious security benefits, 3-D Secure 1.0, deployed in France since 2007, does not provide an optimal user experience, and therefore has an impact on the online purchases conversion rate.

To improve the user experience, the CB, VISA, MASTERCARD and AMEX schemes now offer 3-D Secure 2.0 that provides a more optimal authentication system based on risk assessment and more suitable for smartphones.

Depending on the risk level, issuing banks will decide whether or not to perform strong client authentication: this is an operating mode called " frictionless ". The lower the risk, the higher the probability of a " frictionless " transaction.

How will 3-D Secure v1 and 3-D Secure v2 coexist?

Case 1: you still use 3-D Secure v1, but the issuer uses 3-D Secure v2:

Everything will work, as the issuer keeps on processing 3DSv1 authentication requests. The VISA and MASTERCARD schemes have indeed recommended that issuing banks keep on enrolling their new cards in both 3-D Secure versions (v1 and v2).

Case 2: you already use 3-D Secure v2, but the issuer still uses 3-D Secure v1:

Everything will work as well, since in this case the WL Sips payment server submits authentication requests in 3DSv1.

Visa mandatory fields

To process transactions from their scheme, in 3-D Secure v2, Visa requires that the customer's billing address, name and e-mail fields be populated. If one of these fields is missing from your request, WL Sips consequently switches the transaction to 3-D Secure v1.

It is also a Visa requirement that the fraudData.merchantCustomerAuthentMethod (method of customer authentication by the merchant) be populated. If you do not populate this field in the payment request, WL Sips will set it by default to NO_AUTHENT (no customer authentication by the merchant) to switch the transaction to 3-D Secure v2.

List of mandatory fields requested by Visa:

billingAddress.city

billingAddress.country

billingAddress.addressAdditional1

billingAddress.addressAdditional2

billingAddress.addressAdditional3

billingAddress.zipcode

billingAddress.state

holderContact.lastName

holderContact.email

fraudData.merchantCustomerAuthentMethod

Activating the 3-D Secure option

The Revised Payment Services Directive (PSD2), making it mandatory to carry out strong authentication for payments initiated by the customer on the Internet or via a mobile application, comes into force on the 14th of September 2019, with a running-in phase until the 31st of March 2020. 3-D Secure allows you to be in compliance for card payments with this new regulation. Without activating 3-D Secure, you are exposed to authorization denials due to un-authenticated transactions.

Therefore, unless you advise otherwise, any new webshop is registered on WL Sips with the 3-D Secure option activated by default. (Please read our announcement of the 17th of September 2019 for more information on this).

If the 3-D Secure option is not activated on your webshop, please contact the WL Sips technical support to activate this option.

For the CB network, the activation of the 3-D Secure option is almost immediate.

For VISA, MASTERCARD and AMEX networks, the activation of the 3-D Secure option is done in 2 steps:

  • step 1 = enrollment of your shop on the VISA and MASTERCARD Directory Server, or AMEX
  • step 2 = activation of 3-D Secure when enrolment on DS is completed. For your information, VISA will enroll you in approximately 24 hours, MASTERCARD in 7 days, AMEX in 3 weeks.

3-D Secure and deferred payments

In order to benefit from the liability shift, for any 3-D Secure transaction with a capture time of more than 6 days ( captureDay field > 6), WL Sips forces the capture delay to 6 ( captureDay field forced to 6).

Therefore, in the case of a 3-D Secure payment, with a CB/VISA/MASTERCARD/AMEX card, and for a payment request with a captureDay field greater than 6, you will receive the following reply:

  • The captureDay field is set to 6.
  • If the captureMode field in your request is set to VALIDATION, you only have 6 days to validate the sending of the transaction to the bank.
  • If the captureMode field is set to AUTHOR_CAPTURE or is empty, you only have 6 days to cancel the transaction before it is sent to the bank.

Refusing transactions with a 3-D Secure error

In order to reduce the risk of chargebacks, you have the option to refuse all transactions for which a technical error has prevented the 3-D Secure authentication process from proceeding properly.

If you enable this option and a 3-D Secure error occurs during the 3-D Secure authentication, the transaction is rejected, with a response code 05 ( responseCode field = 05) and the holderAuthentStatus field set to ERROR.

Accepting only guaranteed transactions

In order to ensure that you collect all the funds from your sales and avoid non-payment, you have the option to refuse all 3-D Secure transactions for which the transfer of responsibility does not apply, even if the transaction has been authorised.

If you enable this option, only transactions that benefit from the liability shift ( GuaranteeIndicator field = Y) will be accepted.

This option applies only to the CB, VISA and MASTERCARD 3-D Secure transactions.

This option doesn't apply :

  • to non 3-D Secure transactions
  • to transactions made with a mean of payment different than CB, VISA, MASTERCARD
  • to installments 2 to N of payment in installments
  • to duplications and other recurring payments

Sips Paypage connector

Card payments

This chapter describes how to implement 3-D Secure for one-time payments, one-time payments with OneClick enrollment and OneClick payments.

Flows description

  1. You redirect the customer to Sips Paypage by transmitting the transaction data (amount, currency, etc.) in the request.
  2. WL Sips displays the payment page, the customer enters the card number, the security code and then validates.
  3. WL Sips performs the 3-D Secure check.
  4. WL Sips sends an authorisation request to the acquirer.
  5. WL Sips saves the transaction into the back office.
  6. WL Sips displays the payment receipt page.
  7. WL Sips returns the manual and automatic responses that contain transaction details including the result of the 3-D Secure authentication.
  8. WL Sips The software sends, or not, the transaction as a remittance according to the conditions you have set in the payment request.

The sequence described above is transposed to the CB, Visa, Mastercard and Amex means of payment.

3-D Secure dynamic deactivation

In order to promote a higher conversion rate, depending on the risk (amount, knowledge of the customer, etc.) you may choose to dynamically bypass the 3-D Secure authentification (including for OneClick payments). This option is applicable for CB, Visa and Mastercard means of payment, it has no effect on the AMEX means of payment.

To benefit from this option, you must first get the approval from your acquirer, then ask your technical support for the 3DS activation and set the fraudData.bypass3DS field to ALL (or MERCHANT_WALLET for OneClick payments). As a payment response, the holderAuthentStatus field is then set to BYPASS.

IMPORTANT: given the recent regulation of the 14th of September 2019 that makes authentication mandatory for online payments, by bypassing the 3-D Secure authentication, you are exposed to "soft decline" payment refusals ( acquirerResponseCode = A1). For you not to lose any sales, following this type of refusal, we automatically ask the customer to 3-D Secure authenticate themselves, and send a second authorisation request with the proof of customer authentication.

Implementation

If your webshop is not a 3-D Secure one, please get in touch with the WL Sips technical support to activate the service.

Setting the payment request

You do not have any specific 3-D fields to fill in to offer 3-D Secure payments via Sips Paypage . However, if you would like to activate the dynamic bypass, you must fill in the fraudData.bypass3DS field.

Field Sample field population
fraudData.bypass3DS ALL if you wish to deactivate the 3-D Secure authentication for a one-time payment.
MERCHANT_WALLET if you wish to deactivate the 3-D Secure authentication for a OneClick payment.
Otherwise not filled in.
merchantName Shop name of your website that will be displayed on the authentication page of the holder's bank.
If not filled in, the name of your shop specified when your shop was registered on WL Sips will be displayed.

Please read one of the Sips Paypage guides (316, 317 or 318 ) to find out how to populate the request depending on your business need.

Analysing the response

WL Sips sends back a manual response and a standard automatic paypage response.

The fields pertaining to 3-D Secure payments are as follows:

Use case Response fields
Authenticated holder guaranteeIndicator = cf. Data dictionary
  • connector version equal to or higher than 2.24
    • 3DS: the holder authenticated themselves using a 3-D Secure V1 process
    • 3DS_V2: the holder authenticated themselves using a 3-D Secure V2 process
  • connector version lower than 2.24
    • 3DS: the holder authenticated themselves using a 3-D Secure V1 or 3-D Secure V2 process
holderAuthentMethod =
  • connector version equal to or higher than 2.24
    • if process is 3-D Secure V1: NOT_SPECIFIED
    • if process is 3-D Secure V2: cf. Data dictionary .
  • connector version lower than 2.24
    • NOT_SPECIFIED: whatever the process
holderAuthentStatus = ATTEMPT or SUCCESS
holderAuthentType =
  • if process is 3-D Secure V1: not filled in
  • if process is 3-D Secure V2: cf. Data dictionary .
Card not enrolled guaranteeIndicator = cf. Data dictionary
holderAuthentProgram = NO_AUTHENT
holderAuthentMethod =
  • connector version equal to or higher than 2.24
    • if process is 3-D Secure V1: NOT_SPECIFIED
    • if process is 3-D Secure V2: NO_AUTHENT
  • connector version lower than 2.24
    • NOT_SPECIFIED: whatever the process
holderAuthentStatus = NOT_ENROLLED
  • if process is 3-D Secure V1: not filled in;
  • if process is 3-D Secure V2: NONE
The cardholder was not able to authenticate themselves, payment is inevitably refused. guaranteeIndicator = N
holderAuthentProgram =
  • connector version equal to or higher than 2.24
    • 3DS: the holder attempted to authenticate themselves using a 3-D Secure V1 process
    • 3DS_V2: the holder attempted to authenticate themselves using a 3-D Secure V2 process
  • connector version lower than 2.24
    • 3DS: the holder authenticated themselves using a 3-D Secure V1 or 3-D Secure V2 process
holderAuthentMethod =
  • connector version equal to or higher than 2.24
    • if process is 3-D Secure V1: NOT_SPECIFIED
    • if process is 3-D Secure V2: cf. Data dictionary .
  • connector version lower than 2.24
    • NOT_SPECIFIED: whatever the process
holderAuthentType =
  • if process is 3-D Secure V1: not filled in
  • if process is 3-D Secure V2: CHALLENGE
Technical issue that prevented the successful completion of the 3-D Secure authentication. guaranteeIndicator = cf. Data dictionary
holderAuthentProgram =
  • connector version equal to or higher than 2.24
    • 3DS: the holder authenticated themselves using a 3-D Secure V1 process
    • 3DS_V2: the holder authenticated themselves using a 3-D Secure V2 process
  • connector version lower than 2.24
    • 3DS: the holder authenticated themselves using a 3-D Secure V1 or 3-D Secure V2 process
holderAuthentMethod =
  • if process is 3-D Secure V1: NOT_SPECIFIED
  • if process is 3-D Secure V2: NOT_SPECIFIED
holderAuthentType =
  • if process is 3-D Secure V1: not filled in
  • if process is 3-D Secure V2: NONE or CHALLENGE
You bypass the 3-D Secure authentication. guaranteeIndicator = not filled in
holderAuthentMethod = NO_AUTHENT_METHOD
holderAuthentType = not filled in
Your webshop is not 3-D Secure enrolled. guaranteeIndicator = not filled in
holderAuthentProgram = NO_AUTHENT
holderAuthentMethod = NO_AUTHENT_METHOD
holderAuthentStatus = NO_AUTHENT
holderAuthentType = not filled in
The holder cancels the authentication process. guaranteeIndicator = N
The holder quits on the ACS page and closes their browser. You do not receive any manual response, but only an automatic response with the responseCode field set to 97. guaranteeIndicator = not filled in
holderAuthentProgram = not filled in
holderAuthentMethod = not filled in
holderAuthentRelegationCode = not filled in
holderAuthentStatus = not filled in
holderAuthentType = not filled in

Sips Office connector

Payment from a card number

Flows description

A 3-D Secure payment is made in 3 steps:

  • checking the customer's card enrollment
  • redirecting the customer to their bank's ACS
  • the 3-D Secure authorisation request

Implementation

If your webshop is not a 3-D Secure one, please get in touch with the WL Sips technical support to activate the service.

To implement a 3-D Secure card payment, you must implement the messages received and sent by the "E-commerce server" entity in the above chart.

Step 1: collecting payment data

You collect the cardholder's card data (card number, validity date, security code). You must comply with the PCI DSS recommendations.

Step 2: checking the selected card enrollment

You use the 3-D Secure enrollment of the card using the cardCheckEnrollment function.

Setting the payment request

In a 3-D Secure context, apart from the mandatory method data, here is the request data you should pay attention to.

Field name Population rule
amount Payment amount. The amount is displayed on the holder authentication page.
captureDay Must be 6 or less. If the value is greater than 6, the WL Sips server forces it to 6.
cardCSCValue Value retrieved in the previous step.
cardExpiryDate Value retrieved in the previous step.
cardNumber Value retrieved in the previous step.
merchantName Shop name of your website that will be displayed on the authentication page of the holder's bank.
If not filled in, the name of your shop specified when your shop was registered on WL Sips will be displayed.
merchantReturnUrl Do not populate, this field is deprecated.
merchantUrl URL of your website that will be displayed on the authentication page of the holder's bank. If not filled in, the URL of your shop specified when your shop when registered on WL Sips will be displayed.
orderChannel For payments made through the Internet, please set to INTERNET
panType PAN if you use the standard Office connector

CSE if you use the Office connector in CSE mode

paymentMeanBrand For co-branded cards (CB+VISA or CB+MASTERCARD), the indicated value determines the choice of the DS in a 3-D Secure v2 process.
For example, for a CB+VISA co-branded card:
  • if you set to CB, the WL Sips server will query the CB DS
  • if you set to VISA, the WL Sips server will query the VISA DS.

Analysing the response

Status Field name What to do
Card is 3-D Secure enrolled. redirectionStatusCode = 00 You must redirect the holder to their bank's ACS via the URL indicated in the redirectionUrl field (see next step).
Card is not 3-D Secure enrolled. redirectionStatusCode = 01 Proceed to step 5: authorisation request.
Technical error preventing the 3-D Secure process from running smoothly. redirectionStatusCode = 10, 80, 89, 99 Proceed to step 5: authorisation request.
Webshop is not enrolled in the 3-D Secure programme. responseCode = 40 Please contact Worldline 's technical support.
Transaction is not valid. redirectionStatus = 12 One or more data in the query is not correct. Check the errorFieldName field and correct the wrong value.
Card is not valid. redirectionStatus = 14 The details of the means of payment are not correct, go back to step 1 and ask the cardholder to enter their payment information again.
Duplicate transaction redirectionStatus = 94 The transactionReference field or the transactionId field is already used by another request for this webshop. Please submit the request again using another transaction ID.

Step 3: redirecting the customer to their bank's ACS

If the card is enrolled, you must redirect the customer to their bank's ACS URL that was retrieved in the previous step, in the redirectionUrl field. In the case of passive authentication, you must also perform this step, even if the client will not really be redirected to their bank's ACS.

Please refer to the POST form to the ACS section in the Sips Office JSON documentation to know how to implement this message.

Step 4: retrieving customer authentication data

At the end of the authentication process, the customer is redirected to your website using a HTTP redirection. The authentication result is retrieved through the PARes field.

Please refer to the POST form to the ACS section in the Sips Office JSON documentation to know how to implement this message.

If the customer quits the authentication process (closes their browser and is never redirected to your website), do not submit the authorisation request, do not ship the order.

Step 5: 3-D Secure authorisation request

Upon the customer's return to your e-commerce website after they have been authenticated (including for passive authentication), submit the 3-D Secure authorisation request via the cardValidateAuthenticationAndOrder method.

If the authentication of the client is failed, WL Sips does not send an authorization request to your acquirer, the payment is necessarily refused.

Setting the request

In a 3-D Secure context, apart from the mandatory method data, here is the request data you should pay attention to.

Field name Population rule
redirectionData Contains the payment transaction data. Please populate this field using the redirectionData field received as a response to the cardCheckEnrollment function.
transactionReference
or
Must be identical to the transactionReference or s10TransactionReference field submitted when calling the cardCheckEnrollment function.
paResMessage If you have redirected the holder to their bank's ACS, because their card is enrolled: please populate this field using the data from the PARes field received from the ACS.
If you have not redirected the holder to their bank's ACS, because their card is not enrolled, do not populate this field.
messageVersion Please populate this field using the messageVersion received as a response to the cardCheckEnrollment function
Analysing the response

The fields pertaining to 3-D Secure are:

Status Field name
Authenticated holder Cf. Analysing the response .
The cardholder was not able to authenticate themselves, or has cancelled on the ACS page, payment is univetably refused. Cf. Analysing the response .
Technical issue tht prevented the successful completion of the 3-D Secure authentication. Cf. Analysing the response .
paResMessage not correct.
This case may occur:
  • if the PARES message you submit is not strictly identical to the PARES received from the ACS (message is truncated for example)
  • if the carrier modified the PARES message on purpose before coming back to your site. This may amount to a fraud attempt. In that case, stop the purchasing process.
holderAuthentResponseCode = 95
3D session expired.
This case may occur if you submit the cardValidateAuthenticationAndOrder request more than 15 minutes after the cardCheckEnrollment request was processed.
holderAuthentResponseCode = 89

Payment from a customer ID (also called OneClick)

In this section, we do not describe the card registration phase, we assume the cardholder has already registered their card in the WL Sips wallet. Please refer to the OneClick documentation for more details on this phase.

Flows description

A 3-D Secure payment from a customer identifier is made in 4 steps:

  • authenticating your customer and the means of payment they select in their wallet
  • checking the selected card enrollment
  • redirecting the customer to their bank's ACS
  • the 3-D Secure authorisation request

Implementation

If your webshop is not a 3-D Secure one, please get in touch with the WL Sips technical support to activate the service.

To implement a 3-D Secure OneClick payment, you must implement the messages received and sent by the "E-commerce server" entity in the above chart.

Step 1: authenticating your customer and selecting their means of payment

You authenticate your customer to find the value of the corresponding merchantWalletId data.

You display them the list of means of payment included in their wallet. If you have not stored this list of means of payment in your information system, you can retrieve it calling a getWalletData request.

The customer selects the card means of payment of their choosing, which allows you to find the paymentMeanId data value.

Step 2: checking the selected card enrollment

You check the 3-D Secure enrollment of the card with the use of the walletCheckEnrolment function.

Setting the request

In a 3-D Secure context, apart from the mandatory method data, here is the request data you should pay attention to.

Field name Population rule
amount Payment amount. The amount is displayed on the holder authentication page.
captureDay Must be 6 or less.
If the value is greater than 6, the WL Sips server forces it to 6.
merchantName Shop name of your website that will be displayed on the authentication page of the holder's bank.
If not filled in, the name of your shop specified when your shop was registered on WL Sips will be displayed.
merchantReturnUrl Do not populate, this field is deprecated.
merchantUrl URL of your website that will be displayed on the authentication page of the holder's bank.
If not filled in, the URL of your shop specified when your shop when registered on WL Sips will be displayed.
merchantWalletId Value retrieved in the previous step.
paymentMeanId Value retrieved in the previous step.
orderChannel For payments made through the Internet, please set to INTERNET.

Analysing the response

Status Field name What to do
Card is 3-D Secure enrolled. redirectionStatusCode = 00 You must redirect the holder to their bank's ACS via the URL indicated in the redirectionUrl field (see next step).
Card is not 3-D Secure enrolled. redirectionStatusCode = 01 Proceed to step 5: authorisation request.
Webshop is not enrolled in the 3-D Secure programme. redirectionStatusCode = 40 Please contact Worldline 's technical support.
Technical error preventing the 3-D Secure process from running smoothly. redirectionStatusCode = 10, 80, 89, 99 Proceed to step 5: authorisation request.
Transaction is not valid. redirectionStatus = 12 One or more data in the query is not correct. Check the errorFieldName field and fix the wrong value.
Card is not valid. redirectionStatus = not filled in Ask your customer to select another means of payment or to enter a new means of payment.
Duplicate transaction redirectionStatus = 94 The transactionReference field or the transactionId field is already used by another request for this webshop. Please submit the request again using another transaction ID.

Step 3: redirecting the customer to their bank's ACS

Please refer to the same step of the Sips Office connector section.

Step 4: retrieving customer authentication data

Please refer to the same step of the Sips Office connector section.

Step 5: 3-D Secure authorisation request

Please refer to the very same step of the Sips Office connector section.

Payment from a token

In this section, we do not outline the card processing phase into a token, we assume the customer has already made a first payment and you have stored the token corresponding to their card number, as well as the card validity date.

Flows description

A 3-D Secure payment from a token is made in 4 steps:

  • retrieving the token and collecting the card secure code
  • checking the customer's card enrollment
  • redirecting the customer to their bank's ACS
  • the 3-D Secure authorisation request

Implementation

If your webshop is not a 3-D Secure one, please get in touch with the WL Sips technical support to activate the service.

To implement a 3-D Secure token payment, you must implement the messages received and sent by the "e-commerce server" entity in the above chart.

Step 1: authenticating your customer, retrieving their card token and collecting their secure code

You authenticate your customer to find the token and the validity date of their card, token and validity date that you previously stored when your customer made his first payment.

You also collect the customer's card secure code, asking them to enter that code.

Step 2: checking the selected card enrollment

You check the 3-D Secure enrollment of the card with the use of the cardCheckEnrollment function.

Setting the request

In a 3-D Secure context, apart from the mandatory method data, here is the request data you should pay attention to.

Field name Population rule
amount Payment amount. The amount is displayed on the holder authentication page.
captureDay Must be 6 or less.
If the value is greater than 6, the WL Sips server forces it to 6.
cardCSCValue Value retrieved in the previous step, entered by the customer.
cardExpiryDate Value retrieved in the previous step, stored in your information system beforehand.
cardNumber Card token.
merchantName Shop name of your website that will be displayed on the authentication page of the holder's bank.
If not filled in, the name of your shop specified when your shop was registered on WL Sips will be displayed.
merchantReturnUrl Do not populate, this field is deprecated.
merchantUrl URL of your website that will be displayed on the authentication page of the holder's bank.
If not filled in, the URL of your shop specified when your shop when registered on WL Sips will be displayed.
orderChannel For payments made through the Internet, please set to INTERNET.
panType TOKEN_PAN
paymentMeanBrand For co-branded cards (CB+VISA or CB+MASTERCARD), the value indicated determines which DS is chosen.
For example, for a CB+VISA co-branded card:
  • if you set to CB, the WL Sips server will query the CB DS
  • if you set to VISA, the WL Sips server will query the VISA DS

Analysing the response

Use case Response fields What to do
Card is 3-D Secure enrolled. redirectionStatusCode = 00 You must redirect the customer to their bank's ACS via the URL indicated in the redirectionUrl field (see next step).
Card is not 3-D Secure enrolled. redirectionStatusCode = 01 Proceed to step 5: authorisation request.
Webshop is not enrolled in the 3-D Secure programme. redirectionStatusCode = 40 Please contact Worldline 's technical support.
Technical error preventing the 3-D Secure process from running smoothly. redirectionStatusCode = 10, 80, 89, 99 Proceed to step 5: authorisation request.
Transaction is not valid. redirectionStatusCode = 12 One or more data in the query is not correct. Check the errorFieldName , field and fix the wrong value.
Token is unknown. redirectionStatusCode = 12 Check the cardNumber field.
Card has expired. redirectionStatusCode = 14 Ask again to your customer to select another means of payment or to enter a new means of payment.
Duplicate transaction. redirectionStatusCode = 94 The transactionReference field or the transactionId field is already used by another request for this shop. Please submit the request again using another transaction ID.
Detokenisation is down redirectionStatusCode = 99 This is possibly a one-time issue, please submit the request again. In the event of a further error, please stop the process. Then tell Worldline 's technical support about the incident.

Step 3: redirecting the customer to their bank's ACS

Please refer to the same step of the Sips Office connector section.

Step 4: retrieving customer authentication data

Please refer to the same step of the Sips Office connector section.

Step 5: 3-D Secure authorisation request

Please refer to the very same step of the Sips Office connector section.

Customer authentication uncoupled from payment (also called Authentication-only)

This paragraph describes how to implement 3-D Secure use cases requiring the authentication flow to be uncoupled from the payment flow.

Authentication processed by WL Sips and payment processed by another PSP

Flows description

Implementation

If your webshop is not a 3-D Secure one, please get in touch with the WL Sips technical support to activate the service.

To implement a 3-D Secure card payment in "authentication-only" mode, you must implement the messages received and sent by the "e-commerce server" entity in the above chart.

Step 1: collecting payment data

You collect the customer's card data (card number, validity date, security code). You must comply with the PCI DSS recommendations.

Step 2: checking the card enrollment via WL Sips
Setting the payment request

In a 3-D Secure context, apart from the mandatory method data, here is the request data you should pay attention to.

Field name Population rule
cardCSCValue Value retrieved in the previous step.
cardExpiryDate Value retrieved in the previous step.
cardNumber Value retrieved in the previous step.
merchantName Shop name of your website that will be displayed on the authentication page of the customer's bank.
If not filled in, the name of your shop specified when your shop was registered on WL Sips will be displayed.
merchantReturnUrl Do not populate, this field is deprecated.
merchantUrl URL of your website that will be displayed on the authentication page of the customer's bank.
If not filled in, the URL of your shop specified when your shop was registered on WL Sips will be displayed.
panType Please set to PAN.
paymentMeanBrand For co-branded cards (CB+VISA or CB+MASTERCARD), the value indicated determines which DS is chosen.
For example, for a CB+VISA co-branded card:
  • if you set to CB, the WL Sips server will query the CB DS.
  • if you set to VISA, the WL Sips server will query the VISA DS.
Analysing the response

Please refer to the Analysing the response part of the Sips Office connector section.

Step 3: redirecting the customer to their bank's ACS

Please refer to the same step of the Sips Office connector section.

Step 4: retrieving customer authentication data

Please refer to the same step of the Sips Office connector section.

Step 5: checking the authentication result

Please refer to the same step of the "Enrolling a card without making a payment" section.

Step 6: authorisation request to the other PSP

The 3-D Secure data are included in the response of the cardValidateAuthentication function called in the previous step:

  • If authentication was carried out using 3-D Secure v1, please refer to the authenticationData.threeD container.
  • If authentication was carried out using 3-D Secure v2, please refer to the authenticationData.threeDV2 container.

Authentication processed by another PSP and payment processed by WL Sips

Flows description

Implementation

To implement a 3-D Secure card payment in "authentication-only" mode, you must implement the messages received and sent by the "E-commerce server" entity in the above chart.

Step 1: collecting payment data

You collect the customer's card data (card number, validity date, security code). You must comply with the PCI DSS recommendations.

Step 2: authentication request to another PSP
Step 3: 3-D Secure authorisation request to WL Sips

When the customer is back on your e-commerce website following their authentication, forward the 3-D Secure authorisation request using the cardOrder function.

Setting the payment request

In a 3-D Secure context, apart from the mandatory method data, here is the request data you should pay attention to.

Field name Population rule
amount Must be the same as the authentication amount.
captureDay Must be 6 or less.
If the value is greater than 6, the WL Sips server forces it to 6.
cardCSCValue Filled in using the value retrieved in step 1. Must necessarily be filled in in the context of a 3-D Secure payment.
cardExpiryDate Filled in using the value retrieved in step 1.
cardNumber Filled in using the value retrieved in step 1.
orderChannel For payments made through the Internet, please set to INTERNET.
paymentPattern ONE_SHOT
panType PAN if you use the standard Sips Office connector.
CSE if you use the Sips Office connector in CSE mode.
paymentMeanBrand Filled in using the value retrieved in step 1.
If authentication was carried out with 3-D Secure v1.
authenticationData.threeD.cavv In case of a 3-D Secure v1 authentication, please populate using the respective value received in step 2.
authenticationData.threeD.cavvAlgorithm
authenticationData.threeD.eci In case of a 3-D Secure v1 authentication, please populate using the respective value received in step 2.
authenticationData.threeD.securityIndicator In case of a 3-D Secure v1 authentication, please populate using the respective value received in step 2.
authenticationData.threeD.txStatus In case of a 3-D Secure v1 authentication, please populate using the respective value received in step 2.
authenticationData.threeD.xid In case of a 3-D Secure v1 authentication, please populate using the respective value received in step 2.
If authentication was carried out with 3-D Secure v2.
authenticationData.threeDV2.cavv In case of a 3-D Secure v2 authentication, please populate using the respective value received in step 2.
authenticationData.threeDV2.cavvAlgorithm
authenticationData.threeDV2.securityIndicator In case of a 3-D Secure v2 authentication, please populate using the respective value received in step 2.
authenticationData.threeDV2.eci In case of a 3-D Secure v2 authentication, please populate using the respective value received in step 2.
authenticationData.threeDV2.txStatus In case of a 3-D Secure v2 authentication, please populate using the respective value received in step 2.
authenticationData.threeDV2.authentTransStatusReason In case of a 3-D Secure v2 authentication, please populate using the respective value received in step 2.
authenticationData.threeDV2.authentDsTransId In case of a 3-D Secure v2 authentication, please populate using the respective value received in step 2.
authenticationData.threeDV2.authentAmount In case of a 3-D Secure v2 authentication, please populate using the respective value received in step 2.
authenticationData.threeDV2.authentAcsTransId In case of a 3-D Secure v2 authentication, please populate using the respective value received in step 2.
authenticationData.threeDV2.authentDateTime In case of a 3-D Secure v2 authentication, please populate using the respective value received in step 2.
authenticationData.threeDV2.authentType In case of a 3-D Secure v2 authentication, please populate using the respective value received in step 2.
authenticationData.threeDV2.authentScoreValue In case of a 3-D Secure v2 authentication, please populate using the respective value received in step 2.
authenticationData.threeDV2.challengeMode3DS In case of a 3-D Secure v2 authentication, please populate using the respective value received in step 2.
authenticationData.threeDV2.authentCancelReason In case of a 3-D Secure v2 authentication, please populate using the respective value received in step 2.

Enrolling a card without making a payment

Flows description

Checking a card using the 3-D Secure process prior to this card being enrolled in the WL Sips wallet is a 4-step process:

  • checking the card enrollment
  • redirecting the customer to their bank's ACS to authenticate them
  • checking the 3-D Secure authentication
  • enrolling the card in the wallet if the authentication has suscceded

Implementation

If your webshop is not a 3-D Secure one, please get in touch with the WL Sips technical support to activate the service.

To implement a card 3-D Secure checking prior to the card being enrolled in a wallet, you must implement the messages received and sent by the "E-commerce server" entity in the above chart.

Step 1: collecting payment data

Please refer to the same step of the Sips Office connector section.

Step 2: checking the selected card enrollment

You check the 3-D Secure enrollment of the card with the use of the cardCheckEnrollment function.

Setting the request

In a 3-D Secure context, apart from the mandatory method data, here is the request data you should pay attention to.

Field name Population rule
amount Since there is no payment, you can set to 0.
cardCSCValue Value retrieved in the previous step.
cardExpiryDate Value retrieved in the previsous step.
cardNumber Value retrieved in the previous step.
merchantName Shop name of your website that will be displayed on the authentication page of the customer's bank.
If not filled in, the name of your shop specified when your shop was registered on WL Sips will be displayed.
merchantReturnUrl Do not populate, this field is deprecated.
merchantUrl URL of your website that will be displayed on the authentication page of the customer's bank.
If not filled in, the URL of your shop specified when your shop was registered on WL Sips will be displayed.
panType Please set to PAN.
paymentMeanBrand For co-branded cards (CB+VISA or CB+MASTERCARD), the value indicated determines which DS is chosen.
For example, for a CB+VISA co-branded card:
  • if you set to CB, the WL Sips server will query the CB DS.
  • if you set to VISA, the WL Sips server will query the VISA DS.
Analysing the response

Please refer to the Analysing the response part of the Sips Office connector section.

Step 3: redirecting the customer to their bank's ACS

Please refer to the same step of the Sips Office connector section.

Step 4: retrieving customer authentication data

Please refer to the same step of the Sips Office connector section.

Step 5: checking the authentication result

When the customer is back on your e-commerce website following their authentication, check their authentication result using the cardValidateAuthentication function.

Setting the request

In a 3-D Secure context, apart from the mandatory method data, here is the request data you should pay attention to.

Field name Population rule
redirectionData Contains the payment transaction data. Please populate this field using the redirectionData field received as a response to the cardCheckEnrollment function.
transactionReference
ou
Must be identical to the transactionReference or s10TransactionReference field submitted when calling the cardCheckEnrollment function.
paResMessage If you have redirected the holder to their bank's ACS, because their card is enrolled: please populate this field using the data from the PARes field received from the ACS.
If you have not redirected the holder to their bank's ACS, because their card is not enrolled, do not populate this field.
Analysing the response

Please refer to the Analysing the response part of the Sips Office connector section.

Use case Champs de la réponse
Authenticated holder

holderAuthentResponseCode = 00

  • connector version equal to or higher than 2.24
    • 3DS: the holder authenticated themselves using a 3-D Secure V1 process
    • 3DS_V2: the holder authenticated themselves using a 3-D Secure V2 process
  • connector version lower than 2.24
    • 3DS: the holder authenticated themselves using a 3-D Secure V1 or 3-D Secure V2 process
holderAuthentMethod =
  • connector version equal to or higher than 2.24
    • if process is 3-D Secure V1: NOT_SPECIFIED
    • if process is 3-D Secure V2: cf. Data dictionary .
  • connector version lower than 2.24
    • NOT_SPECIFIED: whatever the process
holderAuthentStatus = ATTEMPT or SUCCESS

if process is 3-D Secure V2 threeDv2.holderAuthentType = cf. dictionnaire des données
The cardholder was not able to authenticate themselves, or has cancelled on the ACS page

holderAuthentResponseCode = 01

holderAuthentProgram =
  • connector version equal to or higher than 2.24
    • 3DS: the holder attempted to authenticate themselves using a 3-D Secure V1 process
    • 3DS_V2: the holder attempted to authenticate themselves using a 3-D Secure V2 process
  • connector version lower than 2.24
    • 3DS: the holder authenticated themselves using a 3-D Secure V1 or 3-D Secure V2 process
holderAuthentMethod =
  • connector version equal to or higher than 2.24
    • if process is 3-D Secure V1: NOT_SPECIFIED
    • if process is 3-D Secure V2: cf. Data dictionary .
  • connector version lower than 2.24
    • NOT_SPECIFIED: whatever the process
if process is 3-D Secure V2 threeDv2.holderAuthentType = CHALLENGE
Technical issue that prevented the successful completion of the 3-D Secure authentication.

holderAuthentResponseCode = 02

holderAuthentProgram =
  • connector version equal to or higher than 2.24
    • 3DS: the holder authenticated themselves using a 3-D Secure V1 process
    • 3DS_V2: the holder authenticated themselves using a 3-D Secure V2 process
  • connector version lower than 2.24
    • 3DS: the holder authenticated themselves using a 3-D Secure V1 or 3-D Secure V2 process
holderAuthentMethod =
  • if process is 3-D Secure V1: NOT_SPECIFIED
  • if process is 3-D Secure V2: NOT_SPECIFIED
if process is 3-D Secure V2 threeDv2.holderAuthentType = CHALLENGE
paResMessage not correct.
This case may occur:
  • if the PARES message you submit is not strictly identical to the PARES received from the ACS (message is truncated for example)
  • if the carrier modified the PARES message on purpose before coming back to your site. This may amount to a fraud attempt. In that case, stop the purchasing process.
holderAuthentResponseCode = 95
3D session expired.
This case may occur if you submit the cardValidateAuthenticationAndOrder request more than 15 minutes after the cardCheckEnrollment request was processed.
holderAuthentResponseCode = 89
Step 6: adding the card to the wallet

If the customer is indeed authenticated, you can enroll their card in their wallet with the use of the addCard function. Please refer to the Sips Office documentation to know the implementation details for this function.

Sips Walletpage connector

Registering a subscriber's card

This section describes how to implement 3-D Secure to enroll a subscriber.

Flows description

  1. During your subscriber enrollment process, you redirect your subscriber to Sips Walletpage to have them register their payment details. The subscriber selects a means of payment, provides their payment details and confirms.
  2. WL Sips proceeds with the 3-D Secure checking.
  3. WL Sips performs the antifraud checks.
  4. WL Sips sends an authorisation request to the acquirer.
  5. In case the fraud checks are OK and the authorisation is accepted, WL Sips saves the data of the means of payment in the wallet.
  6. WL Sips displays the homepage featuring a confirmation message. From now on the subscriber can view their means of payment on the homepage.
  7. WL Sips sends back to you the manual and automatic responses containing the wallet content.

3-D Secure dynamic deactivation

If you are sure of your subscriber's identity because you have authenticated them beforehand, you can choose to dynamically bypass the 3-D Secure authentication.

To activate this option, you must first obtain the approval of your acquirer, then request activation from the technical support and set the fraudData.bypass3DS field to ALL. As a payment response, the holderAuthentStatus field will be set to BYPASS.

Implementation

If your webshop is not a 3-D Secure one, please get in touch with the WL Sips technical support to activate the service.

Setting the payment request

You do not have any specific 3-D Secure field to populate to offer 3-D Secure authentication via Sips Paypage . However, you must populate the fraudData.bypass3DS field if you would like to enable dynamic deactivation.

Field name Population rule
fraudData.bypass3DS ALL if you would like to deactivate 3-D Secure authentication when enrolling the customer's card.
Otherwise do not populate.

Please refer to the Sips Walletpage JSON guide to know how to populate the request depending on your business need.

Analysing the response

WL Sips sends back a manual response and a standard walletpage automatic response.There is no field pertaining to 3-D Secure authentication in a response from Sips Walletpage .

Strong authentication exemptions

Frictionless authentication description

The 3DSv2 protocol allows passive customer authentication, when the risk of fraud is low enough. This authentication type is also known as ‘ frictionless ’ authentication. When making a ‘ frictionless ’ payment, the transaction is authenticated indeed, but the customer is not solicited. In a frictionless case, an authentication cryptogram is provided by the issuer and transmitted in the authorisation request. The DSP2 differentiates between several exemption cases:

  • Exemptions for small amounts (<€30)
  • Exemptions following an acquirer transaction risk analysis (acquirer TRA)
  • Exemptions following an issuer transaction risk analysis (issuer TRA)
  • Exemptions in the context of a payment to a trusted recipient
  • Exemptions on the use of unnamed cards (cards granted to legal entities)

Frictionless payment operates in 2 ways:

Exemptions implementation

Exemption after risk analysis

You can request an exemption if your risk analysis shows that the risk of fraud is low enough to request a frictionless authentication. This case of derogation is called the Transaction Risk Analysis (TRA) acquirer. To take advantage of this functionality, you must request authorization from your acquirer, who will tell you how to use this exemption (maximum amount, rules to be applied in the event of changes over time, etc.).

Setting the request

Field Value setting
fraudData.challengeMode3DS NO_CHALLENGE_TRA_ACQ

Analysing the response

Use case Response fields Action to take
Exemption request granted by the issuer, the client is passively authenticated

holderAuthentType = FRICTIONLESS or DELEGATED_FRICTIONLESS

holderAuthentStatus = SUCCESS or ATTEMPT

authentExemptionReasonList = refer to Data Dictionary

Exemption request rejected by issuer, the client is strongly authenticated

holderAuthentType = CHALLENGE

holderAuthentStatus = SUCCESS or ATTEMPT

authentExemptionReasonList = not filed

Exemption request not authorized because right not allowed on WL Sips , the client is authenticated (in this case WL Sips force with a "basic" exemption request : fraudData.challengeMode3DS = NO_CHALLENGE) see next chapter Please contact WL Sips to add the right to use this feature

Other exemption request

If you do not have the right to use the acquirer TRA exemption, you can also request a basic exemption.

Setting the request

Champ Valorisation
fraudData.challengeMode3DS NO_CHALLENGE

Analysing the response

Use case Response fields Action to take
Exemption request granted by the issuer, the client is passively authenticated

holderAuthentType = FRICTIONLESS or DELEGATED_FRICTIONLESS

holderAuthentStatus = SUCCESS or ATTEMPT

AuthentExemptionReasonList = refer to Data Dictionary

Exemption request rejected by issuer, the client is strongly authenticated

holderAuthentType = CHALLENGE

holderAuthentStatus = SUCCESS or ATTEMPT

authentExemptionreasonList = not filled

Small amount exemption and TRA issuer exemption

Even if you do not explicitly request an exemption, the card issuer can grant an exemption in 2 other cases:

  • small amount payment, less than 30 €.
  • the risk analysis carried out by the issuer shows that the risk of fraud is sufficiently low

Setting the request

There is no specific data to send, however, in order to encourage obtaining an exemption, it is preferable to highlight the fields recommended by the scheme. Please refer to the next chapter .

Analysing the response

Use case Response fields Action to take
Exemption request granted by the issuer, the client is passively authenticated

holderAuthentType = FRICTIONLESS or DELEGATED_FRICTIONLESS

holderAuthentStatus = SUCCESS or ATTEMPT

authentExemptionreasonList = refer to Data Dictionary

Summary of 3-D Secure decision rules

Starting 3-D Secure in 4 steps

Step 1 - implementing the service

Depending on your use case, please follow the integration recommendations described in one of the previous chapters.

Step 2 - testing the service on the test environment

Once you have completed the WL Sips connectors implementation, you can perform tests to validate your WL Sips integration.

Sips Paypage connector

Test data
merchantId 201000076690001
Secret key p64ifeYBVIaRcjaWoahCiw9L8wokNLqG2_YOj_POD4g
Key version 1
Test cards Cf. the " Test cards " page

Sips Office connector

Test data
merchantId 201040040170001
Secret key rxSP61eeP_oNi5TxCD7Ngy9YcwC8MLw6OlmFGGcsY54
Key version 1
Test cards Cf. the " Test cards " page

Simulation ACS

During your tests and depending on the card used, you are redirected to our 3-D Secure v1 ACS simulator or our 3-D Secure v2 ACS simulator.

On the 3-D Secure v1 ACS simulation pages, you can simulate:

  • a successful authentication ( holderAuthentStatus = SUCCESS)
  • a failed authentication (holderAuthentStatus = FAILURE)
  • a technical error during the authentication phase ( holderAuthentStatus = ERROR)
  • a case where the holder did not have to authenticate themselves ( holderAuthentStatus = ATTEMPT)

On the 3-D Secure v2 ACS simulation pages, you can simulate:

  • a successful authentication ( holderAuthentStatus = SUCCESS)
  • a failed authentication ( holderAuthentStatus = FAILURE)
  • a technical error during the authentication phase ( holderAuthentStatus = ERROR)
  • a case where the holder did not have to authenticate themselves ( holderAuthentStatus = ATTEMPT)

Step 3 - subscribing to the production service

If your webshop has not yet been registered with the 3-D Secure service, you must make a request to your usual contact, indicating the means of payment the 3-D Secure service should be activated for (CB/VISA/MASTERCARD and/or AMEX).

For the CB scheme, the activation of the 3-D Secure option is almost immediate.

For the VISA, MASTERCARD and AMEX schemes, the activation of the 3-D Secure option is a 2-step process:

  • Step 1 = your webshop is enrolled on the VISA and MASTERCARD DS, or on the AMEX DS
  • Step 2 = the 3-D Secure option is activated once the enrollment on the DS is complete. For your information, VISA completes the enrollment in approximately 24 hours, MASTERCARD in 7 days, AMEX in 3 weeks.

Step 4 – starting and validating the production service

The 3-D Secure service activation is now up and running in production.

To make sure there is no regression, check the evolution of your conversion rate. The conversion rate is expected to decrease slightly, but if you notice a significant reduction in your conversion rate, quickly notify your usual contact so that they can diagnose the issue with you.