SCA Migration Guide for Billing

    Updating your Billing implementation to support new Strong Customer Authentication (SCA) requirements.

    What is Strong Customer Authentication (SCA)?

    Strong Customer Authentication (SCA), a new rule that takes effect on September 14, 2019 as part of PSD2 regulation in Europe, will require changes to how your European customers authenticate online payments. This regulation applies to online payments where the customer’s bank and the business are both in the European Economic Area (EEA). Some businesses outside of Europe may also be impacted, depending on how European issuers implement the new authentication rules.

    SCA requires that businesses use two independent authentication elements to verify payments. In practice, this means a new payment step where your customers must confirm their payment using an authentication method like a password, hardware token, or biometric. 3D Secure 2—the new version of 3D Secure rolling out in 2019—will be the primary authentication method used to meet SCA requirements for card payments.

    Transactions that don’t meet these new authentication requirements or qualify for any exemption may be declined starting September 14, 2019.

    What’s changing?

    Due to the increased payment friction caused by SCA, you can expect to see longer collection times and lower conversion. Stripe Billing provides an easy to implement set of tools to maximize your revenue under these constraints. There are some changes you will need to make to your integration:

    • New Subscription statuses to facilitate initial subscription payment
    • PaymentIntents that are now exposed on invoices as a mechanism for multi-state payments
    • A new webhook when SCA is required for payment
    • An updated Hosted Invoice Page allowing customers to complete the authentication step required by SCA
    • A new set of dunning emails to help collect payment when SCA is required

    How SCA impacts Billing

    SCA will impact card charges between EEA businesses and EEA customers, increasing the burden for recurring billing for two types of payments — on-session and off-session:

    Term Example Impact
    On-session Customer-present payments, such as an e-commerce checkout, or a subscription signup’s first charge. When SCA is required, your customer needs to provide payment authentication, usually by redirecting to their bank for authentication.
    Off-session A customer-not-present payment using a stored card, such as a monthly subscription automatically charged on its renewal date. When SCA is required, you need to reach out to your customer (e.g. via email) to get them on-session (present on your website or app) so you can take them through the on-session flow.

    Updating your Billing integration to support SCA

    There are a few key scenarios that need to be covered in order to be SCA-ready. Determine which are relevant to your integration, and the required changes for each:

    Scenario 1: On-session First Charge - Charging immediately

    Challenge: When charging immediately, your customers’ first charge for a subscription will require SCA. This means you need to add handling for an authentication flow in your application checkout or signup flow. When setting up a subscription for the first time, customers are on-session. This means that they’re on a browser/app and able to react to your prompts.

    When setting up a subscription that bills immediately, Stripe attempts to charge the card on file for your customer as part of the call to POST /v1/subscriptions (or calls to POST /v1/customers that generate subscriptions).

    Step 1: Subscription creation

    In order to opt-in to SCA support for your subscriptions, you have two options:

    Option 1: Use the enable_incomplete_payments flag

    If you do not upgrade your API version, but pass a new enable_incomplete_payments=true flag on subscription create & update, you will receive this same behavior. See the FAQ at the bottom of this document for a complete list of endpoints you’ll need to pass this flag to.

    If you do not upgrade your API version, and do not pass the enable_incomplete_payments flag, attempts to create subscriptions that fail due to SCA will return a card_error. This is consistent with our legacy behavior of failing subscription creation attempts that fail payment.

    Let’s explore the new subscription creation behavior in more detail:

    • When a payment succeeds, the subscription becomes status=active, and no further action is required.
    • When a payment fails, the subscription becomes status=incomplete and latest_invoice.payment_intent.status=requires_payment_method, and you should attempt payment with another payment method using POST /v1/invoices/:id/pay
    • When a payment requires SCA, the subscription becomes status=incomplete and latest_invoice.payment_intent.status=requires_action, and you should have your user complete a 3D Secure authentication flow using latest_invoice.payment_intent. The following “Handling SCA” section describes how to complete this flow.

    You may use our 3D Secure test cards to explore this behavior in your test environment. For step-by-step instructions on how to implement the subscription creation flow, look at this guide.

    Option 2: Upgrade your API integration

    If you upgrade to API version 2019-03-14 or later, creating a subscription that isn’t immediately successful (due to failed charges or SCA) enters the incomplete status described above.

    Step 2: Handling SCA

    In order to complete payment on a charge that requires SCA, you have two options at your disposal: using Stripe.js, or a browser-redirect flow.

    The suggested integration is to use the Stripe.js handleCardPayment method. This involves passing latest_invoice.payment_intent.client_secret into this method, which displays a modal that allows the user to provide authentication for their payment.

    Alternatively, if you prefer to not use Stripe.js, you can pass a return_url to the PaymentIntent confirmation endpoint and initiate a redirect flow. You can do so by calling:

    curl https://api.stripe.com/v1/payment_intents/:id/confirm \
      -u sk_test_key: \
      -d return_url="https://www.your-website.com/return_url"
    

    For step-by-step instructions on how to use the Payment Intents API to complete 3D Secure authentication for Billing, refer to this guide.

    After the user completes the redirect or modal flow, the subscription should be status=active and the invoice should be status=paid. Be aware that the user may quit their browser after authentication, but before being redirected. To provide more robust handling, we recommend listening to invoice webhooks, as described in the next section.

    Step 3: Provisioning and Fulfillment

    It’s possible that a user will leave their browser (by quitting or connection error) before either the handleCardPayment callback is executed, or the return_url redirect occurs. In this case, your application might not be aware that payment has completed, and the associated product might not be provisioned for your user. This is to be avoided if possible, to prevent customer disputes.

    For this reason, we recommend you listen to the invoice.payment_succeeded as outlined in this guide to ensure consistency between Stripe’s data and your own.

    Scenario 2: Off-session First Charge - Charging later

    Challenge: In cases where payment details are stored for later off-session use, authentication should ideally happen while the customer is on-session. This allows Stripe to claim exemptions on your behalf so that future off-session payments don’t require SCA.

    Examples where the first charge is delayed until a later date are free trials, metered billing, and $0 plans.

    While creating a subscription without immediately processing a payment, SCA rules allow for authentication to be collected in advance and applied to future payments as an exemption. Performing this type of authentication is beneficial because it allows you to complete the authentication flow while you have the user on-session, and skip 3D Secure in the future. This will result in better payment success rates by removing the friction off-session SCA collection introduces.

    SCA rules around subscriptions that don’t immediately process a payment are actively being developed by card networks. As a result, Stripe does not yet have an API interface to authenticate in this way. Stripe is actively developing in this area and will have an updated API to handle this case by July 2019. We expect any change in this area to be additive, and compatible with the rest of this guide.

    If you chose to build an SCA integration without this non-payment handling, your charge attempts may result in a blocked payment. Please refer to the “Off-session recurring Charge” scenario for details on how to handle SCA in this case.

    Scenario 3: Off-session recurring Charge

    Challenge: When the user’s billing-cycle has completed and it’s time to charge for service, you won’t have your customer on-session and ready to complete SCA if it’s required. You can use pre-built Stripe tools for doing this or create your own solution.

    When a billing-cycle date or a subscription threshold is reached, payment for the associated subscription will be attempted. If SCA is required for the associated charge, the subscription will have status=past_due. You have two options for getting the customer back on session and complete SCA:

    • Use Stripe’s pre-built tools — You can enable a set of emails specific to 3D Secure to be sent to your customers when SCA is required (See 3D Secure payment settings). Alternatively, if you want to send your own emails, but don’t want to build your own authentication flow, you can rely on our Hosted Invoice Page (See the Hosted Invoice Page section).
    • Add your own custom handling — Listen to the new invoice.payment_action_required webhook and/or the existing customer.subscription.updated webhook to be notified of subscriptions that become past_due due to invoices requiring SCA. When this happens, you will need to get your user back on-session (e.g.: via an email) and have them complete an authentication flow similar to what is discussed in Scenario #1.

    After the payment is authenticated and succeeds, the subscription will have status=active and invoice status=paid.

    Scenario 4: One-off invoices

    Challenge: One-off invoices may also be subject to SCA

    • If you already use our hosted invoice page, you get support for SCA out of the box with no changes required!
    • If you use billing=charge_automatically invoices that charge a card on file, you will need to get the user back on-session to complete SCA. You can do so with our Hosted Invoice Page, or through the custom handling described in Scenario 3.
    • If you have a flow in your application that makes direct use of POST /v1/invoices/:id/pay, this endpoint will return HTTP 402 whenever SCA is required. Use of the Hosted Invoice Page or custom handling is required.

    Tools for collecting off-session payments

    Stripe Billing offers a set of pre-built tools that can automatically handle payments that require 3D Secure authentication.

    You can choose to have Stripe take care of:

    • Emailing your customers when an off-session payment requires 3D Secure authentication.
    • Scheduling follow-up emails reminding them to complete authentication.
    • Providing a link to a hosted invoice payment page where they can complete authentication.

    You can customize the look and feel of these emails and the hosted invoice page in your Branding settings.

    Emails and dunning

    We’ve expanded our suite of customer emails (which already support sending invoices, receipts, failed payment notifications, and more) to include notifications when 3D Secure authentication is required for off-session payments.

    3D Secure payment settings

    The cadence of 3D Secure email delivery and the effect non-payment has on subscriptions can be configured in a new settings section. To manage these emails, navigate to your Billing settings, where you can turn on email notifications and set up a reminder schedule.

    Request for payment authentication using 3D Secure emails

    • We will have a configurable email template you can use to automatically send your customers an email asking them to authenticate to complete payment for their invoice or subscription.
    • On April 25, 2019, Stripe will launch a new feature that allows us to send emails on your behalf using a domain of your choosing. This update is intended to improve customer trust and payment rates.

    Hosted Invoice Page

    Stripe Billing provides a Hosted Invoice Page that supports all invoices. As part of our SCA support, we now handle 3D Secure authentication on that page.

    If an off-session payment requires the customer to complete 3D Secure authentication, you can send them a link to the hosted invoice page (via Stripe’s automatic emails or your own) where they’ll be asked to confirm their payment (or add a new payment method). Once they click confirm payment, we’ll display the 3D Secure 2 modal so they can complete authentication with their bank.

    SCA exemptions

    Within the SCA regulations will be a set of exemptions which may apply to any given payment attempt, meaning your customer may not need to provide additional authentication to confirm their payment.

    Stripe’s goal is to optimize your payment flow and attempt to automatically apply as many exemptions as possible in order to reduce the likelihood of your customers needing to authenticate. Work on the underlying logistics of these exemptions is still in progress at the card network level. Our confidence level is high that the only potential integration change that might be required in the future is described in Scenario #2 above.

    Summary of API changes

    To allow for the potential requirement of authentication in the payment flow, we’ve made a couple of additions to our API:

    Subscriptions have new statuses for SCA

    We’ve added two new statuses to the Subscription resource: incomplete and incomplete_expired. Subscriptions will enter the incomplete status only when the first charge is attempted and either fails or requires SCA. Any subscription that remains in the incomplete state and is not successfully paid will expire after 23 hours, automatically moving the status to incomplete_expired. Once a subscription is active it cannot enter incomplete again — future instances of payments requiring SCA will result in the subscription being past_due.

    Subscriptions now reference their latest invoice

    The subscription’s latest_invoice field provides a reference to the invoice affecting the status of a subscription.

    All invoices now use PaymentIntents for payment

    The Payment Intents API is Stripe’s new payment API that fully manage the lifecycle of a payment, including the new statuses a payment can enter. This includes a new requires_action status and an associated next_action payload which instructs you how to complete payment (usually through a redirect to the cardholder’s bank for authentication through 3D Secure authentication, using a URL embedded within the response). The Invoice object will now have a payment_intent you can rely on, in addition to the existing charge field.

    Stripe.js support for the Payment Intents API

    Because Stripe’s Billing Invoices are fully compatible with the Payment Intents API, you get the benefit of the Stripe.js helper functions to assist with your checkout payment flow. Specifically, the handleCardPayment JavaScript function will help you display a 3D Secure modal to collect the authentication information needed to complete payment.

    We fire the invoice.payment_action_required webhook when SCA is required

    When an invoice requires customer action, we will fire a new invoice.payment_action_required webhook containing the associated invoice. This webhook is meant to complement existing invoice.payment_succeeded and invoice.payment_failed webhooks.

    Frequently asked questions (FAQ)

    Does SCA apply to my business?

    Strong Customer Authentication (SCA) regulations apply to online payments where the cardholder’s bank and the business’s payment provider are both in the European Economic Area (EEA). Some businesses outside of Europe may also be impacted, depending on how European issuers implement the new authentication rules. Read more in the Strong Customer Authentication Overview.

    What payment methods require SCA?

    Strong Customer Authentication will apply to “customer-initiated” online payments within Europe. As a result, most card payments and all bank transfers will require SCA. The major integration changes that are required pertain to cards, as documented in this guide. Bank transfers won’t require an integration change on your part because it’s up to the customer’s bank to authenticate transfers via their existing online bank interface.

    What happens if I don’t upgrade my integration, or start passing enable_incomplete_payments?

    Calls to create or update subscriptions that result in charges requiring SCA will fail with HTTP 402. Similarly, calls to POST /v1/invoices/:id/pay will fail. As a result you may experience an overall increase in payment failures.

    Which endpoints should I pass enable_incomplete_payments=true to, in order to opt in to new subscription creation behavior?

    Assuming that updating your API version is not an option, you should use this parameter. Since payments can be initiated during subscription updates as well as subscription creation (for example, when changing plans) you should pass this flag to all subscription & subscription_item creation or update calls. Here is a complete list of all endpoints this flag can apply to (some of which are no longer documented, but are supported for legacy reasons):

    • POST /v1/customers
    • POST /v1/customers/:id
    • POST /v1/customers/:id/subscriptions
    • POST /v1/customers/:id/subscriptions/:sub_id
    • POST /v1/subscriptions
    • POST /v1/subscriptions/:sub_id
    • POST /v1/subscription_items/:sub_item_id

    Pass the enable_incomplete_payments parameter only to the endpoints which you currently use in your integration.

    How often SCA will be required and when will I be able to rely on exemptions?

    For subscriptions, Stripe is working to optimize the exemptions claimed on your behalf. SCA will systematically be applied to the first charge in a subscription where both the merchant and the customer are located in the European Economic Area (EEA). Subsequent charges could be subject to exemptions.

    For one-off invoices & charges, Stripe will apply for exemptions on your behalf where possible.

    There are a couple of known caveats to SCA exemptions: (a) Certain card issuing banks won’t support some/all exemption categories on September 14, 2019. (b) The card issuing bank has an unconditional right to challenge a legitimate exemption request - it is expected this will happen when they assess a transaction as high risk.

    For these reasons, the success rate of exemptions won’t be known until after SCA comes into effect. When considering how to update your integration, you should plan for SCA every time.

    Questions?

    We're always happy to help with code or other questions you might have! Search our documentation, contact support, or connect with our sales team. You can also chat live with other developers in #stripe on freenode.

    Was this page helpful? Yes No

    Send

    Thank you for helping improve Stripe's documentation. If you need help or have any questions, please consider contacting support.

    On this page