# 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 backend 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)