3D Secure

Under no circumstances should merchants store or log any credit card details unless they are fully PCI-DSS compliant.
This falls under your responsibility to ensure you do not produce code which circumvents our toolkits. We do not accept any liability for this.

 

3D Secure 2 (EMV 3D Secure)

3D Secure 2.0 (also known as EMV 3DS) is a new version of 3D Secure 1. 3D Secure 2.0 aims to improve the security and consumer experience, including helping merchants achieve Strong Customer Authentication (SCA) compliance under PSD2.

Under certain scenarios, transactions will fall-back to using a 3D Secure 1 payment flow, for as long as 3D Secure 1 is supported.

The Payment Services Directive (PSD2), has introduced a new regulatory requirement: Strong Customer Authentication (SCA). The aim of the SCA is to add an increased layer of security for card not present transactions, when making mobile and online payments.

 

For more information, see Integrating 3D Secure 2 (EMV 3D Secure).

 

The deadline for PSD2 and SCA implementation for all the European Union countries members and UK merchants has now passed.
From:
14th October 2022
Mastercard will stop supporting 3D Secure 1.
15th October 2022 VISA will stop supporting 3D Secure 1.

We have made it a simple implementation for you to upgrade to 3D Secure 2 within your payment flow. See Integrating 3D Secure 2 (EMV 3D Secure)

 

What is Strong Customer Authentication?

The Payment Services Directive (PSD2), has introduced a new regulatory requirement: Strong Customer Authentication (SCA). The aim of the SCA is to add an increased layer of security for card not present transactions, when making mobile and online payments.

 

To authenticate the transaction, merchants can verify the consumer's identity with the Issuer. To be compliant with SCA, 3D Secure 2 transactions have additional authentication and transaction information within the payment flow.

 

This new version of 3D Secure, offers a better user experience and helps to minimise some of the friction the authentication adds to the checkout flow.

SCA requires authentication to use at least two of the following three aspects:

  • Something the consumer knows.

    • For example, password or PIN.

  • Something the consumer has

    • For example, phone or hardware token.

  • Something the consumer is.

    • For example, fingerprint or face recognition.

 

Exemptions to Strong Customer Authentication

Merchants can request specific customer initiated transactions be exempt from Strong Customer Authentication (EMV 3D Secure). 

This has the benefit of reducing friction for your customers and related checkout dropouts.

Judopay will not currently automatically apply for transaction exemptions on behalf of the merchant.

 

Available Exemptions:

Low-Value Transactions:

Transactions up to £45 do not require SCA, up to a maximum of five consecutive transactions, or a cumulative limit of £100.

The consecutive transactions and cumulative limit are made up of all transactions against the card and not the merchant. When the limit is reached, the Issuer will request the consumer to be challenged, before authorising the transaction.

 

Low-Risk Transactions:

The Transaction Risk Analysis (TRA) exemption flag allows for certain remote transactions to be exempt from SCA, provided a robust risk analysis is performed.

 

Trusted Beneficiaries (Whitelisting):

This exemption flag gives the cardholder the option to add the merchant to their trusted list.

 

Secure Corporate Payments:

Request exemption for payments made using a corporate card.

 

Exemption Flags

Exemption flags provide you with the option to request the Issuer, to not challenge their customer at the time of the transaction.

Judopay has introduced the following exemption flags for you to add per transaction:

 

ChallengeRequestIndicator

Indicates the type of challenge request.

 

ScaExemption

The customer initiated transaction type, that is exempt from SCA.

This is subject to the Issuer’s decision; they do not have to honour this request and can reject authentication with a soft decline.
A soft decline is where the Issuer rejects the exemption and requests the customer be challenged for 3D Secure.

For more information, see Payment Flow.

 

Merchant Initiated Transactions

Merchant-Initiated-Transactions (MIT)s, (for example, subscription type payments, unscheduled transactions such as tips and an increase in taxi fares) are also impacted by SCA.

You need to tag your MIT/Recurring transactions correctly to ensure your transactions are not declined by your customers’ issuing bank.

 

Existing Agreements / Subscriptions

There may be cases where you have agreements/subscriptions agreed with customers previous to the SCA deadline.

These transactions still need to be tagged as MIT/Recurring and reference the first transaction's receipt ID for that card or a previous transaction's receipt ID.

The older the transaction referenced in the MIT, the more likely it will be accepted by the issuer (customers bank).

In the event that a customer's issuing bank declines a transaction with reason requiring authentication – you may need this customer to re-register their card through SCA.

 

New Agreements / Subscriptions

For new cards, you must ensure your customer goes through SCA when registering their card.

You must also store the card token and receipt ID returned by the API and/or SDK callbacks for future transactions.

