# Getting Started with Passkeys source: https://developer.mastercard.com/issuer-enrollment/documentation/use-cases/passkeys/index.md ## Overview {#overview} A Mastercard payment passkey is a secure, user-friendly way to authenticate online transactions using familiar biometric methods like fingerprint or face recognition. 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 business 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 whilst offering cardholders a seamless payment authentication experience. ### How it works: {#how-it-works-br} 1. **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. 2. **Passkey Setup** - Cardholders can create Mastercard payment passkey: * During checkout on a merchant's site * While adding a card in a merchant's app or site * Through Issuer's own channels 3. **Seamless Checkout** - Once set up, the cardholder can approve payments at participating merchants by simply using their fingerprint, face recognition, or other built-in device authentication --- no extra steps required. The 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). ### Supported Integration Models: {#supported-integration-models} A Mastercard payment passkey can be created only after the consumer agrees to the Mastercard payment passkey **Terms of Use** and **Privacy Notice**. To provide issuers with flexibility in how they manage passkey enrollment while maintaining strong security and compliance standards, Mastercard supports two integration models: ### 1. Issuer Captures Consent {#1-issuer-captures-consent} Issuers displays the Mastercard payment passkey **Terms of Use** and **Privacy Notice** , along with the required consent text, within their own user interface. Once the cardholder provides consent to create a Mastercard payment passkey, the issuer passes this consent to Mastercard as part of the [Sessions](https://developer.mastercard.com/issuer-enrollment/documentation/api-reference/apis/index.md#authentication-apis) API call. Mastercard retains the consent information for compliance and audit purposes. This integration allows issuers to control the passkey creation experience and helps reduce friction. However, it requires issuers 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") ### 2. Mastercard Captures Consent {#2-mastercard-captures-consent} In this integration model, the Mastercard payment passkey consent is displayed and managed directly on the Mastercard user interface, enabling a simplified and compliant integration. This allows issuers to initiate passkey provisioning from their own channels without the need to build or maintain 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. ## Step 1: Customer Initiation {#step-1-customer-initiation} To begin with payment passkeys, the Issuer must display the passkey registration option on their user interface to the cardholder. Passkey enrolment supports two consent capture models. Implementation requirements vary by model. ### 1. Issuer Captures Consent {#1-issuer-captures-consent-1} The Issuer is responsible for displaying and capturing Mastercard passkey consent before calling the [Sessions](https://developer.mastercard.com/issuer-enrollment/documentation/api-reference/apis/index.md#authentication-apis) Initiation API. On this passkey registration screen, the Issuer must display the following: * Mastercard payment passkey **consent details** for the country and language they 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, call the [Sessions](https://developer.mastercard.com/issuer-enrollment/documentation/api-reference/apis/index.md#authentication-apis) API with the account references to be linked with the payment passkey---such as Mastercard cards, email addresses, and/or phone numbers--- along with the user's consent details and a callback URI. ### 2. Mastercard Captures Consent {#2-mastercard-captures-consent-1} In the Mastercard Captured Consent Model, Mastercard manages the consent experience end‑to‑end. Mastercard payment passkey consent is presented and recorded by Mastercard after [Sessions](https://developer.mastercard.com/issuer-enrollment/documentation/api-reference/apis/index.md#authentication-apis) API initiation, simplifying the Issuer's responsibilities. To support this flow, the Issuer must provide the consumer's resident locale (country and language) in the [Sessions](https://developer.mastercard.com/issuer-enrollment/documentation/api-reference/apis/index.md#authentication-apis) API so that Mastercard can display the appropriate localized consent content. ### Integration Details {#integration-details} Diagram passkey_customer_initiation #### Detailed steps {#detailed-steps} * **Cardholder agrees to enroll for payment passkeys on Issuer website/app** 1. The cardholder logs in to their Issuer's app or website. 2. On the passkey registration screen, * **If the Issuer is capturing consent**: The cardholder accepts the terms and conditions and provides consent to create a Mastercard payment passkey for the selected cards and associated email address/phone number. * **If Mastercard is capturing consent**: The cardholder will first see their card details along with their email address/phone number on the Issuer registration screen. When the Mastercard registration screen is launched, the cardholder must review and accept the passkey consent directly within the Mastercard experience. * **Issuer initiates the passkey registration session** 3. The Issuer requests Mastercard to launch the passkey registration using the [Sessions](https://developer.mastercard.com/issuer-enrollment/documentation/api-reference/apis/index.md#authentication-apis) API, by supplying the following: * If the issuer captures cardholder consent, it must provide the consent details in the `complianceResources` object. If Mastercard captures consent, the issuer only needs to provide the consumer's resident `locale`. * Cardholder details, such as email address, phone number, card details. * `callbackUri` Note: * The Issuer must encrypt the data passed in `SrcSessionInitiationRequestInfo` during the [Sessions](https://developer.mastercard.com/issuer-enrollment/documentation/api-reference/apis/index.md#authentication-apis) API, see the [encryption tutorial](https://developer.mastercard.com/issuer-enrollment/tutorial/perform-encryption/step2/index.md) for details. * The `callbackUri` must be whitelisted with Mastercard during onboarding to prevent misuse or fraudulent activity. If the URI is not whitelisted, the registration flow will not complete successfully. 4. Mastercard provides `authenticationSessionId` and the Mastercard URI to the Issuer to launch payment passkey registration. Warning: The `uri` and `authenticationSessionId` returned as part of [Sessions](https://developer.mastercard.com/issuer-enrollment/documentation/api-reference/apis/index.md#authentication-apis) API response is only valid for **fifteen minutes**. ## Step 2: Passkey Creation and Binding {#step-2-passkey-creation-and-binding} Issuer launches the Mastercard URL in a browser, where Mastercard prompts the cardholder to perform passkey registration. The cardholder will see the passkey creation screen, along with the consent screen requiring agreement to the Mastercard Passkey Terms and Conditions (if the integration model requires Mastercard to capture Passkey consent). Once the cardholder agrees to the Passkey Terms and Conditions, the registration process is initiated. After successful registration, Mastercard provides the proof of registration (JWT) to the Issuer. Issuers must launch the Mastercard URL in first party context in the browser. See a URL sample below: **Global URL (default)**: ```javascript https://verify.mastercard.com/auth/issuer/passkeys?clientId=%3Cvalue%3E&authSessionId=%3Cvalue%3E&clientSessionId=%3Cvalue%3E#accessToken ``` **India URL**: ```javascript https://verify.mastercard.co.in/auth/passkeys?clientId=>&authenticationSessionId&clientSessionId=#accessToken ``` When Mastercard prompts the cardholder to perform passkey registration, one of the following scenarios apply: * [Scenario 2A](https://developer.mastercard.com/issuer-enrollment/documentation/use-cases/passkeys/index.md#scenario-2a-new-mastercard-payment-passkey-flow): No payment passkey exists on a device and Mastercard prompts the cardholder to create a new payment passkey. * [Scenario 2B](https://developer.mastercard.com/issuer-enrollment/documentation/use-cases/passkeys/index.md#scenario-2b-existing-mastercard-payment-passkey-flow): A payment passkey existing on a device and Mastercard prompts the cardholder to verify the payment passkey.
Once the cardholder successfully creates/validates a payment passkey on their device, the Issuer uses the [Authenticators](https://developer.mastercard.com/issuer-enrollment/documentation/api-reference/apis/index.md#authentication-apis) API to bind the payment passkey to a device and the `accountReference` (PAN, email address, phone number) information supplied by the cardholder. ### Scenario 2A: New Mastercard Payment Passkey Flow {#scenario-2a-new-mastercard-payment-passkey-flow} This scenario is valid when there is no Mastercard payment passkey available on cardholder's device and Issuer prompts the cardholder to create a payment passkey with Mastercard. Next, the Issuer requests Mastercard to bind the payment passkey to the cardholder's device and the `accountReference` (PAN, email address, phone number) information. Diagram passkey_on_new_device #### Detailed steps {#detailed-steps-1} * **Issuer launches Mastercard UI for cardholder to create a passkey** 1. Issuer uses Mastercard URL received as part of [Sessions](https://developer.mastercard.com/issuer-enrollment/documentation/api-reference/apis/index.md#authentication-apis) API response to launch Mastercard UI in the first party context in a browser or a native application. For native applications, Issuers must launch the Mastercard URL in a native browser, as recommended below: * For iOS platform, launch **ASWebAuthenticationSession** in non-ephemeral mode. * For Android, launch in **Chrome Custom Tab** . 2. Mastercard recognizes the device and looks for a payment passkey bound to this device. The cardholder will be presented with the passkey creation screen along with a consent prompt asking them to accept the Mastercard Passkey Terms and Conditions (if required by the selected integration model). 3. Since no payment passkey is present for this device, Mastercard prompts the cardholder to create a payment passkey. 4. The cardholder successfully completes payment passkey creation challenge. 5. Mastercard registers the payment passkey, provides the proof of registration (JWT) to the Issuer, and redirects to the `callbackUri` provided by the Issuer. The proof of registration is a Mastercard-generated JWT token which indicates that the cardholder successfully created a payment passkey on their device. Warning: The proof of registration (JWT) generated after passkey registration is only valid for **fifteen minutes**. For a sample `callbackUri`: https://callback_url?status=ENROLLED\&proofOfAuthentication=eyJraWQiOiIyMDIzMDkxNTExNk..... * `status`: ENROLLED/AUTHENTICATED/AUTHENTICATOR_ASSERTED * `proofOfAuthentication`: "eyJraWQiOiIyMDI1MDMyNDE3MTgwNy1kYXMtbWFjLXNpZ24tc3RnIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJpc0NoYWxsZW5nZVBlcmZvcm1lZCI6dHJ1ZSwiY29tcGxldGVkQXQiOjE3NDk1NDQ5MzEsImFzc2VydGlvblR5cGUiOiJvd25lcnNoaXAiLCJjZXJ0aWZpZWRNRkFNZXRob2RJZCI6IjIwMDAxIiwiaXNzIjoiaHR0cHM6XC9cL3N0YWdlLnZlcmlmeS5tYXN0ZXJjYXJkLmNvbSIsImF1dGhlbnRpY2F0aW9uRmFjdG9ycyI6IjAyMEEiLCJhcHBJbnN0YW5jZUlkIjoiblpPLUtodTBTRGVPYTZHNjVnZmdWdzAwMDAwMDAwMDAxMFVTIiwiYXVkIjoiaHR0cHM6XC9cL21hc3RlcmNhcmQuY29tIiwiY2xpZW50U2Vzc2lvbklkIjoiODZiZDRhOTEtNDZiYS00YjJjLTliNGEtNTllZWEzODEyZjA3IiwiYXV0aGVudGljYXRpb25NZXRob2QiOiJGSURPMiIsImRhc0F1dGhlbnRpY2F0b3JJbnN0YW5jZUlkIjoiZmVVdUwtRmVUNmlDaGtFLXhrQnowZzAwMDAwMDAwMDAxMFVTIiwiZXhwIjoxNzQ5NTQ1ODMxLCJpYXQiOjE3NDk1NDQ5MzEsImF1dGhlbnRpY2F0aW9uUmVhc29ucyI6WyJBQ0NPVU5UX0xPR0lOIl19.BJIk-3TAl4e6_bnL1iNpuds8SLoX2I_QocQaaofo41Ke4l8jjXm4l8xDNpnten-n9RhbJ2Oz89QUlX-RNUqHPf1mKS09rdrt_NVoEM3Kr9ejqv1KULrz0owE3VIUWZRTvwtod-m5PFCrLLpFmvQTf2FC-YE8Wb_nt8rIjT8KDfzgDH0cayeA5iGvA092nJNBUXze5-xOuct3LtTEOyZS6OhyjRDuQ7UrHNnQdrYCQHkZv0QOYFAJJ6aVUPnYvI0NjNJgYSE4CUGwr0qJDx046WOe3BtgqgC4oFQyCWN-BI6Z2yC9IjyIEZH4wfNd15mshW5nJ7v46s-RoRR0IMsS5Q" * `status`: ERROR/CANCELLED * `reason`: "reason of failure" | Error Scenario | Status | Reason | |------------------------------------------------------------------------------------------|-----------|----------------------------------| | Cardholder clicks on **Not Now** option. | CANCELLED | USER_CANCELLATION | | Registration failed due to duplicate passkey | ERROR | DUPLICATE_CREDENTIALS | | Cardholder cancels the operation during Registration or any other unknown error occurred | ERROR | CREDENTIALS_CREATION_NOT_ALLOWED | | Compliance details not provided in query params | ERROR | INVALID_QUERY_PARAMS | | Backend enrolment API returns 400 | ERROR | INVALID_ARGUMENT | | Backend enrolment API returns 401 | ERROR | PERMISSION_DENIED | | Backend enrolment API returns 403 | ERROR | FORBIDDEN | | Backend enrolment API returns 404 | ERROR | NOT_FOUND | | Backend enrolment API returns 500 | ERROR | INVALID_STATE | | Backend enrolment API returns 503 | ERROR | SERVICE_UNAVAILABLE | | None of the above API error code | ERROR | SERVICE_ERROR | | Something unexpected happened | ERROR | UNKNOWN_ERROR | * **Issuer requests Mastercard to bind the passkey to a device** 6. Issuer calls the [Authenticators](https://developer.mastercard.com/issuer-enrollment/documentation/api-reference/apis/index.md#authentication-apis) API with the proof of authentication to bind the newly created payment passkey to a device and the `accountReference` (PAN, email address, phone number) information received from [Sessions](https://developer.mastercard.com/issuer-enrollment/documentation/api-reference/apis/index.md#authentication-apis) API. 7. Mastercard responds with a `credentialId` and `bindingId`. ### Scenario 2B: Existing Mastercard Payment Passkey Flow {#scenario-2b-existing-mastercard-payment-passkey-flow} This scenario is valid when there is an existing Mastercard payment passkey available on the cardholder's device and Mastercard prompts the cardholder to validate a payment passkey. Next, the Issuer requests Mastercard to bind the payment passkey to the cardholder's device and the `accountReference` (PAN, email address, phone number) information. Note: If a passkey is already present on the device, the passkey Terms and Conditions will not be displayed unless the prior consent has expired. In that case, the cardholder will be required to re‑consent. Diagram passkey_on_existing_device #### Detailed steps {#detailed-steps-2} * **Issuer launches Mastercard UI for cardholder to check for an existing passkey** 1. Issuer uses Mastercard URL received as part of [Sessions](https://developer.mastercard.com/issuer-enrollment/documentation/api-reference/apis/index.md#authentication-apis) API response to launch Mastercard UI in the first party context in a browser or a native application. For native applications, Issuers must launch the Mastercard URL in a native browser, as recommended below: * For iOS platform, launch **ASWebAuthenticationSession** in non-ephemeral mode. * For Android, launch in **Chrome Custom Tab** . 2. Mastercard recognizes the device and looks for a payment passkey bound to this device. 3. With an existing payment passkey present for this device, Mastercard prompts the cardholder to verify the payment passkey. 4. The cardholder successfully authenticates using an exising payment passkey. 5. Mastercard validates the payment passkey, provides the proof of authentication (JWT) to the Issuer, and redirects to the `callbackUri` provided by the Issuer. The proof of authentication is a Mastercard-generated JWT token which indicates that the cardholder successfully validated a payment passkey on their device. Warning: The proof of registration (JWT) generated after passkey registration is only valid for **fifteen minutes**. For a sample `callbackUri`: https://callback_url?status=ENROLLED\&proofOfAuthentication=eyJraWQiOiIyMDIzMDkxNTExNk..... * `status`: ENROLLED/AUTHENTICATED/AUTHENTICATOR_ASSERTED * `proofOfAuthentication`: "eyJraWQiOiIyMDI1MDMyNDE3MTgwNy1kYXMtbWFjLXNpZ24tc3RnIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJpc0NoYWxsZW5nZVBlcmZvcm1lZCI6dHJ1ZSwiY29tcGxldGVkQXQiOjE3NDk1NDQ5MzEsImFzc2VydGlvblR5cGUiOiJvd25lcnNoaXAiLCJjZXJ0aWZpZWRNRkFNZXRob2RJZCI6IjIwMDAxIiwiaXNzIjoiaHR0cHM6XC9cL3N0YWdlLnZlcmlmeS5tYXN0ZXJjYXJkLmNvbSIsImF1dGhlbnRpY2F0aW9uRmFjdG9ycyI6IjAyMEEiLCJhcHBJbnN0YW5jZUlkIjoiblpPLUtodTBTRGVPYTZHNjVnZmdWdzAwMDAwMDAwMDAxMFVTIiwiYXVkIjoiaHR0cHM6XC9cL21hc3RlcmNhcmQuY29tIiwiY2xpZW50U2Vzc2lvbklkIjoiODZiZDRhOTEtNDZiYS00YjJjLTliNGEtNTllZWEzODEyZjA3IiwiYXV0aGVudGljYXRpb25NZXRob2QiOiJGSURPMiIsImRhc0F1dGhlbnRpY2F0b3JJbnN0YW5jZUlkIjoiZmVVdUwtRmVUNmlDaGtFLXhrQnowZzAwMDAwMDAwMDAxMFVTIiwiZXhwIjoxNzQ5NTQ1ODMxLCJpYXQiOjE3NDk1NDQ5MzEsImF1dGhlbnRpY2F0aW9uUmVhc29ucyI6WyJBQ0NPVU5UX0xPR0lOIl19.BJIk-3TAl4e6_bnL1iNpuds8SLoX2I_QocQaaofo41Ke4l8jjXm4l8xDNpnten-n9RhbJ2Oz89QUlX-RNUqHPf1mKS09rdrt_NVoEM3Kr9ejqv1KULrz0owE3VIUWZRTvwtod-m5PFCrLLpFmvQTf2FC-YE8Wb_nt8rIjT8KDfzgDH0cayeA5iGvA092nJNBUXze5-xOuct3LtTEOyZS6OhyjRDuQ7UrHNnQdrYCQHkZv0QOYFAJJ6aVUPnYvI0NjNJgYSE4CUGwr0qJDx046WOe3BtgqgC4oFQyCWN-BI6Z2yC9IjyIEZH4wfNd15mshW5nJ7v46s-RoRR0IMsS5Q" * `status`: ERROR/CANCELLED * `reason`: "reason of failure" | Error Scenario | Status | Reason | |---------------------------------------------------------------------------------------------------|-----------|--------------------------| | Cardholder clicks on **Not Now** option. | CANCELLED | USER_CANCELLATION | | Cardholder cancels the operation during **Passkey assertion** or any other unknown error occurred | ERROR | CREDENTIALS_NOT_VERIFIED | | Compliance details not provided in query params | ERROR | INVALID_QUERY_PARAMS | | Backend enrolment API returns 400 | ERROR | INVALID_ARGUMENT | | Backend enrolment API returns 401 | ERROR | PERMISSION_DENIED | | Backend enrolment API returns 403 | ERROR | FORBIDDEN | | Backend enrolment API returns 404 | ERROR | NOT_FOUND | | Backend enrolment API returns 500 | ERROR | INVALID_STATE | | Backend enrolment API returns 503 | ERROR | SERVICE_UNAVAILABLE | | None of the above API error code | ERROR | SERVICE_ERROR | | Something unexpected happened | ERROR | UNKNOWN_ERROR | * **Issuer requests Mastercard to bind the passkey to a device** 6. Issuer calls the [Authenticators](https://developer.mastercard.com/issuer-enrollment/documentation/api-reference/apis/index.md#authentication-apis) API with the proof of authentication to bind the existing payment passkey to a device and the `accountReference` (PAN, email address, phone number) information received from [Sessions](https://developer.mastercard.com/issuer-enrollment/documentation/api-reference/apis/index.md#authentication-apis) API. 7. Mastercard responds with a `credentialId` and `bindingId`.