External EMV 3DS (3DS 2.X) Integration

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

This guide is intended for customers or partners who do not use N-Genius Online's native EMV 3DS service to process authentication requests on behalf of customers, and instead rely on a 3rd party MPI (merchant plug-in) to provide EMV 3DS authentication services.

For customers integrating with N-Genius Online, and will use the native EMV 3DS MPI provided therein, please refer to the EMV 3DS (3DS 2.X) Integration article for information on how to integrate with this service, if required.

Pre-requisites

Your EMV 3DS MPI should already be enabled for 3DS 2.x transactions, and - if enabled and integrated correctly - will provide different workflows for you to implement based on whether the transactions requires an authentication challenge to be presented to your card-holder/shopper or not.

If you are unsure about this, please speak with the provider of your EMV 3DS MPI for more information.

Sending EMV Authentication Data to N-Genius Online

There are two possible outcomes from the EMV 3DS workflow: Frictionless and Challenge.

By interrogating the transStatus value being returned by your EMV 3DS MPI, you should present the authentication data to N-Genius Online as below.

Frictionless Authentication

Where transStatus is equal to N, U or R, present the following attributes (returned from your EMV 3DS MPI response) to the N-Genius Online APIs as follows:

HTTP Request Method: POST
Explicit URI: https://api-gateway.ngenius-payments.com/transactions/outlets/{outletId}/orders/{orderId}/payments/{paymentID}/card/3ds2/external

Headers:

Body (example):

{
    "dsTransID": "d560326b-6ec2-4e99-9128-b2399a9020c5",
    "messageVersion": "2.1.0",
    "authentication": {
        "transStatus": "Y",
        "authenticationType": "01",
        "authenticationValue": "AAABBGcZcCOAZoEQFxlwENmlGM4=",
        "eci":"05"
    }
}

Challenge Authentication

Where transStatus is equal to C, present the following attributes (returned from your EMV 3DS MPI response) to the N-Genius Online APIs as follows:

HTTP Request Method: POST
Explicit URI: https://api-gateway.ngenius-payments.com/transactions/outlets/{outletId}/orders/{orderId}/payments/{paymentID}/card/3ds2/external

Headers:

Body (example):

{
    "dsTransID": "d560326b-6ec2-4e99-9128-b2399a9020c5",
    "messageVersion": "2.1.0",
    "authentication": {
        "transStatus": "C",
        "authenticationType": "01"
    },
    "challengeResult": {
        "transStatus": "Y",
        "authenticationValue": "AAABBGcZcCOAZoEQFxlwENmlGM4=",
        "eci":"05"
    }
}