Hosted standalone
Last updated: October 21, 2026
To use scheme passkeys with hosted standalone authentication, start an authentication and then redirect the customer using the URL provided in the response. Checkout.com collects the necessary payment, device, and cardholder data and manages the rest of the authentication.
Note
Scheme passkey authentication is currently available for Visa cards only, for eligible traffic on participating issuers, and in browser-based payments only.
To use scheme passkeys, your authentication request must include the following fields:
completion, with atypeofhostedauthentication_typeset toregularauthentication_categoryset topaymentsource.email, set to the customer's email address
Scheme passkey authentication requires a browser and device that support passkeys. If the request is ineligible, or no passkey is available for the card, the authentication automatically falls back to 3DS when available.
If you host the payment page within an iframe, you must configure it to allow cross-origin resources to use the Payments API and WebAuthn, the browser standard for passkeys. The passkey prompt runs inside a cross-origin iframe and fails unless the embedding iframe delegates these permissions through its allow attribute.
Apply this to the authentication iframe and all parent iframes. If you redirect the customer to the hosted authentication page instead of embedding it, no iframe configuration is required.
A successful scheme passkey authentication returns a cryptogram and an Electronic Commerce Indicator (ECI) value, exactly as a standard 3DS authentication does. Submit these values in your subsequent payment request to retain the liability shift. This applies to both full primary account numbers (FPANs) and network tokens.
Scheme passkeys do not require a token payment, and the session returns no passkey-specific properties.
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, include passkey as the first value in the array.
Information
Your base URL's {prefix} value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see API endpoints.
post
https://{prefix}.api.checkout.com/sessions
If the request is successful, you receive a 202 - Accepted response:
The preferred_experiences field is an ordered preference list. We try the first experience that applies, and move down the list if it is unavailable.
| Preferred experience | Result |
|---|---|
Omitted | Recommended. We select the best authentication experience for each session. |
| Attempts a scheme passkey, then falls back to standard 3DS automatically. |
| Same as |
| Not recommended. A scheme passkey is never attempted, as the session prefers standard 3DS. |
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.
Redirect the customer to the _links.redirect URL provided in the response. On our hosted authentication page, the card scheme collects data directly from the browser for authentication purposes. Checkout.com does not access or store this data. We then present the authentication experience.
If the customer has a scheme passkey for their card, they approve the payment with the same biometric they use to unlock their device. If they have no passkey, we ask them to complete a standard 3DS challenge, and the scheme may then offer to create a passkey for future payments. Enrollment is optional, and if the customer declines, the checkout process continues as normal.
The biometric data never leaves the customer's device, and we never receive or store biometric data.
After completing the authentication, your customer is redirected to the success_url or failure_url that you specified when you created the session.
Information
If you host the challenge page within an iframe, ensure that you allow cross-origin access to the Payments API and WebAuthn, as described in Set up scheme passkeys.
To retrieve the details of the authentication, call the Get session details endpoint with the session id, prefixed by sid_.
If the request is successful, you receive a 200 - OK response:
The properties you need to authorize a scheme passkey payment are the same ones returned for a standard 3DS authentication. For the full list of properties, see the API reference – Get session details.
The following table shows the possible values of the status field:
| Status | Description |
|---|---|
| You requested authentication, and the session has started. |
| The payment was successfully authenticated. |
| The experience was unavailable, because of ineligibility or a technical issue. |
| The issuer declined the authentication. |
| The issuer rejected the authentication. Do not retry the authentication or authorize the payment. |
| The issuer requires a challenge to be presented to the customer. |
| The authentication was not completed within 15 minutes. |
The following table shows the possible values of the next_actions field:
| Action | Description |
|---|---|
| Redirect the customer so that we can handle the necessary actions. |
| The authentication has finished. Retrieve the session details to get the result. |