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 Upgrading to 3D Secure 2 (EMV 3D Secure).

 

The deadline for PSD2 implementation for all the European Union countries members was 31st December 2020.
The deadline for SCA implementation for UK merchants has been extended to 14th March 2022.

 

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 Upgrading to 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 Upgrading Directly via the API.

 

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.

 

3D Secure 2 Payment Flow

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

When authorising /payments or /preauths for 3D Secure 2 transactions, it is recommended to use paymentSession.

 

 

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.

 

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

 

 

Upgrading to 3D Secure 2 (EMV 3D Secure)

The deadline for PSD2 implementation for all the European Union countries members was 31st December 2020.
The deadline for SCA implementation for UK merchants has been extended to 14th March 2022.

 

Authenticating online card payments and meeting the new Strong Customer Authentication (SCA) requirements

 

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.

 

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

You can 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.

 

Upgrading Directly via the API

If you are currently integrating directly via the API (version 6.0.0.0 or higher), an additional way to authenticate is via: paymentSession.

 

When authorising /payments or /preauths for 3D Secure 2 transactions, it is recommended to use paymentSession.

 

For more information, see Transaction API /paymentSession

 

To verify your sandbox integration to 3D Secure 2, see Verify your 3D Secure 2 Integration.

 

If you are currently using one of the Server SDKs, .NET and PHP have been updated to support the 3DS 2 Integration.

 

Upgrading Mobile SDK

Coming Soon.

 

Upgrading Server SDKs

If you are currently using one of the Server SDKs, .NET and PHP have been updated to support the 3DS 2 Integration via API:

 

Upgrading Web Payments

If you are currently using Web Payments:

  1. Amend the URL in the redirect from ‘v1’ to 'v2’.

 

For example:

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

 

For more details, see Web Payments - Version 2.

 

Upgrading Web SDK

If you are currently using Web SDK Integration, Option One - Create paymentSession:

Simply:

  1. Upgrade to the latest version (version 0.0.25 or higher)        

  2. The following additional mandatory parameters to be included in the request:

    • billingAddress

    • mobileNumber

    • phoneCountryCode

    • emailAddress  

For example:
{   
"judoId": "100915867",     
"amount": 5.10,    
"currency": "GBP",    
"phoneCountryCode": "44",    
"yourConsumerReference": " your_consumer_reference",    
"yourPaymentReference": "your_payment_reference",    
"billingAddress":{        
    "address1": "My house",         
    "address2": "My street",        
    "town": "My town",         
    "postcode": "TR14 8PA",         
    "countryCode": 826            
    },     
"mobileNumber": "xxxxxxxx",     
"emailAddress": "example@gmail.com"
}

 

If you are currently using Web SDK Integration, Option Two - Create One Use Token:     

  1. We would recommend updating your integration to Option One - Create paymentSession

    1. This will reduce the calls your server makes.

    2. Let the Web SDK handle the 3DS flows.       

 

If you would prefer to continue using Option Two - Create One Use Token, you will need to follow the integration steps for: Overview of the Integration via API.

 

Overview of the Integration via API

Integrating 3D Secure 2 via Judopay's API, outlining the frictionless and challenge flows:

 

 

Make sure when testing methodNotificationUrl and challengeNotificationUrl you use a real URL for the values.
If you use a localhost URL, it will not work.

 

Step

Description

Create a payment or preAuth transaction request

If the CV2 is supplied in the original transaction request, it will need to be tracked across up to three further calls, should additional transactions checks be required in the challenge flow.

  • Response Option One = Successful. No additional transaction checks are required. This will follow the standard transaction response.

  • Response Option Two = Additional transaction checks are required.

  • This response will contain the:

    • 3DSecure block

    • 3DSecure status

    • Reason for the required additional data check

Gather Device Details (CONDITIONAL)

  1. Render the methodUrl in an invisible iframe to gather the device details.

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

RESUME (CONDITIONAL)

  • Resume the 3D Secure 2 transaction flow.

  • For the transaction that is to be resumed, include the reference in the request.

    • The reference is the value taken from the response in Step Two.

For the methodCompletion parameter (based on Step Two):

  • If methodUrl rendered -> methodNotificationUrl redirect detected -> method completion = YES

  • If methodUrl rendered -> methodNotificationUrl redirect not detected -> method completion = NO

  • If methodUrl not rendered  -> method completion = UNAVAILABLE

Additional Consumer Authentication Required (CONDITIONAL)

If the consumer needs to complete additional authentication:

  1. Render the iframe from the challengeUrl.

  2. Once the consumer has successfully entered their additional SCA details, (something the consumer knows, has or is), the iframe redirects to the challengeNotificationUrl, where the outcome of the challenge request is received.

Complete the 3D Secure 2 Transaction Flow (CONDITIONAL)

  • For the transaction that is to be completed, include the reference in the request.

    • The reference is the same value used in Step Three.

 

Sample code to create an iFrame:
const guid = () => {
    const s4 = () => {
        const arr = new Uint16Array(10)
        return Math.floor(1 + window.crypto.getRandomValues(arr)[0])
            .toString(16)
            .substring(1)
    }
    return `${s4() + s4()}-${s4()}-${s4()}-${s4()}-${s4()}${s4()}${s4()}`
}

const gatherDeviceParameters = async (timeout, src, params) => {
    const targetName = guid()

    const iframe = document.createElement('iframe')
    iframe.setAttribute('name', targetName)
    iframe.setAttribute('title', targetName)
    iframe.setAttribute('id', targetName)
    iframe.style.visibility = 'hidden'
    iframe.style.position = 'absolute'
    iframe.style.left = '0'
    iframe.style.top = '0'
    iframe.style.height = '0'
    iframe.style.width = '0'
    iframe.style.border = 'none'
    document.body.appendChild(iframe)

    const form = document.createElement('form')
    form.style.visibility = 'hidden'
    form.setAttribute('method', 'post')
    form.setAttribute('action', src)
    form.setAttribute('target', targetName)

    Object.keys(params).forEach(key => {
        const input = document.createElement('input')
        input.setAttribute('type', 'hidden')
        input.setAttribute('name', key)
        input.setAttribute('value', stringifyValue(params[key]))
        form.appendChild(input)
    })

    document.body.appendChild(form)

    form.submit()
    form.remove()

    return new Promise(resolve, reject => {
        const timeoutRef = setTimeout(() => {
            iframe.remove()
            clearTimeout(timeoutRef)
            reject('Timeout exceeded.')
        }, timeout * 1000)

        const handlePostMessage = (message) => {
            const { data } = message
            if (data && data.type === 'ThreeDS2MethodNotification') {
                window.removeEventListener('message', handlePostMessage)
                const { payload } = data
                iframe.remove()
                clearTimeout(timeoutRef)
                resolve(payload)
            }
        }

        window.addEventListener('message', handlePostMessage)
    })
}

const { methodUrl, md } = response 
// methodUrl and md parameters retreived from '/transactions/payments' or '/transactions/preauths'
const timeout = 10
const src = methodUrl
const params = {
    threeDSMethodData: md
}

gatherDeviceParameters(timeout, src, params)
    .then(result => console.log(result))
    .catch(error => console.error(error))