Migrating to EMV 3DS

This guide is intended for customers and partners who are being migrated from version 1.x of the 3-D Secure standard, to the EMV 3-D Secure standard

EMV 3-D Secure (3DS) is a messaging protocol that promotes frictionless consumer authentication and enables consumers to authenticate themselves with their card issuer when making card-not-present (CNP) e-commerce purchases.

It was designed to replace the 3DS 1.X standard, which is due to be decommissioned in October 2022.

Before you start

It is important to identify what form of integration you are using to process E-Commerce payments via the N-Genius Online payment gateway. If you are unsure what integration method you are using, please contact the E-Commerce Support team who will be able to advise you.

Customers using N-Genius Online can process payments via a variety of interaction/integration methods, most of which should remain unaffected by the migration from 3DS 1.x to the EMV 3DS standard.

  • Hosted Payment Page (HPP) and Pay-by-Link customers and integrators are unlikely to be required to make any changes to their integration
  • Hosted Session (WebSDK) and Mobile SDK (Android, iOS, React Native) customers and integrators, likewise, will likely be unaffected by the migration
  • Direct API customers, who process the 3-D Secure challenge on behalf of their card-holders, will need to make some changes to their integration in order to support EMV 3DS. See the EMV 3DS (3DS 2.X) Integration for more information.
  • Customers or partners who are using a 3rd party (external, non N-Genius Online ) MPI to process EMV 3DS transactions on behalf of their card-holders, should check the following article for the changes required: External EMV 3DS (3DS 2.X) Integration.

📘

Check your integration

Despite many integration methods requiring no action on behalf of integrators, we strongly recommend customers of all integration types to check the following sections, in order to ensure that these changes will not affect those who have implemented any deviations from a 'standard' integration workflow.

Pay by Link

It is highly likely that, as a customer of the Pay by Link solution Pay by Link, there will be nothing for you to do - you will be enrolled for EMV 3DS and your payments will proceed as normal.

The only occasion where a change might be required on your side is if you are using the N-Genius Online APIs to manually query the transaction outcome, or using the Webhooks functionality for a similar purpose. If you believe this to be the case, you should review the New 3-D Secure Reponse Data section below.

Hosted Payment Page (HPP)

As a customer of the N-Genius Online Hosted Payment Page, again, it is highly likely that there will be nothing required of you in order to get ready for the shift to our EMV 3DS solution - all payment workflows will be handled for you.

However, if you are using the N-Genius Online APIs to manually query the transaction outcome, or interrogating the outcome of the 3-D Secure (3ds) process from the N-Genius Online Webhooks, you should consult the New 3-D Secure Response Data section below.

Things to check:

Functionality

Check

Querying or interrogating the result of the 3ds data block returned from a separate GET call to the N-Genius Online APIs (to get the payment outcome)

You should check that you are not using a specific key/value pair in the 3ds data block to drive further logic downstream on your systems.

Web-hooks

You should check that, if you are using the Web-hooks functionality on N-Genius Online , that you are not relying on a specific key/value pair in the 3ds block of this data to drive further logic downstream on your systems.

Hosted Session (WebSDK)

For customers integrated via the Hosted Session (sometimes referred to as WebSDK, Web SDK Integration Guide), it is unlikely that you will need to make any changes to your integration. The dynamically loaded SDK has already been upgraded to support the new EMV 3DS transaction workflow.

It is possible, however, that you might be following a 'non-standard' integration path, whereby you are interrogating the result of the 3ds authentication data returned from the SDK in order to capture/store this information, or using it to drive additional logic. It is also possible that you are using the N-Genius Online Webhooks functionality to do the same.

Things to check:

Functionality

Check

Querying or interrogating the result of the 3ds data block returned from the JavaScript SDK (WebSDK)

You should check that you are not using a specific key/value pair in the 3ds data block to drive further logic downstream on your systems.

Web-hooks

