Issuer-app authentication

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.”

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.

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"
  },
  ...
}

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)