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:

FunctionalityCheck
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-hooksYou 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:

FunctionalityCheck
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-hooksYou 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:

FunctionalityCheck
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-hooksYou 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:

KeyValue
eciThe E-Commerce Indicator (ECI) of the transaction, which will determine the status of liability shift for this transaction
transStatusWhether the EMV 3DS process was successful, or otherwise
messageVersionThe specific version of the EMV 3DS protocol used
acsReferenceNumberAn internal reference used to identify the EMV 3DS instance to the schemes and to the issuers
threeDSMethodURLThe URL used to authenticate the card-holder following a challenge (or frictionless) workflow
threeDSServerTransIDInternal reference for the EMV 3DS MPI
acsTransIDInternal reference for the EMV 3DS ACS
directoryServerIDThe 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.

PANEMV 3DS ModeOutcome
2303779999000275Frictionless (transStatus != C)Success
2303779999000408Challenge (transStatus == C)Success
2303779999000291Frictionless (transStatus == N)Failed (Not Authenticated)
2303779999000317Frictionless (transStatus == U)Failed (Unavailable)
2303779999000424Challenge (transStatus == N)Failed (Not Authenticated)
2303779999000432Challenge (transStatus == U)Failed (Unavailable)

Overview of transStatus Values

Since N-Genius Online can be configured (a per customer basis) to either proceed with or reject a transaction based on the eci and transStatus values, it is not recommended to use the eci or transStatus values returned from the EMV 3-D Secure workflow to drive acceptance logic on your system.

However, some customers may wish to capture/retain these values for future reference. If so, customers should implement this in a way that is "failure friendly" and does not rely on these values being present to operate their payment acceptance journey.

The following are the current (as of October 2022) possible values that can be returned from the N-Genius Online EMV 3-D Secure workflow:

transStatus valueDescription / meaning
YAccount successfully authenticated
NAccount not verified
UAuthentication could not be performed (usually due to a scheme or issuer technical failure)
AAttempted authentication - account could not be authenticated, but proof of an attempt remains *
CChallenge is required - the payer must undergo an authentication challenge (i.e. OTP, in many cases) before their authentication status can be determined.
RRejected - the issue is rejecting the authentication request, and recommends that no further authorization should take place

*In cases where the transStatus value of A is returned, the relevant card scheme either may or may not confer liability shift for these transactions, depending on rules defined in their ecosystem. In most cases, liability shift will be conferred, but customers should take care to understand that this is not true in all cases.

🚧

transStatus is a dynamic value

The initial value of transStatus will not always remain the same. In cases where the initial value of transStatus == C, the transStatus value will change after the authentication challenge has been completed (successfully or otherwise), to a Y, N, U, A or any other terminating value.