# Hosted standalone 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. --- ## Set up scheme passkeys To use scheme passkeys, your authentication request must include the following fields: - `completion`, with a `type` of `hosted` - `authentication_type` set to `regular` - `authentication_category` set to `payment` - `source.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. ### Configure iframe permissions 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. ```html ``` 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. --- ## Payment authorization 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. --- ## Request a session 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](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md). **Production** `POST` `https://{prefix}.api.checkout.com/sessions` **Sandbox** `POST` `https://{prefix}.api.sandbox.checkout.com/sessions` ### Request example ```json { "source": { "type": "card", "number": "4485040371536584", "expiry_month": 1, "expiry_year": 2030, "email": "hannah.bret@example.com" }, "amount": 100, "currency": "GBP", "authentication_type": "regular", "authentication_category": "payment", "challenge_indicator": "no_preference", "reference": "ORD-5023-4E89", "transaction_type": "goods_service", "completion": { "type": "hosted", "success_url": "https://example.com/sessions/success", "failure_url": "https://example.com/sessions/failure" }, "preferred_experiences": [ "passkey", "3ds" ] } ``` ### Response example If the request is successful, you receive a `202 - Accepted` response: ```json { "id": "sid_y3oqhf46pyzuxjbcn2giaqnb441", "transaction_id": "9aea641d-0549-4222-9ca9-d90b43a4f38c", "amount": 100, "currency": "GBP", "authentication_type": "regular", "authentication_category": "payment", "status": "pending", "next_actions": [ "redirect_cardholder" ], "protocol_version": "2.2.0", "reference": "ORD-5023-4E89", "_links": { "redirect": { "href": "https://3ds2.checkout.com/interceptor/sid_y3oqhf46pyzuxjbcn2giaqnb441" }, "self": { "href": "https://{prefix}.api.checkout.com/sessions/sid_y3oqhf46pyzuxjbcn2giaqnb441" } } } ``` 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. | | `["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 session 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. --- ## Redirect the customer 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. --- ## Complete the challenge 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](#Set_up_scheme_passkeys). --- ## Get session details To retrieve the details of the authentication, call the [Get session details](https://api-reference.checkout.com/tag/Standalone/#operation/getSession) endpoint with the session `id`, prefixed by `sid_`. If the request is successful, you receive a `200 - OK` response: ```json { "id": "sid_did5wxsbpsouredqq777scjnie", "transaction_id": "5edb071a-7c41-489d-9070-87fff9092d41", "amount": 100, "currency": "GBP", "authentication_type": "regular", "authentication_category": "payment", "status": "approved", "approved": true, "next_actions": [], "challenged": true, "cryptogram": "AAAAAAAAAAAAAAAAAAAAAAAAAAA=", "eci": "05", "scheme": "visa", "flow_type": "challenged", "challenge_indicator": "no_preference", "transaction_type": "goods_service", "session_secret": "sek_/24zXia+6TaT9k9ZYhBqwFLINbDY5mtdB9vRwX68uiU=", "authentication_date": "2026-09-17T09:59:56.4833830Z" } ``` 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](https://api-reference.checkout.com/tag/Standalone/#operation/getSession). ### Session status The following table shows the possible values of the `status` field: | Status | Description | | --- | --- | | `pending` | You requested authentication, and the session has started. | | `approved` | The payment was successfully authenticated. | | `unavailable` | The experience was unavailable, because of ineligibility or a technical issue. | | `declined` | The issuer declined the authentication. | | `rejected` | The issuer rejected the authentication. Do not retry the authentication or authorize the payment. | | `challenged` | The issuer requires a challenge to be presented to the customer. | | `expired` | The authentication was not completed within 15 minutes. | ### Next actions The following table shows the possible values of the `next_actions` field: | Action | Description | | --- | --- | | `redirect_cardholder` | Redirect the customer so that we can handle the necessary actions. | | `complete` | The authentication has finished. Retrieve the session details to get the result. |