# Quick Start Guide
source: https://developer.mastercard.com/agent-suite-for-merchants/documentation/quick-start-guide/index.md

👉 Keep only the quick-start templates that match your service model. Each visible option should stay in its own `sliding-tabs-item` block inside the surrounding sliding-tabs wrapper. Replace the included template files or tab titles as needed, then update the remaining tab content so the onboarding path, credential flow, screenshots, and example calls match your real service.

## Overview {#overview}

Use this page to choose the quick start template that matches your service implementation model.
Tip: Select the tab that best matches your service type, then tailor the included content with your service-specific onboarding, credential, and testing details.

### Quick Start Templates {#quick-start-templates}

### Overview {#overview}

Use this guide to go from account setup to your first successful Sandbox request for {Service Name}. You will create a project, generate credentials, make a test call, and prepare the same project for Production access.
Tip: If you want the fastest path to a working Sandbox request, start with the [Postman Collection page](https://developer.mastercard.com/agent-suite-for-merchants/documentation/developer-tools/postman-collection/index.md). It lets you test Sandbox and Production flows without writing code first.

### Before you begin {#before-you-begin}

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

### Sandbox checklist {#sandbox-checklist}

| # |    Step     |                                                                                                                 What to do                                                                                                                 |
|---|-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 1 | Access      | Get access to Reference Service NGW and create your Mastercard Developers project.                                                                                                                                                         |
| 2 | Credentials | Generate your Sandbox OAuth credentials and record your consumer key.                                                                                                                                                                      |
| 3 | Encryption  | If you will test Adoptions, Employees, or other protected-payload flows, complete JWE setup in [API Basics](https://developer.mastercard.com/agent-suite-for-merchants/documentation/api-basics/index.md#transport-encryption).            |
| 4 | First call  | Send your first Sandbox request using the Sandbox base URL and OAuth 1.0a signing.                                                                                                                                                         |
| 5 | Validation  | Use the sample response and [Testing](https://developer.mastercard.com/agent-suite-for-merchants/documentation/testing/index.md) page to validate test data, positive flows, and negative flows.                                           |
| 6 | Production  | After Sandbox validation is complete, use Step 5 and the [Onboarding Checklist](https://developer.mastercard.com/agent-suite-for-merchants/documentation/tutorials-and-guides/onboarding-checklist/index.md) to request Production access. |

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

1. Go to [Mastercard Developers](https://developer.mastercard.com/) and create an account.
2. Activate your account by opening the link sent to your email address, and log in.
3. Open your [My Projects](https://developer.mastercard.com/dashboard) page and start a new project. Sandbox access is open, so you can begin testing as soon as your project credentials are generated.

## 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}

1. Click 'Create new project' on your [My Projects](https://developer.mastercard.com/dashboard) page. ![Pet Store Project Details](https://static.developer.mastercard.com/content/agent-suite-for-merchants/uploads/pet-store-project-details.png)
2. Enter a project name.
3. If prompted, indicate whether you are creating the project on behalf of a client.
4. In the 'Select at least one API' field, choose **Reference Service NGW**.

### Service Details {#service-details}

5. Complete the 'Service details' form if it appears. Note: Some project flows include additional client or service fields. If you do not see them, continue to the next step.

### Project Credentials {#project-credentials}

6. In 'Project Credentials', select the 'OAuth 1.0' radio button for this OAuth 1.0a service.
7. 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/agent-suite-for-merchants/uploads/oauth-type.png)

### Additional Credentials {#additional-credentials}

8. Generate your encryption keys. You can skip this step only if you are limiting your first Sandbox validation to unencrypted requests such as `GET /pets`.
9. If your next tests include Adoptions, Employees, or any other JWE-protected flow, complete the encryption setup now. For the full configuration, see [API Basics](https://developer.mastercard.com/agent-suite-for-merchants/documentation/api-basics/index.md#transport-encryption).
10. Create a key alias and keystore password for your encryption keys, record them securely, and click 'Create Project'.
11. Download the OAuth 1.0a and encryption 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/agent-suite-for-merchants/uploads/project-creation.png)

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

12. On the project dashboard, record the following values:

* Sandbox and Production status
* Authentication consumer key
* Client encryption key fingerprint

![Project dashboard showing Sandbox and Production status and credentials](https://static.developer.mastercard.com/content/agent-suite-for-merchants/uploads/project-dashboard.png)

👉If your API does not use encryption, remove the additional-credentials steps and the encryption fingerprint guidance above.

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

Once you have Sandbox credentials, make a simple GET request to confirm that your project is set up correctly.

Before you run the request, make sure you have:

* Your Sandbox consumer key
* 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 a read-only endpoint so you can verify access, OAuth signing, and the Sandbox base URL before moving on to encrypted flows.
Note: For a full client setup, including encryption configuration, see the [API Basics](https://developer.mastercard.com/agent-suite-for-merchants/documentation/api-basics/index.md#how-to-consume-the-api) section.

**Example Request (cURL):**

```bash
curl --request GET \
   --url "https://sandbox.api.mastercard.com/oauth-petstore/petstore/pets?status=AVAILABLE" \
  --header "Authorization: OAuth oauth_consumer_key=\"YOUR_CONSUMER_KEY\", oauth_signature_method=\"RSA-SHA256\", oauth_timestamp=\"1709596800\", oauth_nonce=\"a1b2c3d4e5f6\", oauth_version=\"1.0\", oauth_signature=\"YOUR_COMPUTED_SIGNATURE\""
```

> This example shows the required OAuth 1.0a header fields explicitly, but uses placeholders for sensitive values.
> Replace `YOUR_CONSUMER_KEY` with the consumer key from your project and generate `oauth_signature` with a Mastercard OAuth library. The library also handles `oauth_timestamp` and `oauth_nonce` for you.
>
> For step-by-step update examples that include `If-Match`, see the [Pets Tutorial](https://developer.mastercard.com/agent-suite-for-merchants/documentation/tutorials-and-guides/pets-tutorial/index.md), [Adoptions Tutorial](https://developer.mastercard.com/agent-suite-for-merchants/documentation/tutorials-and-guides/adoptions-tutorial/index.md), and [Employees Tutorial](https://developer.mastercard.com/agent-suite-for-merchants/documentation/tutorials-and-guides/employees-tutorial/index.md).

**Expected Response:**

```json
{
    "count": 1,
    "offset": 0,
    "limit": 25,
    "total": 1,
    "items": [
         {
             "id": "6f93a031-d45a-4a38-9bdc-cf202541abcb",
             "name": "Bella",
             "breed": "New Zealand Huntaway",
             "color": "Black",
             "gender": "FEMALE",
             "status": {
                  "value": "AVAILABLE"
             }
         }
    ]
}
```

> **Test data:** The sandbox includes pre-loaded available pets. For a negative-flow test, pass an invalid status value (e.g., `?status=INVALID`). The API returns a `400 Bad Request` with a `BAD_REQUEST` reason code. See [Testing](https://developer.mastercard.com/agent-suite-for-merchants/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 [Postman Collection](https://developer.mastercard.com/agent-suite-for-merchants/documentation/developer-tools/postman-collection/index.md) or [Insomnia Collection](https://developer.mastercard.com/agent-suite-for-merchants/documentation/developer-tools/insomnia-collection/index.md) page for setup.
* **Reference Application:** Use the [Reference Application](https://developer.mastercard.com/agent-suite-for-merchants/documentation/developer-tools/reference-app/index.md) page.
* **curl or a custom client:** Use the [Testing](https://developer.mastercard.com/agent-suite-for-merchants/documentation/testing/index.md) page for test cases and additional examples.

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

Once your project is working in Sandbox, request Production access for that same project.

### 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 project you used for Sandbox testing.

2. **Provide commercial countries for your project**
   In the project dashboard, select the commercial countries where you intend to use the service. This information is required for Mastercard to process your Production access request.
   ![Commercial countries selection dropdown on the project dashboard](https://static.developer.mastercard.com/content/agent-suite-for-merchants/uploads/select-countries-project.png)

3. **Request Production access for that project**
   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.

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

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

   * Sandbox: `https://sandbox.api.mastercard.com/oauth-petstore/petstore`
   * Production: `https://api.mastercard.com/oauth-petstore/petstore`

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

Note: OAuth 1.0a authentication and payload encryption work 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/agent-suite-for-merchants/documentation/tutorials-and-guides/onboarding-checklist/index.md).

## Next Steps {#next-steps}

* [API Reference](https://developer.mastercard.com/agent-suite-for-merchants/documentation/api-reference/index.md) for endpoint details
* [API Basics](https://developer.mastercard.com/agent-suite-for-merchants/documentation/api-basics/index.md) for authentication, encryption, and client configuration
* [Testing](https://developer.mastercard.com/agent-suite-for-merchants/documentation/testing/index.md) for additional request scenarios
* [Onboarding Checklist](https://developer.mastercard.com/agent-suite-for-merchants/documentation/tutorials-and-guides/onboarding-checklist/index.md) for the full operational go-live process

### Overview {#overview}

Use this guide to go from account setup to your first successful Sandbox request for {Service Name}. You will create a project, generate credentials, make a token-backed test call, and prepare the same project for Production access.
Tip: If you want the fastest path to a working Sandbox request, start with the [Postman Collection page](https://developer.mastercard.com/agent-suite-for-merchants/documentation/developer-tools/postman-collection/index.md). It lets you test Sandbox and Production flows without writing code first.

### Before you begin {#before-you-begin}

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

### Sandbox checklist {#sandbox-checklist}

| # |    Step     |                                                                                                                 What to do                                                                                                                 |
|---|-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 1 | Access      | Get access to {Service Name} and create your Mastercard Developers project.                                                                                                                                                                |
| 2 | Credentials | Generate your Sandbox OAuth 2.0 credentials and record the values needed for token requests and API calls.                                                                                                                                 |
| 3 | Encryption  | If you will test Adoptions, Employees, or other protected-payload flows, complete JWE setup in [API Basics](https://developer.mastercard.com/agent-suite-for-merchants/documentation/api-basics/index.md#transport-encryption).            |
| 4 | First call  | Send your first Sandbox request using the Sandbox base URL, an access token, and a DPoP proof.                                                                                                                                             |
| 5 | Validation  | Use the sample response and [Testing](https://developer.mastercard.com/agent-suite-for-merchants/documentation/testing/index.md) page to validate test data, positive flows, and negative flows.                                           |
| 6 | Production  | After Sandbox validation is complete, use Step 5 and the [Onboarding Checklist](https://developer.mastercard.com/agent-suite-for-merchants/documentation/tutorials-and-guides/onboarding-checklist/index.md) to request Production access. |

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

1. Go to [Mastercard Developers](https://developer.mastercard.com/) and create an account.
2. Activate your account by opening the link sent to your email address, and log in.
3. Open your [My Projects](https://developer.mastercard.com/dashboard) page and start a new project. Sandbox access is open, so you can begin testing as soon as your project credentials are generated.

## 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}

1. Click 'Create new project' on your [My Projects](https://developer.mastercard.com/dashboard) page. ![Pet Store Project Details](https://static.developer.mastercard.com/content/agent-suite-for-merchants/uploads/pet-store-project-details.png)
2. Enter a project name.
3. If prompted, indicate whether you are creating the project on behalf of a client.
4. In the 'Select at least one API' field, choose **{Service Name}**.

### Service Details {#service-details}

5. Complete the 'Service details' form if it appears. Note: Some project flows include additional client or service fields. If you do not see them, continue to the next step.

### Project Credentials {#project-credentials}

6. In 'Project Credentials', select the 'OAuth 2.0' option for this service.
7. Create the required key alias and keystore password values, record them securely, and click 'Proceed'. ![Select OAuth 2 Type](https://static.developer.mastercard.com/content/agent-suite-for-merchants/uploads/oauth2-type.png)

### Additional Credentials {#additional-credentials}

8. Generate your encryption keys if your next tests include protected payloads.
9. If your next tests include Adoptions, Employees, or any other JWE-protected flow, complete the encryption setup now. For the full configuration, see [API Basics](https://developer.mastercard.com/agent-suite-for-merchants/documentation/api-basics/index.md#transport-encryption).
10. Create a key alias and keystore password for your encryption keys, record them securely, and click 'Create Project'.
11. Download the authentication and encryption 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/agent-suite-for-merchants/uploads/project-creation.png)

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

12. On the project dashboard, record the following values:

* Sandbox and Production status
* Authentication key identifiers and client values needed for token requests
* Client encryption key fingerprint

![Project dashboard showing Sandbox and Production status and credentials](https://static.developer.mastercard.com/content/agent-suite-for-merchants/uploads/project-dashboard.png)

👉If your API does not use encryption, remove the additional-credentials steps and the encryption fingerprint guidance above.

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

Once you have Sandbox credentials, make a simple GET request to confirm that your project is set up correctly.

Before you run the request, make sure you have:

* The client values required to obtain an OAuth 2.0 access token
* The signing material required for your client assertion and DPoP proof
* A supported library or implementation that can generate token requests and DPoP proofs

This first-call example uses a read-only endpoint so you can verify access token generation, DPoP handling, and the Sandbox base URL before moving on to encrypted flows.
Note: For a full client setup, including OAuth 2.0 token handling and encryption configuration, see the [API Basics](https://developer.mastercard.com/agent-suite-for-merchants/documentation/api-basics/index.md#how-to-consume-the-api) section.

**Example Request Flow:**

1. Request an access token from the authorization server using your configured OAuth 2.0 client credentials.
2. Generate a fresh DPoP proof for the API call.
3. Call the Sandbox endpoint with `Authorization: DPoP <access_token>` and the `DPoP` header.

**Example Request (cURL):**

```bash
curl --request GET \
   --url "https://sandbox.api.mastercard.com/oauth-petstore/petstore/pets?status=AVAILABLE" \
  --header "Authorization: DPoP YOUR_ACCESS_TOKEN" \
  --header "DPoP: YOUR_DPOP_PROOF"
```

> This example shows the API call after token acquisition. Replace the placeholders with the access token from the authorization server and a fresh DPoP proof generated for this exact request.
>
> For step-by-step update examples that include `If-Match`, see the [Primary Workflow Tutorial](https://developer.mastercard.com/agent-suite-for-merchants/documentation/tutorials-and-guides/pets-tutorial/index.md), [Transaction Workflow Tutorial](https://developer.mastercard.com/agent-suite-for-merchants/documentation/tutorials-and-guides/adoptions-tutorial/index.md), and [Administrative Workflow Tutorial](https://developer.mastercard.com/agent-suite-for-merchants/documentation/tutorials-and-guides/employees-tutorial/index.md).

**Expected Response:**

```json
{
  "count": 1,
  "offset": 0,
  "limit": 25,
  "total": 1,
  "items": [
    {
      "id": "12345678-1234-1234-1234-123456789abc",
      "name": "Example Resource",
      "type": "PRIMARY",
      "status": {
        "value": "ACTIVE"
      }
    }
  ]
}
```

> **Test data:** Sandbox typically includes pre-loaded data. For a negative-flow test, pass an invalid filter value or an invalid token. The API should return an appropriate `400` or `401` error. See [Testing](https://developer.mastercard.com/agent-suite-for-merchants/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 [Postman Collection](https://developer.mastercard.com/agent-suite-for-merchants/documentation/developer-tools/postman-collection/index.md) or [Insomnia Collection](https://developer.mastercard.com/agent-suite-for-merchants/documentation/developer-tools/insomnia-collection/index.md) page for setup.
* **Reference Application:** Use the [Reference Application](https://developer.mastercard.com/agent-suite-for-merchants/documentation/developer-tools/reference-app/index.md) page.
* **curl or a custom client:** Use the [Testing](https://developer.mastercard.com/agent-suite-for-merchants/documentation/testing/index.md) page for test cases and additional examples.

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

Once your project is working in Sandbox, request Production access for that same project.

### 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 Pet Store project you used for Sandbox testing.

2. **Provide commercial countries for your project**
   In the project dashboard, select the commercial countries where you intend to use the service. This information is required for Mastercard to process your Production access request.
   ![Commercial countries selection dropdown on the project dashboard](https://static.developer.mastercard.com/content/agent-suite-for-merchants/uploads/select-countries-project.png)

3. **Request Production access for that project**
   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.

4. **Generate or download your Production keys**
   After Production access is approved, download the Production authentication and encryption material for the same project. Keep the Production key material separate from your Sandbox keys.

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

   * Sandbox: `https://sandbox.api.mastercard.com/oauth-petstore/petstore`
   * Production: `https://api.mastercard.com/oauth-petstore/petstore`

   Update your application to use the Production credentials, token configuration, and encryption certificates.

Note: OAuth 2.0 authentication and payload encryption follow the same overall integration model in Sandbox and Production. The main changes are the Production credential 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/agent-suite-for-merchants/documentation/tutorials-and-guides/onboarding-checklist/index.md).

## Next Steps {#next-steps}

* [API Reference](https://developer.mastercard.com/agent-suite-for-merchants/documentation/api-reference/index.md) for endpoint details
* [API Basics](https://developer.mastercard.com/agent-suite-for-merchants/documentation/api-basics/index.md) for authentication, encryption, and client configuration
* [Testing](https://developer.mastercard.com/agent-suite-for-merchants/documentation/testing/index.md) for additional request scenarios
* [Onboarding Checklist](https://developer.mastercard.com/agent-suite-for-merchants/documentation/tutorials-and-guides/onboarding-checklist/index.md) for the full operational go-live process

## Onboarding Requirements {#onboarding-requirements}

👉Outline the onboarding requirements. If your outbound API uses a standard Mastercard Developers create-project journey, use the flow below.
👉If your API uses encryption include the additional-credentials step, if it does not then remove that part of the flow.

### Overview {#overview}

Use this guide to go from account setup to your first successful Sandbox request for {Your Service Name}. You will create a project, generate credentials, make a test call, and prepare the same project for Production access.
Tip: If you want the fastest path to a working Sandbox request, start with the [Postman Collection page](https://developer.mastercard.com/agent-suite-for-merchants/documentation/developer-tools/postman-collection/index.md). It lets you test Sandbox and Production flows without writing code first.

### Before you begin {#before-you-begin}

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

### Sandbox checklist {#sandbox-checklist}

| # |    Step     |                                                                                                   What to do                                                                                                    |
|---|-------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 1 | Access      | Get access to {Your Service Name} and create your Mastercard Developers project.                                                                                                                                |
| 2 | Credentials | Generate your Sandbox credentials and record the authentication values required by your outbound service.                                                                                                       |
| 3 | Encryption  | If you will test protected-payload flows, complete payload encryption setup in [API Basics](https://developer.mastercard.com/agent-suite-for-merchants/documentation/api-basics/index.md#transport-encryption). |
| 4 | First call  | Send your first Sandbox request using the Sandbox base URL and the authentication model used by your service.                                                                                                   |
| 5 | Validation  | Use the sample response and [Testing](https://developer.mastercard.com/agent-suite-for-merchants/documentation/testing/index.md) page to validate test data, positive flows, and negative flows.                |
| 6 | Production  | After Sandbox validation is complete, request Production access for the same project.                                                                                                                           |

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

1. Navigate to [Mastercard Developers](https://developer.mastercard.com/) 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. 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}

To generate your Sandbox and Production credentials you must create a new Mastercard Developers project. Generating Sandbox credentials gives you access to test data so you can validate your integration before requesting Production access.

### Project Details {#project-details}

1. Create a project on your [My Projects](https://developer.mastercard.com/dashboard) page. ![Project Details](https://static.developer.mastercard.com/content/agent-suite-for-merchants/uploads/enter-project-image.avif)
2. Name your project.
3. Indicate whether you are creating a project on behalf of a client.
4. Provide the client company name and client company address if applicable.
5. In the 'Select your API service' field select '{Your Service Name}'.
6. Provide the commercial countries for the project.

Note: If you are creating a project on behalf of a client, the commercial countries represent where your client is doing business.

### Project Credentials {#project-credentials}

7. Proceed to create your project credentials and create a key alias and keystore password. ![Project Credentials](https://static.developer.mastercard.com/content/agent-suite-for-merchants/uploads/Oauth-key-image.avif)
8. Click on "Download key file" and keep the downloaded Sandbox credential file safe. ![Project Creation](https://static.developer.mastercard.com/content/agent-suite-for-merchants/uploads/create-project-image.avif)

### Additional Credentials {#additional-credentials}

9. Generate additional credentials, such as encryption keys, if your service requires them. ![Additional Credentials](https://static.developer.mastercard.com/content/agent-suite-for-merchants/uploads/additional-credentials-image.avif)
10. Once you complete this flow, click on the 'Open Project' button to reach the project page. From the Project page take note of your Sandbox and Production status and the credentials you will need for authentication and encryption.

Warning: **Key Expiry:** 👉 Replace this with the actual credential expiry behavior for your service. If there is no fixed expiry window, remove this warning.

## 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: Choose how you want to test and integrate {#step-4-choose-how-you-want-to-test-and-integrate}

* **Postman or Insomnia:** Use the [Postman Collection](https://developer.mastercard.com/agent-suite-for-merchants/documentation/developer-tools/postman-collection/index.md) or [Insomnia Collection](https://developer.mastercard.com/agent-suite-for-merchants/documentation/developer-tools/insomnia-collection/index.md) page for setup.
* **Reference Application:** Use the [Reference Application](https://developer.mastercard.com/agent-suite-for-merchants/documentation/developer-tools/reference-app/index.md) page if a sample app is provided.
* **Custom client:** Use [Testing](https://developer.mastercard.com/agent-suite-for-merchants/documentation/testing/index.md) and [API Basics](https://developer.mastercard.com/agent-suite-for-merchants/documentation/api-basics/index.md) to configure and validate your integration.

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

After you have tested your implementation in Sandbox, it is time to **Move to Production**.

### Steps to move to production {#steps-to-move-to-production}

1. Within your project, select "Request Production Access". ![Project](https://static.developer.mastercard.com/content/agent-suite-for-merchants/uploads/request-prod-image.avif)
2. Enter your Production key alias and keystore password. ![Project](https://static.developer.mastercard.com/content/agent-suite-for-merchants/uploads/enter-your-image.avif)
3. Save your key alias and keystore password for future reference.
4. Confirm and download your Production keys.

Note: Production credentials are generated immediately, 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 whether your access has been approved or denied.

👉If your outbound API does not use the standard create-project journey, adapt or replace the alternative structure below.

## Eligibility and Enrollment {#eligibility-and-enrollment}

* Ensure all eligibility prerequisites are met (e.g., company eligibility, legal compliance).
* Complete necessary enrollment, franchise and onboarding forms.
* Have a kick-off meeting with partners/acquirers/issuers to confirm the scope, timeliness and access rights.
* Contact Mastercard Customer Implementation Service (CIS) representatives, or the relevant support team, and provide your service details such as company name, client name, and customer ID.

## Access and Credentialing {#access-and-credentialing}

* Gain access to Mastercard Connect Portal, or Key Management Portals, or other required platforms.
* Obtain Company ID (CID), client ID, API credentials, and authentication details.
* Exchange encryption keys, certificates, data permissions and security credentials.

## Project Creation \& Configuration {#project-creation--configuration}

* Create a project in our Developer Portal 👉Link to external site if portal is external, link to MCD if portal is internal.
* Configure project settings, security parameters, and API access.
* Define and validate API endpoint details.

## Integration (If SDK or similar) {#integration-if-sdk-or-similar}

* Ensure security and data exchange protocols meet Mastercard's compliance requirements. Establish backend connectivity (e.g., server-to-server communication, encryption, mTLS).
* Set up frontend/backend integration models (e.g., SDK-based, dual app, or direct API calls).
* Configure authentication and authorization mechanisms.

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

* Navigate to the API documentation page.

* Download the API specification (OpenAPI or Swagger).

* Generate and configure an API client for this API.

* 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/).

## Testing and Go-Live {#testing-and-go-live}

* Ensure security and data exchange protocols meet Mastercard's compliance requirements.
* Establish a Sandbox environment and start using the mocked test data.
* Validate integration via the Mastercard Test Facility (MTF). Request access via the customer implementation team if needed.
* After you have tested your implementation in Sandbox and MTF, it is time to **Move to Production**. For Production access, ensure you meet the service requirements and contact the appropriate implementation team or support mailbox.

<br />

## Eligibility and Enrollment {#eligibility-and-enrollment}

* Ensure all eligibility prerequisites are met (e.g., company eligibility, legal compliance).
* Complete necessary enrollment, franchise, and onboarding forms.
* Have a kick-off meeting with partners, acquirers, issuers, or implementation stakeholders to confirm scope, timelines, and access rights.
* Contact Mastercard Customer Implementation Service (CIS) representatives, or the relevant support team, and provide service details such as company name, client name, and customer ID.

## Access and Credentialing {#access-and-credentialing}

* Gain access to Mastercard Connect Portal, or Key Management Portals, or other required platforms.
* Obtain Company ID (CID), client ID, API credentials, and authentication details.
* Exchange encryption keys, certificates, data permissions and security credentials.

## Project Creation \& Configuration {#project-creation--configuration}

* Create a project in the relevant developer portal. 👉 Link to the correct portal here. If the portal is internal, link to the internal experience instead of Mastercard Developers.
* Configure project settings, security parameters, and API access.
* Define and validate API endpoint details.

## Integration (If SDK or similar) {#integration-if-sdk-or-similar}

* Ensure security and data exchange protocols meet Mastercard compliance requirements. Establish backend connectivity, such as server-to-server communication, encryption, or mTLS.
* Set up frontend and backend integration models, such as SDK-based, dual-app, or direct API calls.
* Configure authentication and authorization mechanisms.

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

* Navigate to the API documentation page.

* Download the API specification (OpenAPI or Swagger).

* Generate and configure an API client for this API.

* 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/).

## Testing and Go-Live {#testing-and-go-live}

* Ensure security and data exchange protocols meet Mastercard compliance requirements.
* Establish a Sandbox environment and start using test data.
* Validate integration via the Mastercard Test Facility (MTF) when the service requires it. Request access via the implementation team if needed.
* After you have tested your implementation in Sandbox and MTF, it is time to **Move to Production**. For Production access, ensure you meet the service requirements and contact the appropriate implementation team or support mailbox.

## Next Steps {#next-steps}

After selecting a quick start template, continue with the documentation that matches your next task:

* [API Reference](https://developer.mastercard.com/agent-suite-for-merchants/documentation/api-reference/index.md) for endpoint details
* [API Basics](https://developer.mastercard.com/agent-suite-for-merchants/documentation/api-basics/index.md) for authentication, encryption, and client configuration
* [Testing](https://developer.mastercard.com/agent-suite-for-merchants/documentation/testing/index.md) for additional request scenarios
* [Onboarding Checklist](https://developer.mastercard.com/agent-suite-for-merchants/documentation/tutorials-and-guides/onboarding-checklist/index.md) for the full operational go-live process