You should check that, if you are using the Web-hooks functionality on N-Genius Online , that you are not relying on a specific key/value pair in the 3ds block of this data to drive further logic downstream on your systems.

In these instances, you should refer to the New 3-D Secure Response Data section below.

Mobile SDK (iOS, Android, React Native)

Merchants integrating with the N-Genius Online SDKs for in-app payments across iOS, Android and React Native platforms, will need to ensure that they are using the most recent version of the SDK, for their platform(s) of choice, found here:

https://github.com/network-international

Further, if your integration model relies on separate queries to the N-Genius Online APIs (outside of the SDK workflow) to consume the outcome of the payment, or if the Webhooks service is in use to drive logical workflow in your downstream systems, you should also review the New 3-D Secure Response Data section below.

Things to check:

Functionality

Check

Querying or interrogating the result of the 3ds data block returned from the iOS, Android or React Native SDK(s).

You should check that you are not using a specific key/value pair in the 3ds data block to drive further logic downstream on your systems.

Web-hooks

You should check that, if you are using the Web-hooks functionality on N-Genius Online , that you are not relying on a specific key/value pair in the 3ds block of this data to drive further logic downstream on your systems.

Direct API

Customers integrated with the Direct API integration method for their N-Genius Online service, and which incorporates the 3-D Secure process as part of this integration, will need to make changes to be ready for the migration to EMV 3DS.

For further information on how to do this, customers should consult and follow the EMV 3DS (3DS 2.X) Integration article.

New 3-D Secure Response Data

Following the migration to EMV 3DS, the 3-D Secure information returned in the payment responses from N-Genius Online will change. The following 3ds2 block (or similar) will be returned in place of the previous 3ds block:

{
    "eci": "05",
    "transStatus": "Y",
    "messageVersion": "2.2.0",
    "acsReferenceNumber": "3DS_LOA_ACS_RSAS_020200_00486",
    "threeDSMethodURL": "https://www.securesuite.co.uk/lloyds/threeDSMethod/3ds2/",
    "threeDSServerTransID": "3a9212ae-9a35-4fe1-8732-3a3858f18c5e",
    "acsTransID": "cfc55a4f-b366-4e3e-ac7f-0cd91f26b94d",
    "directoryServerID": "A000000003"
}

The relevant key value pairs are described as follows:

Key

Value

eci

The E-Commerce Indicator (ECI) of the transaction, which will determine the status of liability shift for this transaction

transStatus

Whether the EMV 3DS process was successful, or otherwise

messageVersion

The specific version of the EMV 3DS protocol used

acsReferenceNumber

An internal reference used to identify the EMV 3DS instance to the schemes and to the issuers

threeDSMethodURL

The URL used to authenticate the card-holder following a challenge (or frictionless) workflow

threeDSServerTransID

Internal reference for the EMV 3DS MPI

acsTransID

Internal reference for the EMV 3DS ACS

directoryServerID

The identifier of the Directory Server (DS) used to route the EMV 3DS request and workflow

If your integration currently relies on the 3ds data block for completing your payments and driving your own systems or processes, it is highly recommended that you switch to using the 3ds2 block as your account is migrated to EMV 3DS.

Testing EMV 3DS

The following list of test cards may be used to test various EMV 3DS scenarios through the Sandbox/UAT environment for N-Genius Online .

Note that for the expiry date component (expiry), any future date is acceptable, and any 3-digit value is acceptable for the CVV/CSC (cvv) component of the payment information.

PAN

EMV 3DS Mode

Outcome

2303779999000275

Frictionless (transStatus != C)

Success

2303779999000408

Challenge (transStatus == C)

Success

2303779999000291

Frictionless (transStatus == N)

Failed (Not Authenticated)

2303779999000317

Frictionless (transStatus == U)

Failed (Unavailable)

2303779999000424

Challenge (transStatus == N)

Failed (Not Authenticated)

2303779999000432

Challenge (transStatus == U)

Failed (Unavailable)