# Quick Start Guide
source: https://developer.mastercard.com/commercial-connect-api/documentation/quick-start-guide/index.md

## Overview {#overview}

Use this guide to create a new project and generate the credentials required for the Mastercard Commercial Connect API environments.
>
> #### You can follow this guide to learn: {#you-can-follow-this-guide-to-learn}
>
> * How to create a project for the service.   
> * How Mastercard Developers approach authentication.   
> * How to generate your credentials and API client.   
> * How to get access to Sandbox and Production.
Note: If you are already a Mastercard In Control for Commercial Payments (ICCP) or In Control API customer, no additional contracts or enrollment forms are required. If you are not an ICCP customer, you will be set up in Mastercard Commercial Product's registration service.

## Pre-requisites: {#pre-requisites}

* Create a [Mastercard Developers](https://developer.mastercard.com/) account.
* Have a secure place to store downloaded OAuth.
* Decide how you want to test: Postman, Insomnia, the reference application, or your own client.

## Step 1: Get access to the API {#step-1-get-access-to-the-api}

1. Navigate to [Mastercard Developers](https://developer.mastercard.com/) and click sign up and create an account.
2. Activate your account by opening the link sent to your email address, and log in.
3. Request access to the API if needed. APIs with a lock icon require permission to view their documentation and create a project. To gain access to these services, you will need to submit an access request form. Once submitted, you will receive an email confirmation approving or denying your access.

## Step 2: Create a project and generate Sandbox credentials {#step-2-create-a-project-and-generate-sandbox-credentials}

Create a Mastercard Developers project to generate your Sandbox credentials. Sandbox gives you mocked data so you can validate your integration before requesting Production access.

### Project Details {#project-details}

To generate your Sandbox and Production credentials, you must create a new Mastercard Developers project. Generating Sandbox credentials will give you access to our Sandbox, a pre-production test environment.

1. Create a project on your [My Projects](https://developer.mastercard.com/dashboard) page.
2. Name your project.   
3. Indicate whether you are creating a project on your behalf or on-behalf of a client. Note: Check "no" if you are creating an API integration project for yourself. Check "yes" if you are creating an API integration project for a customer. For example, you could be an integrator, a processor or a service provider, and the customer could be a merchant, issuer or acquirer.

### Service Details {#service-details}

4. If you have selected "no" above, your information, such as name, address, and company name will get populated from your account details. If you have selected "yes" above, provide the client company name and client company address (if applicable).   
5. Select 'Commercial Connect API' for API service and click "Proceed."
6. In the "Registration Token" field, input the registration token that your Commercial Products implementation manager has provided for you. The registration token links your Mastercard Developers identity with your Mastercard Commercial Products Identity providing full access management.

Note: Along with the registration token, the delivery team or the CEP team will also set up the integrator as a company with the test issuer. At that time, they will also generate real cards for testing purposes in the Sandbox. This is an essential step you will need to test your project in the Sandbox environment and make the first Sandbox call.

7. Select whether you want your card number to appear fully or whether you want it masked. A masked card number means that only the last four digits of the card number are visible.
8. Choose the Commercial Connect capability/capabilities that you have signed up for. Currently, the supported capabilities are Card Management and Card Payments. Card Management lets you manage real and virtual cards and implement card controls. Card Payments lets you initiate payments on virtual cards and get payment statuses. Note: You can select the Card Management by itself if you have signed up for managing real and virtual cards. However, if you select Card Payments, you must also select the Card Management capability.
9. If you have selected Card Management capability only, proceed to the next step. If you have selected Card Payments capability, input your organization tax identifier, provide your ICA, and click proceed.

### Project Credentials {#project-credentials}

10. In 'Project Credentials', select the 'OAuth 1.0' radio button for this OAuth 1.0a service.
11. Create a key alias and keystore password for your OAuth keys, record them securely, and click 'Proceed'. ![Select OAuth Type](https://static.developer.mastercard.com/content/commercial-connect-api/uploads/oauth-type.png)

### Additional Credentials {#additional-credentials}

12. Download, and keep safe, your PKCS#12 (.p12) keystore file.
13. Create a key alias and keystore password. Make a note of these values.
14. Download the OAuth 1.0a and keys and store them in a safe place. Then click 'Open Project'. ![Project creation confirmation with key download links](https://static.developer.mastercard.com/content/commercial-connect-api/uploads/project-creation.png)

Tip: Review information regarding consumer keys and [Credential Management](https://developer.mastercard.com/platform/documentation/credential-management/).

### Save the values you will need {#save-the-values-you-will-need}

15. On the project dashboard, record these values:

* Sandbox and Production status
* Authentication consumer key

16. Your project has now been submitted for Mastercard review and needs to be approved.

## Step 3: Make your first Sandbox call {#step-3-make-your-first-sandbox-call}

After your project has been approved and you have Sandbox credentials, you are ready to make a simple GET request to confirm that your project is set up correctly.

First, make sure that your Sandbox is set up with an integrator as the company and real cards for testing purposes. See Step 6 in [Service Details](https://developer.mastercard.com/commercial-connect-api/documentation/quick-start-guide/index.md#service-details).

Before you run the request, make sure that you have:

* The private key used to sign OAuth requests.
* A Mastercard OAuth library or signer that generates `oauth_timestamp`, `oauth_nonce`, and `oauth_signature`.

This first-call example uses `GET /hierarchies/entities`, so you can verify access, OAuth signing, and the Sandbox base URL.
Note: For a full client setup, see the [API Basics](https://developer.mastercard.com/commercial-connect-api/documentation/api-basics/index.md) section. For more information about project setup in MTF, see the [Onboarding Checklist](https://developer.mastercard.com/commercial-connect-api/documentation/onboarding-checklist/index.md).

**Example Request (cURL):**

```bash
curl -X 'GET' \
  'https://sandbox.apiedge.mastercard.com/commercial/hierarchies/entities' \
  -H 'accept: application/json'
```

This example shows the `GET /hierarchies/entities` call to get the entity ID that you need before you can register a real card and create any virtual cards.

**Example of an Expected Response:**

```json
{
  "entityId": "SENTTY5BA786294AB086E21DDB7096803ADA57AB4A3895F5E3FB4D3BB34DCF2656B0951607065524",
  "entityParentId": "SENTTY27A8719BE0A622F48E2A0AF1AE713171175AD8B3D4FAC64183E12F6D606385C71519036959",
  "entityName": "ABC Enterprises",
  "entityNameLine2": "ABC Travel",
  "entityType": "COMPANY",
  "entityStatus": "ACTIVE",
  "ica": 1902,
  "corpNumber": "123456789",
  "createdDate": "2020-10-06T11:09:42.100Z"
}
```

**Test data:** The API returns a `400 Bad Request` with a `BAD_REQUEST` reason code. See [Testing](https://developer.mastercard.com/commercial-connect-api/documentation/testing/index.md) for additional scenarios.

## Step 4: Choose how you want to test and integrate {#step-4-choose-how-you-want-to-test-and-integrate}

After the first Sandbox request succeeds, pick the integration path that matches your workflow:

* **Postman or Insomnia:** Use the Developer Tools page for collection downloads and setup.
* **Reference Application:** Use the Reference Application page.
* **curl or a custom client:** Use the Testing page for test cases and additional examples.

### Generate Your Own API Client {#generate-your-own-api-client}

1. Navigate to the API documentation page.
2. Download the API specification (OpenAPI or Swagger).
3. Generate and configure an API client for this API.
4. Configure your client using our [client libraries](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/#client-libraries). For a detailed step-by-step guide, see [Generating and Configuring a Mastercard API Client](https://developer.mastercard.com/platform/documentation/security-and-authentication/generating-and-configuring-a-mastercard-api-client/).

### Integration Testing {#integration-testing}

After the MTF keys have been configured, test data is loaded and integration testing begins. Your project contact works with you to ensure that sufficient test data is added, and that each endpoint and use case is tested.
Point to use cases to register rc and create vc and test that functionality.
Real card numbers need to be provided by the integration manager, which is a manual process and it's part of integration.

After you have completed the Sandbox implementation, notify your Commercial Products implementation manager that you are ready to proceed to Production. The Commercial Products implementation manager will then:

1. Validate Sandbox integration.
2. Open project for MTF Validation (if the integrator is a software partner, this happens once the Issuer is identified).
3. After successful MTF Validation, Regional Delivery completes Production setup.
4. Validate Production.
5. Go Live.

Note: The Mastercard Test Facility (MTF) environment is not suitable to perform high-volume or load-testing.

### Contact us {#contact-us}

Contact us when you are ready to onboard with our APIs. Provide your company name, the Mastercard program name (Commercial Connect API), and services that interest you.


Contact details for each region:  

**Asia/Pacific:** Contact your account manager.

**Europe:** Contact your account manager.

**[Latin America and the Caribbean](mailto:CIS_LAC_Support@mastercard.com)**

**[Middle East and Africa](mailto:CIS_EEMEA@mastercard.com)**

**[North America](mailto:CIS_NorthAmerica_Support@mastercard.com)**

A regional customer representative will work with you on how to order this product through the [Mastercard Connect Store](https://www.mastercardconnect.com/-/store-plus), set up BINs, ARIDs and ICAs, and promote the Sandbox keys to MTF.

## Step 5: Promote the same project to Production {#step-5-promote-the-same-project-to-production}

After your project is working in Sandbox, request Production access for that same project.
After integration testing in MTF is completed, your customer representative works with you to schedule your go-live date and production access. A user must have the correct Commercial Connect API BIN or ARID access in Access Manager within Mastercard Connect before a Production client ID can be mapped to their account. A Production client ID is associated with one Mastercard Connect User ID.

Prerequisite: Complete [Company Verification](https://developer.mastercard.com/platform/documentation/account-management/company-verification-via-connect-linking/) before requesting Production access.

### Transition your project from Sandbox to Production {#transition-your-project-from-sandbox-to-production}

1. **Open your project in Mastercard Developers** Go to your [My Projects](https://developer.mastercard.com/dashboard) page and open the Commercial Connect API project you used for Sandbox testing.
2. **Request Production access** In the project dashboard, select 'Request Production Access'. Your Sandbox and Production statuses are shown separately on the project page, so you can track when Production moves from `Not Requested` to an enabled `Ready` state.

Note: Production Credentials are generated instantaneously, but they still need to be approved for Production environment access before you can go live. Once your Production access request has been reviewed, you will receive a notification confirming your access has been approved or denied.

3. **Generate or download your Production keys** After Production access is approved, download the Production OAuth for the same project. Keep the Production key material separate from your Sandbox keys.

4. **Update your application configuration** Switch the base URL from Sandbox to Production:

   * Sandbox: `https://sandbox.apiedge.mastercard.com`
   * Production: `https://apiedge.mastercard.com`

Update your application to use the Production consumer key and signing key.

OAuth 1.0a authentication works the same way in Sandbox and Production. The main changes are the Production key set, the Production approval state, and the Production base URL.

If you need the full onboarding process, including contract, MTF, SLA, and escalation details, see the [Onboarding Checklist](https://developer.mastercard.com/commercial-connect-api/documentation/onboarding-checklist/index.md).

## Next Steps {#next-steps}

Continue with the documentation that matches your next task:

* [API Reference](https://developer.mastercard.com/commercial-connect-api/documentation/api-reference/index.md) for endpoint details
* [API Basics](https://developer.mastercard.com/commercial-connect-api/documentation/api-basics/index.md) for authentication and client configuration
* [Testing](https://developer.mastercard.com/commercial-connect-api/documentation/testing/index.md) for additional request scenarios
* [Onboarding Checklist](https://developer.mastercard.com/commercial-connect-api/documentation/onboarding-checklist/index.md) for the full operational go-live process
* [Use Cases](https://developer.mastercard.com/commercial-connect-api/documentation/use-cases/index.md)