# Payment Passkeys source: https://developer.mastercard.com/issuer-enrollment/documentation/use-cases/passkeys/index.md A Mastercard payment passkey is a secure, user-friendly way to authenticate online transactions using familiar biometric methods like fingerprint or face recognition. Payment passkeys authenticate online payments at participating merchants. This page does not cover passkeys for signing in to your banking app or website. For cardholders, it means faster, password-free checkouts. For issuers and merchants, it means better transaction quality, higher approval rates, and reduced fraud. With more consumers and businesses adopting passkeys, issuers can leverage Mastercard's [**Token Authentication Service (TAS)**](https://developer.mastercard.com/product/token-authentication-service/) to increase the penetration of authenticated transactions, ultimately reducing fraud while offering cardholders a seamless payment authentication experience. ## How it Works {#how-it-works} Payment passkey enrollment follows a shared workflow for new and existing passkeys. | Stage | What happens | |-------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Issuer verification** | TAS runs on the [Token Authentication Framework](https://trc-techresource.mastercard.com/r/bundle/m_mc_taf_g_en-us/page/d/en-US/kof1745837091084.html) (TAF). The issuer confirms the cardholder's identity before linking a passkey to the card. | | **Passkey setup** | The cardholder creates a Mastercard payment passkey during checkout on a merchant's site, while adding a card in a merchant's app or site, or through the issuer's own channels. | | **Seamless checkout** | After setup, the cardholder approves payments at participating merchants with a fingerprint, face recognition, or other built-in device authentication --- no extra steps required. | Issuers can integrate with Mastercard to enable their cardholders to create a Mastercard payment passkey, making online transactions both secure and frictionless. For details on program eligibility, participant requirements, and authentication standards, refer to the [TAS Product Guide](https://techdocs.mastercard.com/bundle/m_TAS_en-us). ### Before you start {#before-you-start} * Complete issuer onboarding with Mastercard Checkout Solutions. * Confirm payment passkey availability for your region with your [Mastercard representative](https://developer.mastercard.com/issuer-enrollment/documentation/support/index.md#get-help). * Configure the `callbackUri` and provide it to Mastercard for whitelisting during onboarding. The registration flow cannot complete until it is whitelisted. * Choose a consent model, based on whether you want to handle the consent capture experience yourself or allow Mastercard to manage it: * **Issuer-captured:** Prepare the localized consent details, Terms of Use, and Privacy Notice for display in your interface. Send the captured consent in `complianceResources`. * **Mastercard-captured:** Be ready to send the cardholder's resident `locale` in the `POST /sessions` request. * Prepare the session request's `encryptedValue` containing `SrcSessionInitiationRequestInfo`. See the [Perform Encryption](https://developer.mastercard.com/issuer-enrollment/documentation/tutorials-and-guides/perform-encryption-tutorial/index.md) tutorial for encryption and schema instructions. * Identify the cardholder account references to associate with the passkey, such as a card, email address, or phone number. For Sandbox testing, also confirm that the test card's country and issuer are eligible for FIDO multi-factor authentication. See the [Passkeys testing guide](https://developer.mastercard.com/issuer-enrollment/documentation/testing/passkeys/index.md) for test setup and scenarios. ## Capturing the Cardholder's Consent {#capturing-the-cardholders-consent} Mastercard creates a payment passkey only after the cardholder agrees to the Mastercard payment passkey **Terms of Use** and **Privacy Notice**. We support two consent models, so you can choose how to manage passkey enrollment while maintaining strong security and compliance standards. ### Model 1: Issuer captures consent {#model-1-issuer-captures-consent} Display the Mastercard payment passkey **Terms of Use** and **Privacy Notice** , along with the required consent text, within your own user interface. After the cardholder consents to creating a Mastercard payment passkey, pass this consent to Mastercard as part of the `POST /sessions` API request. Mastercard retains the consent information for compliance and audit purposes. This model gives you control of the passkey creation experience and helps reduce friction. It also requires you to capture the Mastercard payment passkey consent details in advance. ![Passkey Registration](https://static.developer.mastercard.com/content/issuer-enrollment/documentation/img/passkey_creation_and_binding.png "Mastercard Click to Pay Passkey Registration for Issuers") ### Model 2: Mastercard captures consent {#model-2-mastercard-captures-consent} Mastercard displays and manages the payment passkey consent directly in the Mastercard user interface, enabling a simplified and compliant integration. You can initiate passkey provisioning from your own channels without building or maintaining the full consent-capture experience. ![Passkey Registration](https://static.developer.mastercard.com/content/issuer-enrollment/documentation/img/issuer_Passkey_enrollment_MA.png "Mastercard Click to Pay Passkey Registration for Mastercard‑Captured Consent") Note: Contact a [Mastercard representative](https://developer.mastercard.com/issuer-enrollment/documentation/support/index.md#get-help) to check the regional availability of payment passkeys for issuers. ## Initiate Payment Passkey Enrollment {#initiate-payment-passkey-enrollment} To offer payment passkey enrollment, display the passkey registration option to cardholders in your user interface. Then select a consent capture model and follow its implementation requirements. Issuers are responsible for displaying and capturing Mastercard passkey consent before sending the `POST /sessions` request. On the passkey registration screen, display the following: * Mastercard payment passkey **consent details** for the country and language you serve. * Mastercard payment passkey **Terms of Use** and **Privacy Notice** accessible via hyperlinks. * An option for the user to change the country and language. Once the cardholder accepts the terms and proceeds with registration, send the `POST /sessions` request with the account references to be linked with the payment passkey (such as Mastercard cards, email addresses, and phone numbers) along with the user's consent details and a callback URI. In the Mastercard-captured consent model, Mastercard manages the consent experience end‑to‑end. Mastercard presents and records the payment passkey consent after the issuer sends the `POST /sessions` request, simplifying the issuer's responsibilities. To support this flow, you must provide the consumer's resident locale (country and language) in the `POST /sessions` request so Mastercard can display the appropriate localized consent content. See the endpoint structure: API Reference: `POST /sessions`

