Judopay Documentation

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

Warning

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.

Note

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 a 3D Secure 2 /payments or /preauths transaction is via:

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 has been updated to support the 3DS 2.0 Integration. PHP support coming soon.

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.14 or higher)        

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

    1. billingAddress

    2. mobileNumber

    3. phoneCountryCode

    4. 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 these integration steps.

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 Server SDKs

If you are currently using one of the Server SDKs, .NET has been updated to support the 3DS 2.0 Integration via API.

Upgrading Mobile SDK

Coming Soon.

Overview of the Integration via API

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

3DS_Flowv2.png

Step

Description

One.png

Create a Payment or PreAuth Transaction Request

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

Two.png

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. 

Three.png

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

Four.png

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.

Five.png

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.