Example Subscription Flow:

  1. Customer enters payment information

  2. Merchant makes a zero-authorisation to validate card with 3D Secure

  3. Customer completes 3D Secure

  4. Merchant stores Card Token, Consumer Reference and Receipt ID from the transaction response

  5. Future Recurring Payments should be tagged as Recurring and reference the stored information above, with the Receipt ID entered as the Related Receipt ID

 

You can find an example Recurring in our Transaction API Reference here.

(Select FollowOnScheduledRecurringPayment from the examples drop-down).

 

Varying Final Amount (Ride-sharing / Hospitality)

There are instances where the final amount may change, for example a taxi having to take a longer route, or a customer giving a tip after receiving their order.

If the customer is not able to go through SCA again, you will be able to create an MIT request for the additional amount.

 

Example MIT Flow:

  1. Customer enters payment information

  2. Merchant makes a pre-authorisation with 3D Secure for an estimated amount

  3. Customer completes 3D Secure

  4. Merchant stores Card Token, Consumer Reference and Receipt ID from the transaction response

  5. The total amount owed is more than the estimated amount previously pre-authorised

  6. Merchant collects amount pre-authorised previously

  7. Merchant makes MIT payment request for the surplus amount, tagged as MIT and references the stored information above, with the Receipt ID entered as the Related Receipt ID

 

You can find an example MIT request in our Transaction API Reference here.

(Select FollowOnMitPayment from the examples drop-down).

 

3D Secure 2 Flow

In the 3D Secure 2 payment flow, the Issuer will make a decision on whether they have enough authentication data to proceed with the transaction, or if they require the cardholder to further authenticate the transaction with additional Strong Customer Authentication (SCA) checks.

 

The following example takes you through the payment flow using paymentSession to authenticate the transaction.

 

 

Step

Description

Create a /paymentsession.

Use the reference returned from the response to populate the request header in Step 2.

Send the authorisation request with the /payments request header, populated with the reference received in the /paymentsession response.

This step:

  1. Checks if the card is enrolled to support 3D Secure 2.

  2. Gathers the Device and Card Details.

The response will determine whether:

  1. The consumer is challenged for additional information.

  2. The consumer is not challenged, the transaction continues and the consumer is re-directed to the outcome screen.

If the consumer is challenged in order to process the transaction, the 3D Secure 2 challenge screen is presented to the consumer to enter a code or password.

  1. You will be notified via your webhook URL when the consumer has successfully completed the challenge screen.

  2. Resume the transaction flow by calling the /resume3ds endpoint.

Authorisation complete.

The consumer is redirected to the outcome screen.

3D Secure 2 introduces frictionless authentication.

 

Overview of the Frictionless and Challenge Flow

The transaction to be approved without the need for the cardholder to enter additional authentication details.

The acquirer, issuer, and card scheme are able to exchange the necessary information in the background, using the device data.

 

Frictionless Flow:

 

Challenge Flow:

If additional SCA checks are required from the cardholder, the transaction will follow the challenge flow.

An iframe (or similar prompt) will be presented to the cardholder to input additional authentication (something the cardholder knows, has or is),

 

Integrating 3D Secure 2 (EMV 3D Secure)

 

We have made it a simple implementation for you to upgrade and integrate 3D Secure 2 within your payment flow. Use Judopay’s Web SDK for an even simpler integration for 3D Secure 2.
Only a few steps are needed to set up your integration, the SDK does the rest.

 

Make sure your account has 3D Secure enabled. Contact ​Customer Support​​ to set this up.

 

Payment Flow

 

 

3D Secure 2 Integration Steps

This guide will take you through the steps to perform 3D Secure 2 authentication and authorisation, when integrating directly with Judopay's REST API.

 

Prerequisite

For the back-end server integration, make use of our:

  • Server SDKs:

    • .NET (version 3.0.0 or higher)

    • PHP (version 5.5 or higher)

    to call our API or,

  • Call directly using JSON (version 6.0.0.0 or higher)

 

Step One: Create a Payment Request

Payments, PreAuths, CheckCard and RegisterCard are all supported.

 

Once you have the card details and device information from your client-side, your back-end server will need to make a payment request to Judopay's Transaction API.

 

The Cv2 is not stored by Judopay's Transaction API.
You will need to store the CV2 and the version for the duration of the transaction, then delete them as soon as the transaction has completed.

Storing the version will not be required in future updates.

For the full /payments endpoint schema details and descriptions, see our Transaction API Reference here.

 

Sample Request:

 

If no additional transaction checks are required, you will receive the usual paymentReceipt response.
If additional transaction checks are required, you will receive the challenge response.

 

Notification URLs

