Target most up-to-date API base URL

For general information about 3-D Secure v2, check out our PSD2 guide.

Learn here how to implement 3-D Secure safely into the payment process.

Create Payment 3-D Secure v2 transaction flow

The transaction flow involves the following steps:

1. Your customer goes to your check-out pages and finalises the purchase on your payment page
2. You send us the order information and payment details via a Create Payment request, containing a number of additional parameters
3. You receive and response from our platform. Two scenarios are possible:
   
   • If the transaction goes via the frictionless flow, the response contains the standard parameters with the final transaction feedback as per the API reference documentation. This marks the end of the flow
   • If the transaction goes via the challenge flow, the response contains the additional field merchantAction=REDIRECT and the redirectData. The specific payment status Redirect (StatusCode=46) will also be included in the response
4. Redirect the cardholder to the URL included in the redirectData
5. The cardholder identifies herself/himself. Our system receives the result from the issuer
6. Based on the result, two scenarios are possible:
   
   • If the identification was unsuccessful, we redirect the cardholder to the returnUrl cardPaymentMethodSpecificInput.threeDSecure.redirectionData.returnURL, ending the flow. You can retrieve the result via feedback channels: webhooks events or Get Payment call
   • If the identification was successful, we submit the actual financial transaction to the acquirer to process the transaction. You can retrieve the payment result via feedback channels: webhooks events or Get Payment call. We redirect the card holder to the ReturnUrl cardPaymentMethodSpecificInput.threeDSecure.redirectionData.returnURL and depending on the payment result you should inform the cardholder on the status of the transaction.

7. If the transaction was successful, you can deliver the goods / services

Send 3-D Secure v2 request

To process transactions with 3-D Secure, send a set of mandatory, recommended and optional parameters to our platform.

Capture and send parameters

You need to capture the 3DS-specific mandatory / recommended / optional parameters on your payment page.
Find here a Javascript code block you can use to capture the browser information.

Find here a Javascript code block you can use to capture the browser information:

function createHiddenInput(form, name, value) 
{ 
	var input = document.createElement("input"); 
	input.setAttribute("type", "hidden"); 
	input.setAttribute("name", name); 
	input.setAttribute("value", value); 
	form.appendChild(input); 
} 
 
 
var myCCForms = document.getElementsByName("MyForm"); 
if (myCCForms != null && myCCForms.length > 0) 
{ 
	var myCCForm = myCCForms[0]; 
	createHiddenInput(myCCForm, "device.browserData.colorDepth", screen.colorDepth); 
	createHiddenInput(myCCForm, "device.browserData.javaEnabled", navigator.javaEnabled()); 
	createHiddenInput(myCCForm, "device.locale", navigator.language); 
	createHiddenInput(myCCForm, "device.browserData.screenHeight", screen.height); 
	createHiddenInput(myCCForm, "device.browserData.screenWidth", screen.width); 
	createHiddenInput(myCCForm, "device.timezoneOffsetUtcMinutes", new Date().getTimezoneOffset()); 
} 

Send these 3-D Secure-specific parameters along with the other Create Payment mandatory parameters. Our platform will process your request and provide you with a response.

Process platform response

If the transaction goes via the frictionless flow, the response contains the standard parameters with the final transaction feedback as per the API reference documentation. This marks the end of the flow.
If the transaction goes via the challenge flow, the response contains additional parameters. To roll out the authentication to your customers, you need process the additional data provided as described here:

If the identification was unsuccessful, we redirect the card holder to the returnURL cardPaymentMethodSpecificInput.threeDSecure.redirectionData.returnURL, ending the flow. You receive the result via Hosted Checkout mode feedback channels.

If the identification was successful, we submit the actual financial transaction to the acquirer.

You can retrieve the payment result via Direct feedback channels: webhooks events or Get Payment call. We redirect the card holder to the ReturnUrl and depending on the payment result you should inform the cardholder on the status of the transaction.

Use test cards

You can use the following test card to simulate a 3-D Secure registered card in our test environment:

Exclusions and exemptions for 3DSv2

