# Quick Start Guide
source: https://developer.mastercard.com/merchant-identifier/documentation/quick-start-guide/index.md
## Overview {#overview}
The Merchant Identifier service helps enrich transaction data with detailed information about the merchant who participated in the transaction. This tutorial guides you through the process of on-boarding and being able to consume this data.
Tip:
###### Postman Collections Quick Start {#postman-collections-quick-start}
If you are already ready to start making calls you can head over to our [Postman Collections page](https://developer.mastercard.com/merchant-identifier/documentation/developer-tools/postman-collection/index.md) to leverage sandbox and production environments without having to write code.
> #### You can follow this guide to learn: {#you-can-follow-this-guide-to-learn}
>
> * How to create a project for the service.
> * How Mastercard approaches authentication.
> * How to generate your own API client.
> * How to make calls to the Sandbox or Production environment
### Make your first call in 5 minutes {#make-your-first-call-in-5-minutes}
1. [Create a project](https://developer.mastercard.com/dashboard) and select **Merchant Identifier**.
2. Download the project key `.zip`, extract the `.p12` file and note your consumer key and keystore password.
3. Run the cURL sample in Step 4 below against the Sandbox base URL `https://sandbox.api.mastercard.com/merchant-identifier`.
4. Expect HTTP `200` with a `merchants[]` array in the response body.
### Checklist {#checklist}
| # | Step | Description |
|---|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 1 | Access | Create a Mastercard Developers account using your enterprise email id or log in using your existing credentials |
| 2 | Project | Create a Mastercard Developers Project \& Get Access to Merchant Identifier API in sandbox environment |
| 3 | First Call | Send your first Sandbox request using the Sandbox base URL and OAuth 1.0a credentials |
| 4 | Validation | Test the functionality of Merchant Identifier API in sandbox environment to validate using mocked data, positive flows, and negative flows |
| 5 | Production | After Sandbox validation is complete, use the [Onboarding Checklist](https://developer.mastercard.com/merchant-identifier/documentation/tutorials-and-guides/onboarding-checklist/index.md) to request Production access. |
## Step 1: Get Access to Mastercard Developers Platform {#step-1-get-access-to-mastercard-developers-platform}
If you haven't done so already, you must first create an account with Mastercard Developers.
1. Go to [Mastercard Developers](https://developer.mastercard.com/account/sign-up) and [log in](https://developer.mastercard.com/account/log-in) or create your account using enterprise email id.
2. To activate your account, open the link sent to your email address and sign in.
## 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 provides mocked data so that you can validate your integration before requesting Production access.
1. To start, log in to your Mastercard Developers account and go to the [My Projects](https://developer.mastercard.com/dashboard) page.
2. Click **Create new project** from the upper right. 
3. Enter a project name.
4. Indicate whether you are creating the project on behalf of a client.
5. In the Select at least one API field, choose Merchant Identifier and click Proceed. 
**Project Credentials**
6. On the Project credentials page, enter a Key alias and Keystore password for your project. Select Proceed. If you have a custom CSR file to use, select Skip this step instead. You'll upload your CSR on your project dashboard after your project is created.
**Additional Credentials**
7. Download your project key zip file containing the .p12 file required for OAuth authentication in Sandbox.
8. Click Open Project 
**Save the values you will need**
9. In the navigation panel on the left, you also have access to areas where you can get your Sandbox and Production credentials and upload a CSR file for your project. You can also manage your project settings and add other team members to your project
10. After you complete this flow, your project page opens. On the project Summary page, you can see the status of your Sandbox and Production access requests: Ready or Not Requested. You can also choose to Request Production access from this page.
### Import sandbox keys {#import-sandbox-keys}
Open the zip file you downloaded in the previous steps. Import the Sandbox keys (the .p12 file) according to your specific development environment using the Keystore Password for sandbox, which you downloaded as well.
On your project page under CREDENTIALS \> Sandbox, you can find the consumer key that applies to your environment. The consumer key is a 97 character string separated by an exclamation mark. The format is \!\. The Mastercard API Client ID is the first 48 characters of this key (\), which uniquely identifies the API calling user.
## Step 3: Generate Your Own API Client {#step-3-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/).
## Step 4: Make your first Sandbox Request {#step-4-make-your-first-sandbox-request}
Once you have Sandbox credentials, make a simple request to confirm that your project is set up correctly. This first-call example uses merchants endpoint, so you can verify access, OAuth signing, and the Sandbox base URL before moving on. For more information about this endpoint, see the [API Reference](https://developer.mastercard.com/merchant-identifier/documentation/api-reference/index.md).
### Endpoint {#endpoint}
API Reference: `GET /merchants`
**Path Parameters**
```javascript
merchant_descriptor=DOLIUMPTYLTDWELSHPOOLWA
```
**Response:**
A successful call returns merchant details of the matched merchant descriptor input (IMPORTANT - Please remove all spaces from the merchant descriptor before submitting your API request). You should see a response similar to:
```json
{
"merchants": [
{
"matchConfidenceScore": 100,
"address": {
"line1": "UNIT 2 248 WELSHPOOL RD",
"city": "WELSHPOOL",
"postalCode": "6106",
"country": {
"code": "AUS",
"name": "AUSTRALIA"
},
"countrySubdivision": {
"code": "aSTCD"
}
},
"brandName": "TESTBRANDNAME",
"phoneNumber": "1234567890",
"merchantCategory": "5533 - AUTOMOTIVE PARTS ACCESSORIES STORES",
"merchantDbaName": "DOLIUM PTY LTD",
"merchantDescriptor": "DOLIUMPTYLTDWELSHPOOLWA",
"legalCorporateName": "ALEGALNAME",
"locationId": 344147943,
"isBrickAndMortar": true,
"isEcommerce": true
}
]
}
```
If you receive a similar JSON array, your credentials and authentication are working correctly. You have now successfully called the Merchant Identifier API.
### Test in Sandbox {#test-in-sandbox}
After completing your first successful API call, you're now ready to test the full functionality of the Merchant Identifier APIs in sandbox.
* You can check out our [API Reference](https://developer.mastercard.com/merchant-identifier/documentation/api-reference/index.md) to review full request and response definitions.
### Common Errors During Integration {#common-errors-during-integration}
The following issues are commonly encountered when making your first Merchant Identifier API calls.
| Error | Likely Cause | Recommended Action |
|------------------------|------------------------------------------------------------------------------|-----------------------------------------------------------------|
| 401 Unauthorized | OAuth signature, Consumer Key, or keystore issue | Review API Basics authentication setup |
| 403 Forbidden | Project lacks required access | Verify Merchant Identifier API has been enabled for the project |
| MISSING_REQUIRED_INPUT | Required field missing | Validate all mandatory request parameters |
| DESCRIPTOR_TOO_SMALL | The search string does not contain enough characters. | Repeat query with a longer merchant identifier |
| TOO_MANY_MATCHES | The input is associated with many merchants; no unique merchant can be found | Repeat query with a more detailed merchant identifier |
## Step 5: Move to Production {#step-5-move-to-production}
### Production Prerequisites {#production-prerequisites}
Before you can request Production access, you need to complete a few steps located in the Production access prerequisites section on your project Summary page.
1. First you need to verify your company. This ensures your company is registered to do business with Mastercard. You can follow steps in our [Company Verification guide](https://developer.mastercard.com/platform/documentation/account-management/company-verification/#3-complete-verification) to complete this step.
2. You also need to provide your "commercial countries" to indicate where you are doing business for this API integration (i.e. where are your end-customers located)
### GO LIVE {#go-live}
1. Within your project, select "Request Production Access". 
2. We are offering a free trial of Merchant Identifier APIs to provide the access of real world data for better decision-making. On the Select Plan page, select the relevant plan you wish to move forward with \& then select Proceed. 
3. On the Service details page, enter the required information on the form, then select Proceed. 
4. Give consent on the agreement as per the plan selected in steps above 
5. On the Project credentials page, enter a Key alias and Keystore password for your project. Select Proceed.
Production Credentials are generated instantaneously, but they still must be approved for Production environment access before you can go live. After your Production access request has been reviewed by Mastercard's team, you will receive an email from [apisupport@mastercard.com](mailto:apisupport@mastercard.com) confirming your access has been approved or denied.
## Next Steps {#next-steps}
* API Reference: Review the full [API specification](https://developer.mastercard.com/merchant-identifier/documentation/api-reference/index.md).
* Codes \& Formats: Know more about the [Error Codes](https://developer.mastercard.com/merchant-identifier/documentation/code-and-formats/index.md) \& steps to fix the errors
* Use Cases: See [Use Cases](https://developer.mastercard.com/merchant-identifier/documentation/use-cases/index.md) to learn about the different ways clients use these API to create value for their organization.