Cardholder authentication using 3D Secure (2024)

How 3D Secure works

3D Secure (3DS) uses multi-factor authentication to reduce fraud for online transactions where a card isn’t physically present. 3DS is triggered by businesses in online checkout flows, and requires multi-factor authentication (usually through SMS or email-based one-time passcode that Stripe sends) to complete.

Example of a 3D Secure flow

As shown above, the additional 3D Secure step at checkout typically involves showing the cardholder an authentication page from their Issuer, where the cardholder sees a prompt to enter a verification code sent to their phone or email.

Why 3DS is important

In most cases, businesses are responsible for online fraud losses in card-not-present transactions. To protect themselves, businesses can trigger 3DS verification to reduce the chances of accepting a fraudulent transaction. Even if a business triggers 3DS verification, the cardholder only needs to complete the step if your Stripe cards are enrolled in 3DS. In the UK and EU, 3DS is the standard for implementing the regulatory requirements of Strong Customer Authentication (SCA).

Liability shift

When a business triggers 3DS verification, liability for fraud shifts from the business to the issuer in most cases. This applies whether or not your Issuing cards are enrolled in 3DS, meaning issuers can take on increased liability without any additional verification.

3DS Enrollment

• US: 3DS enrollment in the US is optional, and your cards won’t be enrolled in 3DS unless you contact support to request enrollment. As part of our best practices for managing transaction fraud, we recommend enrolling your cards in 3DS early in your Issuing program’s life cycle. While enrollment does increase friction for a subset of your cardholder transactions, it helps to significantly reduce the risk of potential losses because of transaction fraud with online, card-not-present transactions. After you request enrollment, we enroll all active cards associated with your account and automatically enroll all cards created going forward.
  • Cardholders without a phone number or email on file won’t be enrolled in 3DS. After requesting enrollment, you can add contact information to Cardholder objects, to auto-enroll those cards. Conversely, removing the contact info for a cardholder results in the card being unenrolled from 3DS.
• UK and EU: Upon creation, cards are enrolled in 3DS by default because of local regulations.
  • To allow the implementation of SCA over 3DS and comply with local regulations, all cards issued within the EU and UK require a valid phone number on file.

3DS Authentication

When a 3DS authentication request comes through for your cardholder, Stripe sends them either a text message or an email containing a one-time verification code.

The method of authentication depends on the contact information provided for the cardholder. In the UK and EU markets supported by Stripe Issuing, cardholders must have a phone number on file to authenticate with a one-time text message verification code. In the US, the phone number or email on file will be used to authenticate cardholders, but if both the phone number and email are present, then the phone number will be used for authentication. Otherwise, the authentication request uses whichever contact information is available. To enable us to best secure you and your cardholders, we recommend keeping phone numbers and email addresses up to date for cardholders. This enables us to contact them during authentication. You can update your cardholders’ information by changing the field to its new value through the API or Dashboard.

In the UK and EU, cardholders might also see an additional security question. The cardholder sees a list of transactions on the card, and they can select the transactions they recognize. If the cardholder is using the card for the first time, they select the option indicating they don’t recognize any of the presented transactions.

Choose the 3D Secure language

The preferred_locales field of the Cardholder object determines the display language of the 3DS flow. The default 3DS language is English.

To pick a 3DS language for a cardholder, use the API to set their preferred_locales to an array of preferred languages, in order of preference. If you want, you can provide one language only. The supported languages are English (en), French (fr), German (de), Italian (it), and Spanish (es).

curl https://api.stripe.com/v1/issuing/cardholders \ -u "
sk_test_26PHem9AhJZvU623DfE1x4sd
:" \ -d type=individual \ -d name="Jane D. Rocket" \ --data-urlencode email="[email protected]" \ -d "preferred_locales[]"=fr \ -d "preferred_locales[]"=en \ -d "billing[address][line1]"="1234 Main Street" \ -d "billing[address][city]"="San Francisco" \ -d "billing[address][state]"=CA \ -d "billing[address][country]"=US \ -d "billing[address][postal_code]"=94111

In the US, Stripe also supports authentication through a native iOS and Android application. If you want to use this functionality, please reach out to support.

Regardless of the authentication method used, if a cardholder can’t complete three consecutive 3DS attempts in a short period of time, it disables 3DS on their cards for 60 minutes.

Exemptions

