# Quick Start Guide
source: https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/quick-start-guide/index.md

## Overview {#overview}

Use this guide to go from account setup to your first successful Sandbox request for Benefits Allocation Service. You will create a project, generate credentials, make a test call, and prepare the same project for Production access.

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

* Create a [Mastercard Developers](https://developer.mastercard.com/) account.
* Have a secure place to store downloaded mTLS certificates and encryption keys.
* Decide how you want to test: Insomnia, the reference application, or your own client.
* Have an HTTP client configured for mTLS certificate-based authentication (curl, Postman, or your preferred HTTP library).

### Sandbox checklist {#sandbox-checklist}

| # |      Step      |                                                                        What to do                                                                        |
|---|----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
| 1 | Access         | Get access to Benefit Allocations Service and create your Mastercard Developers project.                                                                 |
| 2 | Credentials    | Generate your Sandbox mTLS certificates and download the certificate and key files.                                                                      |
| 3 | Environment    | Confirm that you are using the Sandbox base URL and that your project is still in Sandbox mode.                                                          |
| 4 | Authentication | Configure mTLS certificate authentication for the first request and locate your certificate and key files.                                               |
| 5 | First call     | Send your first Sandbox request using the Sandbox base URL with mTLS certificate authentication.                                                         |
| 6 | Validation     | Use the sample response and [Testing](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/testing/index.md) page to validate. |
| 7 | Production     | After Sandbox validation is complete, 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.

   ![My Projects](https://static.developer.mastercard.com/content/benefit-allocation-service-mtls/uploads/sandbox-tutorial/my-proj.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 **Benefit Allocations Service (MTLS)** and click **Proceed**.

![Project Details](https://static.developer.mastercard.com/content/benefit-allocation-service-mtls/uploads/sandbox-tutorial/project-details.png)

### Project Credentials {#project-credentials}

5. Select **Mutual TLS** as the authentication method and click **Proceed**.

   ![Select mTLS Type](https://static.developer.mastercard.com/content/benefit-allocation-service-mtls/uploads/sandbox-tutorial/proj-cred.png)

### Additional Credentials {#additional-credentials}

6. Click on **Create Project** to create your project and generate the client encryption key and mTLS certificates. ![Confirm to generate mTLS certificates](https://static.developer.mastercard.com/content/benefit-allocation-service-mtls/uploads/sandbox-tutorial/additional-cred.png)
7. Download the mTLS certificate (.pem), private key (.pem), and encryption keys and store them in a safe place. Then click **Open Project** . ![Create project loading icons and download certificates](https://static.developer.mastercard.com/content/benefit-allocation-service-mtls/uploads/sandbox-tutorial/creating-proj.png)

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

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

* Sandbox and Production status
* mTLS certificate file path
* mTLS private key file path

![Project summary screen](https://static.developer.mastercard.com/content/benefit-allocation-service-mtls/uploads/projectView2.png)
Warning: **Key Expiry:** The Sandbox and Production Keys have expiry dates. Users will receive notifications 90 days before expiry. To avoid disruption, renew 30-60 days before expiry. You will have to generate a new set of keys after they expire.

## Step 3: Confirm Sandbox configuration and make your first request {#step-3-confirm-sandbox-configuration-and-make-your-first-request}

Once you have Sandbox credentials, you can start assigning benefits through insomnia, the ref app or a custom client.

### Sandbox Environment and Configuration {#sandbox-environment-and-configuration}

* Use the Sandbox base URL for the first call: `https://mtf.services.mastercard.com/loyalty/benefits/sandbox`.
* Configure mTLS certificate authentication for every request to this service.

Before you run the request, make sure you have:

* Your mTLS client certificate file (.pem format)
* Your mTLS private key file (.pem format)
* The encryption key file used to encrypt payloads
* Your certificate and key file paths accessible to your HTTP client

The first call example uses `POST /card-segments`, so you can verify access, mTLS authentication, JWE encryption, and the Sandbox base URL.
Note: `POST /card-segments` requires JWE payload encryption. Encrypt the sample payload using your encryption certificate before sending. See [API Basics](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/api-basics/index.md) for encryption configuration and library links.

**Structural request template:**

```bash
curl -X POST "https://mtf.services.mastercard.com/loyalty/benefits/sandbox/card-segments" \
  -H "Content-Type: application/json" \
  --cert /path/to/client-certificate.pem \
  --key /path/to/client-key.pem \
  --cacert /path/to/ca-certificate.pem \
  -d '{"encryptedValue":"<jwe-encrypted-payload>"}'
```

> Replace `/path/to/client-certificate.pem` and `/path/to/client-key.pem` with the actual paths to your downloaded mTLS certificate and private key files. The `-d` body is the JWE-encrypted form of the plaintext payload shown below.

**Sample Request Payload (plaintext, before encryption)**

```json
{
  "cardNumber": 5291070000000000,
  "segments": [
    {
      "code": "DART",
      "effectiveDate": "2023-08-08"
    }
  ]
}
```

**Expected response:**

```json
{
  "bundles": [
    {
      "code": "080815",
      "effectiveDate": "2023-08-08",
      "expiryDate": "2024-07-24"
    },
    {
      "code": "087950",
      "effectiveDate": "2023-08-08",
      "expiryDate": "2024-08-18"
    }
  ]
}
```

### What Success Looks Like {#what-success-looks-like}

* The request returns `200 OK`.
* The response body includes a `bundles` array with at least one benefit record.
* Each record includes a bundle `code` and a `effectiveDate` that has the date value which was supplied in the request.

### Common First-Call Errors {#common-first-call-errors}

If your first call does not return `200 OK`, check the following before retrying:

|                     **Error**                     |                    **Likely Cause**                    |                                                           **Quick Fix**                                                            |
|---------------------------------------------------|--------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------|
| `401 Unauthorized`                                | Missing, expired, or invalid mTLS certificate          | Verify the certificate file exists and is valid; re-download if expired; confirm paths are correct in curl command                 |
| `403 Forbidden`                                   | mTLS certificate not authorized for this ICA           | Confirm the certificate belongs to the project with Benefit Allocations Service enabled                                            |
| `SSL: CERTIFICATE_VERIFY_FAILED`                  | mTLS certificate chain validation failed               | Verify the `--cacert` option points to the correct CA certificate file                                                             |
| Code `57` --- Invalid encryption key              | Wrong or expired encryption certificate                | Re-download your encryption certificate from the project dashboard and update your configuration                                   |
| Code `37` --- Required field missing, Card Number | Required fields missing from payload before encryption | Confirm `cardNumber`, `segments[].code`, and `segments[].effectiveDate` are all present in the plaintext payload before encrypting |

> **Test data:** See [Testing](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/testing/index.md) for additional scenarios.

## Step 4: Promote the same project to Production {#step-4-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 Benefit Allocations Service project you used for Sandbox testing.

2. **Production access 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. This information is required for Mastercard to process your Production access request.

   * **Company Verification:** 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](https://developer.mastercard.com/platform/documentation/account-management/company-verification/) guide to complete this step.

   * **Provide commercial countries for your project** 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).

3. **Request Production access for that project** In the project dashboard, select **'Request Production Access'** . Follow the same steps used to generate Sandbox keys. 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. **Update your application configuration** Switch the base URL from Sandbox to Production:

   * Sandbox: `https://mtf.services.mastercard.com/loyalty/benefits/sandbox`
   * MTF: `https://mtf.services.mastercard.com/loyalty/benefits`
   * Production: `https://services.mastercard.com/loyalty/benefits`

   Update your application to use the Production mTLS certificate, private key, and encryption certificates.

Note: mTLS authentication and JWE payload encryption work the same way in Sandbox and Production. The main changes are the Production certificate set, the Production approval state, and the Production base URL.

## 5. Go Live {#5-go-live}

After you have tested your implementation in Sandbox and completed your Production prerequisite steps, you can move to Production and go live.

1. Open your project and click the "Request Production access" button on the Summary page and complete the steps in the flow.
2. When you reach the final step in the flow, your request will be submitted and your credentials will be generated and ready to download. After you download your credentials, click the **"Open project"** button.

Note: Production credentials are generated instantaneously but they are only activated once your Production request is approved.

3. Once we have reviewed and approved your request, you will receive an approval email. Now your Production credentials are activated and you're ready to go live with your API integration.

### Next Steps {#next-steps}

Continue with the documentation that matches your next task:

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