# 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 onboarding 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}
To start with your journey, 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. 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'. Select **Create project** . If you have a custom CSR file, select **Skip this step** . After the project is created, upload the CSR file on the project dashboard. 
**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. After you complete this flow, the project page opens. On the **Summary** page, you can:
* View the status of your Sandbox access request.
* View the status of your Production access request.
* Request Production access.
10. In the left navigation pane, you can:
* Access your Sandbox and Production credentials.
* Upload a CSR file for your project.
* Manage project settings.
* Add team members to your project.

### Import sandbox keys {#import-sandbox-keys}
Open the ZIP file that you downloaded previously. Import the Sandbox keys (.p12 file) into your development environment using the Sandbox keystore password.
On the project page, under **Credentials \> Sandbox**, locate the consumer key for your environment. The consumer key is a 97-character string that uses the following format:
\!\
The Mastercard API Client ID is the first 48 characters of the consumer key (\). This value 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. On 'Summary' page, 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 and select **Proceed** . 
3. On the 'Service details' page, enter the required information on the form, and select **Proceed** . 
4. On the 'Legal agreements' page, select the required checkbox to give consent on the agreement and select **Proceed** . 
5. On the 'Project credentials' page, enter a Key alias and Keystore password for your project and 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.