Judopay Documentation

3D Secure 2 (EMV 3D Secure)

Warning

The deadline for PSD2 implementation for all the European Union countries members was 31st December 2020.

UK merchants will need to be SCA compliant by 14th September 2021.

What is 3D Secure 2?

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.

3D Secure 2 Payment Flow

When authorising /payments or /preauths for 3D Secure 2 transactions, you can either:

  • Call directly to the API using your 3D Secure 2 enabled API token.

  • Use Payment-Session.

    Check you are using Judopay's API version 6.0.0.0 or higher.

The following example takes you through the payment flow using Payment-Session to authenticate the transaction.

3DS_2_0_Auth_Flow.png
  1. Create a Payment-Session.

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

  2. Send the authorisation request with the /payments request header, populated with the reference received in the Payment-Session response.

    This step:

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

    2. Gathers the Device and Card Details.

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

  4. 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 /resume3d endpoint.

  5. Authorisation complete.

    The consumer is redirected to the outcome screen.

Authenticating via API

Prerequisite

  • You are using Judopay's API version 6.0.0.0 or higher.

For more information on the Judopay API, see Judopay API.

To authenticate a 3D Secure 2 transaction to allow for the provision of additional information required for compliance with SCA, Judopay has created:

One.png

An Additional way to Authenticate:

  • Use Payment-Session to authenticate a 3D Secure 2 /payments or /preauths transaction.

    For more details, see 3D Secure 2 Payment Flow.

    • Using Payment-Session to authenticate your requests, allows you to complete transactions with fewer calls to the server.

    • For use with API version 6.0.0.0 or higher.

Two.png

New fields :

  • New fields have been created in the /payments and /preauths endpoints.

    • Providing additional authentication and transaction information.

Three.png

A new endpoint:

  • /resume3d

Four.png

3D Secure 2 Test Details:

Authenticating via Web SDK

To authenticate a 3D Secure 2 transaction to allow for the provision of additional information required for compliance with SCA, Judopay has created:

One.png

Challenge Screen:

  • If the consumer is challenged for additional information (for example a code or password), the Web SDK will automatically present the 3D Secure 2 challenge screen.

Two.png

An Additional way to Authenticate:

  • Use paymentSession to authenticate a 3D Secure 2 payments or preauths transaction.

To authenticate a 3D Secure 2 transaction via the Web SDK, see Creating a Payment with the Web SDK.

Exemptions to Strong Customer Authentication?

Are there exemptions to SCA?

Under this new regulation, specific types of payments that are considered to be low-risk may be exempt from Strong Customer Authentication. 

Note that this is subject to the issuer’s decision; they can reject any request exemptions if they feel these fall foul of their risk analysis processes. 

Possible exemptions include:

  • Low risk transactions: where a bank’s overall fraud rates for card payments do not exceed:

    • 0.13% to exempt transactions below €100 (or local equivalent amount where relevant)

    • 0.06% to exempt transactions below €250

    • 0.01% to exempt transactions below €500

    • Transactions below €30

Banks will need to request authentication if:

  • The exemption has been used five times since the cardholder’s last successful authentication.

  • The sum of previously exempted payments exceeds €100 Fixed-amount subscriptions.

    This can apply when the consumer makes a series of recurring payments for the same amount, to the same business. 

  • It is the consumer's first payment, subsequent charges may be exempt.

3D Secure Integration Questions

What changes do I need to make to my Judopay Mobile SDK implementation?

  • I already have 3D Secure 1

    • To enable 3D Secure 2 and above you will simply need to update your mobile SDKs.

  • I do not have 3D Secure 1

    • You will need to amend your payment flows to include 3D Secure. 

What changes do I need to make to my Judopay Web SDK implementation?

  • I already have 3D Secure 1

    • We will make the changes in the background and automatically update you to 3D Secure 2.

  • I do not have 3D Secure 1

    • You will need to amend your payment flows to include 3D Secure.

    • However, if you want to wait to make the updates directly to 3D Secure 2 later in the year you can.

What changes do I need to make to my Judopay Web Redirect implementation?

  • Check that your Judopay account is configured for 3D Secure 2.

  • Similar to Judopay's Web SDK, we will handle the rest by pre-populating the required fields in the background on your behalf.

When can I start implementing the required changes so I’m ready for 3D Secure 2?

You can start to integrate via the Judopay API now.

Integrating 3D Secure 1

Note

To prepare for the new PSD2 regulatory requirement of Strong Customer Authentication, we recommend Integrating 3D Secure 2.

Prerequisites

  • Ensure you have an API application key (token and secret) enabled for 3D Secure. 

    Note

    Your API token will be enabled for 3D Secure by the on-boarding team. For any queries, please contact customer support.

  • If you are using our hosted web payments redirect to take payments, ensure your account is enabled for 3D Secure. The majority of the integration will be handled for you.

Step One

Using your pre-configured 3D Secure application key, make a payment request to our API from your server:

  • Card Payment

  • Token Payment

  • Token Preauth

  • Preauth

Step Two

If the card is enrolled to support 3D Secure, the response will be set to Requires3DSecure.

  • acsURL

    The URL used to redirect the consumer to 3D Secure.

  • md

    An encrypted blob of information Judopay needs in order to resume the transaction.

  • PaReq

    The Payment authorisation request. A unique ID to identify the 3D Secure request.

Step Three

The consumer will be directed to the 3D Secure screen, to verify the transaction. On the client side (web browser or web view for in-app journeys), a POST method needs to be made to the acsURL received from Judopay's API (see Step Two), which needs to include the following fields:

The POST request needs to include the following fields (case sensitive):

  • PaReq

    The Payment authorisation request. A unique ID to identify the 3D Secure request.

  • MD

    An encrypted blob of information Judopay needs in order to resume the transaction.

  • TermUrl

    The termination URL. This is the location the ACS server will return the consumer to in the event of either success or failure of the 3D Secure authorisation.

Warning

Incorrect usage to your TermUrlwill produce a lack of response, or incomplete data within the ACS URL response.

Step Four

Once the consumer has completed the 3D Secure authentication, they will be navigated to the TermURL supplied in the POST request.

  • PaRes

    A Base64 encoded, encrypted message.

    It is returned from the request made to the ACS server (Step Three) with the results of the 3D Secure authentication.

  • MD

    An encrypted blob of information Judopay needs in order to resume the transaction.

Step Five

Use PaRes and MD to complete the 3D Secure transaction by calling the Complete3DSecure API method.

This sends a PUT request to: 

https://gw1.judopay.com/transactions/{receiptId}

 

Example body request:

{     "PaRes": "response in step (4)",     "Md": "response in step (4)" }

Step Six

Judopay's API will reply with a transaction receipt, including the outcome of the transaction in the Result property.

Result Description

  • Success: The transaction has been successfully processed.

  • Declined: The transaction was declined by the issuing bank, or the 3D Secure process was not successfully completed.

  • Error: There was a problem processing the PUT request. Please confirm you forwarded the complete PaRes and MD values without modification.