Import 3D Secure results

Importing 3D Secure results is an advanced payment flow that allows you to incorporate your external 3D Secure authentication into your Stripe payment by importing the authentication result. You need to import 3D Secure results if you:

• Are in the travel industry and receive card numbers and cryptograms from a travel aggregator, such as Expedia or Sabre
• Use a third-party provider to perform 3D Secure

In these situations, you can pass the card details and cryptogram directly to the Payment Intents API instead of using Stripe Elements to collect payment details and run 3D Secure.

Available in:

Beta All other countries in which Stripe supports card payments.

Not Available in:

Process a payment with card details

If you handle card details on your server:

1. Create and confirm a PaymentIntent with the card details and 3D Secure details in one API call.
2. When creating the PaymentIntent, set confirm to true.
3. Set error_on_requires_action to true when you confirm the PaymentIntent to prevent Stripe from performing a 3DS request during a soft decline.

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d amount=2000 \
  -d currency=eur \
  -d "payment_method_types[]"=card \
  -d "payment_method_data[type]"=card \
  -d "payment_method_data[card][number]"=4000002760003184 \
  -d "payment_method_data[card][exp_month]"=12 \
  -d "payment_method_data[card][exp_year]"=23 \
  -d "payment_method_data[card][cvc]"=123 \
  -d "payment_method_options[card][three_d_secure][version]"="2.1.0" \
  -d "payment_method_options[card][three_d_secure][electronic_commerce_indicator]"=05 \
  --data-urlencode "payment_method_options[card][three_d_secure][cryptogram]"="CJSJbzXT6TRQlvZDX+ZdOG4QriE=" \
  -d "payment_method_options[card][three_d_secure][transaction_id]"=aaa65c7b-b0fc-4e71-bd6c-29c87acad489 \
  -d confirm=true \
  -d error_on_requires_action=true

Process a payment with a PaymentMethod

If you tokenize card details with the Payment Methods API:

1. Create and confirm a PaymentIntent with the PaymentMethod ID and 3D Secure details in one API call.
2. When creating the PaymentIntent, set confirm to true.
3. Set error_on_requires_action to true when you confirm the PaymentIntent to prevent Stripe from performing a 3DS request during a soft decline.

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d amount=2000 \
  -d currency=eur \
  -d "payment_method_types[]"=card \
  -d customer=
{{CUSTOMER_ID}} \
  -d payment_method=
{{PAYMENT_METHOD_ID}} \
  -d "payment_method_options[card][three_d_secure][version]"="2.2.0" \
  -d "payment_method_options[card][three_d_secure][electronic_commerce_indicator]"=02 \
  --data-urlencode "payment_method_options[card][three_d_secure][cryptogram]"="M6+990I6FLD8Y6rZz9d5QbfrMNY=" \
  -d "payment_method_options[card][three_d_secure][transaction_id]"=f879ea1c-aa2c-4441-806d-e30406466d79 \
  -d confirm=true \
  -d error_on_requires_action=true

Set up future payments

The 3DS protocol supports two message categories:

• Payment Authentication: used for authenticating cardholders during transactions.
• Non-Payment Authentication: used for identity verification and account confirmation.

If you want to onboard customers for future payments, include the non-payment authentication cryptogram and either the card details or PaymentMethod ID when creating and confirming a SetupIntent.

curl https://api.stripe.com/v1/setup_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d "payment_method_types[]"=card \
  -d customer=
{{CUSTOMER_ID}} \
  -d payment_method=
{{PAYMENT_METHOD_ID}} \
  -d "payment_method_options[card][three_d_secure][version]"="2.2.0" \
  -d "payment_method_options[card][three_d_secure][electronic_commerce_indicator]"=05 \
  --data-urlencode "payment_method_options[card][three_d_secure][cryptogram]"=4BQwsg4yuKt0S1LI1nDZTcO9vUM= \
  -d "payment_method_options[card][three_d_secure][transaction_id]"=f879ea1c-aa2c-4441-806d-e30406466d79 \
  -d confirm=true \
  -d "expand[]"=latest_attempt

Import 3DS exempted outcomes

If you obtain a 3D Secure result outside of Stripe that contains a ‘low-risk’ SCA exemption, you can flag the exemption-based nature of the 3D Secure result to Stripe by using the exemption_indicator parameter.

If Stripe’s real-time transaction risk analysis determines that it’s appropriate, Stripe requests the low-risk exemption from the issuer and communicates this action to you by returning exemption_indicator_applied in to the authorization request response.

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d amount=2000 \
  -d currency=eur \
  -d "payment_method_types[]"=card \
  -d payment_method=
{{PAYMENT_METHOD_ID}} \
  -d "payment_method_options[card][three_d_secure][version]"="2.2.0" \
  -d "payment_method_options[card][three_d_secure][electronic_commerce_indicator]"=07 \
  --data-urlencode "payment_method_options[card][three_d_secure][cryptogram]"="CJSJbzXT6TRQlvZDX+ZdOG4QriE=" \
  -d "payment_method_options[card][three_d_secure][transaction_id]"=aaa65c7b-b0fc-4e71-bd6c-29c87acad489 \
  -d "payment_method_options[card][three_d_secure][exemption_indicator]"=low_risk \
  -d confirm=true \
  -d error_on_requires_action=true \
  -d "expand[]"=latest_charge

