Stripe: Create a 3 DS Authentication

← Three d secure operations · Get started

Operation stripe.postthreedsecureauthentications

Provider route: POST /v1/three_d_secure/authentications. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/stripe with npm, or alter-sdk-stripe with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { StripeIntegration } from "@alter-ai/stripe";

async function execute(input: Parameters<StripeIntegration["threeDSecure"]["postThreeDsecureAuthentications"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new StripeIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.threeDSecure.postThreeDsecureAuthentications(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_stripe import StripeIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = StripeIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.three_d_secure.post_three_dsecure_authentications(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
headers	object	Optional	Additional keys: not allowed
headers.Idempotency-Key	string	Optional	Minimum length: 1 Maximum length: 255
body	object	Required within parent	Additional keys: not allowed
body.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](/payments/3d-secure/standalone-3d-secure#pass-acquirer-details-and-directory-server) for more information.
body.acquirer_details.acquirer_bin	string	Required within parent	Maximum length: 11
body.acquirer_details.acquirer_country	string	Required within parent	Maximum length: 5000
body.acquirer_details.acquirer_merchant_id	string	Required within parent	Maximum length: 35
body.acquirer_details.mcc	string	Optional	Maximum length: 5000
body.acquirer_details.merchant_name	string	Optional	Maximum length: 40
body.acquirer_details.requestor_id	string	Optional	Maximum length: 35
body.amount	integer	Optional	A non-negative integer representing the amount in the [smallest currency unit](/currencies#zero-decimal). You can’t include this parameter if `message_category` is `non_payment_authentication`
body.channel	object	Required within parent	Contains additional details on the channel used for this 3DS Authentication.
body.channel.browser	object	Optional
body.channel.browser.accept_header	string	Required within parent	Maximum length: 2048
body.channel.browser.color_depth	integer	Optional
body.channel.browser.device_id	string	Optional	Maximum length: 64
body.channel.browser.ip_address	string	Required within parent	Maximum length: 45
body.channel.browser.java_enabled	boolean	Optional
body.channel.browser.javascript_enabled	boolean	Required within parent
body.channel.browser.language	string	Required within parent	Maximum length: 35
body.channel.browser.screen_height	integer	Optional
body.channel.browser.screen_width	integer	Optional
body.channel.browser.timezone_offset	integer	Optional
body.channel.browser.user_agent	string	Required within parent	Maximum length: 2048
body.channel.three_r_i	object	Optional
body.channel.three_r_i.previous_authentication	string	Required within parent	Maximum length: 5000
body.channel.three_r_i.type	string	Required within parent	One of: delayed_shipment, other_payment, recurring, split_shipment
body.channel.type	string	Required within parent	One of: browser, three_r_i
body.currency	string	Optional	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies). Format: currency
body.directory_server	string	Optional	The 3DS directory server with which this 3DS Authentication was processed. One of: american_express, cartes_bancaires, discover, mastercard, visa
body.expand	array	Optional	Specifies which fields in the response should be expanded.
body.expand[]	string	Each item	Maximum length: 5000
body.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](/payments/3d-secure/standalone-3d-secure#specify-a-flow-preference) for more information.
body.flow_preference.challenge	object	Optional
body.flow_preference.challenge.type	string	Required within parent	One of: mandated, preferred
body.flow_preference.data_share	object	Optional
body.flow_preference.data_share.type	string	Required within parent	One of: ds_specific, emv_standard
body.flow_preference.frictionless	object	Optional
body.flow_preference.frictionless.type	string	Required within parent	One of: low_risk, none
body.flow_preference.type	string	Required within parent	One of: challenge, data_share, frictionless
body.future_usage	object	Optional	Contains information about future usage of this 3DS Authentication
body.future_usage.installment	object	Optional
body.future_usage.installment.amount	integer	Required within parent
body.future_usage.installment.expiry	object	Required within parent
body.future_usage.installment.expiry.date	string	Optional	Maximum length: 5000
body.future_usage.installment.expiry.type	string	Required within parent	One of: date, never
body.future_usage.installment.interval	string	Optional	One of: day
body.future_usage.installment.interval_count	integer	Optional
body.future_usage.installment.number	integer	Required within parent
body.future_usage.recurring	object	Optional
body.future_usage.recurring.amount	integer	Required within parent
body.future_usage.recurring.expiry	object	Required within parent
body.future_usage.recurring.expiry.date	string	Optional	Maximum length: 5000
body.future_usage.recurring.expiry.type	string	Required within parent	One of: date, never
body.future_usage.recurring.interval	string	Optional	One of: day
body.future_usage.recurring.interval_count	integer	Optional
body.future_usage.type	string	Required within parent	One of: card_on_file, installment, recurring
body.message_category	string	Required within parent	Indicates whether this 3DS Authentication is being performed for a payment or non-payment use case. One of: non_payment_authentication, payment_authentication
body.metadata	JSON	Optional	Set of [key-value pairs](https://docs.stripe.com/api/metadata) 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`.
body.metadata (anyOf 1)	object	Alternative	Additional keys: see wildcard field
body.metadata (anyOf 1).*	string	Additional keys
body.metadata (anyOf 2)	string	Alternative	One of:
body.payment_method	string	Optional	ID of the payment method (a PaymentMethod object) to attach to this 3DS Authentication. Maximum length: 255
body.payment_method_data	object	Optional	Hash used to generate the PaymentMethod to be used for this Authentication. This is mutually exclusive with the `payment_method` parameter.
body.payment_method_data.billing_details	object	Optional
body.payment_method_data.billing_details.address	object	Optional
body.payment_method_data.billing_details.address.city	string	Optional	Maximum length: 50
body.payment_method_data.billing_details.address.country	string	Optional	Maximum length: 5000
body.payment_method_data.billing_details.address.line1	string	Optional	Maximum length: 50
body.payment_method_data.billing_details.address.line2	string	Optional	Maximum length: 50
body.payment_method_data.billing_details.address.postal_code	string	Optional	Maximum length: 16
body.payment_method_data.billing_details.address.state	string	Optional	Maximum length: 3
body.payment_method_data.billing_details.email	string	Optional
body.payment_method_data.billing_details.name	string	Optional	Maximum length: 5000
body.payment_method_data.billing_details.phone	string	Optional
body.payment_method_data.card	JSON	Required within parent
body.payment_method_data.card (anyOf 1)	object	Alternative
body.payment_method_data.card (anyOf 1).cvc	string	Optional	Maximum length: 5000
body.payment_method_data.card (anyOf 1).exp_month	integer	Required within parent
body.payment_method_data.card (anyOf 1).exp_year	integer	Required within parent
body.payment_method_data.card (anyOf 1).number	string	Required within parent	Maximum length: 5000
body.payment_method_data.card (anyOf 2)	object	Alternative
body.payment_method_data.card (anyOf 2).token	string	Required within parent	Maximum length: 5000
body.payment_method_data.type	string	Required within parent	One of: card
body.reason	string	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. One of: cardholder_authentication, issuer_requested, liability_shift, processing_costs, regulatory_compliance
body.shipping_address	object	Optional	The shipping address requested by the cardholder. You should try to include as complete address information as possible.
body.shipping_address.city	string	Optional	Maximum length: 50
body.shipping_address.country	string	Optional	Maximum length: 5000
body.shipping_address.line1	string	Optional	Maximum length: 50
body.shipping_address.line2	string	Optional	Maximum length: 50
body.shipping_address.postal_code	string	Optional	Maximum length: 16
body.shipping_address.state	string	Optional	Maximum length: 3
body.submit	string	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](/payments/3d-secure/standalone-3d-secure#submit-at-creation) for more information. One of: always, if_fingerprinting_not_supported, never

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	Model	Root	Expand Cancel a 3 DS Authentication — response body

Referenced models: Cancel a 3 DS Authentication — response body

Schemas

720 more schemas are linked from the tables above, on the schema pages.

Cancel a 3 DS Authentication — response body

Field	Type	Presence	Description and constraints
$	object	Root	The Standalone 3DS API allows you to run EMV 3D Secure (3DS) authentication using Stripe while authorizing the payment with any PSP. Related guide: [Standalone 3DS](/payments/3d-secure/standalone-3d-secure)
acquirer_details	Model	Optional	Expand Cancel a 3 DS Authentication — response body — acquirer details
amount	JSON	Optional
amount (anyOf 1)	integer	Alternative	The amount for this 3DS Authentication.
amount (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
challenge_url	string	Optional	The URL for presenting a challenge to your cardholder, present if status is requires_challenge. Maximum length: 5000
channel	Model	Required within parent	Expand Cancel a 3 DS Authentication — response body — channel
created	JSON	Required within parent
created (anyOf 1)	integer	Alternative	Time at which the object was created. Measured in seconds since the Unix epoch. Format: unix-time
created (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
currency	string	Optional	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies). Format: currency
directory_server	string	Required within parent	The 3DS directory server with which this 3DS Authentication was processed. Known values: american_express, cartes_bancaires, discover, mastercard, visa
fingerprinting_url	string	Optional	The URL for performing issuer fingerprinting, present if fingerprinting is supported for the given payment method. Maximum length: 5000
flow_preference	Model	Optional	Expand Cancel a 3 DS Authentication — response body — flow preference
future_usage	Model	Optional	Expand Cancel a 3 DS Authentication — response body — future usage
id	string	Required within parent	Unique identifier for the object. Maximum length: 5000
livemode	boolean	Required within parent	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
message_category	string	Required within parent	Indicates whether this 3DS Authentication is being performed for a payment or non-payment use case. Known values: non_payment_authentication, payment_authentication
metadata	JSON	Optional
metadata (anyOf 1)	object	Alternative	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Additional keys: see wildcard field
metadata (anyOf 1).*	string	Additional keys	Maximum length: 500
metadata (anyOf 2)	null	Alternative
object	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: three_d_secure.authentication
outcome	string	Optional	The outcome of this 3DS Authentication. Known values: abandoned, attempt_acknowledged, authenticated, canceled, denied, informational, internal_error, not_supported, not_triggered, processing_error, rejected
outcome_details	Model	Optional	Expand Cancel a 3 DS Authentication — response body — outcome details
payment_method	JSON	Required within parent	ID of the payment method (a PaymentMethod object) to attach to this 3DS Authentication.
payment_method (anyOf 1)	string	Alternative	Maximum length: 5000
payment_method (anyOf 2)	Model	Alternative	Expand Create a Payment Method — response body
reason	string	Optional	The reason for invoking this 3DS Authentication. Known values: cardholder_authentication, issuer_requested, liability_shift, processing_costs, regulatory_compliance
shipping_address	Model	Optional	Expand Cancel a 3 DS Authentication — response body — shipping address
status	string	Required within parent	Status of this Authentication. Known values: canceled, error, failed, requires_challenge, requires_submission, succeeded

Referenced models: Create a Payment Method — response body, Cancel a 3 DS Authentication — response body — acquirer details, Cancel a 3 DS Authentication — response body — channel, Cancel a 3 DS Authentication — response body — flow preference, Cancel a 3 DS Authentication — response body — future usage, Cancel a 3 DS Authentication — response body — outcome details, Cancel a 3 DS Authentication — response body — shipping address

Cancel a 3 DS Authentication — response body — acquirer details

Field	Type	Presence	Description and constraints
$	object	Root	Contains additional details about the acquirer for a 3DS Authentication.
acquirer_bin	string	Optional	The Acquirer BIN (specific to the directory_server). Maximum length: 5000
acquirer_country	string	Optional	The two-letter country code of the acquirer ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). Maximum length: 5000
acquirer_merchant_id	string	Optional	The Merchant ID (or Card Acceptor ID) that your acquirer assigned you (specific to the directory_server). Maximum length: 5000
mcc	string	Optional	The [merchant category code](https://en.wikipedia.org/wiki/Merchant_category_code) as defined by each payment system or directory server. Maximum length: 5000
merchant_name	string	Optional	The merchant name assigned by the acquirer or payment system. Same name used in the authorization message as defined in [ISO 8583](https://en.wikipedia.org/wiki/ISO_8583). Maximum length: 5000
requestor_id	string	Optional	Requestor ID if you’re enrolled in the card network’s 3DS program. Otherwise, you can omit this field because Stripe assigns a Requestor ID with the card networks. Maximum length: 5000

Cancel a 3 DS Authentication — response body — channel

Field	Type	Presence	Description and constraints
$	object	Root	Contains details on the channel used (browser, 3RI) for a standalone 3DS Authentication.
browser	Model	Optional	Expand Cancel a 3 DS Authentication — response body — channel browser
three_r_i	Model	Optional	Expand Cancel a 3 DS Authentication — response body — channel three r i
type	string	Required within parent	Type of channel you would prefer to use for this 3DS Authentication. Only browser. Known values: browser, three_r_i

Referenced models: Cancel a 3 DS Authentication — response body — channel browser, Cancel a 3 DS Authentication — response body — channel three r i

Cancel a 3 DS Authentication — response body — flow preference

Field	Type	Presence	Description and constraints
$	object	Root	Contains details of the flow preference used for a standalone 3DS Authentication.
challenge	Model	Optional	Expand Cancel a 3 DS Authentication — response body — flow preference challenge
data_share	Model	Optional	Expand Cancel a 3 DS Authentication — response body — flow preference data share
frictionless	Model	Optional	Expand Cancel a 3 DS Authentication — response body — flow preference frictionless
type	string	Required within parent	Type of flow you requested for this 3DS Authentication. Known values: challenge, data_share, frictionless

Referenced models: Cancel a 3 DS Authentication — response body — flow preference challenge, Cancel a 3 DS Authentication — response body — flow preference data share, Cancel a 3 DS Authentication — response body — flow preference frictionless

Cancel a 3 DS Authentication — response body — future usage

Field	Type	Presence	Description and constraints
$	object	Root	Contains information about the future authorisations related to this authentication
installment	Model	Optional	Expand Cancel a 3 DS Authentication — response body — future usage installment
recurring	Model	Optional	Expand Cancel a 3 DS Authentication — response body — future usage recurring
type	string	Required within parent	The type of future usage declared for this 3DS Authentication. Known values: card_on_file, installment, recurring

Referenced models: Cancel a 3 DS Authentication — response body — future usage installment, Cancel a 3 DS Authentication — response body — future usage recurring

Create a Payment Method — response body — zip

Field	Type	Presence	Description and constraints
$	object	Root

Policy, approvals and errors

SDK function policy ID: stripe.postthreedsecureauthentications. Catalog operation: PostThreeDSecureAuthentications. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Pinned headers: {"Stripe-Version": "2026-09-30.endive"}

Official provider source