# Integrate with Secure Card on File source: https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/integrate-apis-scof-tutorial/index.md Use this tutorial to learn about the required steps to integrate with Secure Card on File. ## 1. Onboard to Mastercard Checkout Solutions {#1-onboard-to-mastercard-checkout-solutions} 1. Order the [Mastercard Checkout Solutions - Sandbox](https://www.mastercardconnect.com/-/store-plus/item-details/A/srconbrmtf) on [Mastercard Connect](https://www.mastercardconnect.com/). 2. [Enroll in the programs](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/onboarding-sandbox-tutorial/index.md) you require for your sandbox projects. 3. [Create a sandbox project](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/onboarding-sandbox-tutorial/index.md). You can create up to 30 sandbox projects to allow testing in different lower environments. 4. Download the auto-generated [API Signing Key (OAuth key)](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/key-management-tutorial/index.md) and [Consumer Key](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/key-management-tutorial/index.md). 5. Download the auto-generated [Payload Encryption Key](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/key-management-tutorial/index.md). Note: For detailed steps on onboarding for each product in Mastercard Checkout Solutions, please refer to the [Onboard to Sandbox](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/onboarding-sandbox-tutorial/index.md) tutorial. ## 2. Integrate the APIs {#2-integrate-the-apis} * To get started with the API integration, you can generate an API client using an [OpenAPI Generator](https://openapi-generator.tech/), which provides generators and library templates for supporting multiple languages and frameworks. * To help you sign requests and perform payload encryption/decryption, Mastercard provides [client authentication libraries](https://github.com/Mastercard?q=oauth1-signer) and [encryption libraries](https://github.com/Mastercard?&q=client-encryption). * Follow the steps in [Generating and Configuring a Mastercard API Client](https://developer.mastercard.com/platform/documentation/security-and-authentication/generating-and-configuring-a-mastercard-api-client/) tutorial to enable authentication and perform encryption/decryption. * Mastercard supports two protocols for authenticating client applications to integrate with Mastercard APIs. Learn more on /documentation/api-basics/ page. Note: **In case of OAuth Authentication:** * Site identifier `X-Src-Cx-Flow-Id` is added as a part of all inbound API response headers for resolving site affinity issues on subsequent calls. * When making back-to-back API calls, the client must include the `x-Src-Cx-Flow-Id` of the initial API response in the header of the subsequent API request. This ensures that the consecutive API calls will be sent to the same Mastercard server that returned the initial response. **In case of Mutual TLS (MTLS) Authentication:** * The `X-Src-Response-Host` containing a site-specific URL is initially sent from Mastercard in response to the client. * Use this same URL instead of the standard services.mastercard.com domain to ensure that the subsequent calls are directed to the same server that returned the initial response. * MTLS is an alternate authentication mechanism, available on request. Work with your [Mastercard representative](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/support/index.md#get-help) for details. ## 3. Register DPAs With the DPA Registration API {#3-register-dpas-with-the-dpa-registration-api} After successful onboarding for different program types, Mastercard Checkout Solution creates the following IDs which can be used to make the API calls: | Program Types | IDs created | API calls | |---------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Direct Merchant | Unique `serviceId` and `srcDpaId` are generated. | Call [Enroll Card](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#card) API for card tokenization. If you need to onboard merchants, register them as DPAs using [DPA Registration](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#registration) API and provide the `programType` as `SECURE_COF_MERCHANT`. | | Direct Commerce Platform | A unique `serviceId` is generated. | Call [Enroll Card](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#card) API for card tokenization. If you need to commerce platforms, register them as DPAs using [DPA Registration](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#registration) API and provide the `programType` as `SECURE_COF_COMMERCE_PLATFORM`. | | On-Behalf-Of Merchants | Unique `serviceId` and `srcDpaId` are generated. | You must call the [DPA Registration](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#registration) API with `programType` as `SECURE_COF_MERCHANT_OBO` to create test dpas and then call [Enroll Card](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#card) API for card tokenization. | | On-Behalf-Of Commerce Platforms | A unique `serviceId` is generated. | You must call the [DPA Registration](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#registration) API with `programType` as `SECURE_COF_COMMERCE_PLATFORM_OBO` to create test dpas and then call [Enroll Card](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#card) API for card tokenization. | | On-Behalf-Of Shared Merchants | `serviceId` (shared between sub-merchants) and `srcDpaId` are generated and sub-merchants are grouped under these IDs. The serviceId pattern for **On-Behalf-Of Shared Merchants** is `SECURE_COF_MERCHANT_OBO_SHARED#--#01`. Here, **SH** denotes that the TRID (or `serviceId`) is shared between sub-merchants, and it is a mandatory prefix to the Program Name. | You must call the [DPA Registration](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#registration) API with `programType` as `SECURE_COF_MERCHANT_OBO_SHARED` to create test dpas and then call [Enroll Card](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#card) API for card tokenization. | ### Key responsibilities of a PSP/Payment Gateway {#key-responsibilities-of-a-psppayment-gateway} If you are a PSP/Payment Gateway offering the Secure Card on File services to the merchants or commerce platforms, you are responsible for the following: * Maintain a mapping between the `srcDigitalCardId` returned in the Secure Card on File response to the **Enroll Card** ([**POST /cards**](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#card)) request and the `srcDpaId`, `serviceId` used to request this token. * Maintain a mapping between the unique ID it allocates internally for each merchant / commerce platform and the `srcDpaId` and `serviceId`. * Use the Card ID returned from Card enrollment to obtain a cryptogram and a token via the Checkout API to make payments. * Retain and update the following information (with the information received in notifications requests) for each Secure Card on File token: * Token Status * Token Expiry Date * panLastFour (last 4 digits of the PAN or Primary Account Number associated with this token) * digitalCardData * If using a Secure Card on File token as the underlying payment instrument for each payment gateway token then you also need to maintain a mapping between these two token types. ## 4. Enroll Card and Retrieve Details {#4-enroll-card-and-retrieve-details} ### Enroll a Card {#enroll-a-card} Call the [Enroll Card](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#card) API for card tokenization and retrieve the `srcDigitalCardId` and `authenticationMethods`. This token (`srcDigitalCardId`) is associated with the PAN (Primary Account Number) in the consumer's profile. Warning: Use Mastercard provided `src-fpan-encryption` public key to encrypt the card object before calling ([POST /cards](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#card)). Refer to [Card Encryption](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/perform-encryption-tutorial/index.md) tutorial for details on how to obtain the public keys and encrypt the card object.
Alternatively, for tokenizing multiple cards (PANs or TURs) in a batch, use [Card Batch Enroll](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#cards-batch-enrollment) API. Refer to the [Tokenization of Multiple Existing Cards](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/use-cases/card-on-file/create-tokens/tokenization-of-existing-cards/index.md) use cases. ### Retrieve Card Details {#retrieve-card-details} Use the [Get Cards](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#card) API to fetch the latest card information, such as `srcDigitalCardId`, `maskedCard`, `mfaEligibility`, and `authenticationMethods`. These credentials are used for [authentication](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/integrate-apis-scof-tutorial/index.md) and [displaying token/card details](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/use-cases/card-on-file/displaying-tokenized-pan-details/index.md) on Integrator's website. ## 5. Launch Auth UI and Perform Authentication {#5-launch-auth-ui-and-perform-authentication} Note: Performing cardholder authentication is required for Secure Card on File. However, it may not be applicable for all checkout or transaction scenarios. Once a PAN is registered with Secure Card on File, an Integrator can perform ID\&V using one of the following approaches:

Integrators can use **B2B APIs** to retrieve the **Authentication UI URL** for: * Redirecting users from a **web browser** * Loading inside a **web-hosted iFrame** * Launching within a [mobile app](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/scof-passkey-mobile-integration-tutorial/index.md) via an **in-app browser** There are two methods for doing this: ### Option 1: Mastercard-managed authentication {#option-1-mastercard-managed-authentication} 1. Fetch Available Authentication Methods - Call the [Lookup Authentication Method API](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#lookupAccountHolderAuthenticationProfile). For example, when `authenticationMethodType = MANAGED_AUTHENTICATION`, it indicates that the PAN supports transaction authentication using passkeys. When calling the **Lookup Authentication Method API** , ensure that you include a value for `authenticationReasons` = **'ENROL_FINANCIAL_INSTRUMENT'** OR **'CONSUMER_IDENTITY_VALIDATION'** OR **'TRANSACTION_AUTHENTICATION'** . 2. Retrieve the authentication UI URL (`uri`) from the response of the [Authenticate API](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#cccountHolderAuthenticationsAuthenticateProfile) . Ensure that all required fields are provided in the request. ```json { "body": { "srcClientId": "13435294-fa4e-4acb-8fe6-05ab66b08881", "serviceId": "SECURE_COF_COMMERCE_PLATFORM#START_CPD_STG#01", "srcCorrelationId": "c3c3fc36-bc37-418f-bbbc-591dc2791178", "srcDigitalCardId": "EVnHnwc5QBmzzxDwYTIspA000000000000GB", "authenticationMethod": { "authenticationMethodType": "MANAGED_AUTHENTICATION", "authenticationSubject": "CARDHOLDER" }, "authenticationContext": { "authenticationReasons": [ "TRANSACTION_AUTHENTICATION" ], "dpaData": { "dpaPresentationName": "Mastercard MTT Integrated - DPA 3 COF", "dpaName": "dpa3_of_MTT Integrated SRCI COF", "acquirerId": "550e8400", "acquirerBin": "44444" }, "dpaTransactionOptions": { "transactionAmount": { "transactionAmount": 9.19, "transactionCurrencyCode": "USD" }, "merchantName": "START", "merchantCategoryCode": "0008", "merchantCountryCode": "US", "threeDsInputData": { "forceChallenge": false, "billingAddress": {} }, "dpaLocale": "en_AU" }, "consumerDeviceData": { "appInstanceId": "8c55b3bc-349c-4f0f-8daf-9f2787cb6d74", "spcEnabled": false }, "callbackUri": { "uri": "https://eta-macs-test-tools.apps.stl.pcfstage00.mastercard.int/macstools/auth-processing?clientSessionId=a5132a4b-3578-41a8-8bbd-55ace74ea893", "uriType": "WEB_URI" } } }, "headers": { "X-Src-Cx-Flow-Id": "34f4a04b.c5deb17f-a130-4ba7-a000-5bf7c33c75db.1758142793" } } ``` ```json { "body": { "srcCorrelationId": "c3c3fc36-bc37-418f-bbbc-591dc2791178", "authenticationSessionId": "8ac870af-e9f3-4af5-9a45-184e5086a221", "authenticationResult": "NOT_AUTHENTICATED", "authenticationStatus": "PENDING", "methodAttributes": { "uriData": { "uri": "https://stage.src.mastercard.com/auth?sav=ZXlKcmFXUWlPaUl5TURJek1ERXlOakV4TkRNME5TMXpkR2N0YldNdGJtVjNMV2xrWlc1MGFYUjVMWFpsY21sbWFXTmhkR2x2YmkxemNtTXRiV0Z6ZEdWeVkyRnlaQzFwYm5RaUxDSjBlWEFpT2lKS1YxUXJaWGgwTG5ObGMzTnBiMjVwWkY5MGIydGxiaUlzSW1Gc1p5STZJbEpUTWpVMkluMC5leUpoZFdRaU9pSm9kSFJ3Y3pwY0wxd3ZiV0Z6ZEdWeVkyRnlaQzVqYjIwaUxDSmpiMjV6ZFcxbGNrbGtJam9pTVRNME16VXlPVFF0Wm1FMFpTMDBZV05pTFRobVpUWXRNRFZoWWpZMllqQTRPRGd4SWl3aWFYTnpJam9pYUhSMGNITTZYQzljTDIxaGMzUmxjbU5oY21RdVkyOXRJaXdpYzJOdmNHVkVZWFJoSWpvaWUxd2lZWFYwYUZObGMzTnBiMjVKWkZ3aU9sd2lPR0ZqT0Rjd1lXWXRaVGxtTXkwMFlXWTFMVGxoTkRVdE1UZzBaVFV3T0RaaE1qSXhYQ0lzWENKemNtTkRiR2xsYm5SSlpGd2lPbHdpTVRNME16VXlPVFF0Wm1FMFpTMDBZV05pTFRobVpUWXRNRFZoWWpZMllqQTRPRGd4WENJc1hDSnpjbU5EYjNKeVpXeGhkR2x2Ymtsa1hDSTZYQ0pqTTJNelptTXpOaTFpWXpNM0xUUXhPR1l0WW1KaVl5MDFPVEZrWXpJM09URXhOemhjSW4waUxDSmxlSEFpT2pFM05UZ3hOREl5TVRBc0ltbGhkQ0k2TVRjMU9ERTBNVGt4TUN3aWFuUnBJam9pWlRZeU0yUmpOakF0WkRRNU5TMDBaVFExTFdFeE5XUXRaV0V6TjJGa1l6azJNekpqSW4wLlQtNGhSQ3VmblM0WGZONmhVcjRwZnZkZEFHODJoOGExWldHWE9tOHhVRmV0V3E1dUFfZTkxX1VfdFhhQ0dNLXd5aDlVVlNObXlvUnhkSTJhaGVzV0cwdWNhVEhrVWtFb0EtT3lXeU1QRGN0aE04eWtOdWFSbjlZOGRIZkNfRy1MeFprUThxckdiLWc0VTdXNzhaMDVlZXBXam1acS1hZmkwYTU5UEtJOEpPQmtkZUc0Q19pdFZIR1B0TV9uaHE4WEhNUDZkZjYzN3pscmp4YVRCamNJUjlyVm9aZklJcUQyYXQyYVlJdzc2TFZOMjhLUFFtU2Nmd0NydWUwRmRkcUJndFcwTmFmNWRmWVF3SGRHX2laSzB3MW83Y05SajB6MEJCblp6ckRmcEh2YkxJVUdNLTZ1Z0NLb0g1Qll2cGdLdURmWG1tS091dmVwWmZMY1R0b3dVQQ==&traceId=34f4a04b.c5deb17f-a130-4ba7-a000-5bf7c33c75db.1758142793", "uriType": "WEB_URI" } }, "sessionAssuranceValue": "ZXlKcmFXUWlPaUl5TURJek1ERXlOakV4TkRNME5TMXpkR2N0YldNdGJtVjNMV2xrWlc1MGFYUjVMWFpsY21sbWFXTmhkR2x2YmkxemNtTXRiV0Z6ZEdWeVkyRnlaQzFwYm5RaUxDSjBlWEFpT2lKS1YxUXJaWGgwTG5ObGMzTnBiMjVwWkY5MGIydGxiaUlzSW1Gc1p5STZJbEpUTWpVMkluMC5leUpoZFdRaU9pSm9kSFJ3Y3pwY0wxd3ZiV0Z6ZEdWeVkyRnlaQzVqYjIwaUxDSmpiMjV6ZFcxbGNrbGtJam9pTVRNME16VXlPVFF0Wm1FMFpTMDBZV05pTFRobVpUWXRNRFZoWWpZMllqQTRPRGd4SWl3aWFYTnpJam9pYUhSMGNITTZYQzljTDIxaGMzUmxjbU5oY21RdVkyOXRJaXdpYzJOdmNHVkVZWFJoSWpvaWUxd2lZWFYwYUZObGMzTnBiMjVKWkZ3aU9sd2lPR0ZqT0Rjd1lXWXRaVGxtTXkwMFlXWTFMVGxoTkRVdE1UZzBaVFV3T0RaaE1qSXhYQ0lzWENKemNtTkRiR2xsYm5SSlpGd2lPbHdpTVRNME16VXlPVFF0Wm1FMFpTMDBZV05pTFRobVpUWXRNRFZoWWpZMllqQTRPRGd4WENJc1hDSnpjbU5EYjNKeVpXeGhkR2x2Ymtsa1hDSTZYQ0pqTTJNelptTXpOaTFpWXpNM0xUUXhPR1l0WW1KaVl5MDFPVEZrWXpJM09URXhOemhjSW4waUxDSmxlSEFpT2pFM05UZ3hOREl5TVRBc0ltbGhkQ0k2TVRjMU9ERTBNVGt4TUN3aWFuUnBJam9pWlRZeU0yUmpOakF0WkRRNU5TMDBaVFExTFdFeE5XUXRaV0V6TjJGa1l6azJNekpqSW4wLlQtNGhSQ3VmblM0WGZONmhVcjRwZnZkZEFHODJoOGExWldHWE9tOHhVRmV0V3E1dUFfZTkxX1VfdFhhQ0dNLXd5aDlVVlNObXlvUnhkSTJhaGVzV0cwdWNhVEhrVWtFb0EtT3lXeU1QRGN0aE04eWtOdWFSbjlZOGRIZkNfRy1MeFprUThxckdiLWc0VTdXNzhaMDVlZXBXam1acS1hZmkwYTU5UEtJOEpPQmtkZUc0Q19pdFZIR1B0TV9uaHE4WEhNUDZkZjYzN3pscmp4YVRCamNJUjlyVm9aZklJcUQyYXQyYVlJdzc2TFZOMjhLUFFtU2Nmd0NydWUwRmRkcUJndFcwTmFmNWRmWVF3SGRHX2laSzB3MW83Y05SajB6MEJCblp6ckRmcEh2YkxJVUdNLTZ1Z0NLb0g1Qll2cGdLdURmWG1tS091dmVwWmZMY1R0b3dVQQ==", "authenticationSessionExpiry": "1758228310562" }, "headers": { "X-SRC-CX-FLOW-ID": "34f4a04b.c5deb17f-a130-4ba7-a000-5bf7c33c75db.1758142810" } } ``` 3. Redirect the user to the authentication UI URL (`uri`) to perform managed authentication, and capture the authentication status via the HTTPS `callbackUri`. ````javascript // Example Authentication URL https://sandbox.src.mastercard.com/auth?sav=ZXlKcmFXUWlPaUl5TURJek1ERXlOakV4TkRNME5TMXpkR2N0YldNdGJtVjNMV2xrWlc1MGFYUjVMWFpsY21sbWFXTmhkR2x2YmkxemNtTXRiV0Z6ZEdWeVkyRnlaQzFwYm5RaUxDSjBlWEFpT2lKS1YxUXJaWGgwTG5ObGMzTnBiMjVwWkY5MGIydGxiaUlzSW1Gc1p5STZJbEpUTWpVMkluMC5leUpoZFdRaU9pSm9kSFJ3Y3pwY0wxd3ZiV0Z6ZEdWeVkyRnlaQzVqYjIwaUxDSmpiMjV6ZFcxbGNrbGtJam9pTVRNME16VXlPVFF0Wm1FMFpTMDBZV05pTFRobVpUWXRNRFZoWWpZMllqQTRPRGd4SWl3aWFYTnpJam9pYUhSMGNITTZYQzljTDIxaGMzUmxjbU5oY21RdVkyOXRJaXdpYzJOdmNHVkVZWFJoSWpvaWUxd2lZWFYwYUZObGMzTnBiMjVKWkZ3aU9sd2lPR0ZqT0Rjd1lXWXRaVGxtTXkwMFlXWTFMVGxoTkRVdE1UZzBaVFV3T0RaaE1qSXhYQ0lzWENKemNtTkRiR2xsYm5SSlpGd2lPbHdpTVRNME16VXlPVFF0Wm1FMFpTMDBZV05pTFRobVpUWXRNRFZoWWpZMllqQTRPRGd4WENJc1hDSnpjbU5EYjNKeVpXeGhkR2x2Ymtsa1hDSTZYQ0pqTTJNelptTXpOaTFpWXpNM0xUUXhPR1l0WW1KaVl5MDFPVEZrWXpJM09URXhOemhjSW4waUxDSmxlSEFpT2pFM05UZ3hOREl5TVRBc0ltbGhkQ0k2TVRjMU9ERTBNVGt4TUN3aWFuUnBJam9pWlRZeU0yUmpOakF0WkRRNU5TMDBaVFExTFdFeE5XUXRaV0V6TjJGa1l6azJNekpqSW4wLlQtNGhSQ3VmblM0WGZONmhVcjRwZnZkZEFHODJoOGExWldHWE9tOHhVRmV0V3E1dUFfZTkxX1VfdFhhQ0dNLXd5aDlVVlNObXlvUnhkSTJhaGVzV0cwdWNhVEhrVWtFb0EtT3lXeU1QRGN0aE04eWtOdWFSbjlZOGRIZkNfRy1MeFprUThxckdiLWc0VTdXNzhaMDVlZXBXam1acS1hZmkwYTU5UEtJOEpPQmtkZUc0Q19pdFZIR1B0TV9uaHE4WEhNUDZkZjYzN3pscmp4YVRCamNJUjlyVm9aZklJcUQyYXQyYVlJdzc2TFZOMjhLUFFtU2Nmd0NydWUwRmRkcUJndFcwTmFmNWRmWVF3SGRHX2laSzB3MW83Y05SajB6MEJCblp6ckRmcEh2YkxJVUdNLTZ1Z0NLb0g1Qll2cGdLdURmWG1tS091dmVwWmZMY1R0b3dVQQ==&traceId=34f4a04b.c5deb17f-a130-4ba7-a000-5bf7c33c75db.1758142793 ``` // Https callbackUri Example with base64 encoded authentication status https://stage.mcsrcteststore.com/macstools/auth-processing?&res=eyJyZXN1bHQiOiJBVVRIRU5USUNBVElPTl9TVUNDRVNTIiwicmVxdWlyZUFkZGl0aW9uYWxBdXRoIjpmYWxzZSwiYXV0aGVudGljYXRpb25TZXNzaW9uSWQiOiJmYTY3Yjc4Yy1hMWZkLTQyYTQtYTg5MS1mZDdmODE1MDgxZmQifQ%3D%3D ```` Note: In some instances you may not receive the callback URL containing the authentication status, for example, due to network connectivity issues. To confirm authentication is successful, it is essential to complete step 4 to retrieve the authentication assurance data from from the Authenticate API response prior to taking further action. 4. Once the authentication status is received via `callbackUri`, retrieve the proof of authentication (`assuranceData`) from the response of the **Authenticate API**. Make sure all required fields are included in the request. ```json { "body": { "srcClientId": "13435294-fa4e-4acb-8fe6-05ab66b08881", "serviceId": "SECURE_COF_COMMERCE_PLATFORM#START_CPD_STG#01", "srcCorrelationId": "dae7a75c-a8fe-4469-90a8-66033e4798a4", "srcDigitalCardId": "2QXmbgiVSyy9Im-La45iUQ000000000000US", "authenticationSessionId": "3c4908a8-edcc-43b0-9d95-57c3e6821ce6", "authenticationMethod": { "authenticationMethodType": "MANAGED_AUTHENTICATION", "authenticationSubject": "CARDHOLDER" } }, "headers": { "X-Src-Cx-Flow-Id": "34f4a04b.bddf2b43-0e31-42c1-afc7-88d155feaa22.1758314236" } } ``` ```json { "body": { "srcCorrelationId": "dae7a75c-a8fe-4469-90a8-66033e4798a4", "authenticationSessionId": "3c4908a8-edcc-43b0-9d95-57c3e6821ce6", "authenticationResult": "AUTHENTICATED", "authenticationStatus": "COMPLETE", "assuranceData": { "verificationData": [ { "verificationType": "CARDHOLDER", "verificationEntity": "02", "verificationMethod": "07", "verificationResults": "01", "verificationTimestamp": "1758313379228", "verificationEvents": [ "01" ], "additionalData": "eyJ0eXBlIjoiRklETzIiLCJjZXJ0aWZpZWRNZmFNZXRob2RJZCI6IjIwMDAxIiwibWZhTWV0aG9kSW5zdGFuY2VJZCI6InM0eWRYdzQ3VExPYnNKS3VTZE9rT3cwMDAwMDAwMDAwMTBVUyIsImFzc2VydGlvbiI6ImV5SnJhV1FpT2lJeU1ESXpNREV5TmpFeE5ETTBOUzF6ZEdjdGJXTXRibVYzTFdsa1pXNTBhWFI1TFhabGNtbG1hV05oZEdsdmJpMXpjbU10YldGemRHVnlZMkZ5WkMxcGJuUWlMQ0owZVhBaU9pSktWMVFyWlhoMExtTmhjbVJmZEc5clpXNGlMQ0poYkdjaU9pSlNVekkxTmlKOS5leUpoZFdRaU9pSm9kSFJ3Y3pwY0wxd3ZiV0Z6ZEdWeVkyRnlaQzVqYjIwaUxDSmpiMjV6ZFcxbGNrbGtJam9pTVRNME16VXlPVFF0Wm1FMFpTMDBZV05pTFRobVpUWXRNRFZoWWpZMllqQTRPRGd4SWl3aWFYTnpJam9pYUhSMGNITTZYQzljTDIxaGMzUmxjbU5oY21RdVkyOXRJaXdpYzJOdmNHVkVZWFJoSWpvaWUxd2lZWFYwYUZObGMzTnBiMjVKWkZ3aU9sd2lPR0ZqT0Rjd1lXWXRaVGxtTXkwMFlXWTFMVGxoTkRVdE1UZzBaVFV3T0RaaE1qSXhYQ0lzWENKemNtTkRiR2xsYm5SSlpGd2lPbHdpTVRNME16VXlPVFF0Wm1FMFpTMDBZV05pTFRobVpUWXRNRFZoWWpZMllqQTRPRGd4WENJc1hDSnpjbU5EYjNKeVpXeGhkR2x2Ymtsa1hDSTZYQ0pqTTJNelptTXpOaTFpWXpNM0xUUXhPR1l0WW1KaVl5MDFPVEZrWXpJM09URXhOemhjSW4waUxDSmxlSEFpT2pFM05UZ3hOREl5TVRBc0ltbGhkQ0k2TVRjMU9ERTBNVGt4TUN3aWFuUnBJam9pWlRZeU0yUmpOakF0WkRRNU5TMDBaVFExTFdFeE5XUXRaV0V6TjJGa1l6azJNekpqSW4wLlQtNGhSQ3VmblM0WGZONmhVcjRwZnZkZEFHODJoOGExWldHWE9tOHhVRmV0V3E1dUFfZTkxX1VfdFhhQ0dNLXd5aDlVVlNObXlvUnhkSTJhaGVzV0cwdWNhVEhrVWtFb0EtT3lXeU1QRGN0aE04eWtOdWFSbjlZOGRIZkNfRy1MeFprUThxckdiLWc0VTdXNzhaMDVlZXBXam1acS1hZmkwYTU5UEtJOEpPQmtkZUc0Q19pdFZIR1B0TV9uaHE4WEhNUDZkZjYzN3pscmp4YVRCamNJUjlyVm9aZklJcUQyYXQyYVlJdzc2TFZOMjhLUFFtU2Nmd0NydWUwRmRkcUJndFcwTmFmNWRmWVF3SGRHX2laSzB3MW83Y05SajB6MEJCblp6ckRmcEh2YkxJVUdNLTZ1Z0NLb0g1Qll2cGdLdURmWG1tS091dmVwWmZMY1R0b3dVQQ==" } ] } }, "headers": { "X-SRC-CX-FLOW-ID": "34f4a04b.bddf2b43-0e31-42c1-afc7-88d155feaa22.1758314279" } } ``` 5. Use the payment authentication `assuranceData` for completing the Checkout. ### Option 2: Integrator-managed authentication {#option-2-integrator-managed-authentication} 1. Fetch Available Authentication Methods - Call the [Lookup Authentication Method API](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#lookupAccountHolderAuthenticationProfile) with applicable authenticationReasons (one of `ENROLL_FINANCIAL_INSTRUMENT` for card add or `CONSUMER_IDENTITY_VALIDATION` for verify account use case, and `AUTHENTICATOR_REGISTRATION`) and inspect the response to identify available authenticationMethods. Check `authenticationMethods.authenticationMethodType` per table below to identify ID\&V eligibility. | Method Type | Description | |---------------------------|------------------------------------------------------------------------------------------------------------------------------| | **SMS_OTP** | OTP sent to the Cardholder's phone number registered with the Issuer | | **EMAIL_OTP** | OTP sent to the Cardholder's email address registered with the Issuer | | **ISSUER_RBA** | Risk-based authentication assessed by the Issuer; may result in frictionless approval or a declined authentication request | | **APP_AUTHENTICATION** | Issuer Mobile Banking app launched by the Integrator using a deep-link/Android intent with an Integrator callback URL | | **APP_PUSH_NOTIFICATION** | Issuer Mobile Banking app opened when the Cardholder interacts with a Push Notification sent by the Issuer | | **ONBEHALF_ISSUER_IDV** | Mastercard-hosted ID\&V flow using channels provided by the Issuer; equivalent app-based APP_AUTHENTICATION is not supported |
Note: Ensure that the `authenticationReasons` field includes **two values** ---one for **Card Add or Verify Account** and another for **Authenticator Registration** ---when invoking the **Lookup Authentication Method** API. 2. Perform ID\&V - Call the [Authenticate API](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#authentication) to perform ID\&V. You can request: * **OTP** * **App Authentication link** * **Push Notification to App** * **Check results** or * **Risk-Based Authentication (Issuer RBA)** Ensure that **all required fields** are included in the request. ```json { "body": { "srcClientId": "13435294-fa4e-4acb-8fe6-05ab66b08881", "serviceId": "SECURE_COF_COMMERCE_PLATFORM#START_CPD_STG#01", "srcCorrelationId": "c3c3fc36-bc37-418f-bbbc-591dc2791178", "srcDigitalCardId": "EVnHnwc5QBmzzxDwYTIspA000000000000GB", "authenticationMethod": { "authenticationMethodType": "SMS_OTP", "authenticationSubject": "CARDHOLDER" }, "authenticationContext": { "authenticationReasons": ["ENROLL_FINANCIAL_INSTRUMENT"], "dpaData": { "dpaPresentationName": "Mastercard MTT Integrated - DPA 3 COF", "dpaName": "dpa3_of_MTT Integrated SRCI COF" }, "dpaTransactionOptions": { "merchantName": "SAMPLE_MERCHANT", "dpaLocale": "en_AU" } } }, "headers": { "X-Src-Cx-Flow-Id": "34f4a04b.c5deb17f-a130-4ba7-a000-5bf7c33c75db.1758142793" } } ``` ```json { "body": { "srcCorrelationId": "c3c3fc36-bc37-418f-bbbc-591dc2791178", "authenticationSessionId": "8ac870af-e9f3-4af5-9a45-184e5086a221", "authenticationResult": "NOT_AUTHENTICATED", "authenticationStatus": "PENDING", "methodAttributes": { "uriData": { "uri": "https://stage.src.mastercard.com/auth?sav=ZXlKcmFXUWlPaUl5TURJek1ERXlOakV4TkRNME5TMXpkR2N0YldNdGJtVjNMV2xrWlc1MGFYUjVMWFpsY21sbWFXTmhkR2x2YmkxemNtTXRiV0Z6ZEdWeVkyRnlaQzFwYm5RaUxDSjBlWEFpT2lKS1YxUXJaWGgw...", "uriType": "WEB_URI" } }, "sessionAssuranceValue": "ZXlKcmFXUWlPaUl5TURJek1ERXlOakV4TkRNME5TMXpkR2N0..." }, "headers": { "X-SRC-CX-FLOW-ID": "34f4a04b.c5deb17f-a130-4ba7-a000-5bf7c33c75db.1758142810" } } ``` > **Note:** If `authenticationMethods.authenticationMethodType` = **ISSUER_RBA**, then Step 3 below can be skipped. 3. After the consumer has entered an OTP or completed App Authentication or used Push Notification App Authentication, call the **Authenticate API** again to request **proof of authentication** and `assuranceData`. ```json { "body": { "srcClientId": "13435294-fa4e-4acb-8fe6-05ab66b08881", "serviceId": "SECURE_COF_COMMERCE_PLATFORM#START_CPD_STG#01", "srcCorrelationId": "c3c3fc36-bc37-418f-bbbc-591dc2791178", "srcDigitalCardId": "EVnHnwc5QBmzzxDwYTIspA000000000000GB", "authenticationMethod": { "authenticationMethodType": "SMS_OTP", "authenticationSubject": "CARDHOLDER" }, "authenticationContext": { "authenticationReasons": ["ENROLL_FINANCIAL_INSTRUMENT"], "dpaData": { "dpaPresentationName": "Mastercard MTT Integrated - DPA 3 COF", "dpaName": "dpa3_of_MTT Integrated SRCI COF" }, "dpaTransactionOptions": { "merchantName": "SAMPLE_MERCHANT", "dpaLocale": "en_AU" } } }, "headers": { "X-Src-Cx-Flow-Id": "34f4a04b.c5deb17f-a130-4ba7-a000-5bf7c33c75db.1758142793" } } ``` ```json { "body": { "srcCorrelationId": "c3c3fc36-bc37-418f-bbbc-591dc2791178", "authenticationSessionId": "8ac870af-e9f3-4af5-9a45-184e5086a221", "authenticationResult": "NOT_AUTHENTICATED", "authenticationStatus": "PENDING", "methodAttributes": { "uriData": { "uri": "https://stage.src.mastercard.com/auth?sav=ZXlKcmFXUWlPaUl5TURJek1ERXlOakV4TkRNME5TMXpkR2N0YldNdGJtVjNMV2xrWlc1MGFYUjVMWFpsY21sbWFXTmhkR2x2YmkxemNtTXRiV0Z6ZEdWeVkyRnlaQzFwYm5RaUxDSjBlWEFpT2lKS1YxUXJaWGgw...", "uriType": "WEB_URI" } }, "sessionAssuranceValue": "ZXlKcmFXUWlPaUl5TURJek1ERXlOakV4TkRNME5TMXpkR2N0..." }, "headers": { "X-SRC-CX-FLOW-ID": "34f4a04b.c5deb17f-a130-4ba7-a000-5bf7c33c75db.1758142810" } } ``` 4. Passkey Registration -- Retrieve Authentication UI URL - Call the **Authenticate API** and extract the `uri` from the response. This `uri` represents the **Authentication UI URL** that the integrator must launch or redirect the user to. Make sure **all required fields** are included in the request. ```json { "body": { "srcClientId": "13435294-fa4e-4acb-8fe6-05ab66b08881", "serviceId": "SECURE_COF_COMMERCE_PLATFORM#START_CPD_STG#01", "srcCorrelationId": "c3c3fc36-bc37-418f-bbbc-591dc2791178", "srcDigitalCardId": "EVnHnwc5QBmzzxDwYTIspA000000000000GB", "authenticationMethod": { "authenticationMethodType": "FIDO2", "authenticationSubject": "CARDHOLDER" }, "authenticationContext": { "authenticationReasons": ["AUTHENTICATOR_REGISTRATION"], "dpaData": { "dpaPresentationName": "Mastercard MTT Integrated - DPA 3 COF", "dpaName": "dpa3_of_MTT Integrated SRCI COF", "acquirerId": "550e8400", "acquirerBin": "44444" }, "dpaTransactionOptions": { "merchantName": "START", "merchantCategoryCode": "0008", "merchantCountryCode": "US", "threeDsInputData": { "forceChallenge": false, "billingAddress": {} }, "dpaLocale": "en_AU" }, "consumerDeviceData": { "appInstanceId": "8c55b3bc-349c-4f0f-8daf-9f2787cb6d74", "spcEnabled": false }, "callbackUri": { "uri": "https://eta-macs-test-tools.apps.stl.pcfstage00.mastercard.int/macstools/auth-processing?clientSessionId=a5132a4b-3578-41a8-8bbd-55ace74ea893", "uriType": "WEB_URI" } } }, "headers": { "X-Src-Cx-Flow-Id": "34f4a04b.c5deb17f-a130-4ba7-a000-5bf7c33c75db.1758142793" } } ``` ```json { "body": { "srcCorrelationId": "c3c3fc36-bc37-418f-bbbc-591dc2791178", "authenticationSessionId": "8ac870af-e9f3-4af5-9a45-184e5086a221", "authenticationResult": "NOT_AUTHENTICATED", "authenticationStatus": "PENDING", "methodAttributes": { "uriData": { "uri": "https://stage.src.mastercard.com/auth?sav=ZXlKcmFXUWlPaUl5TURJek1ERXlOakV4TkRNME5TMXpkR2N0YldNdGJtVjNMV2xrWlc1MGFYUjVMWFpsY21sbWFXTmhkR2x2YmkxemNtTXRiV0Z6ZEdWeVkyRnlaQzFwYm5RaUxDSjBlWEFpT2lKS1YxUXJaWGgw...", "uriType": "WEB_URI" } }, "sessionAssuranceValue": "ZXlKcmFXUWlPaUl5TURJek1ERXlOakV4TkRNME5TMXpkR2N0..." }, "headers": { "X-SRC-CX-FLOW-ID": "34f4a04b.c5deb17f-a130-4ba7-a000-5bf7c33c75db.1758142810" } } ``` 5. Launch the Authentication UI - Redirect or launch the **Authentication UI URL (`uri`)** to perform **Passkey Registration** . The authentication status will be sent via the configured HTTPS `callbackUri`. ```javascript Example Authentication URL https://sandbox.src.mastercard.com/auth?sav=ZXlKcmFXUWlPaUl5TURJek1ERXlOakV4TkRNME5TMXpkR2N0YldN... ``` 6. Receive Authentication Callback - After authentication is completed, Mastercard sends a **Base64-encoded authentication status** to your callback endpoint. ```javascript Example Callback URI https://stage.mcsrcteststore.com/macstools/auth-processing?res=eyJyZXN1bHQiOiJBVVRIRU5USUNBVElPTl9TVUNDRVNTIiwicmVxdWlyZUFkZGl0aW9uYWxBdXRoIjpmYWxzZSwiYXV0aGVudGljYXRpb25TZXNzaW9uSWQiOiJmYTY3Yjc4Yy1hMWZkLTQyYTQtYTg5MS1mZDdmODE1MDgxZmQifQ%3D%3D ``` 7. Retrieve Proof of Authentication - Once the callback status is received, call the **Authenticate API** again to fetch the **proof of authentication (`assuranceData`)**. Ensure all required parameters are included. > **Note:** The **ID\&V** and **Passkey Registration** steps can be performed in any order, but both must be completed **before Step 8 -- Bind**. 8. Bind Passkey to Consumer Device - Call the **Authenticators API** and provide both the **proof of authentication** and **assuranceData** to bind the Passkey to the Consumer's device. 9. Complete Secure Card on File Checkout without Authentication - Returning consumers on the same device can use the Passkey created in this process to perform **payment authentication** for completing the checkout. ### Launch Auth UI {#launch-auth-ui} Integrators can utilize our SDK to invoke the Authentication UI. 1. Fetch the `authenticationMethods` available in the response of [Enroll Card](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#card), [Get Cards](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#card) or [Lookup Authentication Method](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#authentication) API endpoints to launch the Authentication UI. * For example, `authenticationMethodType` = MANAGED_AUTHENTICATION indicates that transaction authentication is supported using passkey for the PAN. * Ensure that you pass a value in `authenticationReasons` while calling Lookup Authentication Method API. 2. Implement the JavaScript library into your application using one of these URLs (for either Sandbox or Production environments): The `sdk.js` is provided as JavaScript code. Use a script tag in the `` of the HTML page. | Environment | Script tag containing the URL | Description | |-------------|-----------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Sandbox | `` | Sandbox credentials available in [Mastercard Connect](https://www.mastercardconnect.com/) are useful for testing the integration. Checkouts made in this environment are simulated and do not reflect your Production records. | | Production | ` ` | Upon successful integration testing, you can then request for Production credentials. You can change your initialization to use Production environment to start accepting live transactions. | 3. Call the [authenticate()](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/sdk-reference/authenticate/index.md) method via the following window: NAMESPACE = window.AUTHSDK_MASTERCARD. 4. Mastercard responds with the payload containing authentication result and status. ```javascript { authenticationStatus: 'COMPLETE', authenticationResult: 'AUTHENTICATED', assuranceData: { verificationData: [{ verificationType: 'CARDHOLDER', verificationEntity: '03', verificationMethod: '01', verificationResults: '01', verificationTimestamp: '2023-02-13T14:18:40.968Z', verificationEvents: ['02'], additionalData: 'eyJraWQiOiIxNDkwMjQtc3RnLXNyYy1pZGVudGl0eS12ZXJpZmljYXRpb24iLCJ0eXAiOiJKV1QrZXh0LmNhcmRfdG9rZW4iLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJodHRwczpcL1wvbWFzdGVyY2FyZC5jb20iLCJjYXJkSWQiOiI3NWZlOGFlYi1hMGM0LTQ1Y2UtODMxMy1kZGU2YmI1ZTZjNGUiLCJpc3MiOiJodHRwczpcL1wvbWFzdGVyY2FyZC5jb20iLCJjb3JyZWxhdGlvbklkIjoiNmNiMDVkYWMtNzJlZS00M2E2LTgwMmQtMzQ0NDM1NDQ4OGJmIiwic2NvcGVEYXRhIjoie1wiYXV0aFNlc3Npb25JZFwiOlwiN2RiMGQyMzUtNDQwZS00ZTdjLWI5NDAtNGJhY2YxMDc4MzFiXCIsXCJhdXRoZW50aWNhdGlvblJlc3VsdFwiOlwiQVVUSEVOVElDQVRFRFwiLFwiYXV0aGVudGljYXRpb25NZXRob2RcIjpcIjNEU1wiLFwic3JjaUNsaWVudElkXCI6XCJjZTgxMjJhZS04OGJiLTQ1MzctODdmZS04ZTU2Zjk0NzVjYjRcIixcInRocmVlRHNQQVZlcmlmaWVkXCI6XCJ0cnVlXCIsXCJhdXRoZW50aWNhdGlvblRpbWVcIjpcIjIwMjMtMDItMTNUMTQ6MTg6NDAuOTc2WlwiLFwiYXV0aGVudGljYXRpb25SZWFzb25zXCI6W1wiRU5ST0xfRklOQU5DSUFMX0lOU1RSVU1FTlRcIl19IiwiZXhwIjoxNjc2Mjk4MjIwLCJpYXQiOjE2NzYyOTc5MjAsImp0aSI6IjMyMzA0NmM4LTMyMjQtNGE3Zi04NDM3LTA2OGI5ZmE5MmJlMCJ9.to4jlDd3CFPM_ucB9jbCP8_i0xFCFLCOZhHjadO0VZ3keOub0k4fmn_fLw1XZG5U0B8CZMXdsWS_wjBgJ4jaiv_nVF--i_29-YyeQ7BPg6oIPGpEXDEhqxl4ZeeY7quMrMhh2nbupkcHcyB36dCK285D-BLhVtXhed4S1KK-qr6qcOJ76qnDZlDNSx2rIvXwChslXBXFwpPij9JxjKcjv5RWL0qAUXMxKQE8Gf0ZnB_bVZQxRDzw-1CWhKMIyShzahoDJI9dRzKSv-c1xwzz5wTn6FhctGAOk0Sd6KsUIrCBw3W3MXd0uWQXDOhvuYA0aZX9GMRFpOP5penmZNlUaA' }] }, srcCorrelationId: '6cb05dac-72ee-43a6-802d-3444354488bf' } ```
### Perform Authentication {#perform-authentication} Request transaction authentication while adding a card or performing checkout. * [Option 1](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/integrate-apis-scof-tutorial/index.md#option-1-perform-authentication-using-passkey): Perform Authentication using Passkey * [Option 2](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/integrate-apis-scof-tutorial/index.md#option-2-perform-authentication-using-a-preferred-method): Perform Authentication using a Preferred Method #### Option 1: Perform Authentication using Passkey {#option-1-perform-authentication-using-passkey} Mastercard allows the cardholders to create a passkey and the Integrators to use these passkeys for authenticating a transaction. 1. Launch the Mastercard [Authentication UI](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/integrate-apis-scof-tutorial/index.md) to perform Identity and Verification (ID\&V). The authentication request must comprise of: * `authenticationMethodType` = MANAGED_AUTHENTICATION * `authenticationReasons` = ENROL_FINANCIAL_INSTRUMENT or CONSUMER_IDENTITY_VALIDATION or TRANSACTION_AUTHENTICATION * `transactionAmount` \> 0 and other required parameters * Mandatory data fields: **acquirerMerchantId** /**acquirerId** , **acquirerBIN** , **merchantCategoryCode** , **dpaLocale** , and **merchantCountryCode** Note: The `transactionAmount` is required for `authenticationReasons` = TRANSACTION_AUTHENTICATION. 2. If a passkey is not present, Mastercard initiates 3DS authentication. Once the ID\&V is successful, the cardholder is prompted to create a passkey. 3. If a passkey exists, Integrator prompts the cardholder for authentication. 4. Mastercard authenticates the transaction using the passkey and shares the results in `authenticationResult`= AUTHENTICATED and `authenticationStatus`= COMPLETE within `assuranceData` with the Integrator, detailed out [here](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/integrate-apis-scof-tutorial/index.md). 5. Pass these authentication results in the [Checkout API](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/integrate-apis-scof-tutorial/index.md) call. For more information on the use cases, see cases [Authentication by Mastercard (TAS)](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/token-authentication/secure-card-on-file/by-mastercard/index.md). #### Option 2: Perform Authentication using a Preferred Method {#option-2-perform-authentication-using-a-preferred-method} To perform authentication using Issuer supported methods (3DS), follow these steps: 1. Launch the Mastercard [Authentication UI](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/integrate-apis-scof-tutorial/index.md) to perform 3DS transaction authentication. The authentication request must comprise of: * `authenticationMethodType` = 3DS * `authenticationReasons` = TRANSACTION_AUTHENTICATION * `transactionAmount` \> 0 and other required parameters * Mandatory data fields: **acquirerMerchantId** , **acquirerBIN** , **merchantCategoryCode** , and **merchantCountryCode** 2. The Issuer may present the challenge on the Authentication UI or a frictionless 3DS transaction authentication is done. 3. The Issuer shares the authentication results with Mastercard. 4. Upon successful 3DS transaction authentication, Mastercard shares the results in `authenticationResult`= AUTHENTICATED and `authenticationStatus`= COMPLETE within `assuranceData` with the Integrator, detailed out [here](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/integrate-apis-scof-tutorial/index.md). 5. Pass these authentication results in the [Checkout API](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/integrate-apis-scof-tutorial/index.md) call. Use case is available [here](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/token-authentication/secure-card-on-file/by-mastercard/authentication-with-3ds/index.md). ### Launch Auth UI {#launch-auth-ui} Integrators can utilize our URL to invoke the Authentication UI. 1. Fetch the `authenticationMethods` and `uriData.uri` available in the response of [Enroll Card](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#card), or [Lookup Authentication Method](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#authentication) API endpoint to launch the Authentication UI. * For example, `authenticationMethodType` = MANAGED_AUTHENTICATION indicates that transaction authentication is supported using passkey for the PAN. * Ensure that you pass a value in `authenticationReasons` while calling Lookup Authentication Method API. 2. Create a window object. Mastercard recommends to use popup. 3. Define the initialization payload to be sent in the postMessage in Step 7. ```javascript const payload = { authenticationMethod: { authenticationMethodType: "MANAGED_AUTHENTICATION", authenticationSubject: "CARDHOLDER", } srcCorrelationId: 'a5fe8aeb-a0c4-45ce-8313-dde6bb5e6c3d', serviceId: "SECURE_COF_MERCHANT#TESTPROJECT_PROD-PGMNAME#01", srcClientId: "eccbf087-f159-4d69-b31d-00bec75c0474", accountReference: { srcDigitalCardId: '75fe8aeb-a0c4-45ce-8313-dde6bb5e6c4e' }, authenticationContext: { authenticationReasons: ['ENROL_FINANCIAL_INSTRUMENT'], acquirerMerchantId: '550e8400', acquirerBIN: '444444', dpaTransactionOptions: { transactionAmount: { transactionAmount: 250, transactionCurrencyCode: 'USD', "merchantCategoryCode":"0008", "merchantCountryCode":"US" }, threeDsInputData: { billingAddress: { name: 'Coby Greenholt', 'line1': '49674 Gorczany Village', 'line2': 'Hansen Circle', state: 'CT', zip: '98410', countryCode: 'US' } } } } } ``` 4. Navigate to `?origin= ` and load the URL in the window object. ```javascript // extract `uri` from methodAttributes - this is the URL to the hosted Auth UI const { uri } = payload.authenticationMethod.methodAttributes.uriData // load the Auth UI URL with the window origin host defined as a query string parameter const launchUri = `${uri}?origin=${window.location.origin}` ``` 5. Apply an event listener to listen to *Ready* , *Success* and *Error* postMessage events. Provide an event listener in the same webpage as the one that opened the window in step 2 to wait for a postMessage arriving from the Auth UI. The table below describes the different actions: | Action | Description | |-------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| | **Ready** | The Auth UI is ready to receive the initial payload to initialize the authentication experience via `window.postMessage()`. Use the payload from Step 3. | | **Success** | The Auth UI has completed the authentication experience successfully. | | **Error** | The Auth UI has failed to complete the authentication experience. | 6. Mastercard returns a postMessage with `action` = *Ready*. ```javascript dictionary { action: 'Ready' } ``` 7. Further, send a postMessage with `action` = *Authenticate* and the payload containing required fields to perform the authentication within the window object. ```javascript dictionary { action: 'Authenticate', payload: { accountReference: AccountReference, authenticationContext: AuthenticationContext, authenticationMethod: AuthenticationMethod, srcCorrelationId: string, srciTransactionId: string } } ``` 8. Mastercard responds via postMessage with `action` = *Success* or *Error* and the payload containing authentication result and status. ```javascript { authenticationStatus: 'COMPLETE', authenticationResult: 'AUTHENTICATED', assuranceData: { verificationData: [{ verificationType: 'CARDHOLDER', verificationEntity: '03', verificationMethod: '01', verificationResults: '01', verificationTimestamp: '2023-02-13T14:18:40.968Z', verificationEvents: ['02'], additionalData: 'eyJraWQiOiIxNDkwMjQtc3RnLXNyYy1pZGVudGl0eS12ZXJpZmljYXRpb24iLCJ0eXAiOiJKV1QrZXh0LmNhcmRfdG9rZW4iLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJodHRwczpcL1wvbWFzdGVyY2FyZC5jb20iLCJjYXJkSWQiOiI3NWZlOGFlYi1hMGM0LTQ1Y2UtODMxMy1kZGU2YmI1ZTZjNGUiLCJpc3MiOiJodHRwczpcL1wvbWFzdGVyY2FyZC5jb20iLCJjb3JyZWxhdGlvbklkIjoiNmNiMDVkYWMtNzJlZS00M2E2LTgwMmQtMzQ0NDM1NDQ4OGJmIiwic2NvcGVEYXRhIjoie1wiYXV0aFNlc3Npb25JZFwiOlwiN2RiMGQyMzUtNDQwZS00ZTdjLWI5NDAtNGJhY2YxMDc4MzFiXCIsXCJhdXRoZW50aWNhdGlvblJlc3VsdFwiOlwiQVVUSEVOVElDQVRFRFwiLFwiYXV0aGVudGljYXRpb25NZXRob2RcIjpcIjNEU1wiLFwic3JjaUNsaWVudElkXCI6XCJjZTgxMjJhZS04OGJiLTQ1MzctODdmZS04ZTU2Zjk0NzVjYjRcIixcInRocmVlRHNQQVZlcmlmaWVkXCI6XCJ0cnVlXCIsXCJhdXRoZW50aWNhdGlvblRpbWVcIjpcIjIwMjMtMDItMTNUMTQ6MTg6NDAuOTc2WlwiLFwiYXV0aGVudGljYXRpb25SZWFzb25zXCI6W1wiRU5ST0xfRklOQU5DSUFMX0lOU1RSVU1FTlRcIl19IiwiZXhwIjoxNjc2Mjk4MjIwLCJpYXQiOjE2NzYyOTc5MjAsImp0aSI6IjMyMzA0NmM4LTMyMjQtNGE3Zi04NDM3LTA2OGI5ZmE5MmJlMCJ9.to4jlDd3CFPM_ucB9jbCP8_i0xFCFLCOZhHjadO0VZ3keOub0k4fmn_fLw1XZG5U0B8CZMXdsWS_wjBgJ4jaiv_nVF--i_29-YyeQ7BPg6oIPGpEXDEhqxl4ZeeY7quMrMhh2nbupkcHcyB36dCK285D-BLhVtXhed4S1KK-qr6qcOJ76qnDZlDNSx2rIvXwChslXBXFwpPij9JxjKcjv5RWL0qAUXMxKQE8Gf0ZnB_bVZQxRDzw-1CWhKMIyShzahoDJI9dRzKSv-c1xwzz5wTn6FhctGAOk0Sd6KsUIrCBw3W3MXd0uWQXDOhvuYA0aZX9GMRFpOP5penmZNlUaA' }] }, srcCorrelationId: 'a5fe8aeb-a0c4-45ce-8313-dde6bb5e6c3d' } ``` ```javascript /** * Launches the Mastercard-hosted Auth UI. */ function authenticate (payload) { // extract `uri` from methodAttributes - this is the URL to the hosted Auth UI const { uri } = payload.authenticationMethod.methodAttributes.uriData // load the Auth UI URL with the window origin host defined as a query string parameter const launchUri = `${uri}?origin=${window.location.origin}` // open a new window with the hosted Auth UI URL following the windowRef object size requirements. const windowRef = window.open(launchUri, 'AuthenticatorWindow', 'width=,height=') return new Promise((resolve, reject) => { // listen to postMessage events coming from the Auth UI window window.addEventListener('message', ({ data, source, origin }) => { if (source !== windowRef) return // ensure it is the correct window switch (data.action) { case AuthenticateAction.Ready: // Auth UI has loaded and is ready to receive the initial payload windowRef.postMessage({ action: AuthenticateAction.Authenticate, payload }, origin) break case AuthenticateAction.Success: // Auth UI has completed with success windowRef.close() return resolve(data.payload) case AuthenticateAction.Error: // Auth UI has failed to perform authentication windowRef.close() return reject(data.payload) } }) }) } ``` ### Perform Authentication {#perform-authentication} Request transaction authentication while adding a card or performing checkout. * [Option 1](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/integrate-apis-scof-tutorial/index.md#option-1-perform-authentication-using-passkey): Perform Authentication using Passkey * [Option 2](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/integrate-apis-scof-tutorial/index.md#option-2-perform-authentication-using-a-preferred-method): Perform Authentication using a Preferred Method #### Option 1: Perform Authentication using Passkey {#option-1-perform-authentication-using-passkey} Mastercard allows the cardholders to create a passkey and the Integrators to use these passkeys for authenticating a transaction. 1. Launch the Mastercard [Authentication UI](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/integrate-apis-scof-tutorial/index.md) to perform Identity and Verification (ID\&V). The authentication request must comprise of: * `authenticationMethodType` = MANAGED_AUTHENTICATION * `authenticationReasons` = ENROL_FINANCIAL_INSTRUMENT or CONSUMER_IDENTITY_VALIDATION or TRANSACTION_AUTHENTICATION * `transactionAmount` \> 0 and other required parameters * Mandatory data fields: **acquirerMerchantId** /**acquirerId** , **acquirerBIN** , **merchantCategoryCode** , **dpaLocale** , and **merchantCountryCode** Note: The `transactionAmount` is required for `authenticationReasons` = TRANSACTION_AUTHENTICATION. 2. If a passkey is not present, Mastercard initiates 3DS authentication. Once the ID\&V is successful, the cardholder is prompted to create a passkey. 3. If a passkey exists, Integrator prompts the cardholder for authentication. 4. Mastercard authenticates the transaction using the passkey and shares the results in `authenticationResult`= AUTHENTICATED and `authenticationStatus`= COMPLETE within `assuranceData` with the Integrator, detailed out [here](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/integrate-apis-scof-tutorial/index.md). 5. Pass these authentication results in the [Checkout API](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/integrate-apis-scof-tutorial/index.md) call. Use cases are available [here](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/token-authentication/secure-card-on-file/by-mastercard/authentication-with-passkey/create-passkey/index.md). #### Option 2: Perform Authentication using a Preferred Method {#option-2-perform-authentication-using-a-preferred-method} To perform authentication using Issuer supported methods (3DS), follow these steps: 1. Launch the Mastercard [Authentication UI](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/integrate-apis-scof-tutorial/index.md) to perform 3DS transaction authentication. The authentication request must comprise of: * `authenticationMethodType` = 3DS * `authenticationReasons` = TRANSACTION_AUTHENTICATION * `transactionAmount` \> 0 and other required parameters * Mandatory data fields: **acquirerMerchantId** , **acquirerBIN** , **merchantCategoryCode** , and **merchantCountryCode** 2. The Issuer may present the challenge on the Authentication UI or a frictionless 3DS transaction authentication is done. 3. The Issuer shares the authentication results with Mastercard. 4. Upon successful 3DS transaction authentication, Mastercard shares the results in `authenticationResult`= AUTHENTICATED and `authenticationStatus`= COMPLETE within `assuranceData` with the Integrator, detailed out [here](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/integrate-apis-scof-tutorial/index.md). 5. Pass these authentication results in the [Checkout API](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/integrate-apis-scof-tutorial/index.md) call. Use case is available [here](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/token-authentication/secure-card-on-file/by-mastercard/authentication-with-3ds/index.md). ### Perform Authentication {#perform-authentication} Integrators can also opt for Mastercard-approved, third-party authentication solution. In this solution, an Authenticating Entity (AE) serves as a third-party entity and performs authentication. For more details, refer to the [Authentication by Third Party](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/token-authentication/secure-card-on-file/by-third-party/index.md) use cases. ## 6. Retrieve Transaction Payload {#6-retrieve-transaction-payload} Warning: For cards issued in **India** , Integrators must use the API URL endpoints applicable for **India region**. Please note that use of incorrect URLs will lead to failure of API calls. 1. Call the [Checkout](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#checkout) API using `srcDigitalCardId` for the token associated with the chosen card to retrieve the transaction credentials from Mastercard Checkout Solutions. The response will be a JWS which in turn includes an encrypted object - `encryptedPayload`. Note: * Ensure that the value in `srcCorrelationId` in Checkout API request matches the value received from Authentication UI in [Step 5](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/integrate-apis-scof-tutorial/index.md) to receive an authenticated payload, else Mastercard will return `eci` = *06 - Merchant Risk* . * Call the Checkout API within **five** minutes of performing the authentication to receive `eci` = *02 - Authenticated* . Else, the proof of authentication will expire and Mastercard will return `eci` = *06 - Merchant Risk* . * If a region has fraud liability protection for transactions authenticated under the TAF, the **digital transaction data** must be collected from the Integrator to qualify for fraud liability protection. 2. If you opted for transaction authentication, preview the authentication results in `assuranceData` object of `checkoutResponseJWSPayload` in the following table: | Authentication method used | Payload with an example of assuranceData | |----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Passkeys | * DSRP cryptogram and cloud Token * verificationMethod = `07 - FIDO2 authentication` ```javascript { "assuranceData": { "verificationData": [ { "verificationType":"CARDHOLDER", "verificationEntity": "02", "verificationEvents": [ "01"], "verificationMethod": "07", "verificationResults": "01", "verificationTimestamp": "1709591301345", "verificationEvents": ["01"], "additionalData": "proof of passkeys authentication" } ] "eci": "02", } } ``` | | 3DS | * **threeDSOutputData** contains `dsTransId` and `authenticationValue` * verificationMethod = `01 - 3D Secure (3DS)` ```javascript { "assuranceData": { "verificationData": [ { "verificationType": "CARDHOLDER", "verificationEntity": "03", "verificationMethod": "01", "verificationResults": "01", "verificationTimestamp": "1709591301345", "verificationEvents": [ "01" ] } ], "threeDsOutputData": { "dsTransID": "d701e51c-45e2-45e1-8bdb-e53a4155c38b", "authenticationValue": "sjduwxiclotcscsvvseqdlitaamg" }, "eci": "02" } } ``` | 3. Extract the `encryptedPayload` value from the `checkoutResponseJWSPayload`. This value contains a JWE in compact serializable form. The JWE content is signed or encrypted using the public Payload Encryption key (which is a part of the public/private payload encryption key pair) provided by you at the time of onboarding. *Example of an encryptedPayload object:* ```Javascript "eyJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.MIq_v15_eowvwX8MRgrb_H1EevZKB9CZSMMD8-lcbTjQvPFwAyx1USZbZRDB3RGfA_of6aDggnbmQmgsUStPQEpzYMma5mxlv5-VT6ry94xyttBFuCjBV0hudmcOEHiQeIiwS5xBb1iBPFaXTEmMpgDv8lvAm_ncbJ0V5FFDUYYVhK0-SbaODY5OKMdP2N3Y9bCkqjLCAcmkkN3mkrJ6WbzJURmNdfPyL344Cxc14NLZW3fk_yHkmjXybIXJWnUUsdxwFWS5ImwaZGEhbeLGGdpsPTkTkwD86uZCYJlx_dsZi02Vbm9AIiPpKE4L8GS_ltmOQ3YfgfxS6UuzYzaxKw.Xi3KLm7BvjSQuPMSVwSepg.U6Yp-DXd55F6jqy8-LIbmxmExzLaZNCF9Rcmg0g7ViUN3ydm_G5IqJmCFgXg1aO50HYJvnxi5OWG_rs6uV-1I2rrpu3bkuSjkj03N82yhFJBbhr8W_ahlgAMv2FPu4k7aeGp5rWm5lEdvH2UpSvKG2Ae111iFtL842Pk0pgPLOv4jnxFaCrvAPZ4vTvHS1RU27XGW7qXfAOtqpZ38oUJFamYueCIycDrsvacPT650O_JM_QS0ReXkH49bgAt1Sog9r2PY7fjU22ff1oGno51uVK_D9EXyHWcD4I5LYdVd6NenPDfycuQZ_wA98nqMCTzrqx5yQjUQDNYOoDF8ztoKVpYsTJeIUcFTpGXfoLLPTWjoIUds3mIyrXtBWO46rqN8c2nQ6FKC04-CBK9RGbWr1q1ENgfmsBvfXPCIUZ5ACzM1UaU2LkgEYlyiaxn-I3MfauP1adsA3ZOhrDHwSNgA0aVejT_9OTOaBUmywKGtdD7E8PhP7JqbMTXH2gM_9xU7t7TRvntE5uXeALKv4EDurn0p5bASwsYie7xWbsMHGF8lN0aGqJhNKiHL_NFGnR0wzPWS3UXFP7wZFbLM9qSPw.XFMSREEcssFqUM5kIwChIA", ``` ## 7. Decrypt the Payload {#7-decrypt-the-payload} Decrypt the `encryptedPayload` using your private key from the Payload Encryption public / private key pair. Mastercard uses the public key of this key-pair to encrypt response payloads containing payment card credentials. See [Key Management](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/key-management-tutorial/index.md) to understand more about which keys to use to decrypt the payload. The payload will be returned in the most secure format possible and in accordance with the `DpaTransactionOptions.PaymentOptions.dynamicDataType` parameter passed in the [Checkout](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#checkout) API. | dynamicDataType | Description | Payload format | |----------------------------------------|-------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM | Payment authorization using DSRP cryptogram passed in **dynamicData** object. | **DSRP** : Dynamic Secure Remote Payments (DSRP) cryptogram is a type of dynamic data which the Integrator will have to pass within Dynamic Payment Data field (DE104 SE001) of the payment authorization request. This cryptogram is base64 encoded and can be up to 32 characters in length. It is passed in the [Checkout](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#checkout) API. | Diagram encryption_decryption 1. For decrypting the payload, you can use [Mastercard's encryption/decryption libraries](https://github.com/Mastercard?&q=client-encryption) 2. [Add the library](https://github.com/Mastercard/oauth1-signer-java#maven) to your project. 3. Define `util`, which will set the JWE Decryption configuration as per instructions defined in the library. ```Java private static JweConfig decryptionConfig; // Configuration defined by library public static JweConfig getDecryptionConfig() throws Exception { if (ObjectUtils.isEmpty(decryptionConfig)) { File decryptionCert = ResourceUtils.getFile("{{Decryption Certificate Path}}"); //.p12 file PrivateKey decryptionKey = EncryptionUtils.loadDecryptionKey( decryptionCert.getPath(), {{decryptionCertAlias}}, {{decryptionCertPassword}}); decryptionConfig = JweConfigBuilder.aJweEncryptionConfig() .withDecryptionKey(decryptionKey) .withDecryptionPath("$.encryptedPayload", "$") .withEncryptedValueFieldName("encryptedPayload") .build(); } return decryptionConfig; } ``` 4. Define a service interface and implementation for decryption using configuration defined in util. 1. Service Interface: To define behavior and structure of the decryption function. ```Java DecryptedPayloadDTO getDecryptedPayload(clicktopayResponseDTO clicktopayResponseDTO) throws Exception; ``` 2. Service Implementation: Implement service function as per the defined interface. ```Java public DecryptedPayloadDTO getDecryptedPayload(clicktopayResponseDTO clicktopayResponseDTO) throws Exception { JweConfig jweConfig = clicktopayUtils.getDecryptionConfig(); String payload = JweEncryption.decryptPayload(new Gson().toJson(clicktopayResponseDTO), jweConfig); DecryptedPayloadDTO decryptedPayload = new Gson().fromJson(payload,DecryptedPayloadDTO.class) return decryptedPayload; } ``` When the `encryptedPayload` field is decrypted, you will see a JSON object containing transaction information. * DSRP ```DSRP // DSRP cryptogram in the dynamicData object { "token": { "paymentToken": "5480983179133165", "tokenExpirationMonth": "07", "tokenExpirationYear": "22", "paymentAccountReference": "50017Q9JP3JRJXIZ1BXQL2MKMX4LE" }, "shippingAddress": { "addressId": "adb12da8-474b-4e53-9c3b-5541af7c27bf", "name": "John doe", "line1": "test address", "city": "New York", "state": "NY", "countryCode": "US", "zip": "10011" }, "consumerEmailAddress": "johndoe@dummyemail.com", "consumerFirstName": "john", "consumerLastName": "doe", "consumerFullName": "john doe", "consumerMobileNumber": { "countryCode": "1", "phoneNumber": "9912797896" }, "srcTokenResultsData": { "unpredictableNumber": "63f43cff", "tokenRequesterId": "50123197928" }, "dynamicData": { "dynamicDataValue": "AIrqb3XZSbgpAAl2lQeDGgADFA==", "dynamicDataType": "CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM" }, "billingAddress": { "addressId": "3374e6e9-293a-4612-aa5d-0e42a8ff7aae", "name": "John doe", "line1": "test address", "city": "New York", "state": "NY", "countryCode": "US", "zip": "10011" } } ``` | Field | Description | |------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------| | **token** object | Indicates that the transaction has been tokenized. | | ↳ **paymentToken** | A 16 digit token rather than a PAN (Primary Account Number). | | ↳ **tokenExpirationMonth** ↳ **tokenExpirationYear** | Parameters which provide the tokenized values for digitized card. | | ↳ **paymentAccountReference** | Non-transactable value that is paired with a FPAN and is linked to any token created that represents that FPAN. | | **dynamicData** object | A cryptogram object. | | ↳ **dynamicDataValue** | Containing the 32 char DSRP cryptogram in base64. | | ↳ **dynamicDataType** | `CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM` indicates DSRP. | | **srcTokenResultsData** object | Additional token data. | | ↳ **tokenRequesterId** | Token Requester identifier. | | ↳ **unpredictableNumber** | Unpredictable Number used to generate this cryptogram. | Once the Mastercard Checkout Solution receives the payload response for a tokenized payment, they can proceed to make a payment authorization with their acquirer or payment provider. ## 8. Send the Payload for Authorization {#8-send-the-payload-for-authorization} When the consumer submits the order, send the decrypted payload for authorization. For tokenized transactions, the response payload fields are passed in a Payment Authorization request as follows: | Solution | Description | |----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **DSRP** | PAN with the **paymentToken** value, DE 104(Digital Payment Data), subelement 001 (Digital Payment Cryptogram) with the **dynamicDataValue** and Date Expiration (DE14) with **tokenExpirationMonth** and **tokenExpirationYear** in YYMM format. | Note: The API specification does not define requirements for transaction processing. For more information about DSRP transactions, refer to: * [DSRP --- Acquirer Implementation Guide](https://trc-techresource.mastercard.com/r/bundle/m_an5843/page/z/ndg1634167211641.html) * [AN3363 --- Mandatory Use of Digital Payment Data Field for Remote Commerce Transactions with Cryptograms](https://trc-techresource.mastercard.com/r/bundle/m_an3363_en-us/page/d/en-US/jvw1585260985294.html) ## 9. Manage Card Lifecycle Notifications {#9-manage-card-lifecycle-notifications} Configure your notification URL in the [Card Notifications](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#notifications) API to receive [lifecycle management notifications](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/use-cases/card-on-file/managing-tokens/index.md) relating to a token or the underlying payment account, such as updates on card details and PAN expiration.