You will need to set up two endpoints for your client to receive event notifications from the Issuer's ACS:

  • 3DS Method Completion: Informs your client application that the ACS has completed device detail gathering.

    • methodNotifcationURL

  • ACS Challenge Completion: Informs your client application that the challenge has been completed by the customer.

    • challengeNotificationURL

Each endpoint should be configured to accept:

  • HTTP POST

  • Base64 encoded values

 

Step Two: (Conditional) - Device Detail Gathering

Some Issuer ACS’ support device data gathering.
Skip this step if no method URL is provided in the response from the API.

 

Check the response from Step One: Create a Payment Request

The following fields in the response will indicate if the device details have been requested by the issuer:

  • The result field: "Additional device data is needed for 3D Secure 2"

  • The message field: "Issuer ACS has requested additional device data gathering"

  • A methodURL will be returned in the response from the initial payment request.

In this instance, the following steps will need to be performed:

  1. Render a hidden iFrame on the client-side targeting the methodURL

 

Rendering a hidden iFrame example:

 

  1. POST the 3DS Method Data (md) object to it.

    The md is an encoded base 64 value containing the threeDSServerTransID and NotificationURL as JSON.

    (It is also returned in the Transaction API response from Step One: Create a Payment Request )

  2. Listen for the redirect of the methodNotificationUrl

 

We recommend you time-out after 10 seconds if you have not received a response from any NotificationURLs or rendered the methodURL from Step Two: (Conditional) - Device Detail Gathering .

 

Step Three: (Conditional) - Resume Transaction

Once the device details have been gathered, the 3D Secure authentication flow needs to be resumed.

  1. Render a hidden iFrame on the client-side targeting the methodNotificationURL

  1. Listen for the redirect of the methodNotificationUrl where the method completion message is received.

  2. Resume the 3D Secure flow by submitting the results of the device detail gathering.

 

For the full /resume3ds endpoint schema details and descriptions, see our Transaction API Reference here.

 

Sample Request:

 

methodCompletion value:

  • methodCompletion = Yes

    • If your client received a POST to the methodNotifcationURL

  • methodCompletion = No

    • If your client did NOT received a POST to the methodNotifcationURL

  • methodCompletion = Unavailable

    • If your client was unable to render the methodURL

 

Step Four: (Conditional) - Render Challenge Page

After you have resumed the transaction, check the response from Step Three: (Conditional) - Resume Transaction

Sample Response
{
    "challengeUrl": "https://mysampleapp/challenge/",
    "cReq": "ewo8fdhJKESWujmlpsalIiA6ICIwMSIKfQ",
    "version": "2.1.0",
    "receiptId": "123456789",
    "result": "Challenge completion is needed for 3D Secure 2",
    "message": "Issuer ACS has responded with a Challenge URL",
    "md": "zNkcy9tZXRob2ROb3RpZmljYXRp9ojhFSik9"
}

The following fields in the response will indicate if your customer's bank may want to challenge:

  • The result field: "Challenge completion is needed for 3D Secure 2"

  • The message field: "Issuer ACS has responded with a Challenge URL"

  • A challengeURL: to render the challenge page iFrame for your customer 

  1. Render the ChallengeURL for your customer to complete the challenge.

 

Rendering a hidden iFrame example:

 

  • Creq: Should be set to the cReq received in the response

  • threeDSSessionData: Can be set to contain any details you would like returned in the post.

  1. Listen for the redirect of the challengeNotificationUrl

 

Step Five: Complete 3DS

Upon receiving a POST back to the challengeNotificationUrl

  1. Send a request to Judopay's Transaction API to complete the transaction

    If no additional transaction checks are required, you will receive the usual paymentReceipt response.
    If additional transaction checks are required, you will receive the completion response

For the full /complete3ds endpoint schema details and descriptions, see our Transaction API Reference here.

 

Sample Request:

 

Judopay's Transaction API will respond with the both the:

  • Authentication

  • Authorisation status

of the transaction.

 

Integrating via Web Payments

If you are currently using Web Payments Version 1, simply amend the URL in the redirect from ‘v1’ to 'v2’.

For example:

Version 1:
"postUrl": "https://pay.judopay-sandbox.com/v1"
"reference": "yth67_82nhjmf903jnmaiine…"
Amended:
"postUrl": "https://pay.judopay-sandbox.com/v2",       
"reference": "yth67_82nhjmf903jnmaiine…"

For more details, see Web Payments Set Up.

 

Integrating via Web SDK

If you are currently using Web SDK Integration, we would recommend updating your integration to authenticate using Payment Session.

Simply:

  • Upgrade to the latest version (version 0.0.25 or higher)        

For more details, see Creating a Payment with the Web SDK.

 

Integrating via Mobile SDK