3D Secure card payments with Sources

Use Sources to accept card payments verified using 3D Secure, an additional layer of authentication that protects you from liability for fraudulent card payments.

Use of this API is no longer recommended. If you wish to use 3D Secure, we strongly encourage you to adopt the Payment Intents API. This new integration lets you benefit from Dynamic 3D Secure, supports 3D Secure 2, and helps you support Strong Customer Authentication regulation in Europe.

Stripe users in the United States, Canada, Europe, Hong Kong, Singapore, Japan, Australia, and New Zealand can process card payments that require authentication with 3D Secure using Sources—a single integration path for creating payments using any supported method. Users in other countries that Stripe supports can request an invite.

The process for 3D Secure card payments begins in the same way as regular card payments with your integration first creating a Source object that represents the card information. Instead of using this source to make a charge request, it’s used to create a 3D Secure Source object. Your customer is then potentially redirected to their card issuer’s website to verify their identity using 3D Secure.

Once completed, your integration uses the 3D Secure source to make a charge request and complete the payment. You then have the option of saving the card information to use for future payments.

Within the scope of Sources, 3D Secure card payments are a pull-based, single-use and synchronous method of payment. This means that your integration takes action to debit the amount from the customer’s card and there is immediate confirmation about the success or failure of a payment.

Handling card information

Card information is sensitive by nature. Card sources must be created client-side using Stripe.js and Elements. This ensures that no sensitive card data passes through your server so your integration can operate in a PCI compliant way.

When your customer submits their card information using your payment form, it is sent directly to Stripe, and a representative Source object is returned for you to use. The process is similar to the creation of tokens. If you’re already using Elements to tokenize card information, switching to sources is only a small change.

Create a card Source object using Elements

To create a card Source client-side, create a payment form. You then create a Source object instead of a token by calling the createSource instead of the createToken method.

// Create a source or display an error when the form is submitted.
var form = document.getElementById('payment-form');
form.addEventListener('submit', function(event) {
  event.preventDefault();

  stripe.createSource(card).then(function(result) {
    if (result.error) {
      // Inform the user if there was an error
      var errorElement = document.getElementById('card-errors');
      errorElement.textContent = result.error.message;
    } else {
      // Send the source to your server
      stripeSourceHandler(result.source);
    }
  });
});

Refer to the last steps of accepting a payment to submit the source, along with any additional information that has been collected, to your server.

function stripeSourceHandler(source) {
  // Insert the source ID into the form so it gets submitted to the server
  var form = document.getElementById('payment-form');
  var hiddenInput = document.createElement('input');
  hiddenInput.setAttribute('type', 'hidden');
  hiddenInput.setAttribute('name', 'stripeSource');
  hiddenInput.setAttribute('value', source.id);
  form.appendChild(hiddenInput);

  // Submit the form
  form.submit();
}

Once the source is created, you can either proceed with a regular card payment and make a charge request, or continue with the 3D Secure process.

Source creation in mobile applications

If you’re building an iOS or Android app, you can implement sources using our mobile SDKs. Refer to our sources documentation for iOS or Android to learn more.

Determine if the card supports or requires 3D Secure

The behavior of, and support for, 3D Secure can vary across card networks and types. For cards that are not supported, perform a regular card payment instead.

Some card issuers, however, require the use of 3D Secure to reduce the risk for fraud, declining all charges that do not use this process. So you can best handle these different situations, check the card.three_d_secure attribute value of the card source before continuing with the 3D Secure process.

Value	Description
`required`	3D Secure is required, and the process must be completed for a charge to be successful.
`recommended`	3D Secure is recommended. The process is not required, but it is highly recommended and has minimal impact to your conversion rate.
`optional`	3D Secure is optional. The process is neither required nor recommended, but it can be performed to help reduce the likelihood of fraud.
`not_supported`	3D Secure is not supported on this card. Proceed with a regular card payment instead.

Charges made after successfully completing the 3D Secure process are covered by a liability shift.

At this stage, you can either proceed with the rest of the 3D Secure process below or perform a regular card payment (if 3D Secure is not supported).

Create a 3D Secure Source object

Using the card source that has been created with Stripe.js, a 3D Secure Source object is then created. This can be created client-side using Stripe.js or server-side using the API, providing the following values:

Parameter	Value
`type`	three_d_secure
`amount`	A positive integer in the smallest currency unit representing the amount to charge the customer (e.g., 1099 for a €10.99 payment).
`currency`	The currency the payment is being created in (e.g., eur).
`redirect[return_url]`	The URL the customer should be redirected to after the verification process.
`three_d_secure[card]`	The ID of the card source.

Client-side source creation

stripe.createSource({
  type: 'three_d_secure',
  amount: 1099,
  currency: "eur",
  three_d_secure: {
    card: "src_19YP2AAHEMiOZZp1Di4rt1K6"
  },
  redirect: {
    return_url: "https://shop.example.com/crtA6B28E1"
  }
}).then(function(result) {
  // handle result.error or result.source
});

