Issuer-app authentication

Learn how to authenticate users using your custom, in-app flow for 3DS.

When a card is used to make an online transaction using 3DS, two steps happen:

1. The authentication challenge. The cardholder might be required to verify ownership of the card.
2. The authorization flow .

By default, Stripe will handle the authentication challenge for you by either sending a one-time password (OTP) to the cardholder’s email or phone number or prompting the cardholder to identify a past transaction. Upon successful completion of the challenge, the authorization flow follows.

However, instead of using this default flow, you can handle this authentication flow using your custom, in-application flow. We refer to this as "issuer-app authentication.”

Regional considerations United States

Issuer-app authentication is available only for US Issuing users. Access is limited to eligible users and might require enrollment. Contact your Stripe account manager or Stripe Support to confirm eligibility.

Issuer-app authentication flow

Issuer-app authentications follow these steps:

1. Upon receiving a 3DS challenge request, Stripe sends an issuing_authentication.requires_api_approval webhook event, letting you know we’re awaiting a decision about an authentication.
2. You notify your cardholder of a pending authentication request through a push notification to your application.
3. Retrieve the pending Authentication . You can have your user application call one of the following:

• The list endpoint , to fetch all pending authentications for the card with parameter status as requires _ api _ approval . Using this endpoint allows for your application to recover from lost notifications.
• The retrieve endpoint , to fetch the Authentication by the data. object. id in the issuing _ authentication. requires _ api _ approval event.

4. The cardholder reviews the transaction details and completes the authentication challenge within your application.
5. Depending on whether the authentication was successful, your application backend will call either the Authentication approve or decline endpoint. The Authentication’s status is updated to approved or failed , respectively. If the status is failed , see status _ reason for the reason.
6. If the authentication is successful, then the regular authorization flow occurs. Otherwise, the flow ends and the authorization flow doesn’t occur.

Don’t make on-behalf-of approvals for challenges with issuer-app authentication. The cardholder must authenticate directly.

Authentication responsibility

With issuer-app authentication, your application (not Stripe) is responsible for performing strong customer authentication (SCA) on the cardholder.

Warning

Your user application, not Stripe, is performing two-factor authentication on the cardholder. The elements used must be from different domains; for example, you can’t authenticate the user with two “knowledge” elements. For further details about SCA requirements, see What’s Strong Customer Authentication?

We suggest showing merchant_amount, merchant_currency, and merchant_data to the cardholder for verification.

{
 "id": "iauthn_1I7C5jEEsyYlpYZ9y03lmgFU",
 "object": "issuing.authentication",
 "authentication_method": "api",
 ...
 "merchant_amount": 500,
 "merchant_currency": "usd",
 "merchant_data": {
 "country": "US",
 "name": "Rocket Rides",
 "redirect_url": null,
 "url": "https://www.rocketrides.io"
 },
 ...
}

Note

The merchant_amount isn’t a finalized amount and might change between authentication and authorization. The authentication amount itself doesn’t impact your account’s transaction volume or balance.

Authentication cancellations

Cardholders might choose not to proceed with the authentication challenge, in which case an issuing_authentication.updated webhook event is sent. The canceled Authentication will have a status of failed and status_reason of canceled.

Status reasons

When an authentication fails, the status_reason field indicates why the authentication was unsuccessful:

• rejected : The authentication was declined using the decline API endpoint
• canceled : The cardholder canceled the authentication (including abandonment scenarios)