# Onboarding and Registration in Sandbox source: https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/onboarding-sandbox-tutorial/index.md This tutorial guides you through program enrollment, directory creation, and the steps to create and test your project in Sandbox. ## Requirements {#requirements} | Entity | Requirement | |-----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Merchants, Commerce Platforms** | * Mastercard requires that whoever handles payment card information is PCI-DSS compliant. If you are a merchant who isn't compliant, we recommend you work with a PCI-DSS compliant PSP. * Your business must be capable of handling payment transactions. To do this you will need to request checkout data from Mastercard, decrypt payment tokens, and interface with your Acquirer or Payment Gateway to process the authorization. | | **Payment Service Providers** | * Your business must accept Mastercard as a payment method. * Your business must be capable of executing and completing eCommerce transactions. * Your business must be PCI-DSS compliant. | ## Key Terms {#key-terms} The following table lists some common terms used in the application and their purpose: | Term | Description | |--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Program** | Programs are consolidation of payment methods which you want to offer to your customers to use during checkout. Available Remote Commerce Programs - Secure Card on File, Guest Checkout Tokenization, and Click to Pay. The list of programs available to you is displayed in the Program enrollment tab. | | **Enroll Program** | Program enrollment in Sandbox is auto-approved whereas in Production, approval is required by Mastercard admin. Once you finish testing in the Sandbox environment for a program, you can enroll your program into the Production environment. | | **Project** | Project is a collection of enrolled programs. The project attributes (SRC Client ID, support emails, keys, DPAs) cannot be shared across projects. | | **Directory** | Directory acts as a logical container for consumer credentials and program configurations. Creating one lets you manage credential sharing, governance, and program enablement across your Mastercard Checkout Solutions implementation. | ## 1. Sign Up - Get Access to Mastercard Connect {#1-sign-up---get-access-to-mastercard-connect} To onboard as an integrator, you need an account on [Mastercard Connect](https://www.mastercardconnect.com). Each user who needs access within your company should request access. The welcome screen on Mastercard Connect provides a link to the [Connect Sign Up Guide](https://www.mastercardconnect.com/business/public/content/dam/b2b/mcc/guides/Mastercard%20Connect%20Sign%20Up%20Guide.pdf) with full instructions detailing the sign-up process. * The first time you sign in, you are prompted to reset your temporary password. * If your organization already has accounts on Mastercard Connect, a member of your staff would have been nominated as your **Security Administrator**. This user is responsible for approving requests (such as access the Mastercard Checkout Solutions onboarding application) from other users in your organization. * If your organization is new to Mastercard Connect, note that you will need to set up the **Security Administrator** account to approve requests on behalf of other users. * Each user should create a User ID, set up a suitable password and provide two security questions and answers. They will also need to provide the Customer ID (CID) and Interbank Card Association (ICA) number, which can be obtained from the **My Company Manager** application in MC Connect. Tip: Contact your [Mastercard representative](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/support/index.md#get-help) if you need help identifying your Security Administrator or signing up for Mastercard Connect. ![Welcome Screen](https://static.developer.mastercard.com/content/mastercard-checkout-solutions/img/mc_connect_welcome_screen.png "Welcome Screen") ## 2. Order the Sandbox version of the Mastercard Checkout Solutions Onboarding Application {#2-order-the-sandbox-version-of-the-mastercard-checkout-solutions-onboarding-application} 1. Log in to Mastercard Connect, go to the **Store** tab and search for the application **"Mastercard Checkout Solutions - Sandbox"** . ![Mastercard Checkout Solutions Onboarding Application for Sandbox](https://static.developer.mastercard.com/content/mastercard-checkout-solutions/documentation/images/order_app_mtf_1.png "Remote Commerce Application for MTF") 2. Locate the Sandbox version of the application, as above, and click the **Request Access** button. You will be presented with an Order Confirmation. You should then notify your company's Mastercard Connect Security Administrator and request that they approve access. 3. From the Order Confirmation, you can either print the order (for your records) or click **Track status** to view its progress. The application will appear on the **My Items** tab with an **Access pending** status label. 4. The Mastercard Checkout Solutions onboarding application will look like the following where a **Company ID** (CID) identifies a customer's unique legal identity. ![Mastercard Checkout Solutions Onboarding Application](https://static.developer.mastercard.com/content/mastercard-checkout-solutions/documentation/images/dpe_programenrollment_sandbox1.png "Remote Commerce Application") ## 3. Add Email Address to Receive Notifications {#3-add-email-address-to-receive-notifications} Use the **Manage notifications** button to sign up to receive email notifications about all company-level activities. Any updates to program settings (such as adding/updating a merchant name) and program enrollment are sent via email. If you do not add an email address, the first time you enroll in a program you will be asked to provide an email address. You can add additional email addresses, or edit the existing ones at any time. On the **Program enrollment** tab, click the **Manage notifications** button. ![Program notifications](https://static.developer.mastercard.com/content/mastercard-checkout-solutions/documentation/images/dpe_programnotif_1-sandbox.png "Manage notifications button") ## 4. Enrollment of a Technical Integrator from Settings {#4-enrollment-of-a-technical-integrator-from-settings} Note: The information/instructions in this section is only applicable for Technical Integrators enrolling for 'On Behalf Of' programs. It is recommended for Technical Integrators to take the following steps: 1. [Enroll as a Technical Integrator](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/onboarding-sandbox-tutorial/index.md#1-enroll-as-a-technical-integrator) 2. [Register clients](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/onboarding-sandbox-tutorial/index.md#2-register-clients)
### 1. Enroll as a Technical Integrator {#1-enroll-as-a-technical-integrator} * On the **Program enrollment** tab, select the **Settings** icon. ![Click Settings](https://static.developer.mastercard.com/content/mastercard-checkout-solutions/documentation/images/dpe_showsettings_sandbox.png "Settings Tab") * Proceed with the enrollment steps on the Settings page. The enrollment request is auto-approved in the Sandbox environment. ![Technical Integrator](https://static.developer.mastercard.com/content/mastercard-checkout-solutions/documentation/images/dpe_requestdaspenrollment_sandbox.png "Technical Integrator") * Once the enrollment is approved, you will be able to see the **Clients** tab to add and manage your clients. ![See Clients](https://static.developer.mastercard.com/content/mastercard-checkout-solutions/documentation/images/dpe_edoapprovedshowclients-sandbox.png "See Clients") ### 2. Register Clients {#2-register-clients} The **Clients** tab enables the Technical Integrator to add and manage client's company names, and the associated company IDs (assigned by Mastercard) by using the **Register Client** button. Client registration is auto-approved in Sandbox environment. ![Client Page Options](https://static.developer.mastercard.com/content/mastercard-checkout-solutions/documentation/images/dpe_clientpageoptions_sandbox.png "Client Page") Note: * Currently, you can add upto 20 clients in the list. To increase this number, connect with your [Mastercard representative](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/support/index.md#get-help). * It is recommended to use the legal name of your clients. * For Technical Integrators it is recommended to add client names and company IDs to enroll for 'On Behalf of Commerce Platform Model', 'On Behalf of Shared Merchant Model', and 'On Behalf of Merchant Model'. ## 5. Program Enrollment and Directory Creation {#5-program-enrollment-and-directory-creation} Preparing your Sandbox environment for Mastercard Checkout Solutions implementation may involve enrolling in one or more programs, creating a directory, or both, depending on your project requirements. Each action serves a different purpose and can be completed independently or together, as needed. Note: Program enrollment and directory creation are separate actions in the Mastercard Checkout Solutions onboarding application. Depending on your project requirements, you can complete either action independently or complete both. Enroll in the required programs to enable program configurations for Sandbox testing. Create a directory if your project requires a logical container to manage consumer credentials, program associations, and configuration settings. Refer to Sections 5.1 and 5.2 for the respective instructions. ### 5.1 Enroll a Program {#51-enroll-a-program} #### Steps to Enroll a Program {#steps-to-enroll-a-program} 1. Access the Mastercard Checkout Solutions onboarding application from the **My Items** tab on Mastercard Connect. 2. The **Program enrollment** tab displays the programs available for your enrollment. 3. For the program you are enrolling in, click **Enroll Program** to initiate testing the program integration on the Program enrollment tab. For example, if you want to integrate to "Merchant Direct Model", click **Enroll Program** under the **Program enrollment** label in the **Merchant Direct Model** program tile. 4. Program enrollment requests for the Sandbox environment are immediately approved. Once the program management status changes to **Enrolled**, you can create projects in Sandbox for testing your integration. ![Mastercard Checkout Solutions Onboarding Application](https://static.developer.mastercard.com/content/mastercard-checkout-solutions/documentation/images/dpe_programenrollment_sandbox1.png "Remote Commerce Application") ### 5.2 Create a Directory {#52-create-a-directory} A directory helps you manage consumer credentials, program associations, and configuration settings within Mastercard Checkout Solutions. Directories can be associated with Click to Pay program and used across projects during onboarding. #### Steps to Create a Directory {#steps-to-create-a-directory} 1. On the **Directory Management** tab, select **Create Directory** . ![Mastercard Checkout Solutions Onboarding Application](https://static.developer.mastercard.com/content/mastercard-checkout-solutions/documentation/images/create_directory_sandbox.png "Select create directory option") 2. Enter the **Directory name** , **Description** , and **Support email addresses** . You can optionally configure directory rules under Rules and configurations to customize the directory's behavior. ![Mastercard Checkout Solutions Onboarding Application](https://static.developer.mastercard.com/content/mastercard-checkout-solutions/documentation/images/dpe_directory-creation-step-1.png "Fill details for step 1") 3. Select the programs to associate with the directory: * **Click to Pay (C2P)** can be enabled if required. 4. Configure your directory details and program configurations. 5. Select **Create directory** to submit the request. ![Mastercard Checkout Solutions Onboarding Application](https://static.developer.mastercard.com/content/mastercard-checkout-solutions/documentation/images/dpe_directory-creation-step-2.png "Select programs for directory") 6. Your directory will be auto-approved, you can start using it at once. ![Mastercard Checkout Solutions Onboarding Application](https://static.developer.mastercard.com/content/mastercard-checkout-solutions/documentation/images/dpe_directory-creation-step-3.png "Select programs for directory") 7. View the directory status on the **Directory Management** page. In the sandbox environment, once the directory is auto-approved, you can associate it with a project for credential management and program enablement. ![Mastercard Checkout Solutions Onboarding Application](https://static.developer.mastercard.com/content/mastercard-checkout-solutions/documentation/images/dpe_directory-approved_sandbox.png "Directory approved") ## 6. Create a Project in Sandbox {#6-create-a-project-in-sandbox} On the **Projects** tab, click **Create project**, fill out the form, and read the necessary requirements to create your first project. Warning: * The **Create project** button on the **Projects** tab is visible only after enrolling for a specific program or creating a directory. * Your project attributes (SRC Client ID, support emails, keys, DPAs) cannot be shared across Sandbox projects or Production environments. You can create a maximum of 30 Sandbox projects. You can contact your [Mastercard representative](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/support/index.md#get-help) if you would like to create more than that. Each sandbox project has distinct attributes (SRC Client ID, support emails, keys, \& DPAs) to perform testing across various lower environments. For example, you may have one or more environments for integration and testing. Tip: SRC Client ID is the identifier for the connecting client, refer to the [API Specifications](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md) to learn more. ### 6.1 Provide Project Details {#61-provide-project-details} ![Create a Project](https://static.developer.mastercard.com/content/mastercard-checkout-solutions/documentation/images/dpe_create_project_step_1.png "Fill Project Details") To create a Sandbox project, provide the following information: * **Project Name** --- the name of the project. * **Description** --- a brief description of your project. * **Notifications** --- Support email addresses will receive notifications related to their Mastercard Checkout Solutions onboarding application project. These email addresses are used for support or troubleshooting. You can add up to 4 email addresses by clicking the **Add** button. * **Requirements** --- You should be eligible to accept payment credentials in the payload response returned by Mastercard. Select the check box and click **Continue** to create a project and move to Program selection. ### 6.2 Choose Programs and Directories for Your Project {#62-choose-programs-and-directories-for-your-project} ![Choose a Program for a Project](https://static.developer.mastercard.com/content/mastercard-checkout-solutions/documentation/images/select-program-for-project.png "Choose a Program") * **Choose enrolled programs** --- select the program(s) you want to include in this project. The enrollment form will vary depending on the program type being requested: There is no enrollment form for this program. There is no enrollment form for this program. For Commerce Platforms who want to become an integrator. You can specify only one Commerce Platform name. For merchants who want to integrate directly with Mastercard for tokenization programs, for example, large streaming merchant, can have between 1 and 20 program names. There is no enrollment form for this program. It is for service providers who want to provide merchant tokenization programs to their merchants. The program names for this model are generated using the [Submit DPA Data API](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#registration) endpoint and do not require user input during enrollment. There is no enrollment form for this program. It is for service providers who want to provide tokenization programs to their sub-merchants. Payment Facilitator (Service Provider) uses a `serviceId` to register a group of sub-merchants. A `serviceId` is shared between sub-merchants. Tip: Mastercard provides upto five `serviceId` to Payment Facilitator. The Payment Facilitator should register their sub-merchants as `srcDpaId` within each `serviceId` that they will use. Mastercard recommends segmenting sub-merchants into `serviceId` based on Merchant Category Code (MCC). The program names for this model are generated using the [Submit DPA Data API](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#registration) endpoint. Up to five program names can be generated to be used amongst the sub-merchants. For Technical Integrators who want to provide technical integration service for their commerce platforms. In step 2 of project creation (refer to the above image), provide the consumer-facing name of the commerce platform, and assign the client name with the company ID combination. ![OBO Project](https://static.developer.mastercard.com/content/mastercard-checkout-solutions/documentation/images/edo_obocp1.png "OBO Project") * The program name is mapped to the merchant's customer-facing name or to the entity that stores the cardholder's credentials on file. Choose a program name that the issuer uses to identify the merchant during tokenization and transaction authorization. Depending on the model you enroll in, you can edit or remove one or more program names or Commerce Platform names for the selected program type. * Select the directory you want to include in this project. ![Choose a directory for a Project](https://static.developer.mastercard.com/content/mastercard-checkout-solutions/documentation/images/dpe-select-directory-project-creation-step.png "Choose directory") * Click **Create project** to complete the step. * Each project will be visible as a separate tile on the **Projects** tab. ![Projects Tab](https://static.developer.mastercard.com/content/mastercard-checkout-solutions/documentation/images/dpe_project_list_sandbox.png "Projects tab") ### Understanding a Project Tile {#understanding-a-project-tile} On the **Projects** tab, a tile will be visible for each project. The following callouts help you understand the information contained within a project tile. ![Understand Project Tile](https://static.developer.mastercard.com/content/mastercard-checkout-solutions/documentation/images/mcc_project_tile_dpe.png "Project tile") 1. Denotes a program included in the project. 2. Denotes a program enrolled in Sandbox but not included in this project. 3. A red dot indicates that Mastercard could not generate a `serviceid` for a program. An amber dot indicates that a `serviceid` generation for a program is in progress. 4. Denotes a directory included in the project. 5. Denotes a directory enrolled in Sandbox but not included in this project. 6. Allows you to edit the email addresses and other project details, except the project name. 7. Indicates the project status as **Approved**. ## 7. View the Project Dashboard {#7-view-the-project-dashboard} On the **Projects** tab, click the Project Name to access the Dashboard, which will look like this: ![Project Dashboard](https://static.developer.mastercard.com/content/mastercard-checkout-solutions/documentation/images/edo_view_project_dashboard.png "Project Dashboard") Alert: Make a note of your SRC Client ID (this may also be referred to as srcClientId, SRCI ID \& srcInitiatorId). You will need this to call our APIs. ## 8. Manage Keys {#8-manage-keys} Create new API Signing and Payload Encryption Keys; you will need these to call the APIs. You can start testing the APIs using the predefined keys for Sandbox. This will also show the expiry date of all your keys. Note: When first created, keys will typically have a lifetime of one year. For more information refer to [Key Management](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/key-management-tutorial/index.md). ## 9. Manage DPAs {#9-manage-dpas} Digital Payment Applications (DPAs) could be a merchant e-commerce website or mobile application with unique registrations for each digital channel. To initiate payments for Click to Pay, Guest Checkout Tokenization, or Secure Card on file programs, you must register your DPAs. | Program | DPA Registration | |--------------------------------|------------------| | Click to Pay | Mandatory | | Guest Checkout Tokenization | Mandatory | | Commerce Platform Direct | Optional | | On Behalf of Commerce Platform | Optional | | Merchants Direct | Mandatory | | On Behalf of Merchants | Mandatory | | On Behalf of Shared Merchants | Mandatory | ### Program Information {#program-information} On the **DPA management** page, you will see all the available program types for that project. The program information for each of the active program types is listed in tabular form. When the program information shows "pending" approval, there is a pending tag beside the program information section. ### Generate Test DPA Data {#generate-test-dpa-data} To generate sample SRC DPA ID (also referred to as `srcDpaId`) values for initial testing on Sandbox: 1. Click on the projects tab and open a project. 2. Go to the **DPA Management** tab and click **Generate Data**. 3. In the Generate test data dialog box, select the applicable program. 4. This table lists the actions you should do in the Generate test data dialog box to create test data for each Program Type. | Program Type | Action | |--------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Click to Pay | * Select **Yes** if you want Click to Pay to return token-based credentials in the payload * Select **No** for PAN-based credentials. | | Commerce Platform Direct model | Select the name of an available Commerce Platform you want to create the test data for and click **Generate** to create test ID values. | | Guest Checkout Tokenization | Click the **Generate** button to create test ID values. | | Merchant Direct model | Select the name of an available Merchant you want to create the test data for and click **Generate** to create test ID values. | | On Behalf of Merchant Model | Click the **Generate** button to create test ID values. | | On Behalf of Shared Merchant Model | Click the **Generate** button to create test ID values. | | On Behalf of Commerce Platform Model | Click on the 'On Behalf of Commerce Platform Model' from the Program Type, choose the commerce platform name and the client name combination, and click on **Generate** to test ID values. | You can follow the same steps to generate a maximum of six SRC DPA ID Values. You will need to wait for a while (up to 5 minutes) before the test data shows up. At any point if you choose to delete any test DPA data, use the **Delete** button in the Test DPAs section. #### Use the Sample serviceId {#use-the-sample-serviceid} To call the DPA Registration API in the Sandbox, you will require a sample `serviceId` value. Along with the test DPA data, a sample `serviceId` is available for your initial testing in the Sandbox environment. For more information on the usage of `serviceId` refer to [Enroll Card API](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#card). ![ServiceId in Test DPA](https://static.developer.mastercard.com/content/mastercard-checkout-solutions/documentation/images/mcc_test_dpas.png "ServiceId and Program Name") ### DPA Registration API {#dpa-registration-api} When you have finished testing, the sample data should be replaced. You can create new DPA data by calling the [DPA Registration API](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/api-reference/apis/index.md#registration). The following table outlines the required fields for UPDATE function for each program type: | Program Type | Mandatory fields for UPDATE function | |--------------------------------------|-------------------------------------------------------| | Click to Pay | * `dpaName` * `srcDpaId` * `dpaAddress.countrycode` | | Merchant Direct Model | * `serviceId` * `srcDpaId` * `dpaName` | | Commerce Platform Direct Model | * `serviceId` * `srcDpaId` * `dpaName` | | On Behalf of Merchant Model | * `serviceId` * `programName` | | On Behalf of Shared Merchant Model | * `serviceId` * `programName` | | On Behalf of Commerce Platform Model | * `serviceId` * `srcDpaId` * `dpaName` * `customerId` | | Guest Checkout | * `dpaName` * `srcDpaId` | Note: Under 'On Behalf of Commerce Platform Model', 'On Behalf of Merchant Model', and 'On Behalf of Shared Merchant Model', a Technical Integrator can execute DPA Registration APIs only for their approved clients. ## 10. Edit Project Details {#10-edit-project-details} Initially, you will have provided these details when you created the project. To make changes you can use the **Edit project** button on the **Project details** tab. ![Edit Project](https://static.developer.mastercard.com/content/mastercard-checkout-solutions/documentation/images/dpe_project_detail.png "Edit Project Details") Note: * You can also use **Edit project** to associate another available program type to an existing project. * You can edit the project details except for your project name. ## 11. Enable TAF/TAS {#11-enable-taftas} Use this option to enable payment authentication methods supported by TAF/TAS, such as 3DS, Passkeys, and other secure mechanisms. ### Steps to enable TAF/TAS {#steps-to-enable-taftas} 1. From the **Projects** tab, select the project for which you want to enable the TAF/TAS feature. 2. Select **Settings** option. 3. Under **Enable TAF/TAS** , select **Request enrollment**. All Payment Authentication requests require admin approval before they become active. This ensures Mastercard can control which customers are enabled for Payment Authentication. The following table describes the possible approval statuses for a TAF/TAS enrollment request and what each status means for feature availability. | Approval status | Description | Example | |------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Request Enrollment** | Submit a request to enable the TAF/TAS feature. The request is sent for review and does not take effect until it is approved. | ![Request enrollment](https://static.developer.mastercard.com/content/mastercard-checkout-solutions/documentation/images/edo_request_enrollment.png "Request enrollment") | | **Pending** | The request is under review. Payment Authentication is not available until the request is approved. | ![Pending](https://static.developer.mastercard.com/content/mastercard-checkout-solutions/documentation/images/edo_pending_status.png "Pending") | | **Rejected** | The request has been declined, and Payment Authentication is not enabled. After addressing the reason for rejection, select **Resubmit** to submit a new request. | ![Rejected](https://static.developer.mastercard.com/content/mastercard-checkout-solutions/documentation/images/edo_rejected_status.png "Rejected") | ## 12. Test Project and Integration in Sandbox {#12-test-project-and-integration-in-sandbox} Once you set up all necessary information for your integration, test your project in the Sandbox environment. Follow the steps in this [tutorial](https://developer.mastercard.com/mastercard-checkout-solutions/documentation/tutorials-and-guides/onboarding-production-tutorial/index.md) to further enroll in Production environment.