### Example sequence {#example-sequence} Diagram passkey-initiate-session 1. The cardholder logs in to their issuer's app or website. 2. Follow the selected consent model: * **Issuer-captured:** Display the Mastercard payment passkey consent details, Terms of Use, and Privacy Notice in the issuer experience. The cardholder must accept before you send the `POST /sessions` request. * **Mastercard-captured:** Show the cardholder the account details to be linked, but do not collect consent in the issuer experience. Mastercard presents the consent after you start the session and launch its registration experience. 3. Send a `POST /sessions` request to start the registration session: * For issuer-captured consent, include the consent details in `complianceResources`. * For Mastercard-captured consent, include the cardholder's resident `locale`; Mastercard collects consent later in its experience. * Include the cardholder and account-reference details to be linked, and the `callbackUri` for the registration flow. 4. In the successful `200` response, Mastercard returns the `authenticationSessionId` and the Mastercard URI to launch payment passkey registration. Warning: The `uri` and `authenticationSessionId` are only valid for **fifteen minutes**. ## Create and Bind Passkey {#create-and-bind-passkey} To initiate passkey registration, launch the Mastercard URL in a first-party browser context. Do not embed the Mastercard-hosted experience in an iframe or other third-party context. For URL examples, see below: **Global URL (default)** ```javascript https://verify.mastercard.com/auth/issuer/passkeys?clientId=&authenticationSessionId=&clientSessionId=#accessToken ``` **India URL** ```javascript https://verify.mastercard.co.in/auth/passkeys?clientId=&authenticationSessionId=&clientSessionId=#accessToken ``` Mastercard prompts the cardholder to register a passkey and, if you're using the Mastercard-captured consent model, displays the Mastercard Passkey Terms and Conditions. After the cardholder accepts the terms and completes registration, Mastercard sends you the proof of registration in the form of a JSON Web Token (JWT). When Mastercard prompts the cardholder to perform passkey registration, the next steps depend on whether there is an existing passkey on the device. * **No payment passkey exists**: Mastercard prompts the cardholder to create a new payment passkey. * **Payment passkey exists**: Mastercard prompts the cardholder to verify the payment passkey.
Once the cardholder successfully creates or verifies a payment passkey on their device, send a `POST /authenticators` request to bind the payment passkey to the device and the `accountReference` information (PAN, email address, phone number) the cardholder supplied. See the endpoint structure: API Reference: `POST /authenticators`
Note: If a passkey is already present on the device, Mastercard does not display the passkey Terms and Conditions unless the prior consent has expired. In that case, the cardholder is required to re‑consent. ### Example sequence {#example-sequence-1} Diagram passkey-registration-binding 1. Use the Mastercard URL received in the `POST /sessions` response to launch the Mastercard UI in a first-party browser context or native application. For native applications, launch the URL in a native browser: * **iOS** : Use **ASWebAuthenticationSession** in non-ephemeral mode * **Android** : Use **Chrome Custom Tab** 2. Mastercard recognizes the device and checks for a payment passkey bound to it. If no passkey is present, Mastercard prompts the cardholder to create one. If a passkey is present, Mastercard prompts the cardholder to verify it. Mastercard displays the consent prompt when required by the selected consent model. 3. The cardholder completes the applicable passkey creation or verification challenge. 4. After a successful challenge, Mastercard registers or validates the payment passkey and generates a JWT token, which indicates that the cardholder successfully created or validated a payment passkey on their device. 5. Mastercard returns the proof of registration (JWT) and redirects the cardholder to the `callbackUri` provided in the `POST /sessions` request. The proof is valid for **fifteen minutes**. ```json https://callback_url?status=ENROLLED&proofOfAuthentication=eyJraWQiOiIyMDI1MDMyNDE3MTgwNy1kYXMtbWFjLXNpZ24tc3RnIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJpc0NoYWxsZW5nZVBlcmZvcm1lZCI6dHJ1ZSwiY29tcGxldGVkQXQiOjE3NDk1NDQ5MzEsImFzc2VydGlvblR5cGUiOiJvd25lcnNoaXAiLCJjZXJ0aWZpZWRNRkFNZXRob2RJZCI6IjIwMDAxIiwiaXNzIjoiaHR0cHM6XC9cL3N0YWdlLnZlcmlmeS5tYXN0ZXJjYXJkLmNvbSIsImF1dGhlbnRpY2F0aW9uRmFjdG9ycyI6IjAyMEEiLCJhcHBJbnN0YW5jZUlkIjoiblpPLUtodTBTRGVPYTZHNjVnZmdWdzAwMDAwMDAwMDAxMFVTIiwiYXVkIjoiaHR0cHM6XC9cL21hc3RlcmNhcmQuY29tIiwiY2xpZW50U2Vzc2lvbklkIjoiODZiZDRhOTEtNDZiYS00YjJjLTliNGEtNTllZWEzODEyZjA3IiwiYXV0aGVudGljYXRpb25NZXRob2QiOiJGSURPMiIsImRhc0F1dGhlbnRpY2F0b3JJbnN0YW5jZUlkIjoiZmVVdUwtRmVUNmlDaGtFLXhrQnowZzAwMDAwMDAwMDAxMFVTIiwiZXhwIjoxNzQ5NTQ1ODMxLCJpYXQiOjE3NDk1NDQ5MzEsImF1dGhlbnRpY2F0aW9uUmVhc29ucyI6WyJBQ0NPVU5UX0xPR0lOIl19.BJIk-3TAl4e6_bnL1iNpuds8SLoX2I_QocQaaofo41Ke4l8jjXm4l8xDNpnten-n9RhbJ2Oz89QUlX-RNUqHPf1mKS09rdrt_NVoEM3Kr9ejqv1KULrz0owE3VIUWZRTvwtod-m5PFCrLLpFmvQTf2FC-YE8Wb_nt8rIjT8KDfzgDH0cayeA5iGvA092nJNBUXze5-xOuct3LtTEOyZS6OhyjRDuQ7UrHNnQdrYCQHkZv0QOYFAJJ6aVUPnYvI0NjNJgYSE4CUGwr0qJDx046WOe3BtgqgC4oFQyCWN-BI6Z2yC9IjyIEZH4wfNd15mshW5nJ7v46s-RoRR0IMsS5Q ``` | Parameter | Description | |-------------------------|---------------------------------------------------------------------------------------------------------------------------------------------| | `status` | Indicates the passkey registration or authentication was successful. Possible values: `ENROLLED`, `AUTHENTICATED`, `AUTHENTICATOR_ASSERTED` | | `proofOfAuthentication` | The Mastercard-generated JWT token. | If passkey registration or validation is unsuccessful, the `callbackUri` contains an error `status` and `reason` for the error. | Status | Reason | Description | Recommended action | |-----------|----------------------------------|--------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | CANCELLED | USER_CANCELLATION | Cardholder selected **Not Now** option. | End the attempt without an automatic retry. Let the cardholder restart if they choose. | | ERROR | DUPLICATE_CREDENTIALS | Registration failed because the passkey already exists. | Do not repeat creation. Continue with the existing-passkey verification flow described above. | | ERROR | CREDENTIALS_CREATION_NOT_ALLOWED | Cardholder canceled during registration or another error prevented passkey creation. | If the cardholder canceled, end the attempt. Otherwise, inspect the returned error details; contact Mastercard support if the issue persists. | | ERROR | CREDENTIALS_NOT_VERIFIED | Cardholder canceled during passkey assertion or verification otherwise failed. | Let the cardholder retry verification. If it continues to fail, inspect the error details and contact Mastercard support. | | ERROR | INVALID_QUERY_PARAMS | Compliance details were missing from query parameters. | Check the registration URL and required consent details for the selected consent model, then restart the flow. | | ERROR | INVALID_ARGUMENT | Backend enrollment API returned a 400 response. | Inspect the error message and details, correct missing or invalid request fields, and retry. | | ERROR | PERMISSION_DENIED | Backend enrollment API returned a 401 response. | Check API authentication and client permissions. Correct configuration issues; contact your Mastercard representative if access remains denied. | | ERROR | FORBIDDEN | Backend enrollment API returned a 403 response. | Check that the client ID and related request identifiers are present and correct, then retry. | | ERROR | NOT_FOUND | Backend enrollment API returned a 404 response. | Verify the referenced session, resource, and account identifiers. Correct missing or invalid values before retrying. | | ERROR | INVALID_STATE | Backend enrollment API returned a 500 response. | Show a generic error and inspect the returned details. [Codes and Formats](https://developer.mastercard.com/issuer-enrollment/documentation/code-and-formats/index.md) notes that retrying may succeed; follow your integration's safe retry policy. | | ERROR | SERVICE_UNAVAILABLE | Backend enrollment API returned a 503 response. | Retry after a delay according to your integration's retry policy. Contact Mastercard support if the service remains unavailable. | | ERROR | SERVICE_ERROR | Backend enrollment API returned another error code. | Check the returned HTTP status and error details. Follow the matching [Codes and Formats](https://developer.mastercard.com/issuer-enrollment/documentation/code-and-formats/index.md) guidance or contact Mastercard support if unclear. | | ERROR | UNKNOWN_ERROR | An unexpected error occurred. | Do not assume the attempt succeeded. Inspect the returned error details and contact Mastercard support if the cause is unclear or persists. | 6. To bind the passkey to the device, send a request to `POST /authenticators` with the proof of authentication and the `accountReference` information (PAN, email address, phone number) supplied in the initial `POST /sessions` request. 7. On successful binding, Mastercard returns a `200` response with a `credentialId` and `bindingId`. ## Error Resolution {#error-resolution} For details on error resolution please visit our [codes and formats](https://developer.mastercard.com/issuer-enrollment/documentation/code-and-formats/index.md) section. ## Next Steps {#next-steps} * To validate the passkey creation flow, see the [Passkeys](https://developer.mastercard.com/issuer-enrollment/documentation/testing/passkeys/index.md) testing page.