Server-side source creation

Terminal

curl https://api.stripe.com/v1/sources \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d amount=1099 \
  -d currency=eur \
  -d type="three_d_secure" \
  -d "redirect[return_url]"="https://shop.example.com/crtA6B28E1" \
  -d "three_d_secure[card]"=src_19YP2AAHEMiOZZp1Di4rt1K6 \

Using either method, Stripe returns a Source object containing the relevant details for the method of payment used. Information specific to 3D Secure is provided within the three_d_secure subhash.

{
  "id": "src_19YlvWAHEMiOZZp1QQlOD79v",
  "object": "source",
  "amount": 1099,
  "client_secret": "src_client_secret_kBwCSm6Xz5MQETiJ43hUH8qv",
  "created": 1483663790,
  "currency": "eur",
  "flow": "redirect",
  "livemode": false,
  "metadata": {},

As 3D Secure card payments are a pull-based payment method, there is no movement of funds during the creation of a source. Only when a charge request has been made, and the payment is successful, is the customer’s card debited and you receive the funds.

Checking if verification is still required

When creating a 3D Secure source, its status is most commonly first set to pending and cannot yet be used to create a charge. In some cases, a 3D Secure source’s status can be immediately set to chargeable. This can happen if the customer’s card supports 3D Secure, but it has not yet been enrolled by the card issuer. Should this occur, the redirect.status value is set to not_required and three_d_secure.authenticated set to false.

For supported cards that have not been enrolled for 3D Secure, liability shift still occurs for any charges you create using 3D Secure sources—even though the 3D Secure process is not performed.

The status attribute of the 3D Secure source is immediately set to failed if the card does not support 3D Secure, or there was a technical failure (e.g., the card issuer’s 3D Secure service is down). Should this occur, you can either continue with a regular card payment, interrupt the payment flow, or attempt to create a 3D Secure source later.

Error codes

Source creation for 3D Secure card payments may return any of the following errors:

Error	Description
`payment_method_not_available`	The payment method is currently not available. You should invite your customer to fallback to another payment method to proceed.
`processing_error`	An unexpected error occurred preventing us from creating the source. The source creation should be retried.

Have the customer complete 3D Secure verification

Once you determine if the card supports or requires 3D Secure, your customer must successfully verify their identity with their card issuer to make the source chargeable. To allow your customer to verify their identity using 3D Secure, redirect them to the URL provided within theredirect[url] attribute of the Source object.

After the verification process, your customer is redirected back to the URL provided as a value of redirect[return_url]. This happens regardless of whether verification was successful or not. If the customer has completed verification, the Source object’s status is updated to chargeable and it is ready to use in a charge request. If not, the status transitions to failed.

Stripe populates the redirect[return_url] with the following GET parameters when returning your customer to your website:

source: a string representing the original ID of the Source object
livemode: indicates if this is a live payment, either true or false
client_secret: used to confirm that the returning customer is the same one who triggered the creation of the source (source IDs are not considered secret)

You may include any other GET parameters you may need when specifying redirect[return_url]. Do not use the above as parameter names yourself as these would be overridden with the values we populate.

Mobile applications

To integrate 3D Secure within a mobile application, provide your application URI scheme as the redirect[return_url] value. By doing so, your customers are returned to your app after completing authorization. Refer to our Sources documentation for iOS or Android to learn more.

If you are integrating without using our mobile SDKs, the redirect URL must be opened using the device’s native browser. The use of in-app web views and containers can prevent your customer from completing authentication—resulting in a lower conversion rate.

No verification required

If the customer’s card is enrolled in 3D Secure but the card issuer has not implemented additional authentication steps, your customer may not have to complete verification during the redirect. In that case, the source’s three_d_secure.authenticated attribute is set to false.

Charge the Source

Once the customer has authenticated the payment, the source’s status transitions to chargeable and it can be used to make a charge request. This transition happens asynchronously and may occur after the customer was redirected back to your website.

Customers may also assume that the order process is complete once they have completed the 3D Secure authentication flow. This can result in the customers closing their browser instead of completing the redirection back to your app or website.

For these reasons it is essential that your integration rely on webhooks to determine when the source becomes chargeable in order to create a charge. Please refer to our best practices for more details on how to best integrate payment methods using webhooks.

Webhooks

The following webhook events are also sent to notify you about changes to the source’s status:

Event	Description
`source.chargeable`	A `Source` object becomes `chargeable` after a customer has authenticated and verified a payment.
`source.failed`	A `Source` object failed to become chargeable as your customer declined or failed to authenticate the payment.
`source.canceled`	A `Source` object expired and cannot be used to create a charge.

Make a charge request using the source

Once the source is chargeable, from your source.chargeable webhook handler, you can make a charge request using the source ID as the value for the source parameter to complete the payment.

Terminal

curl https://api.stripe.com/v1/charges \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d amount="1099" \
  -d currency="eur" \
  -d source=src_18eYalAHEMiOZZp1l9ZTjSU0

Confirm that the charge has succeeded and the payment is complete

Since 3D Secure-based card payments is a synchronous payment method, the Charge object’s status immediately reflects whether or not it has been successful. One of the following events is sent when the charge is created depending on its state.

Event	Description
`charge.succeeded`	The charge succeeded and the payment is complete.
`charge.failed`	The charge has failed and the payment could not be completed.

We recommend that you rely on these webhook events to notify your customer about the payment success or failure. Please refer to our best practices for more details on how to best integrate payment methods using webhooks.

Disputed payments and liability shift

Payments that have been successfully authenticated using 3D Secure are covered by a liability shift. Should a 3D Secure payment be disputed as fraudulent by the cardholder, the liability shifts from you to the card issuer. These types of disputes are handled internally, do not appear in the Dashboard, and do not result in funds being withdrawn from your Stripe account.

Should a customer dispute a payment for any other reason (e.g., product not received), then the standard dispute process applies. As such, you should make the appropriate decisions regarding your business and how you manage disputes, if they occur, and how to avoid them completely.

When a customer successfully completes 3D Secure authentication, the value of redirect.status is set to succeeded and three_d_secure.authenticated is set to true. If the cardholder disputes the payment as fraudulent, liability has shifted to the card issuer.

Liability shift can also occur when 3D Secure 1 is required by the card network, but 3D Secure isn’t available for the card or issuer. This can happen if the issuer’s 3D Secure server is down or if the issuer does not support 3D Secure, despite the card network requiring 3D Secure support. During the payment process, the cardholder isn’t prompted to complete 3D Secure authentication, since the card is not enrolled. Instead, the value of redirect.status automatically transitions to not_required, though the value of three_d_secure.authenticated is false. Although the cardholder did not complete 3D Secure authentication, liability still shifts to the issuer.

Liability shift cannot occur if the card does not support 3D Secure (in that case, the value of card.three_d_secure is not_supported), or if you charge the card source instead of the 3D Secure source of a card that supports it.

There are certain circumstances where payments that are successfully authenticated using 3D Secure do not experience a liability shift. This is rare and can happen, for example, if you have an excessive level of fraud on your account and are enrolled in a fraud monitoring program.

Source expiration

A chargeable 3DSecure source must be charged within six hours of becoming chargeable. If it is not, its status is automatically transitioned to canceled and your integration receives a source.canceled webhook event. Make sure the order is canceled on your end and the customer is notified when you receive the source.canceled event.

Additionally, pending sources are canceled after one hour if they are not used to authenticate a payment, ensuring that all sources eventually transition out of their pending state to the canceled state if they are not used.

Saving 3D Secure card information for later

Once the 3D Secure source has been used to make a successful payment, you can save the original card source to a new Customer object.

Terminal

curl https://api.stripe.com/v1/customers \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "email"="paying.user@example.com" \
  -d "source"="src_18eYalAHEMiOZZp1l9ZTjSU0"

The ID of the card source can be retrieved from the 3D Secure source as the value of the three_d_secure.card attribute.

Since the 3D Secure process has already taken place, you can create additional payments using the customer as normal.

Terminal

curl https://api.stripe.com/v1/charges \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "amount"=1099 \
  -d "currency"="eur" \
  -d "customer"="cus_VWaMywLC4keKS6"

As the 3D Secure process isn’t performed when using saved card information to make a charge request, future payments are not protected by 3D Secure’s liability shift.

3D Secure cards and subscriptions

If you wish to make use of 3D Secure-enabled cards for subscription payments, there are some additional steps you can take to ensure they are handled correctly.

Testing 3D Secure payments

Not all cards support 3D Secure or require the customer be redirected to their card issuer’s authentication page. You can use the following card information to fully test 3D Secure payments. Each of these card sources returns a different value for the card.three_d_secure property.

Status	Allowed?	Required?	Description
`required`	Yes	Yes	3D Secure must be completed for a charge to be successful.
`recommended`	Yes	No	Charges succeed whether 3D Secure is used or not.
`optional`	Yes	No	Charges succeed whether 3D Secure is used or not. 3D secure may still be performed, but is not required.
`optional`	Yes	No	Charges succeed whether 3D Secure is used or not. If 3D Secure is used, the source is immediately chargeable (the value of `redirect.status` is `not_required`).
`not_supported`	No	No	Proceed with a regular card payment.
`required`	Yes	Yes	3D Secure authentication is required, but charge will still be declined with a `card_declined` after authentication.

All other Visa and Mastercard test cards do not require verification from the customer’s card issuer. The card source status is immediately set to chargeable upon source creation.

Testing the redirect process

When creating a Source object using your test API keys, you can follow the URL returned in the redirect[url] field. This leads to a Stripe page that displays information about the API request, and where you can either authorize or cancel the payment. Authorizing the payment redirects you to the URL specified in redirect[return_url].

Clicking on the Failure button results in the 3D Secure source status transitioning to failed.

Next steps

Congrats! You’ve learned about processing 3D Secure-based card payments using Sources. Some documentation you might want to read next: