WL SIPS DOCS

Release 21.4

go directly to content
Search by keywords

3-D Secure

To search in the page use Ctrl+F on your keyboard

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, Bancontact and AMEX means of payment up to the production start.

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, Bancontact and AMEX means of payment.

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

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

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, MASTERCARD and Bancontact schemes. If the payment is guaranteed, the guaranteeIndicator field is set to Y.

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.

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.

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.

With 3-D Secure V2 and to be compliant with PSD2 :

  • payment in instalments must be set up with an authentication of an amount equals to the global order amount (with 3-D Secure V1, the authenticated amount was set to the first instalment only).
  • payment to set up a subscription must be authenticated with an amount equals to the average recurring payments.
Note: WL Sips allows you to specify a different amount than the one to authorise, through the use of the authenticationData.authentAmount field.

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 enrollment on DS is completed. For your information, VISA will enroll you in approximately 24 hours, MASTERCARD in 7 days, AMEX in 3 weeks.

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.

With the application of PSD2, you have the obligation to request a strong customer authentication when your customers initate payment in instalments. The field paymentPattern needs to be set to the appropriate value (INSTALMENT).

To be compliant with PSD2, when setting up a payment in instalments, you must request an authentication of the global order amount.

WL Sips allows you to request a specific amount to authenticate that could be different from the amount to pay to be compliant with PSD2. It can be done with the field authenticationData.authentAmount.

If you use Sips Paypage connector to handle these payments in instalments, your request has to contain all instalment details (see container instalmentData). Therefore, you do not have to specify the amount to authenticate because Sips Paypage is able to set the appropriate amount and the necessary details for this type of payment.

If you use Sips Office or Sips In-App connectors to handle these payments in instalments, your request has to contain the amount to authenticate, the amount to pay on the first instalment but also some details that are necessary to authenticate a payment in instalments. If we take the example of a payment in instalments of a total amount of €400.00, with 4 monthly instalments of €100.00 each, you have to set the following fields :

With the application of PSD2, you have the obligation to request a strong customer authentication when your customers initate recurring payments or payment in instalments. The field paymentPattern needs to be set to the appropriate value (RECURRING_1).

When setting up a subscription, you must request an authentication of the average recurring amount.

WL Sips allows you to request a specific amount to authenticate that could be different from the amount to authorize to be compliant with PSD2 on those terms of payments. It can be done with the field authenticationData.authentAmount.

Note: An authorisation amount of 0 € (amount=0) for the first payment is possible (in case for exemple of the free first month) via the Sips Office and Sips Paypage connectors. An information request is then made in order to verify the card information.

If we take the example of a subscription to 15€ phone plan with a discount for the first payment to 1€, you have to set the following fields :

  • Field amount must be set to the amount to pay for the first payment (100 here for 1€);
  • Field authenticationData.authentAmount must be set to the average recurring amount (1500 here for 15€).
Note: The amount indicated in the authenticationData.authentAmount field has to be superior thant the authorisation amount indicated in the amount field. If the authenticationData.authentAmount field is not populated, then the 3-D Secure authentication will be made on the amount indicated in the amount field.

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.

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

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


flux-paypage-en

  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.

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, Mastercard and Bancontact 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 or WIP_BANCONTACT for OneClick Bancontact 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.

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

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.

WIP_BANCONTACT if you wish to deactivate the 3-D Secure authentication for a OneClick Bancontact 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.

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

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

PaiementCarteViaSipsOffice-en

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.

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

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

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.
Status Field name What to do
Card is 3-D Secure enrolled.

responseCode = 00

redirectionStatusCode = 00
You must redirect the cardholder to their bank's ACS via the URL indicated in the redirectionUrl field (see next step).
Card is not 3-D Secure enrolled.

responseCode = 00

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.

responseCode = 00

redirectionStatusCode = 12
One or more data in the request is not correct. Check the errorFieldName field and fix the incorrect value.
Card is not valid. redirectionStatusCode = 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.
Secret key or key version is not valid

responseCode = 34

redirectionStatusCode = 34
Check the secret key used (field secretKey) and the key version (field keyVersion)
WL Sips server temporairement indisponible responseCode = 99 You can submit the request a second time. If the error persists, notify Worldline Technical Support.

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

