Integrate with Hosted Checkout Page
Target most up-to-date API base URL
To allow you a smooth transition, previous API base URLs remain available until further notice.
An important part of the transaction processing flow for your customer is the 3-D Secure (3DS). There is no effort for you involved, except having 3DS active on all your card payment methods, and we will take care of everything necessary
Following the introduction of 3DSv2 , new rules apply. Although we collect all relevant data for you during the payment process, you can still make the 3DSv2 approach to risk evaluation more effective. You can achieve this by sending additional parameters along with the transaction.
Have a look on the recommended and optional parameters for a typical transaction request.
Use test cards
You can use the following test card to simulate a 3-D Secure registered card in our test environment:
Frictionless flow | |
Brand | Card number / Expiry date |
Visa | 4186455175836497 / Any date in the future |
MasterCard | 5137009801943438 / Any date in the future |
American Express | 375418081197346 / Any date in the future |
Challenge Flow | |
Brand | Card number / Expiry date |
Visa | 4874970686672022 / Any date in the future |
MasterCard | 5130257474533310 / Any date in the future |
American Express | 379764422997381 / Any date in the future |
If a transaction is blocked due to incorrect identification, the transaction result will be:
Status= Rejected
statusCode=2
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
- 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
- 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 SecurecardPaymentMethodSpecificInput.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.