3D Secure Overview

ORX provides 3D Secure authentication to add an extra layer of security against unauthorized credit card use. The process is triggered when a payment request is made with the three-ds prefer flag enabled. If 3D Secure authentication is required, ORX will return a 3D Secure action object instead of an immediate success response.

To complete the 3D Secure authentication, pass the returned object to the threeDs method in @ndcsol/orx, which will handle the authentication flow. Once successfully authenticated, the returned payload can be included in the order request to complete the payment.

3D Secure Trigger

3D Secure authentication may be required when calling a payment-related endpoint, such as POST /flights/[sessionId]/order. If required, the response will include an action property set to three_d_s, along with authentication details.

Initiate 3D Secure

When a payment requires 3D Secure authentication, the API will return a response containing a 3D Secure action object.

Response Example

POST /flights/[sessionId]/order

{
    "gateway": "stripe",
    "payload": {
        "client_secret": "seti_dklsfjlsd12121212",
        "payment_method": "pm_sklj346jdfgn2",
        "publishable_key": "pk_test_sdfsdfsdfsdfklsdfjsdkflsdljflsd"
    },
    "action": "three_d_s"
}

If 3D Secure is presented, the response object will be of type 3D Secure Action.

Possible Errors

Status Code	Error	Reason	Reason Code
400	[Validation Error]	Failed Validation	ORX_VALIDATION_EXCEPTION
400	Authentication Failure	3D Secure authentication failed.
400	Payment Authorization Failed When Confirming a Successful 3DS	Payment Authorization Failed. Could not find a successful authorization attempt.	ORX_PAYMENT_AUTHORIZATION_FAILED
400	Payment Authorization Failed When Triggering 3DS	Payment Authorization Failed. The payment intent was not successful.	ORX_PAYMENT_AUTHORIZATION_FAILED

ORX SDK Authentication

To proceed with 3D Secure authentication, pass this object to the threeDs function in @ndcsol/orx.

npm install @ndcsol/orx

import { threeDs } from '@ndcsol/orx';
 
const threeDsResult = await threeDs(threeDsActionObject);

After passing the 3D Secure action object to the threeDs method, the function will return either a success or an error response.

Successful Authentication

If authentication succeeds, threeDs will return an object with a status of success. The returned payload should be included in the next order request to complete the payment.

{
  "gateway": "stripe",
  "payload": {
    "paymentIntent" : {
      "id": "pi_1J2f3sdf",
      "status": "succeeded"
    }
  },
  "status": "success"
}

Upon success, the response object will be of type 3d secure success.

Include this payload in the next request:

POST /flights/[sessionId]/order

{
  //... other parameters
  "threeDs" : {
    "gateway": "stripe",
    "payload": {
      "paymentIntent" : {
        "id": "pi_1J2f3sdf",
        "status": "succeeded"
      }
    },
    "status": "success"
  }
}

Failed Authentication

If authentication fails, threeDs will return an object with a status of "error". This object may include an error message detailing the issue.

{
  "status": "error",
  "gateway": "stripe",
  "message": "3D Secure authentication failed",
  "error": {
    "message" : "3D Secure authentication failed",
    "code" : "payment_intent_authentication_failure"
  }
}

The response object will be of type 3d secure failure.

Example

You can find a minimal example of how to use the threeDs method, where you can paste the 3D Secure action object and recieve a 3D Secure success and/or failure objects here (opens in a new tab).

Webhook Glossary