At the end of the authentication process, the customer is redirected to your website using an 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 cancels the authentication process (closes their browser and is never redirected to your website), do not submit the authorisation request, do not ship the order.

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 authorisation request to your acquirer, the payment is necessarily refused.

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 cardholder to their bank's ACS, because their card is enrolled: please populate this field using the data from the PARes field, previously URL encoded, received from the ACS.
If you have not redirected the cardholder 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

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
Secret key or key version is not valid responseCode = 34
Operation already performed on this transaction. responseCode = 24

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.

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

PaiementOneClickViaSipsOffice-en

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.

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.

For the CB/VISA/MASTERCARD network's payment means, the CSC entry is not mandatory in case of strong authentication. The next step "Step 2: checking the selected card enrollment" details how to make sure that the selected card is eligible for strong authentication. We assume that your acquirer supports this feature (feel free to contact the support teams for more information).

Note: Payments processed without strong authentication and without CSC will end with a refusal status and an associated responseCode = 12. It's up to you to retry the payment with asking beforehand the customer his card security code

For all other payment means, and the payments not processed into a 3D secure context, you must collect the customer's card security code.

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

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.
Status Field name What to do
Card is 3-D Secure enrolled.

responseCode = 00

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.

responseCode = 00

redirectionStatusCode = 01
Proceed to step 5: authorisation request.
Webshop is not enrolled in the 3-D Secure programme.

responseCode = 40

redirectionStatusCode = 40
Please contact Worldline's technical support.
Technical error preventing the 3-D Secure process from running smoothly. redirectionStatusCode = 10, 80, 89 Proceed to step 5: authorisation request.
Transaction is not valid.

responseCode = 12

redirectionStatus = 12
One or more data in the query is not correct. Check the errorFieldName field and fix the wrong value.
Expired card

responseCode = 54

redirectionStatus = not filled in
Ask your customer to select another means of payment or to enter a new means of payment.
Secret key or key version is not valid responseCode = 34 Check the secret key used (field secretKey) and the key version (field keyVersion)
WL Sips Server temporarly unavailable responseCode = 99 You can submit the request a second time. If the error persists, please notify Worldline Technical Support

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

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

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

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.

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

PaiementTokenViaSipsOffice-en

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.

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.

On an kinematic using a card token, you are not obliged to ask your customer's card security code in case of a strong authentication. The following step "Step 2: checking the selected card enrollment" details how to make sure that the selected card is eligible for strong authentication. We assume that your acquirer supports this feature (feel free to contact the support teams for more information).

Note: Payments processed without strong authentication and without CSC will end with a refusal status and an associated responseCode = 12. It's up to you to retry the payment with asking beforehand the customer his card security code

For all other payment means, and the payments not processed into a 3D secure context, you must collect the customer's card security code.

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

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

When you receive the response, before analyzing it and following the advice in the table below, check the seal. The recalculated seal must be identical to the seal received.

Use case Response fields What to do
Card is 3-D Secure enrolled.

responseCode = 00

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.

responseCode = 00

redirectionStatusCode = 01
Proceed to step 5: authorisation request.
Webshop is not enrolled in the 3-D Secure programme.

responseCode = 40

redirectionStatusCode = 40
Please contact Worldline's technical support.
Technical error preventing the 3-D Secure process from running smoothly. redirectionStatusCode = 10, 80, 89 Proceed to step 5: authorisation request.
Transaction is not valid.

responseCode = 12

redirectionStatusCode = 12
One or more data in the query is not correct. Check the errorFieldName, field and fix the wrong value.
Token is unknown.

responseCode = 14

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.
Secret key or key version is not valid

responseCode = 34

redirectionStatusCode = 34
Check the secret key used (field secretKey) and the key version (field keyVersion)
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.

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

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

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

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


AuthenticationOnlyAuthentSips-en

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.

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

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.

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

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

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

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

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 authenticationResult.threeD container.
  • If authentication was carried out using 3-D Secure v2, please refer to the authenticationResult.threeDV2 container.

AuthenticationOnlyAutorSips-en

When using this integration mode, WL Sips does not process cardholder authentication and therefore, cannot decide if 3-D Secure Liability Shift is applicable. Field guaranteeIndicator will be empty regardless of the authentication and authorization results.