To see whether Stripe requested the low-risk exemption, expand the latest_charge and inspect the three_d_secure attribute.

{
    "id": "pi_3aTnU0Aif3fLhNTb0le1BSXI",
    "object": "payment_intent",
    // ...
    "latest_charge": {
        "id": "ch_3aTnU1AifffLhNTb0tUoEZcd",
        "object": "charge",
        // ...
        "payment_method_details": {
            "card": {

Importing Cartes Bancaires outcomes

To use 3DS Import for transactions that process on the Cartes Bancaires network, you need to explicitly pass card brand choice in your request using the network parameter.

To import Cartes Bancaires cryptograms, you also need additional data from your external 3DS server. The table below specifies the details of these additional required and recommended fields.

Provide as many of these additional fields as possible to increase the chances of a successful authorization.

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d amount=2000 \
  -d currency=eur \
  -d "payment_method_types[]"=card \
  -d payment_method=
{{PAYMENT_METHOD_ID}} \
  -d "payment_method_options[card][network]"=cartes_bancaires \
  -d "payment_method_options[card][three_d_secure][version]"="2.2.0" \
  -d "payment_method_options[card][three_d_secure][electronic_commerce_indicator]"=05 \
  --data-urlencode "payment_method_options[card][three_d_secure][cryptogram]"="CJSJbzXT6TRQlvZDX+ZdOG4QriE=" \
  -d "payment_method_options[card][three_d_secure][transaction_id]"=aaa65c7b-b0fc-4e71-bd6c-29c87acad489 \
  -d "payment_method_options[card][three_d_secure][requestor_challenge_indicator]"=02 \
  -d "payment_method_options[card][three_d_secure][ares_trans_status]"=Y \
  -d "payment_method_options[card][three_d_secure][network_options][cartes_bancaires][cb_avalgo]"=1 \
  -d "payment_method_options[card][three_d_secure][network_options][cartes_bancaires][cb_score]"=9 \
  -d "payment_method_options[card][three_d_secure][network_options][cartes_bancaires][cb_exemption]"=BAAA \
  -d confirm=true \
  -d error_on_requires_action=true

Exemptions with Cartes Bancaires

If you have been granted an SCA exemption over 3DS, you must submit either the cb_exemption parameter, the exemption_indicator parameter, or both. If either of these parameters indicates that the exemption is low risk due to acquirer transaction risk analysis, Stripe reassesses the transaction, as described in Import 3DS exempted outcomes.

• If you have access to cb_exemption, pass that value and don’t populate exemption_indicator. Stripe infers the appropriate exemption indicator based on cb_exemption.
• If you pass both the cb_exemption parameter and exemption_indicator parameter, make sure that they both correctly indicate the exempted status.
• If there’s a mismatch where exemption_indicator=none and the bitmap in cb_exemption indicates that the applied exemption is a low risk exemption, Stripe rejects the request.

Testing

You can validate your integration in test mode using either the authentication required test card: 4000 0027 6000 3184 or pm_card_authenticationRequired.

The simulation accepts any correctly-formatted 3D Secure result. For example:

• Version: 2.1.0
• Electronic Commerce Indicator: 02
• Cryptogram: M6+990I6FLD8Y6rZz9d5QbfrMNY=
• Transaction ID: 5f5d08f2-8c36-4f72-99d1-57b4fb70b7d5

Or:

• Version: 2.2.0
• Electronic Commerce Indicator: 05
• Cryptogram: 4BQwsg4yuKt0S1LI1nDZTcO9vUM=
• Transaction ID: f879ea1c-aa2c-4441-806d-e30406466d79

Exemptions granted through 3DS

In test mode, all cards that include exemption_indicator return exemption_indicator_applied as true. To test a PaymentIntent creation that doesn’t pass the internal TRA check, and that returns false, use card number 4000 0000 0001 6123 and set exemption_indicator=low_risk.

Cartes Bancaires

You can use the following co-badged cards to test importing Cartes Bancaires outcomes:

You can use any valid cb_exemption value in your tests. For example:

• AAAA - No exemption granted
• BAAA - Low risk exemption granted

Like the standard exemptions flow, when the value of cb_exemption corresponds to low risk, only the test card 4000 0000 0001 6123 returns false for exemption_indicator_applied.

Raw PAN usage

Stripe requires users to validate that cardholder data is handled securely and in compliance with the Payment Card Industry Data Security Standard (PCI DSS) before granting access to raw card data APIs.

For businesses that require this functionality, Stripe imposes stringent requirements, including:

• Validation of PCI DSS compliance
• Submission to Stripe’s rigorous review process
• Agreement to maintain additional controls on top of Stripe’s default security settings

See Enabling access to raw card data APIs support article for enablement details.