Ingenico Direct Support Site

Results for

icon-search-large No search results yet
Enter your search query above

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.

2'. Optional: We perform a Fraud check 

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

IntegrateWithS2S-3DSflow.png

This graph describes the Create Payment + Fraud transaction flow.

Whether a liability shift applies or not if 3-D Secure is not rolled out, depends on your acquirer contract. Therefore, we recommend you check the terms and conditions with your acquirer.

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:

Parameter Values
payment.status REDIRECTED
merchantAction.actionType REDIRECT
merchantAction.redirectData.RETURNMAC A Message Authentication Code (MAC) is used to authenticate the redirection back to merchant after the payment
merchantAction.redirectData.returnURL The URL that the customer should be redirected to. Be sure to redirect using the GET method

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

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
More test cards numbers can be downloaded here.

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 PSD2. If any of your transactions are among them, 3-D Secure will not be rolled out.

Frictionless / challenge flow and indication of preferred flow

The below parameters are mandatory (in case for a preference for a specific flow).

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

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

Exemptions of 3DS

To skip 3-D secure altogether, send the following parameters:

Parameter Values
SkipAuthentication

Data Type: Boolean
Values accepted:
true
false

Possible values:

  • true: 3D Secure authentication will be skipped for this transaction. This setting should be used when isRecurring is set to true and recurringPaymentSequenceIndicator is set to recurring.
  • false: 3D Secure authentication will not be skipped for this transaction

This is option is only available if your account in our system is setup for 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.

Transactions for which 3-D secure should be skipped can only be processed as authorisations (which will end up in status Pending Capture if they are successful). To receive the funds for these transactions, you will have to capture them at a later point. Successfully captured transaction will reach status Captured.