3DS Authentication

Overview

3DS Authentication Types

There are two types of the 3DS authentication, Frictionless and Challenge, that are handled automatically by the gateway itself. Both types apply to all authentication handling options (i.e. Automatic, Partly Automatic, Third Party MPI), except for the Manual 3DS Handling.

  • Frictionless

The Frictionless flow is triggered when the required request data has been submitted (customer's fingerprint and any other additional data provided) to the issuer, and the issuer opts to authenticate the customer with this data. In this scenario, the transaction is processed without any interaction from the customer.

  • Challenge

The Challenge flow is triggered when the issuer opts for the customer to provide additional identification via the two-factor authentication (either via SMS or biometrics).

3DS Authentication Handling Options

There are four 3DS authentication handling options:

  • Automatic;
  • Partly Automatic (Manual Redirect);
  • Third Party MPI;
  • Manual 3DS handling.

For all four options, the process starts in the same way:

  1. Create an order
  2. Collect the card data

From the on, the process differs, depending on the chosen 3DS authentication handling option.

Automatic

Available for the Full Page, Embedded Iframe, Payform Web SDK checkout options.

The Automatic 3DS authentication flow is completely handled by the gateway, and the merchant does not have to participate. The gateway returns the authorization and the 3DS authentication results together.

Partly Automatic (Manual Redirect)

Available for the Host2Host checkout option.

The Partly Automatic 3DS authentication flow is completely handled by the gateway, and the merchant does not have to participate. The gateway returns the authorization and the 3DS authentication results together. The only difference from the Automatic flow is that, after the card data submission, the gateway returns a threed_check_url to which the merchant must redirect the customer for a fully automatic 3DS process.

Third Party MPI

Available for the Host2Host checkout option.

After creating an order and collecting the card data, send a request to POST payment api_do_url.
Request example:

{
    "cardholder_name": "Adam Smith",
    "card_number": "4242424242424242",
    "exp_month": 6,
    "exp_year": 23,
    "csc": "111",
    "eci": "str",
    "cavv": "string",
    "xid": "string",
    "3ds_protocol": "string",
    "3ds_ds_id": "string",
    "ip_address": "198.51.100.42",
}

Manual 3DS Handling

  1. After creating an order and collecting the card data, send a request to POST payment api_do_url.

Request example:

{
    "cardholder_name": "CARDHOLDER NAME",
    "card_number": "4111111111111111",
    "exp_month": "06",
    "exp_year": "23",
    "csc": "111",
    "manual_acs": true,
    "termurl": "https://your.site/3ds-webhook"
}

manual_acs: True/False - used to define that the merchant will manage 3DS flow by themselves;
termurl: “merchant URL” - URL will be used by the issuer ACS server to redirect customers when 3DS authentication is completed. CRes/PaRes parameters will be posted by the ACS server to the merchant URL.

During this step the gateway performs a request to 3DS MPI Server that will check the card participation from the 3D Secure directory published ranges.

Response when mdstatus: 51 (3DS method is not needed. tds_method_content is empty):

{
    "status": "tds_initiated",
    "next_step": "enrollment_request",
    "next_step_url": "https://transactions.gateway.com/p/uuid/3d/tds_enrollment/",
    "three_d_secure_details": {
        "txid": "111111111",
        "xid": "RGVjdGEgR2F0ZXdheQ==",
        "protocol": "3DS2.2.0",
        "mdstatus": "51"
    },
    "tds_method_content": ""
}

Response when mdstatus: 50 (Performs 3DS method. tds_method_content is populated):

{
    "status": "tds_initiated",
    "next_step": "enrollment_request",
    "next_step_url": "https://transactions.gateway.com/p/uuid/3d/tds_enrollment/",
    "three_d_secure_details": {
        "txid": "111111111",
        "xid": "RGVjdGEgR2F0ZXdheQ==",
        "protocol": "3DS2.2.0",
        "mdstatus": "50"
    },
    "tds_method_content": "HTML content"
}

Upon receiving mdstatus=50 response, the merchant must take the HTML content from field tds_method_content and render an intermediate page with this content, and then and wait approximately 3-5 seconds. After that, the merchant should perform the following step.

  1. In the previous response, the next_step_url parameter was returned. Send a request to POST next_step_url.

Request example:

{
    "tds_attributes": {
        "language": "en-US",
        "jsEnabled": true,
        "javaEnabled": false,
        "colorDepth": "24",
        "height": "1080",
        "width": "1920",
        "pixelDepth": "24",
        "timezoneOffset": "-180"
    }
}

tds_attributes parameters defined in the example are mandatory. For the Frictionless flow, the gateway will automatically send the authorization request to processing. In this case, no customer actions are required, and the gateway receives the final 3DS authentication status and immediately performs authorization requests to the processing system.

Frictionless response:

{
    "next_step": null,
    "next_step_url": null,
    "processing_status": "000",
    "redirectToACSForm": null,
    "status": "tds_completed",
    "three_d_secure_details": {
        "mdstatus": "1",
        "protocol": "3DS2.2.0",
        "txid": "111111111",
        "xid": "RGVjdGEgR2F0ZXdheQ=="
    }
}

The example response contains status parameter value “tds_completed” and processing_status parameter value “000”. This means that 3DS authentication is completed and the processing request has been sent. “000” code means that the authorization has been approved by the processor. Thus the order gets paid and the merchant will receive a webhook.

Challange respone:

{
    "next_step": "tds_validate",
    "next_step_url": "https://transactions.gateway.com/p/uuid/3d/tds_enrollment/",
    "processing_status": null,
    "redirectToACSForm": "HTML content",
    "status": "tds_pending",
    "three_d_secure_details": {
        "mdstatus": "9",
        "protocol": "3DS2.2.0",
        "txid": "111111111",
        "xid": "RGVjdGEgR2F0ZXdheQ=="
    }
}

For the Challenge flow, the response contains a redirecttoACSForm parameter that must be rendered in the customer's browser. As a result, the customer will be redirected to the bank issuer ACS form. Note that you have 30 seconds to render HTML content from the redirecttoACSForm parameter to the customer. This action will post CReq value to ACS server.

  1. This step is necessary to finish the Challange flow. When the cardholder authenticates the transaction, the issuer ACS system will redirect the customer and POST “CRes/PaRes” data to the URL provided in the termurl parameter. The merchant must post the ”CRes/PaRes” parameter value to the validation endpoint. The validation endpoint has been received in the previous step in next_step_url parameter.

Send a request to POST next_step_url.
Request example:

{
    "cres": "cres value"
}

or

{
    "pares": "pares value"
}

Response example:

{
    "next_step": null,
    "next_step_url": null,
    "processing_status": "116",
    "status": "tds_completed",
    "three_d_secure_details": {
        "mdstatus": "1",
        "protocol": "3DS2.2.0",
        "txid": "111111111",
        "xid": "RGVjdGEgR2F0ZXdheQ=="
    }
}
Jump to
  • Overview
  • Automatic
  • Partly Automatic (Manual Redirect)
  • Third Party MPI
  • Manual 3DS Handling