When processing the authorization, WL Sips considers that you checked authentication result and that you wish to proceed further with the payment. Specific rules (such as 3D_ERROR automatic refusal, refusal of transaction without liability shift) that could be enabled on WL Sips to block payments depending on authentication result are ignored on this integration mode.

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.

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

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

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
authenticationResult.holderAuthentProvider Must be set to 2 (other PSP)
amount Amount to authorize.
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 or RECURRING_1
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.
authenticationResult.threeD.cavv To be populated with value of protocol field "cavv" received in step 2.
authenticationResult.threeD.cavvAlgorithm To be populated with value of protocol field "cavvAlgorithm" received in step 2.
authenticationResult.threeD.eci To be populated with value of protocol field "eci" received in step 2.
authenticationResult.threeD.txStatus To be populated with value of protocol field "status" received in step 2.
Specific case for cards not enrolled to 3-D Secure 1.0 : in this case only, value can be set to "9" (card not enrolled).
authenticationResult.threeD.xid To be populated with value of protocol field "xid" received in step 2.
If authentication was carried out with 3-D Secure v2.
authenticationResult.threeDV2.cavv To be populated with value of protocol field "authenticationValue" received in step 2.
authenticationResult.threeDV2.cavvAlgorithm To be populated with value of message extension "CB-AVALGO" received in step 2 (required only when authentication was processed using FAST'R by CB).
authenticationResult.threeDV2.eci To be populated with value of protocol field "eci" received in step 2.
authenticationResult.threeDV2.txStatus To be populated with value of protocol field "transStatus" received in step 2.
authenticationResult.threeDV2.authentTransStatusReason To be populated with value of protocol field "transStatusReason" received in step 2.
authenticationResult.threeDV2.authentAcsTransId To be populated with value of protocol field "acsTransID" received in step 2.
authenticationResult.threeDV2.authentDsTransId To be populated with value of protocol field "dsTransID" received in step 2.
authenticationResult.threeDV2.authentThreedsServerTransId To be populated with value of protocol field "threeDSServerTransID" received in step 2.
authenticationResult.threeDV2.authentAmount To be populated with value of protocol field "purchaseAmount" set by PAT in charge of processing the authentication at step 2.
authenticationResult.threeDV2.authentDateTime To be populated with value of protocol field "purchaseDate" set by PAT in charge of processing the authentication at step 2.
authenticationResult.threeDV2.holderAuthentType To be set accordingly to the authentication mode during step 2 (Challenge or Frictionless).
authenticationResult.threeDV2.authentScoreValue To be populated with value of message extension "CB-SCORE" received in step 2 (required only when authentication was processed using FAST'R by CB).
authenticationResult.threeDV2.challengeMode3DS To be populated depending on procotol field "threeDSRequestorChallengeInd" (merchant requested challenge mode) set by PAT in charge of processing the authentication at step 2.
authenticationResult.threeDV2.authentCancelReason To be populated with value of protocol field "challengeCancel" received in step 2.
authenticationResult.threeDV2.authentDSMerchantName To be populated with your commercial name. It should be the same that was used during authentication at step 2 (only required for CB payments).
authenticationResult.threeDV2.authentExemptionReasonList To be populated with respective value received in step 2 (only required if authentication mode is frictionless).
authenticationResult.threeDV2.authentMessageVersion To be populated with the version of the EMV 3-D Secure protocol used in step 2 (example 2.1.0).
authenticationResult.threeDV2.authentACSMethod To be populated with value of protocol field "authenticationMethod" received in step 2.
Use case Response fields
Payment is accepted responseCode = 00
guaranteeIndicator Not provided.
authentRelegationCode Set to Y if issuer rejects liability shift, N otherwise.
Secret key or key version is not valid responseCode = 34
Payment is declined responseCode <> 00

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

EnrolementSansPaiement-en

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.

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

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

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.

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

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

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

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

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, previously URL encoded, 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.

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

Use case Champs de la réponse
Authenticated holder responseCode = 00

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. data dictionnary
The cardholder was not able to authenticate themselves, or has cancelled on the ACS page

responseCode = 00

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.

responseCode = 00

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
Secret key or key version is not valid responseCode = 34
Usage of the cardValidateAuhtentication not allowed on this webshop
Contact the technical support
responseCode = 40

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.

A 3-D Secure payment is a 3-step process:

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

PaiementCarteViaSipsInApp-en

If your shop does not have 3-D Secure authentication, please contact the WL Sips technical support to activate the service.

In order to accept a 3-D Secure card payment, you have to implement the messages received and transmitted by the entities named "E-Commerce Server" and "Mobile App" in the diagram above.

You can initialise the payment using the orderInitialize method.

In a 3-D Secure context, besides the mandatory method data, here are the request data you need to pay attention to.

Field name Sample field population
amount Amount of payment. The amount is displayed on the customer authentication page.
captureDay Must be less than or equal to 6. If the value is larger than 6, the WL Sips server forces it to 6.
orderChannel Payments made by Internet must be populated with INTERNET.
sdkOperationName THREEDSECUREANDORDER
Use case Response fields Action to take
Successful initialisation of the payment redirectionStatusCode = 00 You display the payment data collection screen in your mobile application. You transmit the data necessary for the payment to be processed to the mobile application:
Invalid initialisation request redirectionStatusCode = 12, 30 One or more data in the request are not correct. Check the redirectionStatusMessage field and fix the incorrect value.
WL Sips server temporarily unavailable redirectionStatusCode = 99 Resubmit the request. If the issue lasts, please alert Worldline's technical support.
Duplicated transaction redirectionStatusCode = 94 The transactionReference or the transactionId is already used by another request from your shop. Resubmit the request with another transaction reference.

You can collect the cardholder's card data (card number, validity date, security code) via your mobile application.

You can check the 3-D Secure enrollment of the card using the SDK cardCheckEnrollment function.

In a 3-D Secure context, besides the mandatory method data, here are the request data you need to pay attention to.

Field name Sample field population
cardCSCValue Value retrieved in the previous step.
cardExpiryDate Value retrieved in the previous step.
cardNumber Value retrieved in the previous step.
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.
Use case Response fields 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 6: authorisation request.
Technical error preventing the 3-D Secure process from running smoothly. redirectionStatusCode = 10, 80, 89, 99 Proceed to step 6: authorisation request.
Webshop is not enrolled in the 3-D Secure programme. responseCode = 40 Please contact Worldline's technical support.
Transaction is not valid. redirectionStatusCode = 12 One or more data in the request is not correct. Check the errorFieldName field and fix the incorrect value.
Card is not valid. redirectionStatusCode = 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.

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 authentRedirectionUrl field. In the case of passive authentication, you must also perform this step, even if the customer will not really be redirected to their bank's ACS.

Please refer to the paragraph relating to the redirection to the ACS of the Sips In-App documentation to know how to implement this message.

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

Please refer to the paragraph back from the ACS of the Sips Office JSON documentation to know how to implement this message.

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

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 customer has failed,WL Sips does not send an authorisation request to your acquirer, the payment is necessarily refused.

In a 3-D Secure context, besides the mandatory method data, here are the request data you need to pay attention to.

Field name Population rule
paResMessage If you have redirected the cardholder to their bank's ACS, because their card is enrolled: please populate this field using the data from the paResMessage field, previously URL encoded, received from the ACS.
If you have not redirected the cardholder to their bank's ACS, because their card is not enrolled, do not populate this field.

Please refer to the Sips In-App documentation.

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.

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

PaiementOneClickviaSipsInApp_en

If your shop does not have 3-D Secure authentication, please contact the WL Sips technical support to activate the service.

In order to accept a 3-D Secure card payment, you have to implement the messages received and transmitted by the entities named "E-Commerce Server" and "Mobile App" in the diagram above.

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.

For the CB/VISA/MASTERCARD network's payment means, the CSC entry is not mandatory in case of strong authentication. The next step "Step 2: checking the selected card enrollment" details how to make sure that the selected card is eligible for strong authentication. We assume that your acquirer supports this feature (feel free to contact the support teams for more information).

Note: Payments processed without strong authentication and without CSC will end with a refusal status and an associated responseCode = 12. It's up to you to retry the payment with asking beforehand the customer his card security code

For all other payment means, and the payments not processed into a 3D secure context, you must collect the customer's card security code.

Besides mandatory request data, here is the request data that you need to pay attention to:

Field name Population rule
merchantWalletId Wallet Id of the customer
sdkOperationName GETWALLETDATA
Status Field name What to do
Wallet Initialize success redirectionStatusCode = 00 You transmit the data necessary for the payment to be processed to the mobile application:
Invalid wallet initialisation request redirectionStatusCode = 12, 30 One or more data in the request are not correct. Check the redirectionStatusMessage field and fix the incorrect value.
WL Sips server temporarily unavailable redirectionStatusCode = 99 Resubmit the request. If the issue lasts, please alert Worldline's technical support.

The data returned in the walletInitialize response are sent to the getWalletData request

Use case Response fields Action to take
Successful initialisation of the payment redirectionStatusCode = 00 You display the list of payment means returned:
Wallet not found inAppResponseCode = 25 Check the value of merchantWalletId

To initialize the payment you have to call the orderInitialize method.

In a 3-D Secure context, besides the mandatory method data, here are the request data you need to pay attention to.

Field name Sample field population
amount Payment amount. The amount is displayed on the holder authentication page.
merchantWalletId Value retrieved in the previous step.
sdkOperationName THREEDSECUREANDWALLETORDER
Use case Response fields Action to take
Successful initialisation of the payment redirectionStatusCode = 00 You display the payment data collection screen in your mobile application. You transmit the data necessary for the payment to be processed to the mobile application:
Invalid initialisation request redirectionStatusCode = 12, 30 One or more data in the request are not correct. Check the redirectionStatusMessage field and fix the incorrect value.
WL Sips server temporarily unavailable redirectionStatusCode = 99 Resubmit the request. If the issue lasts, please alert Worldline's technical support.
Duplicated transaction redirectionStatusCode = 94 The transactionReference or the transactionId is already used by another request from your shop. Resubmit the request with another transaction reference.

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

In a 3-D Secure context, besides the mandatory method data, here are the request data you need to pay attention to.

Field name Sample field population
paymentMeanId Value retrieved in the previous step.
Use case Response fields 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 6: authorisation request.
Technical error preventing the 3-D Secure process from running smoothly. redirectionStatusCode = 10, 80, 89, 99 Proceed to step 6: authorisation request.
Webshop is not enrolled in the 3-D Secure programme. responseCode = 40 Please contact Worldline's technical support.
Transaction is not valid. redirectionStatusCode = 12 One or more data in the request is not correct. Check the errorFieldName field and fix the incorrect value.
Card is not valid. redirectionStatusCode = 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.
Wallet or payment mean not found. redirectionStatusCode = 25 One or more data in the request is not correct. Check the errorFieldName field or the errorFieldName field and fix the incorrect value.

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 authentRedirectionUrl field. In the case of passive authentication, you must also perform this step, even if the customer will not really be redirected to their bank's ACS.

Please refer to the paragraph relating to the redirection to the ACS of the Sips In-App documentation to know how to implement this message.

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

Please refer to the paragraph back from the ACS of the Sips Office JSON documentation to know how to implement this message.

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

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 customer has failed,WL Sips does not send an authorisation request to your acquirer, the payment is necessarily refused.

In a 3-D Secure context, besides the mandatory method data, here are the request data you need to pay attention to.

Field name Population rule
paResMessage If you have redirected the cardholder to their bank's ACS, because their card is enrolled: please populate this field using the data from the paResMessage field, previously URL encoded, received from the ACS.
If you have not redirected the cardholder to their bank's ACS, because their card is not enrolled, do not populate this field.

Please refer to the Sips In-App documentation.

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


flux-walletpage-en

  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.

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.

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

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.

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.

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:

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.), and ask your usual contact to activate the "TRA acquirer" option.

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

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

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


frictionless-en

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

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

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

Server test URL
Paypage POST https://payment-webinit.test.sips-services.com/paymentInit
Paypage JSON https://payment-webinit.test.sips-services.com/rs-services/v2/paymentInit
Paypage SOAP https://payment-webinit.test.sips-services.com/services/v2/paymentInit
Test data
merchantId 201040040170001
Secret key rxSP61eeP_oNi5TxCD7Ngy9YcwC8MLw6OlmFGGcsY54
Key version 1
Test cards Cf. the "Test cards" page

Server test URL
Office https://office-server.test.sips-services.com

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)

ecranACSSimu3DSv1

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)

ecranACSSimu3DSv2

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.

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.

This site uses cookies to improve your experience, perform analysis and researches on your use of WL Sips documentation website.
You have several options:
Closing this banner you refuse the use of cookies on your device.

Configuration