# 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](https://docs.stripe.com/issuing/3d-secure.md), two steps happen:

1. The authentication challenge. The cardholder might be required to verify ownership of the card.
2. The [authorization flow](https://docs.stripe.com/issuing/purchases/authorizations.md).

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 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](https://support.stripe.com/) 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](https://docs.stripe.com/api/events/types.md#event_types-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](https://docs.stripe.com/api/issuing/authentications.md). You can have your user application call one of the following:
   - The [list endpoint](https://docs.stripe.com/api/issuing/authentications/list.md), to fetch all pending authentications for the card with parameter [status](https://docs.stripe.com/api/issuing/authentications/list.md#list_issuing_authentications-status) as `requires_api_approval`. Using this endpoint allows for your application to recover from lost notifications.
   - The [retrieve endpoint](https://docs.stripe.com/api/issuing/authentications/retrieve.md), 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 back end will call either the Authentication [approve](https://docs.stripe.com/api/issuing/authentications/approve.md) or [decline](https://docs.stripe.com/api/issuing/authentications/decline.md) 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.

> 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](https://stripe.com/guides/strong-customer-authentication#what-is-strong-customer-authentication)?

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

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

> 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](https://docs.stripe.com/api/events/types.md#event_types-issuing_authentication.requires_api_approval) webhook event is sent. The canceled [Authentication](https://docs.stripe.com/api/issuing/authentications.md) 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](https://docs.stripe.com/api/issuing/authentications/decline.md) API endpoint
- `canceled`: The cardholder canceled the authentication (including abandonment scenarios)