# Create a 3DS Authentication

This endpoint creates a 3DS Authentication. Refer to the [Create a 3DS Authentication object section of the Standalone 3DS guide](https://docs.stripe.com/payments/3d-secure/standalone-3d-secure.md#create-a-3ds-authentication-object) for more information.

You can pass the submit parameter to automatically submit the 3DS Authentication object when you create it. Refer to the [Submit at creation section of the Standalone 3DS guide](https://docs.stripe.com/payments/3d-secure/standalone-3d-secure.md#submit-at-creation) for more information.

## Request

```curl
curl https://api.stripe.com/v1/three_d_secure/authentications \
  -u "<<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-10-28.endive" \
  -d amount=1000 \
  -d currency=eur \
  -d message_category=payment_authentication \
  -d "flow_preference[type]=frictionless" \
  -d "channel[type]=browser" \
  --data-urlencode "channel[browser][accept_header]=Accept:  *.*;" \
  -d "channel[browser][java_enabled]=false" \
  -d "channel[browser][javascript_enabled]=true" \
  -d "channel[browser][language]=en-US" \
  -d "channel[browser][color_depth]=24" \
  -d "channel[browser][screen_height]=756" \
  -d "channel[browser][screen_width]=1528" \
  -d "channel[browser][timezone_offset]=0" \
  --data-urlencode "channel[browser][user_agent]=Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36" \
  -d "channel[browser][ip_address]=1.12.123.255" \
  -d payment_method=pm_card_visa \
  -d "acquirer_details[acquirer_bin]=424242" \
  -d "acquirer_details[acquirer_merchant_id]=050661454304761" \
  -d "acquirer_details[requestor_id]=V0000000001234" \
  -d "acquirer_details[acquirer_country]=IE" \
  -d directory_server=visa
```

### Response

```json
{
  "id": "tdsa_1QmCRMJM0r9zBvr4OVmMRa6X",
  "object": "three_d_secure.authentication",
  "acquirer_details": {
    "acquirer_bin": "424242",
    "acquirer_merchant_id": "050661454304761",
    "requestor_id": "V0000000001234",
    "acquirer_country": "IE"
  },
  "amount": 1000,
  "channel": {
    "browser": {
      "accept_header": "Accept:  *.*;",
      "color_depth": 24,
      "ip_address": "1.12.123.255",
      "java_enabled": false,
      "javascript_enabled": true,
      "language": "en-US",
      "screen_height": 756,
      "screen_width": 1528,
      "timezone_offset": 0,
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36"
    },
    "type": "browser"
  },
  "currency": "eur",
  "directory_server": "visa",
  "fingerprinting_url": "https://hooks.stripe.com/three_d_secure/fingerprint/tdsa_1QmCRMJM0r9zBvr4OVmMRa6X",
  "flow_preference": {
    "type": "frictionless"
  },
  "livemode": false,
  "message_category": "payment_authentication",
  "payment_method": "pm_1QmCRLJM0r9zBvr43F9eNoly",
  "status": "requires_submission"
}
```

## Parameters

- [`channel`](https://docs.stripe.com/api/three-d-secure/authentication/create.md?query=channel) (object, required)
  Contains additional details on the channel used for this 3DS Authentication.

- `message_category` (enum, required)
  Indicates whether this 3DS Authentication is being performed for a payment or non-payment use case.
Possible enum values:
  - `non_payment_authentication`
    Use `non_payment_authentication` to indicate that this 3DS Authentication is being performed for a non-payment use case.

  - `payment_authentication`
    Use `payment_authentication` to indicate that this 3DS Authentication is being performed for a payment use case.

- [`acquirer_details`](https://docs.stripe.com/api/three-d-secure/authentication/create.md?query=acquirer_details) (object, optional)
  Contains additional details about the acquirer for this 3DS Authentication.

  Refer to the [Pass acquirer details and directory server section of the standalone 3DS guide](https://docs.stripe.com/payments/3d-secure/standalone-3d-secure.md#pass-acquirer-details-and-directory-server) for more information.

- `amount` (integer, Required if message_category=payment_authentication)
  A non-negative integer representing the amount in the [smallest currency unit](https://docs.stripe.com/currencies.md#zero-decimal). You can’t include this parameter if `message_category` is `non_payment_authentication`

- `currency` (enum, Required if message_category=payment_authentication)
  Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://docs.stripe.com/currencies.md).

- `directory_server` (enum, Required if acquirer_details is provided)
  The 3DS directory server with which this 3DS Authentication was processed.
Possible enum values:
  - `american_express`
    American Express Directory Server

  - `cartes_bancaires`
    Cartes Bancaires Directory Server

  - `discover`
    Discover Directory Server

  - `mastercard`
    Mastercard Directory Server

  - `visa`
    Visa Directory Server

- [`flow_preference`](https://docs.stripe.com/api/three-d-secure/authentication/create.md?query=flow_preference) (object, optional)
  Contains additional details on your flow preference for this 3DS Authentication.

  Refer to the [Specify a flow preference section of the standalone 3DS guide](https://docs.stripe.com/payments/3d-secure/standalone-3d-secure.md#specify-a-flow-preference) for more information.

- [`future_usage`](https://docs.stripe.com/api/three-d-secure/authentication/create.md?query=future_usage) (object, optional)
  Contains information about future usage of this 3DS Authentication

- `metadata` (map, optional)
  Set of [key-value pairs](https://docs.stripe.com/api/metadata.md) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`.

- `payment_method` (string, Required unless payment_method_data is provided)
  ID of the payment method (a PaymentMethod object) to attach to this 3DS Authentication.

  The maximum length is 255 characters.

- [`payment_method_data`](https://docs.stripe.com/api/three-d-secure/authentication/create.md?query=payment_method_data) (object, Required unless payment_method is provided)
  Hash used to generate the PaymentMethod to be used for this Authentication. This is mutually exclusive with the `payment_method` parameter.

- `reason` (enum, optional)
  The reason for invoking standalone 3DS. This is tailored specifically for cases when you want Stripe to help determine the standalone 3DS flow to fit your use case instead of needing to select a specific 3DS flow.

  This parameter is exclusive with `flow_preference`. You can either use `reason` for controlling 3DS according to your business requirements, or use `flow_preference` for having fine-grained control over your 3DS flow preference.
Possible enum values:
  - `cardholder_authentication`
    The authentication is performed to attempt to require the cardholder to actively complete a challenge.

  - `issuer_requested`
    The authentication is performed when the issuer soft declines the transaction. This option should be used when you have tried authorization without 3DS authentication and the bank responded in a soft decline. Stripe will then trigger 3DS, post which you can retry authorization with the issuer.

  - `liability_shift`
    The authentication is performed to try to shift liability away from the merchant and onto the issuer to reduce the cost implications from disputes.

    **Note**: If you don’t select `liability_shift` as your reason, the 3DS flow won’t prioritize liability shift as a desired outcome. And even when `liability_shift` is selected, liability shift is not guaranteed, since that decision is made by the network and not Stripe([source](https://docs.stripe.com/payments/3d-secure/authentication-flow.md#disputed-payments)).

  - `processing_costs`
    The authentication is performed to optimize payments processing cost.

  - `regulatory_compliance`
    The authentication is performed solely to enable compliance with local regulations such as SCA (Strong Customer Authentication). Use this option when your sole requirement is compliance with local regulations, such as SCA or other 3DS-related mandates. The authentication will be performed only as necessary for compliance purposes.

    **Note:** This `reason` parameter value will always apply even when you do not choose this value explicitly.

- [`shipping_address`](https://docs.stripe.com/api/three-d-secure/authentication/create.md?query=shipping_address) (object, optional)
  The shipping address requested by the cardholder. You should try to include as complete address information as possible.

- `submit` (enum, optional)
  Set to `always` to skip the fingerprinting step and submit this Authentication immediately or `if_fingerprinting_not_supported` to submit this Authentication only if fingerprinting is not available. This parameter defaults to `never`.

  Refer to the [Submit at creation section of the standalone 3DS guide](https://docs.stripe.com/payments/3d-secure/standalone-3d-secure.md#submit-at-creation) for more information.
Possible enum values:
  - `always`
    If set, skips the fingerprinting step and submits this Authentication immediately.

  - `if_fingerprinting_not_supported`
    If set, submits this Authentication immediately if fingerprinting is not available.

  - `never`
    (Default) This Authentication will have a `requires_submission` status upon creation.

## Returns

Returns a 3DS Authentication object.