# Move from M4M to Secure Card on File
source: https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/m4m-migration-tutorial/index.md
Secure Card on File (SCOF) extends the power of Mastercard Digital Enablement Service (MDES) by offering new features, use cases, and capabilities that are not available on MDES for Merchants. This tutorial is for MDES for Merchants (M4M) customers who want to use the extra features and services that Secure Card on File (SCOF) offers.
### Things to Remember {#things-to-remember}
* If you're a new customer looking to use SCOF for tokenization, review our [SCOF documentation](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/use-cases/card-on-file/index.md) and [integration tutorial](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/integrate-apis-scof-tutorial/index.md) to integrated with SCOF.
* If you're an M4M customer with tokenized data (Primary Account Numbers or PANs) as Token Unique References (TURs), you can start using our new APIs to move these tokens to the SCOF platform.
* Migration is a process of exchanging each unique TUR for an `srcDigitalCardId`. By doing so, you're enabled to utilize the value-added services of Secure Card on File.
## Prerequisites {#prerequisites}
1. [Onboard to Sandbox](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/onboarding-sandbox-tutorial/index.md): Onboard with the required products, create projects, and configure your test environment.
2. [API Keys](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/key-management-tutorial/index.md): Create and manage the API keys required to integrate with Mastercard Checkout Solutions.
3. [Onboard to Production](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/onboarding-production-tutorial/index.md): Onboard with the required products, set up, and configure your production environment.
4. [Integrate with SCOF](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/integrate-apis-scof-tutorial/index.md): Follow the steps outlined in this tutorial to integrate with the APIs to provide SCOF experience.
### Key Identifiers {#key-identifiers}
| Identifier in M4M | Equivalent identifier in SCOF |
|-----------------------------------|-------------------------------|
| Token Requestor Identifier - TRID | `serviceId` |
| Token Unique Reference - TUR | `srcDigitalCardId` |
## 1. Onboard to Secure Card on File {#1-onboard-to-secure-card-on-file}
Before you begin the migration process, you must onboard to SCOF.
SCOF offers several [program types](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/use-cases/card-on-file/index.md#program-types) to support different integrations. The program types relevant to M4M customers are:
* On Behalf Of Merchant
* On Behalf Of Shared Merchant
* Merchant Direct
To onboard M4M TRIDs to SCOF, you must provide the TRID and SCOF provides an equivalent `serviceId`.
### Service ID {#service-id}
For MDES for Merchants (M4M), Customer Facing Entity Names (CFENs) are associated with Token Requester Identifiers (TRIDs). While for Secure Card on File, the serviceId is associated with the Program Name and is mapped with the Token Requester Identifier (TRID), which means the serviceId represents the entity that interacts with the cardholder. Hence, CFEN is identified with Program Name and serviceId is identified with TRID. Integrators must ensure that the Program Name represents the merchant's name that the cardholder interacts with.
Follow the steps outlined in this [tutorial](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/onboarding-sandbox-tutorial/index.md) to understand how to get access to our application, enroll in programs, and manage keys in Mastercard Checkout Solutions. Follow the steps outlined below to onboard specific M4M TRIDs to SCOF.
### Onboard as an On-Behalf-of-Merchant or On-Behalf-of-Shared-Merchant {#onboard-as-an-on-behalf-of-merchant-or-on-behalf-of-shared-merchant}
1. In the Mastercard Checkout Solutions onboarding application, ensure that you have onboarded and registered as **Program Type** = *On Behalf Of Merchant* or *On Behalf Of Shared Merchant* . This creates a unique `serviceId` for your **Program Type**.
2. Integrate with the [DPA (Digital Payment Application) Registration](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#registration) API to obtain a `serviceId` and a create `srcDpaId`. Use these identifiers to onboard the M4M TRIDs.
3. Register your TRIDs on SCOF and map them to the new `serviceId`. Use the **ADD** function in [DPA Registration](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#registration) API to insert your TRID, `programName`, and `dpaData`. Note: Onboard one M4M TRID per DPA Registration API call.
In case of multiple M4M TRIDs onboarding to Secure Card on File, register one entity per call at an agreed Transaction per Second (TPS).
```json
"items": [
{
"action": "ADD",
"programType": "SECURE_COF_MERCHANT_OBO",
"programName": "myShop*pay",
"trid": "99999999999",
"dpas": [
{
"srcDpaId": "src_dpa_99999",
"dpaData": {
"dpaPresentationName": "Ecom Holdings",
"dpaAddress": {
"name": "Ecom Online Store",
"line1": "100 Avenue Lane Street",
"line2": "Address line 2",
"line3": "Address line 3",
"city": "Metropolis",
"state": "MH",
"countryCode": "US",
"zip": 41321
},
"dpaName": "Ecom Holdings Online Inc",
"dpaLogoUri": "https://example.com/ecom-online-ltd/images/ecom-logo.png",
"dpaUri": "https://example.com/ecom-online-ltd/basket.html"
}
}
],
"merchantCategoryCode": [
"9999",
"9998"
]
},
]
```
### Onboard as a Technial Enabler (Digital Activity Service Provider) {#onboard-as-a-technial-enabler-digital-activity-service-provider}
For Integrators who identify as [Digital Activity Service Provider](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/onboarding-sandbox-tutorial/index.md) must work with a [Mastercard representative](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/support/index.md#get-help) to onboard from M4M to Secure Card on File.
Note: Ensure that you use the same Company ID (CID) in M4M and Secure Card on File.
### Onboard as a Direct Merchant {#onboard-as-a-direct-merchant}
Work with your [Mastercard representative](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/support/index.md#get-help) to onboard from M4M to Secure Card on File as a Direct Merchant.
## 2. Transfer M4M Tokens to SCOF {#2-transfer-m4m-tokens-to-scof}
Similar to a Token Unique Reference (TUR) and on M4M (MDES for Merchant), Secure Card on File (SCOF) needs `srcDigitalCardId` to make API calls. This `srcDigitalCardId` is created as part of tokenization in SCOF.
Warning: The migration does not re-tokenize your existing tokens, and you must use SCOF APIs to create and migrate new identifiers in SCOF.
You can migrate M4M tokens to SCOF in one of two ways:
1. Calling the [Enroll Card API](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/m4m-migration-tutorial/index.md#for-integrators-utilizing-the-enroll-api) to migrate one TUR in a single request.
2. Calling the [Batch Enroll API](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/m4m-migration-tutorial/index.md#for-integrators-utilizing-the-batch-enroll-api) to migrate 250 TURs in a single request.
### For Integrators Using the Enroll API {#for-integrators-using-the-enroll-api}
Single card enrollment is recommended for Integrators looking to migrate a smaller volume of TURs onto Secure Card on File (for example: less than or equal to 20 million active tokens).
You can use the Enroll Card API request by following the steps outlined below:
1. Provide each TUR in the [Enroll Card](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#card) request by populating:
* `enrolmentReferenceId` with the existing M4M TUR
* `enrolmentReferenceType` as `EXISTING_TOKEN_UNIQUE_REFERENCE`
```javascript
{
"serviceId": "SECURE_COF_MERCHANT_OBO#START_SANDBOX_SRCI-KAUSHAL_TAILOR#01",
"srcDpaId": "b756a2b0-ef62-4c62-a6de-f72e75ce5f17",
"enrolmentReferenceData": {
"enrolmentReferenceId": "DM4MMC0000144136fb04571884c24d7388daa18a772b05e5",
"enrolmentReferenceType": "EXISTING_TOKEN_UNIQUE_REFERENCE"
}
}
```
2. On successful enrollment, SCOF provides a `srcDigitalCardId` that you can use for future Checkouts.
```javascript
{
"srcCorrelationId": "b6db0d1c-5afa-46a0-b336-47ca05da15a6",
"maskedCard": {
"srcDigitalCardId": "fb921d5c-89cd-44d3-90f6-3d465e277791",
"panBin": "222269",
"panLastFour": "4574",
"tokenUniqueReference": "DM4MMC0000144136fb04571884c24d7388daa18a772b05e5",
"tokenLastFour": "0728",
"digitalCardData": {
"status": "ACTIVE",
"descriptorName": "MasterCard Test Bank",
"artUri": "https://sbx.assets.mastercard.com/card-art/combined-image-asset/6713d73d-a701-4bd2-bc9b-2e98940de9c7.png",
"isCoBranded": "false",
"issuerName": "Test IssuerÂ",
"longDescription": "Test Bank for MasterCard MTF",
"foregroundColor": "0f0f0f"
},
"panExpirationMonth": "12",
"panExpirationYear": "2024",
"paymentCardDescriptor": "mastercard",
"paymentCardType": "CREDIT",
"serviceId": "SECURE_COF_MERCHANT_OBO#START_SANDBOX_SRCI-KAUSHAL_TAILOR#01",
"dateOfCardCreated": "2023-05-31T20:23:47.005Z",
"maskedConsumer": {
"srcConsumerId": "4ba06d41-0c59-41f5-adc1-b62b9ab6e74d",
"maskedConsumerIdentity": {
"identityType": "EXTERNAL_ACCOUNT_ID",
"maskedIdentityValue": "SYSTEM_GENERATED_ccb5ef5d-c109-412f-8aa3-27b24080c14d"
},
"complianceSettings": {
"privacy": null,
"tnc": null
},
"status": "ACTIVE",
"dateConsumerAdded": "2023-05-31T20:23:46.344Z"
}
}
}
```
3. Maintain the status of migrated tokens and map the TURs/tokens to `srcDigitalCardId` to ensure all tokens are eventually migrated.
Note: Transaction per Second (TPS) will be throttled in the single-card enrollment use case at 5 TPS.
### For Integrators Using the Batch Enroll API {#for-integrators-using-the-batch-enroll-api}
[Batch Enrollment](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/use-cases/card-on-file/create-tokens/tokenization-of-existing-cards/index.md) is recommended for Integrators looking to migrate a larger volume of TURs onto Secure Card on File (for example: more than or equal to 20 million active tokens).
Note: These TURs will be migrated asynchronously offline, and you will receive a new Batch Enrollment Notification (on a per-card basis) as each TUR is processed. Listen for these notifications, as newly migrated TURs can be used immediately upon receipt of the notification. For detailed instructions on completing this flow, refer to the [Batch Enrollment Notification](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/use-cases/card-on-file/create-tokens/tokenization-of-existing-cards/index.md) section.
You can use the [Batch Enroll API](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#cards-batch-enrollment) by following the steps outlined below:
1. Submit a Batch request (with up to 250 existing TURs) containing the existing TUR in the `EnrollmentReferenceId` parameter, and a unique `externalEnrollmentReferenceId` for each TUR.
```javascript
{
"srcClientId": "eccbf087-f159-4d69-b31d-00bec75c0474",
"serviceId": "SECURE_COF_COMMERCE_PLATFORM#Mastercard#01",
"srcDpaId": "b756a2b0-ef62-4c62-a6de-f72e75ce5f17",
"externalBatchId": "9d56d47e-70d6-470f-a0a6-c0fccb7e3a43",
"enrollmentData": [
{
"enrollmentSource": [
{
"externalEnrollmentReferenceId": "ebcaf087-f159-4d69-b31d-00bec75c0864",
"enrollmentReferenceType": "EXISTING_TOKEN_UNIQUE_REFERENCE",
"enrollmentReferenceId": "DM4MMC0000144136fb04571884c24d7388daa18a772b05e5"
}
]
},
{
"enrollmentSource": [
{
"externalEnrollmentReferenceId": "ebcaf087-f159-4d69-b31d-00bec75c0868",
"enrollmentReferenceType": "EXISTING_TOKEN_UNIQUE_REFERENCE",
"enrollmentReferenceId": "DM4MMC0000144136fb04571884c24d7388daa18a772b05e4"
}
]
},
{
"enrollmentSource": [
{
"externalEnrollmentReferenceId": "ebcaf087-f159-4d69-b31d-00bec75c0868",
"enrollmentReferenceType": "EXISTING_TOKEN_UNIQUE_REFERENCE",
"enrollmentReferenceId": "DM4MMC0000144136fb04571884c24d7388daa18a772b05e4"
}
]
}
]
}
```
2. Receive an acknowledgement response from Mastercard Checkout Solutions. The response will contain a `batchId`, which is a unique identifier generated by Mastercard Checkout Solutions created per batch request and shared with the Issuer. Use the `batchID` to get the status of the batch process later.
```javascript
{
"batchId": "dccbf087-f159-4d69-b31d-00bec75c0970",
"externalBatchId": "6ecbf087-f159-4d69-b31d-00bec75c0478"
}
```
3. Mastercard Checkout Solutions adds the batch request to the Batch Processing queue.
4. Batch Processing queue processes the TURs asynchronously offline.
5. Receive a Batch Enrollment Notification (per-card) containing a `srcDigitalCardId` and associated card metadata for successful enrollments, or an error for unsuccessful enrollments.
Note:
* To prevent cross-batch mapping errors, always check `batchId` first upon receiving a per-card enrollment notification. Then, use `externalEnrollmentReferenceId` to map `srcDigitalCardId` (or errors) correctly.
* Use the `srcDigitalCardId` in Checkout API to fetch the token and cryptogram when a transaction is occurring.
* For any missed Batch Migration Notifications, utilize the [getBatch API](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#cards-batch-enrollment) to retrieve the status of the TUR. After calling the getBatch API, you will receive a successful migration response with the `cardId` or an unsuccessful response with an error message. Refer to the [Batch Notification Status](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/use-cases/card-on-file/create-tokens/tokenization-of-existing-cards/index.md#receiving-bulk-enrollment-notifications) for step-by-step instructions on how to retrieve the status of bulk migration.
### Key Considerations {#key-considerations}
* Until all tokens are successfully migrated, you must maintain two integrations (M4M and SCOF) to support lifecycle management updates from both MDES and Mastercard Checkout Solutions.
* Migrating tokens from M4M to SCOF will not result in the creation of a new token. SCOF creates new `srcDigitalCardId` that need to be used for subsequent API calls in SCOF.
* For each TRID you migrate, we recommend a TUR migration before the first FPAN based tokenization to ensure that the Integrator has mapped the new `serviceId` to the expected TRID/Token correctly, but it is not mandatory.
* During the process of migration, you can enroll all net-new cards in SCOF using [PAN](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/use-cases/card-on-file/create-tokens/index.md) and [push account receipt](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/use-cases/card-on-file/create-tokens/scof-push-acc-receipt/index.md). It is not recommended to enroll new cards via M4M and then immediately migrate to SCOF; this is a redundant process that will add latency and is inconsistent with best practices.
* Migration of tokens from M4M to SCOF should happen offline (when the consumer is not present) and throttled at Transaction per Second (TPS) agreed with Mastercard.
* Trying to migrate an invalid credential will give a **INVALID_STATE** (HTTP 400 Bad Request) error. Delete this credential and refrain from migrating this credential.
* After successfully transferring an M4M token to SCOF, if you make further requests to MDES APIs, MDES may respond with **AUTHORIZATION_FAILED** error.
## 3. Manage and Use Tokens on SCOF {#3-manage-and-use-tokens-on-scof}
Once you have added a card to SCOF, either through tokenizing a new PAN (Primary Account Number) or migrating an M4M TUR to SCOF, you can leverage the existing use cases from SCOF to use `srcDigitalCardId`:
* [Manage Tokens](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/use-cases/card-on-file/managing-tokens/index.md)
* [Display Tokenized Card Details](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/use-cases/card-on-file/displaying-tokenized-pan-details/index.md)
* [Perform Authentication](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/token-authentication/index.md)
* [Make Payments](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/use-cases/card-on-file/making-payments/index.md)
## 4. Test Scenarios {#4-test-scenarios}
As part of the test plan, ensure that you onboard to SCOF, migrate your tokens, add cards, and checkout using SCOF APIs.
### Scenario 1: TRID (Token Requester Identifier)-based Onboarding {#scenario-1-trid-token-requester-identifier-based-onboarding}
1. Onboard to SCOF using the [onboarding steps](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/integrate-apis-scof-tutorial/index.md) and enroll into the OBO-COF program using your existing TRIDs.
2. Next, integrate with the DPA registration API to replace the TRIDs in M4M to `serviceId` in SCOF. The `serviceId` will replace TRID as an identifier and SCOF will maintain the TRID mapping.
```json
{
"requestId": "543cb179-3688-4515-8e46-6bd8b83f0e10",
"items": [
{
"action": "ADD",
"programType": "SECURE_COF_MERCHANT_OBO",
"programName": "myShop*pay",
"trid": "99999999999",
"dpas": [
{
"srcDpaId": "src_dpa_99999",
"dpaData": {
"dpaPresentationName": "Ecom Holdings 1",
"dpaAddress": {
"name": "Ecom Online Store 1",
"line1": "101 Avenue Lane Street",
"line2": "Address line 2",
"line3": "Address line 3",
"city": "Metropolis",
"state": "MH",
"countryCode": "US",
"zip": 41321
},
"dpaName": "Ecom Holdings Online 1 Inc",
"dpaLogoUri": "https://example.com/ecom-online-ltd/images/ecom-logo.png",
"dpaUri": "https://example.com/ecom-online-ltd/basket.html"
}
}
],
"merchantCategoryCode": [
"9999",
"9998"
]
}
]
}
```
### Scenario 2: Transferring an MDES for Merchant or M4M token to Secure Card on File (SCOF) and Checkout {#scenario-2-transferring-an-mdes-for-merchant-or-m4m-token-to-secure-card-on-file-scof-and-checkout}
1. Once onboarded, use SCOF [Enroll API](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#card) or the [Batch Enroll API](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#cards-batch-enrollment) to migrate an existing TUR in M4M to SCOF.
```javascript
{
"serviceId": "SECURE_COF_MERCHANT_OBO#START_SANDBOX_SRCI-KAUSHAL_TAILOR#01",
"srcDpaId": "b756a2b0-ef62-4c62-a6de-f72e75ce5f17",
"enrolmentReferenceData": {
"enrolmentReferenceId": "DM4MMC0000144136fb04571884c24d7388daa18a772b05e5",
"enrolmentReferenceType": "EXISTING_TOKEN_UNIQUE_REFERENCE",
}
}
```
```javascript
{
"srcCorrelationId": "b6db0d1c-5afa-46a0-b336-47ca05da15a6",
"maskedCard": {
"srcDigitalCardId": "fb921d5c-89cd-44d3-90f6-3d465e277791",
"panBin": "222269",
"panLastFour": "4574",
"tokenUniqueReference": "DM4MMC0000144136fb04571884c24d7388daa18a772b05e5",
"tokenLastFour": "0728",
"digitalCardData": {
"status": "ACTIVE",
"descriptorName": "MasterCard Test Bank",
"artUri": "https://sbx.assets.mastercard.com/card-art/combined-image-asset/6713d73d-a701-4bd2-bc9b-2e98940de9c7.png",
"isCoBranded": "false",
"issuerName": "Test IssuerÂ",
"longDescription": "Test Bank for MasterCard MTF",
"foregroundColor": "0f0f0f"
},
"panExpirationMonth": "12",
"panExpirationYear": "2024",
"paymentCardDescriptor": "mastercard",
"paymentCardType": "CREDIT",
"serviceId": "SECURE_COF_MERCHANT_OBO#START_SANDBOX_SRCI-KAUSHAL_TAILOR#01",
"dateOfCardCreated": "2023-05-31T20:23:47.005Z",
"maskedConsumer": {
"srcConsumerId": "4ba06d41-0c59-41f5-adc1-b62b9ab6e74d",
"maskedConsumerIdentity": {
"identityType": "EXTERNAL_ACCOUNT_ID",
"maskedIdentityValue": "SYSTEM_GENERATED_ccb5ef5d-c109-412f-8aa3-27b24080c14d"
},
"complianceSettings": {
"privacy": null,
"tnc": null
},
"status": "ACTIVE",
"dateConsumerAdded": "2023-05-31T20:23:46.344Z"
}
}
}
```
2. On using the [Batch Enroll API](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#cards-batch-enrollment), Mastercard sends a notification to the Integrator via [Batch Enrollment Notification API](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#notifications) on per-card basis for each submitted record. For successful enrolments, the notification contains an `srcDigitalCardId` (mapped to the `externalEnrollmentReferenceId`), which can be used in Checkout API to make payments.
```javascript
{
"srcClientId": "eccbf087-f159-4d69-b31d-00bec75c0474",
"serviceId": "SECURE_COF_COMMERCE_PLATFORM#Mastercard#01",
"srcDpaId": "b756a2b0-ef62-4c62-a6de-f72e75ce5f17",
"externalBatchId": "9d56d47e-70d6-470f-a0a6-c0fccb7e3a43",
"enrollmentData": [
{
"enrollmentSource": [
{
"externalEnrollmentReferenceId": "ebcaf087-f159-4d69-b31d-00bec75c0864",
"enrollmentReferenceType": "EXISTING_TOKEN_UNIQUE_REFERENCE",
"enrollmentReferenceId": "DM4MMC0000144136fb04571884c24d7388daa18a772b05e5"
}
]
},
{
"enrollmentSource": [
{
"externalEnrollmentReferenceId": "ebcaf087-f159-4d69-b31d-00bec75c0868",
"enrollmentReferenceType": "EXISTING_TOKEN_UNIQUE_REFERENCE",
"enrollmentReferenceId": "DM4MMC0000144136fb04571884c24d7388daa18a772b05e4"
}
]
},
{
"enrollmentSource": [
{
"externalEnrollmentReferenceId": "ebcaf087-f159-4d69-b31d-00bec75c0868",
"enrollmentReferenceType": "EXISTING_TOKEN_UNIQUE_REFERENCE",
"enrollmentReferenceId": "DM4MMC0000144136fb04571884c24d7388daa18a772b05e4"
}
]
}
]
}
```
```javascript
{
"batchId": "c77a1d67-447e-431a-9e0a-fa4d60455154",
"externalBatchId": "2f094233-07b3-4c96-871f-eb0b0cab2739",
"enrollmentStatus": "SUCCESS",
"enrollmentReferenceType": "EXISTING_TOKEN_UNIQUE_REFERENCE",
"eventTimeStamp": "2024-12-20T14:56:08.918Z",
"externalEnrollmentReferenceId": "fb741031-8fdf-4330-98f2-0c58b5a16e78",
"maskedCard": {
"dateOfCardCreated": "2024-09-25T15:50:14.500Z",
"digitalCardData": {
"artUri": "https://stage.assets.mastercard.com/card-art/combined-image-asset/8fca6dbf-e3f1-42da-80ab-fb0cee75ee9c.png",
"coBrandedName": "Co brand partner",
"descriptorName": "Issuing Bank",
"isCoBranded": true,
"status": "ACTIVE",
"issuerName": "Issuing Bank",
"longDescription": "Bank Rewards Mastercard with rewards program",
"foregroundColor": "1A2B3C"
},
"panBin": "520000",
"panExpirationMonth": "01",
"panExpirationYear": "2020",
"panLastFour": "0123",
"paymentAccountReference": "500181d9f8e0629211e3949a08002",
"paymentCardDescriptor": "mastercard",
"paymentCardType": "CREDIT",
"serviceId": "SECURE_COF_COMMERCE_PLATFORM#E2E#01",
"srcDigitalCardId": "9sJkUbYQRVSDTlAbVhtW2Q000000000000US"
}
}
```
```javascript
{
"batchId": "a6016322-ac86-4ac7-8567-e7b8a424c78c",
"externalBatchId": "6ecbf087-f159-4d69-b31d-00bec75c0478",
"eventTimeStamp": "1585741817000",
"enrollmentRecordNotifications": [
{
"cardRecords": [
{
"enrollmentReferenceType": "FPAN",
"externalEnrollmentReferenceId": "ef016322-ac86-4ac7-8567-e7b8a424c79d",
"status": "SUCCESS",
"maskedCard": {
"dateOfCardCreated": "2020-02-24T11:32:32.060Z",
"digitalCardData": {
"artUri": "https://assets.mastercard.com/card-art/combined-image-asset/9d42df54-c5fd-438b-a886-ff0bd1e8f7ec.png",
"descriptorName": "Mastercard",
"foregroundColor": "000000",
"issuerName": "Issuing Bank",
"presentationName": null,
"status": "ACTIVE"
},
"panBin": "545503",
"panExpirationMonth": "04",
"panExpirationYear": "2023",
"panLastFour": "6828",
"paymentAccountReference": "500150F5DE22SND132Y6PR32AR5HB",
"paymentCardDescriptor": "Mastercard",
"paymentCardType": "CREDIT",
"srcDigitalCardId": "e6016322-ac86-4ac7-8567-e7b8a424c70b"
}
}
]
}
]
}
```
### Scenario 3: New PAN Tokenization and Checkout {#scenario-3-new-pan-tokenization-and-checkout}
1. After successfully onboarding the existing TRIDs in M4M to SCOF, use SCOF [Enroll Card](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#card) API to tokenize net new PANs.
```javascript
{
"serviceId": "SECURE_COF_MERCHANT_OBO#START_SANDBOX_SRCI-KAUSHAL_TAILOR#01",
"srcDpaId": "b756a2b0-ef62-4c62-a6de-f72e75ce5f17",
"enrolmentReferenceData": {
"enrolmentReferenceId": "DM4MMC0000144136fb04571884c24d7388daa18a772b05e5",
"enrolmentReferenceType": "EXISTING_TOKEN_UNIQUE_REFERENCE",
}
}
```
2. The Enroll response will return a `srcDigitalCardId`, which can be used in Checkout API to make payments.
```javascript
{
"srcCorrelationId": "3b467cce-2e77-4d39-a064-628d7e64cc0c",
"maskedCard": {
"srcDigitalCardId": "fbf181d0-2fd4-4c53-b827-49d40ae348d0",
"panBin": 222269,
"panLastFour": 4574,
"tokenUniqueReference": "DM4MMC0000144136aca1ae6e62854ce0a41bb0a247238441",
"digitalCardData": {
"status": "ACTIVE",
"descriptorName": "Mastercard Test Bank",
"artUri": "https://sbx.assets.mastercard.com/card-art/combined-image-asset/5f21f08e-0490-4603-bcd1-ac0be7ea0ecd.png",
"pendingEvents": [
"PENDING_SCA"
],
"isCoBranded": false
},
"panExpirationMonth": 12,
"panExpirationYear": 2024,
"paymentCardType": "CREDIT",
"serviceId": "SECURE_COF_MERCHANT##Mastercard#01",
"paymentAccountReference": "50014KLPZI457IUA3CW8K0V9QGXHZ",
"dateOfCardCreated": "2023-05-02T19:32:12.885Z"
},
"maskedConsumer": {
"srcConsumerId": "9b792e44-cc05-4426-be5a-4e996f04a4e0",
"maskedConsumerIdentity": {
"identityType": "EXTERNAL_ACCOUNT_ID",
"maskedIdentityValue": "f0c04b97-4dcb-485d-a4f4-7ae437a2e955"
},
"status": "ACTIVE",
"dateConsumerAdded": "2023-05-02T19:32:10.404Z",
"authenticationMethods": []
}
}
```
```javascript
{
"srcDigitalCardId": "9sJkUbYQRVSDTlAbVhtW2Q000000000000US",
"serviceId": "SECURE_COF_COMMERCE_PLATFORM#E2E#01",
"srcDpaId": "5e0d4b84-189d-4c86-822d-590602f62062_dpa1",
"srcClientId": "6aff5cba-3aac-4fe0-b0cd-a52fc948d0c6",
"srcCorrelationId": "c529d2b3-32a8-4d55-b83e-568b50deb93b"
}
```
### Scenario 4: Card Notifications {#scenario-4-card-notifications}
Upon successful migration of tokens/TURs to SCOF, you will receive [Card Notifications](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/use-cases/card-on-file/managing-tokens/index.md) and token lifecycle management through SCOF.
```json
{
"digitalCardUpdateNotifications": [
{
"eventTimeStamp": "1585741817000",
"maskedCard": {
"dateOfCardCreated": "2020-02-24T11:32:32.060Z",
"dateOfCardLastUsed": "2020-02-24T11:32:32.060Z",
"digitalCardData": {
"artUri": "https://assets.mastercard.com/card-art/combined-image-asset/9d42df54-c5fd-438b-a886-ff0bd1e8f7ec.png",
"descriptorName": "Citi Bank Product Configuration",
"presentationName": null,
"status": "CANCELLED"
},
"panBin": "545503",
"panExpirationMonth": "04",
"panExpirationYear": "2023",
"panLastFour": "6828",
"paymentAccountReference": "500150F5DE22SND132Y6PR32AR5HB",
"paymentCardDescriptor": "Mastercard",
"paymentCardType": "CREDIT",
"serviceId": "COF_CP_GOO_1",
"srcDigitalCardId": "e6016322-ac86-4ac7-8567-e7b8a424c70b",
"tokenBinRange": "123456",
"tokenExpirationMonth": "02",
"tokenExpirationYear": "2023",
"tokenLastFour": "01234",
"tokenUniqueReference": null
},
"reason": "ACCOUNT_CLOSED "
}
]
}
```
### Scenario 5: Card Enrollment using Push Account Receipt and Checkout {#scenario-5-card-enrollment-using-push-account-receipt-and-checkout}
1. After successfully onboarding the existing TRIDs in M4M to SCOF, enroll cards into SCOF using `pushAccountReceipt`.
```json
{
"srcDpaId": "srcDpaIDITF_01",
"srcClientId": "5d783ef2-e8a1-43e7-8064-67dd6466c2ac",
"srcCorrelationId": "5df5c25e-70d6-470f-a0a6-c0fccb7c5e6f",
"serviceId": "SECURE_COF_MERCHANT_OBO#TESTITFPROJECTM4S-170531_MERCHANT#01",
"enrolmentReferenceData": {
"enrolmentReferenceId": "MCC-STL-B363210D-36D2-41AF-9AA3-7C55BA2B9192",
"enrolmentReferenceType": "PUSH_ACCOUNT_RECEIPT"
}
}
```
2. The Enroll response will return a `srcDigitalCardId`, which can be used in Checkout API to make payments.
```json
{
"srcCorrelationId": "5df5c25e-70d6-470f-a0a6-c0fccb7c5e6f",
"maskedCard": {
"srcDigitalCardId": "77a26046-e319-47c8-8432-c7cde329c8f4",
"panBin": 520798,
"panLastFour": 7981,
"tokenUniqueReference": "DM4MMC00001182544b8b9401593044a6b5e1b4606e8d8eec",
"tokenLastFour": 5684,
"tokenExpirationMonth": 3,
"tokenExpirationYear": 2024,
"digitalCardData": {
"status": "ACTIVE",
"descriptorName": "TESTFORSRC",
"artUri": "https://stage.assets.mastercard.com/card-art/itf/combined-image-asset/2f0ac8a2-6607-4341-a127-58117d1ebef8.png",
"isCoBranded": true,
"coBrandedName": "SRC CoBrandName Test",
"issuerName": "TESTFORSRC",
"foregroundColor": 786868
},
"panExpirationMonth": 3,
"panExpirationYear": 2024,
"paymentCardDescriptor": "mastercard",
"paymentCardType": "CREDIT",
"serviceId": "SECURE_COF_MERCHANT_OBO#TESTITFPROJECTM4S-170531_MERCHANT#01",
"paymentAccountReference": "50014TCB8OPH0WLA9IASF8235H0B5",
"dateOfCardCreated": "2023-06-13T15:41:57.061Z",
"delegatedAuthenticationModels": [
{
"modelType": "AE_TYPE_3",
"isSupported": true
}
]
},
"maskedConsumer": {
"srcConsumerId": "b15ee489-b7d2-4d89-8820-1399bbb5679b",
"maskedConsumerIdentity": {
"identityType": "EXTERNAL_ACCOUNT_ID",
"maskedIdentityValue": "SYSTEM_GENERATED_8ca03256-1152-46c7-affe-ab09600a4085"
},
"complianceSettings": {
"privacy": {},
"tnc": {}
},
"status": "ACTIVE",
"dateConsumerAdded": "2023-06-13T15:41:55.239Z",
"authenticationMethods": [],
"encryptedAccountData": "eyJraWQiOiJNNFNlbmNyeXB0aW9uS2V5IiwiZW5jIjoiQTEyOEdDTSIsImFsZyI6IlJTQS1PQUVQLTI1NiJ9.dnSQvnhWs0rOiv81qRu3Qb0cghTHtNwCP1gNhzoqVdchdGlbnBICtlXWl6xN3z76JBgMOBjSheLjKk7XhEZW8I8_rNmdfasZMiDHd4ulKOfbmf9MiCSxzLVj9BiJ3iTRDa-hsRmNHIAlK0mUtC0bJ9ucaBVQo7F1AlgSB_k5JCDBBhmpRmodB19uer6JXYvNEbVEUTov27MjVHErsNsylexIkWMJ-ijsFrprZm3CNO4ui0VtRAcINxOn7mrupZdTTYAFhLUEWGfT78vojfJpGqmsEeQbPORgAUvrT15v3jS8EDxbi7XQspffZqBodTE9d_9Ms2nUL7zMFjdkVHDnLg.yIDKcTNtE9OXRoVS.LRg_KHBAKE9qfK7JqIUf1zp-jbNrV6C4P0Zq6myeyz5QVrQ439wi55AtVCtJpLGqBOPACiGIFcrkv1jnarqlJA3bREFF8BoVFdzCrVvV7lYdn3g58ahOqWeTH_gZkGYr9eioGyhF8DYUcGTytrhYjCZVvpkraQamfTvw-Y5LoLeBLyQXP_sNuSlGHOz3S7GkCrz0yKzBsOxCj8p_-5VCnsr1peRLXJDFZ-Bza8ZmL81vDBedZGNdGUm7lLQlok6PjLWuYyJ4eidkfe7Ja5RhgscR_m4_GdNa1fVF1BAUa8i5Lfo2uIt_9Y3kSnWyRxAYUbXt7KMgd6R3VF3lCVA7GuqfURCcabVs3p0N20HS4jX407icwuNrVM8OnRnPHd_Brv2xNfLnlk7ULItLSdb6QdmrV_LLdZ6jgnyIUpsflnFt49OlZf67mArqH8IciOP9sQp-kHx2dSk6izEGYAcIuMbz030XM4QqfmeR.SlwuhaId-XcSIvZAYZifOg"
}
}
```
## 5. Best Practices for Migration {#5-best-practices-for-migration}
* Get access to Sandbox/MTF environment, test in lower environments and enable test TRIDs on M4M.
* Create and maintain a migration/rollout plan for SCOF. For example, go-live on SCOF with new merchants (if applicable), start migration, and then scale.
* Once onboarded to SCOF, all new TRIDs/merchants should be onboarded to SCOF.
* Perform migration of TURs to SCOF when the cardholder is not actively transacting.
* Establish a support model for escalation.
* Maintain a status of migrated and non-migrated tokens.
### Important Recommendations {#important-recommendations}
* Onboard to TRID API in both MTF and Production environments to complete testing.
* TRID numbers should differ in MTF and Production environments so testing aligns with the current SCOF set up.
## 6. Token Status and Error Codes {#6-token-status-and-error-codes}
You will only be able to migrate **ACTIVE** or **SUSPENDED** tokens to SCOF. Mastercard does not migrate unmapped or deleted tokens.
| Token Status | Definition | Expected Behavior from Migration |
|-----------------|------------------------------------|---------------------------------------------------------------------------------------------------------------|
| Active Token | The token is fully active. | Allowed to migrate successfully. |
| Suspended Token | An issuer has suspended the token. | Allowed to migrate successfully. |
| Cancelled Token | An issuer has deleted the token. | Not allowed to migrate and MDES will return an error reason code of **INVALID_STATE** (HTTP 400 Bad Request). |
### Card Enrollment Error Responses {#card-enrollment-error-responses}
* **TOKEN_MIGRATION_NOT_ELIGIBLE**: Token was not in a status that was eligible for migration.
```javascript
{
"status": 400,
"reason": "INVALID_STATE",
"message": "Request cannot be executed due to the incorrect field value",
"errordetail": [
{
"reason": "TOKEN_MIGRATION_NOT_ELIGIBLE",
"message": "Token is not eligible for migration",
"sourceType": "BODY",
"source": "enrolmentReferenceData.enrolmentReferenceId"
}
]
}
```
* **INVALID_TOKEN_REQUESTOR_ID**: Client is not authorized to TRID or TUR belongs to a different TRID than the one requested
```javascript
{
"status": 400,
"reason": "INVALID_STATE",
"message": "Request cannot be executed due to the incorrect field value",
"errordetail": [
{
"reason": "INVALID_CONFIGURATION",
"message": "Cannot process the request because it is malformed or has incorrect/missing fields or values. ",
"sourceType": "BODY",
"source": "enrollCardRequest.`serviceId`"
}
]
}
```
* **INVALID_TOKEN_REQUESTOR_ID** : Token was not found for the given TRID.
```javascript
{
"status": 400,
"reason": "INVALID_STATE",
"message": "Request cannot be executed due to the incorrect field value",
"errordetail": [
{
"reason": "INVALID_TOKEN_UNIQUE_REFERENCE",
"message": "Invalid Field Value",
"sourceType": "BODY",
"source": "enrolmentReferenceData.enrolmentReferenceId"
}
]
}
```
* **AUTO_TRID_SERVICEID_LINK_FAILURE** : The ServiceID is not linked to the TRID automatically. In order to use the new serviceId, migrate one TUR via the Enroll API.
```javascript
{
"status": 500,
"reason": "INTERNAL_SERVER_ERROR",
"message": "Internal processing exception",
"errordetail": [
{
"reason": "AUTO_TRID_SERVICEID_LINK_FAILURE",
"message": "We have successfully created a serviceId for your M4M TRID. In order to proceed, you must migrate one TUR via the Enroll API with your new serviceId to be able to enroll new cards on Secure Card on File. If you encounter further errors, please contact the admin. Any srcDpaIds that were submitted have been uploaded successfully.",
"sourceType": "BODY",
"source": "MerchantServiceImpl:DPA_CREATION"
}
]
}
```
Refer to the [Error Codes](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/code-and-formats/index.md) for a full list of error scenarios, sample error responses, and http status codes.