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

Send third-party 3-D Secure (3DS) authentication data to N-Genius Online using your merchant plug-in (MPI).

3DS lets customers authenticate themselves with their card issuer when making online purchases, without presenting a physical card. It replaces the 3DS 1.x standard.

Before you start

Use this guide if you authenticate customers through a third-party MPI rather than the native N-Genius 3DS service.

If you use the native service, follow the native 3DS integration guide.

Prerequisites

Before you send authentication data, complete these checks:

1. Confirm with your MPI provider that 3DS 2.x transactions are enabled.
2. Confirm that your MPI integration supports workflows with and without a customer authentication challenge.

Contact your MPI provider if you need help confirming these settings.

Send authentication data to N-Genius

The 3DS workflow follows one of two paths: frictionless authentication or challenge authentication.

Read the transStatus value your MPI returns to select the authentication workflow:

Frictionless authentication

If your MPI returns transStatus as N, U or R, send its authentication data to N-Genius.

Send the request using these settings:

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

Replace {outletId}, {orderId} and {paymentID} with the outlet reference, order reference and payment reference for your transaction.

Include these request headers:

Replace ACCESS_TOKEN with your access token.

Request body example:

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

Challenge authentication

If your MPI returns transStatus as C, send its authentication data and challenge result to N-Genius.

Send the request using these settings:

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

Replace {outletId}, {orderId} and {paymentID} with the outlet reference, order reference and payment reference for your transaction.

Include these request headers:

Replace ACCESS_TOKEN with your access token.

Request body example:

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