Some transactions are excluded from SCA. If any of your transactions are among them, 3-D Secure will not be rolled out. For more information which type of transaction they are, consult our dedicated guide here. 

You can request to omit 3-D Secure in two ways

1. Authentication by selecting the appropriate values for cardPaymentMethodSpecificInput.challengeIndicator and cardPaymentMethodSpecificInput.threeDSecure.exemptionRequest
   

   Parameter	Values
   cardPaymentMethodSpecificInput.challengeIndicator	Data Type: String Values accepted: Possible values: no-preference - You have no preference whether to challenge the customer or not (default) no-challenge-requested - you prefer the cardholder not to be challenged challenge-requested - you prefer the customer to be challenged challenge-required - you require the customer to be challenged no-challenge-requested-risk-analysis-performed – letting the issuer know that you have already assessed the transaction with fraud prevention tool no-challenge-requested-data-share-only – sharing data only with the DS no-challenge-requested-consumer-authentication-performed – authentication already happened at your side – when login in to your website no-challenge-requested-use-whitelist-exemption – cardholder has whitelisted you at with the issuer challenge-requested-whitelist-prompt-requested – cardholder is trying to whitelist you request-scoring-without-connecting-to-acs – sending information to CB DS for a fraud scoring
   cardPaymentMethodSpecificInput.threeDSecure.exemptionRequest	Data Type: String Possible values: none = No exemption requested transaction-risk-analysis = Fraud analysis has been done already by your own fraud module and transaction scored as low risk low-value = Below 30 euros whitelist = The cardholder has whitelisted you with their issuer

   Check property payment.paymentOutput.CardPaymentSpecificOutput.threeDSecureResults.appliedExemption in our server response  to see if the issuer has granted the exemption. However, you will loose the liability shift in a case of a fraudulent transaction

2. Authorisation by selecting the appropriate cardPaymentMethodSpecificInput.threeDSecure.exemptionRequest and cardPaymentMethodSpecificInput.threeDSecure.skipAuthentication
   To skip 3-D secure altogether, send the following parameters:
   
   

   Parameter	Values
   cardPaymentMethodSpecificInput.threeDSecure.skipAuthentication	true = Skip 3-D Secure false = Do not skip 3-D Secure
   cardPaymentMethodSpecificInput.threeDSecure.exemptionRequest	Data Type: String Possible values: none = No exemption requested transaction-risk-analysis = Fraud analysis has been done already by your own fraud module and transaction scored as low risk low-value = Below 30 euros whitelist = The cardholder has whitelisted you with their issuer

   
   However, it is still up to the issuer whether an authentication process must take place. In case the issuer insists on 3DS, the transaction will be declined with error code 40001139.
   If transaction is accepted without 3-D Secure, you will loose the liability protection.
   
   
   When your customers are setting up a new recurring payment with you, under the PSD2 rules, the first transaction always have to be strongly authenticated. Submit all the relevant 3DS parameters, COF parameters together with cardPaymentMethodSpecificInput.challengeIndicator=challenge-requested. This will make sure that the issuer is aware of this request and will approve the transaction

Frictionless / challenge flow

If you do not want to request an exemption but rely on the issuers rolling out a frictionless flow and keep your liability protection, send some additional parameters.
Sending these parameters for these schemes raise the chance for a frictionless flow:

• Carte Bancaire (if you are on low risk merchant program, they are strongly required)
  order.customer.billingaddress.city
  order.customer.billingaddress.countrycode
  order.customer.billingaddress.street
  order.customer.billingaddress.zip
  order.customer.contactDetails.emailaddress
  order.customer.contactDetails.phoneNumber
  order.shipping.addressIndicator
  fraudFields.customerIpAddress
  
  
• Visa/MasterCard
  order.customer.billingaddress.city
  order.customer.billingaddress.countrycode
  order.customer.billingaddress.street
  order.customer.billingaddress.zip
  order.customer.contactDetails.emailaddress
  order.customer.contactDetails.phoneNumber
  order.additionalInput.Shipping.addressIndicator
  fraudFields.customerIpAddress

You can even increase the chance of a frictionless flow and a higher conversion rate by sending more optional parameters.