# 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.
Currently, 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).
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.
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---and a callback URI.
### Guidelines for providing CallbackUri {#guidelines-for-providing-callbackuri}
The Issuer may provide the callback Uri in one of the two ways while considering its corresponding security requirements:
| Provisioning Options | Security Requirements |
|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| As part of the [Sessions](https://developer.mastercard.com/issuer-enrollment/documentation/api-reference/apis/index.md#authentication-apis) API call (Recommended) | Issuers must ensure that the URL is duly validated to prevent misuse or potentially fraudulent activity. |
| As a query parameter when launching the Mastercard UI | * The domain of the URL must be whitelisted by Mastercard. * Issuers must share this domain during onboarding and ensure it is properly whitelisted to enable successful callbacks after payment passkey registration. |
### 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, the cardholder accepts the terms and conditions, and provides the consent to create a Mastercard payment passkey for the cards and email/phone number.
* **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:
* Cardholder's consent.
* 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.
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. Once the cardholder successfully completes the 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:
```javascript
https://verify.mastercard.com/auth/passkeys?clientId=&authenticationSessio
nId=&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.
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/unsuccessfully 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
* `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.
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/unsuccessfully 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
* `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`.