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)

The following 3D Secure 2 versions are supported:
- 3DS2.1
- 3DS2.2

The deadline for PSD2 and SCA implementation for all the European Union countries members and UK merchants has now passed.
3D Secure 1 is no longer supported.

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.

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 card holder 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 the card holder 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:

  • No Preference

  • No Challenge

  • Challenge Preferred

  • Challenge As Mandate

For more information on each type of challenge request, see .

• ScaExemption

  The Customer-Initiated-Transaction (CIT) 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 card holder be challenged for 3D Secure.

For more information, see Payment Flow.

What Device Data is being Collected?

We have implemented the (EMV) 3DS2 protocol and collect the recommended 150 data elements detailed in the (EMV) 3DS2 Device Information Specification.

This information is used in risk analysis by the card schemes and card issuing banks.

Among the data elements collected by Judopay's Judokit are key browser details such as:

• IP address

• User agent

• Browser language

• System time zone

• Screen dimensions

• Colour depth

For in-app payments, our Android and iOS SDKs collect the following key details among others, recommended in the (EMV) 3DS2 Device Information Specification:

• App-specific device ID:

  • identifierForVendor on iOS

  • ANDROID_ID on Android 8.0 or higher

    Any apps installed on a previous version to Android 8.0, will observe a global ANDROID_ID instead of an app-specific value.

• Device model

• OS version

• System language

• System country

• System time zone

• Screen dimensions

The Android and iOS SDKs encrypt the device data using a key held by the card network. Judopay’s servers do not have access to this data.

As per the (EMV) 3DS2 protocol, the Android and iOS SDKs perform basic checks to detect rooted devices. Only the Boolean value representing whether the check succeeded or failed, is transmitted to the server.

The components of the Android SDK involved in 3DS2 transactions are obfuscated.

When is the 3D Secure 2 Device Data Collected?

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

When the consumer taps the PAY button, the payment flow is triggered. The device data is collected at the stage when you call CARD_PAYMENT.

For more information, see Payment Flow.

Collecting device data is a requirement of the (EMV) 3DS2 protocol and is only triggered during the 3DS2 payment flow.

Liability Shift

What is Liability Shift?

The 3D Secure liability shift is a rule protecting you from fraudulent transactions.

For example, if your consumer denies they authorised or made a purchase, (due to a lost or stolen card) and the 3D Secure authentication was successful (following either the frictionless or challenge flow), the liability for the payment shifts from you to the issuing bank.

If the 3D Secure authentication:

• was attempted but not successful

• could not be performed

• failed

the liability does not shift and remains with you.

Liability Shift Rules

The following 3D Secure 2 versions are supported:
- 3DS2.1
- 3DS2.2

Electronic Commerce Indicator

The Electronic Commerce Indicator (ECI) is a value returned by Directory Servers (for example Visa, Mastercard, American Express, JCB), which represents the authentication outcome of 3D Secure 2 transactions .

A cryptogram is a unique value returned by Directory Servers when authentication is successful. The liability shifts to the issuing bank when 3D Secure authentication is successful, except for a few cases where it depends on the cryptogram being available from the card scheme's directory server.
Card schemes observe liability shift rules based on a combination of ECI values and the presence of the cryptogram in the response from the Directory Server.

Authentication Successful

The liability shifts to the issuing bank when authentication is successful (following the frictionless or challenge flow), except for a few cases where it depends on the cryptogram being available.

Authentication Attempted but not Successful

Authentication could not be Performed

Authentication Failed

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

To test MIT, see Test Scenarios

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.

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 2 enabled. Contact ​Customer Support​​ to set this up.

Payment Flow

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

• 3D Secure enabled API credentials. Contact ​Customer Support​​ to set this up.

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

• Server SDKs:

  • Server SDKs (version 3.0.0 or higher)

  • PHP Integration (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:

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

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

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

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

primaryAccountDetails Block:

The primaryAccountDetails block is optional, however it is mandatory for merchants who have an MCC code of 6012 to submit additional Information about the primary account holder for payment pre-authorisation.

Example primaryAccountDetails block:

"primaryAccountDetails": {  
    "name": "Smith", 
    "accountNumber": "1234567890", 
    "dateOfBirth": "1980-01-01", 
    "postCode": "AB1 2CD"
}

Step Four: (Conditional) - Render Challenge Page

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

{
    "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:

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

Upgrading your Integration to 3D Secure 2

The following 3D Secure 2 versions are supported:
- 3DS2.1
- 3DS2.2

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:

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

"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 3D Secure 2 Payment with the Web SDK.

Integrating via Mobile SDK

If you are currently using Mobile SDK integration, we would recommend updating your integration to the latest version of the SDK.

Version 3.0.0 or higher supports 3DS 2, helping your mobile app be SCA compliant. For more information see, What is Strong Customer Authentication?

• For Android see, 3D Secure 2 for Android.

• For iOS, see 3D Secure 2 for iOS

• For React Native, see 3D Secure 2 for React Native.

Testing your Integration

To test 3D Secure 2 user journeys, see 3D Secure 2 Authentication