Certain types of low-risk payments might be exempt from SCA. Exemptions limit friction for low-risk payments by reducing the frequency of customer authentication. By default, Stripe might claim the following exemptions for 3DS-eligible cards to limit the friction associated with transactions it deems low risk or low value:

When an issuer-claimed exemption is applied, the Authorization object looks like this:

{ "object": "issuing.authorization", ... "verification_data" : { ... "authentication_exemption": { "type": "low_value_transaction", "claimed_by": "issuer" }, ... }, ...}

Conversely, when an acquirer-claimed exemption is applied, the Authorization object looks like this:

{ "object": "issuing.authorization", ... "verification_data" : { ... "authentication_exemption": { "type": "low_value_transaction", "claimed_by": "acquirer" }, ... }, ...}

If you’re based in the UK or EU and your use case only requires virtual cards, you can contact Stripe Support to discuss whether a Secure Corporate Payment (SCP) exemption is applicable to your program.

Managing fraud through 3DS

Stripe includes details about a 3DS attempt through the API in the authorization endpoint. Use the three_d_secure hash in the verification_data hash to determine if an authorization was successfully authenticated. If you maintain your own authorization logic, we suggest using these values as key inputs that determine whether to approve or reject an authorization.

Additionally, if the business didn’t attempt 3DS, the three_d_secure field is null. If 3DS was exempted, then the authentication_exemption is present and the three_d_secure field is null. An authorization can’t contain both three_d_secure and authentication_exemption.

You can find guidelines on what the values represent and how you can use them to combat fraud in the table below.

How to test 3DS

Use the Stripe Payments API to test 3DS.

Create a PaymentMethod with your issued card

You can create a PaymentMethod using your own issued card by running the following command:

curl https://api.stripe.com/v1/payment_methods \  -u 
pk_test_qblFNYngBkEdjEZ16jxxoWSM
: \  -d type=card \  -d "card[number]"=YOUR_ISSUED_CARD_NUMBER \  -d "card[exp_month]"=YOUR_ISSUED_CARD_EXPIRATION_MONTH \  -d "card[exp_year]"=YOUR_ISSUED_CARD_EXPIRATION_YEAR \  -d "card[cvc]"=YOUR_ISSUED_CARD_CVC

Replace the following values:

• YOUR_ISSUED_CARD_NUMBER with the card number of your issued card
• YOUR_ISSUED_CARD_CVC with the CVC of your issued card
• YOUR_ISSUED_CARD_EXPIRATION_MONTH with the expiration month of your issued card
• YOUR_ISSUED_CARD_EXPIRATION_YEAR with the expiration year of your issued card

Create a PaymentIntent

You can create a PaymentIntent by running the following command:

curl https://api.stripe.com/v1/payment_intents \  -u 
sk_test_26PHem9AhJZvU623DfE1x4sd
: \  -d amount=15000 \  -d currency=usd \  -d "payment_method_types[]"=card \  -d "payment_method_options[card][request_three_d_secure]"=any \  -d "capture_method"=manual

This command creates a PaymentIntent that initiates a 3D Secure authentication request. Use the payment_method_options[card][request_three_d_secure]=any parameter to perform 3D Secure authentication. The amount must be large enough to warrant a challenge. This example uses 150 USD.

The "capture_method"=manual parameter enables manual capture for the PaymentIntent, which means the funds are authorized but not captured yet.

Confirm the PaymentIntent

You can confirm the PaymentIntent by running the following command:

curl https://api.stripe.com/v1/payment_intents/pi_XXX/confirm \  -u 
sk_test_26PHem9AhJZvU623DfE1x4sd
: \  -d payment_method=pm_XXX \  -d return_url=https://www.example.com

Replace pi_XXX with your PaymentIntent ID and pm_XXX with your PaymentMethod ID. After confirming the PaymentIntent, the response you receive contains the next_action field. That field includes a URL that you can use to redirect the user to complete 3DS authentication.

..."next_action": { "redirect_to_url": { "return_url": "https://www.example.com ", "url": "https://hooks.stripe.com/3d_secure_2/hosted?...." }, "type": "redirect_to_url" },...

Void the authorization

After completing the 3DS challenge and payment authorization, you can cancel the PaymentIntent without capturing funds.

curl https://api.stripe.com/v1/payment_intents/pi_XXX/cancel \  -u 
sk_test_26PHem9AhJZvU623DfE1x4sd
: \  -d "cancellation_reason"=abandoned

Replace pi_XXX with your PaymentIntent ID.