# Quick Start Guide
source: https://developer.mastercard.com/unified-installments/documentation/quick-start-guide/index.md

## Overview {#overview}

Use this guide to go from account setup to your first successful Sandbox request for Reference Service NGW. 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 Collections page](https://stage.developer.mastercard.com/reference-service-ngw/documentation/developer-tools/postman-collection). It lets you test Sandbox and Production flows without writing code first.

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

* Create a [Mastercard Developers](https://stage.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/unified-installments/documentation/api-basics/index.md#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/unified-installments/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\] to request Production access.                                                                                                  |

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

1. Go to [Mastercard Developers](https://stage.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://stage.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/) page.

   ![Mastercard Installments Project Details](https://static.stage.developer.mastercard.com/content/reference-service-ngw/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.stage.developer.mastercard.com/content/reference-service-ngw/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://stage.developer.mastercard.com/reference-service-ngw/documentation/api-basics/#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.stage.developer.mastercard.com/content/reference-service-ngw/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.stage.developer.mastercard.com/content/reference-service-ngw/uploads/project-dashboard.png)

## 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 `GET /pets`, 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://stage.developer.mastercard.com/reference-service-ngw/documentation/api-basics/#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://stage.developer.mastercard.com/reference-service-ngw/documentation/tutorials-and-guides/pets-tutorial), [Adoptions Tutorial](https://stage.developer.mastercard.com/reference-service-ngw/documentation/tutorials-and-guides/adoptions-tutorial), and [Employees Tutorial](https://stage.developer.mastercard.com/reference-service-ngw/documentation/tutorials-and-guides/employees-tutorial).

**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://stage.developer.mastercard.com/reference-service-ngw/documentation/testing) 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://stage.developer.mastercard.com/reference-service-ngw/documentation/developer-tools/postman-collection) or [Insomnia Collection](https://stage.developer.mastercard.com/reference-service-ngw/documentation/developer-tools/insomnia-collection) page for setup.
* **Reference Application:** Use the [Reference Application](https://stage.developer.mastercard.com/reference-service-ngw/documentation/developer-tools/reference-app) page.
* **curl or a custom client:** Use the [Testing](https://stage.developer.mastercard.com/reference-service-ngw/documentation/testing) 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://stage.developer.mastercard.com/dashboard) page and open the Mastercard Installments 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.stage.developer.mastercard.com/content/reference-service-ngw/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/installments`
   * Production: `https://api.mastercard.com/installments`

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

> \[!NOTE\]
>
> OAuth 1.0a authentication and JWE 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://stage.developer.mastercard.com/reference-service-ngw/documentation/tutorials-and-guides/onboarding-checklist).

## Next Steps {#next-steps}

Continue with the documentation that matches your next task:

* [API Reference](https://developer.mastercard.com/unified-installments/documentation/api-reference/index.md) for endpoint details.
* [API Basics](https://developer.mastercard.com/unified-installments/documentation/api-basics/index.md) for authentication, encryption, and client configuration.
* [Testing](https://developer.mastercard.com/unified-installments/documentation/testing/index.md) for additional request scenarios.