# Scheme passkeys

Scheme passkeys let cardholders verify online payments with the same biometric they use to unlock their device, as an alternative to a one-time password or [3D Secure (3DS)](https://www.checkout.com/docs/payments/authenticate-payments/3d-secure.md) challenge.

Cardholders complete biometric authentication with a passkey during a 3DS transaction. For example, the cardholder can approve the payment with their fingerprint instead of retrieving a one-time password externally. The biometric data never leaves the cardholder's device, and Checkout.com never receives or stores biometric data.

Scheme passkeys are available on devices and browsers that support passkeys. They run over your existing 3DS integration, so no separate authentication API is required.

After a passkey is created, it's bound to the cardholder's device and reused on future payments, with no re-enrollment.

With scheme passkeys, you benefit by:

- Increasing your authentication success rate.
- Giving your cardholders a faster, phishing-resistant biometric experience.
- Reducing abandonment, so fewer customers drop off during authentication.
- Retaining the same issuer liability shift as a standard 3DS transaction.

> **Note**
>
> Scheme passkey authentication is currently available for Visa cards only, for eligible traffic on participating issuers, and in browser-based payments only.
>
> To enable scheme passkey authentication, contact your account manager or [request support](https://dashboard.checkout.com/support/new?topic=case_account_management_and_access&issue=issue_account_changes).

---

## Set up scheme passkeys

To set up scheme passkeys, you must:

1. Configure the iframe permissions.
2. Request the passkey experience.

## Configure iframe permissions

The passkey prompt uses WebAuthn, the browser standard for passkeys, and runs inside a cross-origin iframe. Under EMV 3DS guidance, WebAuthn fails in a cross-origin iframe unless the embedding iframe delegates the required permissions through its `allow` attribute.

If you embed our hosted authentication page in an iframe, add the following permissions so the passkey prompt can reach the challenge iframe:

```html
<iframe
  src="https://your-checkout-page.example.com"
  allow="payment *; publickey-credentials-get *; publickey-credentials-create *">
</iframe>
```

## Request the passkey experience

If you authenticate payments using our [integrated authentication](https://www.checkout.com/docs/payments/authenticate-payments.md#Integrated_authentication) solution, you can use the `authentication.preferred_experiences` [field](https://api-reference.checkout.com/tag/Payments/#operation/requestAPaymentOrPayout!path=0/authentication&t=request) to tell us which authentication experiences to attempt, and in what order.

The `preferred_experiences` field is optional, and we recommend omitting it. If you omit it, we select the authentication experience for each session on your behalf, so you benefit from our optimization without changing your integration.

To request a scheme passkey explicitly, list `passkey` as the first value in the array. For example:

```json
{
  "authentication": {
    "preferred_experiences": [
      "passkey"
    ]
  }
}
```

The array is an ordered preference list. We try the first experience that applies and move down the list if it's unavailable. The following table shows how different values behave:

| Preferred experience | Result |
| --- | --- |
| Omitted | Recommended. We select the best authentication experience for each payment. |
| `["passkey"]` | Attempts a scheme passkey, then falls back to standard 3DS automatically. |
| `["passkey", "3ds"]` | Same as `["passkey"]`. |
| `["3ds", "passkey"]` | Not recommended. A scheme passkey is never attempted, as the payment prefers standard 3DS. |

### Fall back to 3D Secure

If a passkey is unavailable for the card, or the cardholder does not complete it, the payment automatically continues as a standard 3DS authentication.

For this fallback to work, provide 3DS authentication data in all of your payment requests.

- [Hosted standalone](https://www.checkout.com/docs/payments/authenticate-payments/scheme-passkeys/hosted-standalone.md): Use scheme passkeys with hosted standalone authentication, where we manage the authentication flow and redirect your customer to a hosted page.