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

## Overview {#overview}

Use this guide to integrate with the Benefit Allocation Service in sequence: create a project, validate connectivity in Sandbox, test the end-to-end integration in MTF, then request Production access and go live.

### 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).

### Integration checklist {#integration-checklist}

| # |              Step               |                                                 What to do                                                  |
|---|---------------------------------|-------------------------------------------------------------------------------------------------------------|
| 1 | Account access                  | Create and activate your Mastercard Developers account.                                                     |
| 2 | Project and Sandbox credentials | Create a Benefit Allocation Service project and generate Sandbox mTLS certificates and encryption keys.     |
| 3 | Sandbox smoke test              | Use the Sandbox URL to check connectivity, mTLS authentication, and JWE request encryption.                 |
| 4 | MTF integration testing         | Run end-to-end tests against real pre-production data using the MTF URL.                                    |
| 5 | Production                      | After MTF validation and completion of the Production prerequisites, request Production access and go live. |

## Step 1: Get access to Mastercard Developers {#step-1-get-access-to-mastercard-developers}

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 [My Projects](https://developer.mastercard.com/dashboard) to create your Benefit Allocation Service project in the next step.

## Step 2: Create a project and generate Sandbox credentials {#step-2-create-a-project-and-generate-sandbox-credentials}

Create a Benefit Allocation Service project and generate Sandbox credentials. Sandbox is for an initial smoke test of connectivity, mTLS authentication, and JWE encryption; it does not process real card or benefit data. Complete end-to-end integration testing in MTF 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 Allocation 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. On the **Project credentials** screen, enter a certificate alias and keystore password to generate the mTLS credentials, then click **Proceed** . The screen also lets you provide the distinguished-name (DN) values used in the certificate signing request (CSR). If you already have a custom CSR or mTLS certificate, choose **Skip this step** and add it from the project dashboard after creating the project.

![Project credentials form for generating mTLS credentials](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: Run a Sandbox smoke test {#step-3-run-a-sandbox-smoke-test}

Once you have Sandbox credentials, send an initial request using Insomnia, the reference application, or a custom client. This checks that your connection, certificate authentication, and payload encryption are configured correctly; it is not full integration testing.

### 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 Sandbox success looks like {#what-sandbox-success-looks-like}

* The request returns `200 OK`.
* The response body includes a `bundles` array.
* The response reflects values supplied in the request, but does not represent real card or benefit data.

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

> **Next:** Use MTF for end-to-end integration tests with real pre-production data. See the [Testing guide](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/testing/index.md) for recommended workflows.

## Step 4: Validate the integration in MTF {#step-4-validate-the-integration-in-mtf}

After the Sandbox smoke test succeeds and the required agreements are signed, complete the MTF access prerequisites and run the full integration tests. MTF uses real pre-production data and is the environment for validating Benefit Allocation Service behavior before Production.

### MTF environment and testing {#mtf-environment-and-testing}

* Use the MTF base URL: `https://mtf.services.mastercard.com/loyalty/benefits`.
* Use your Sandbox mTLS certificates to authenticate.
* Continue to encrypt requests that contain sensitive data using JWE.
* Exercise the end-to-end workflows in the [Testing guide](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/testing/index.md), including the operations your integration will use.

MTF validation is complete when all required integration tests pass with a 100% success rate. Complete any remaining Production prerequisites before requesting access. See the [Onboarding Checklist](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/tutorials-and-guides/onboarding-checklist/index.md) for agreement, MTF access, and Production-transition requirements.

## Step 5: Promote to Production and go live {#step-5-promote-to-production-and-go-live}

After successful MTF testing, request Production access for the same project.

1. Open the Benefit Allocation Service project in [My Projects](https://developer.mastercard.com/dashboard).

2. Complete the Production access prerequisites shown on the project Summary page. These include Company Verification and providing the commercial countries for the integration. See the [Company Verification guide](https://developer.mastercard.com/platform/documentation/account-management/company-verification/) for details.

3. Select **Request Production Access** in the project and submit the request. The Sandbox and Production statuses are shown separately on the project page.

4. After approval, download the Production mTLS certificate, private key, and encryption keys from the project dashboard. Update your application to use these Production credentials and the Production base URL:

   `https://services.mastercard.com/loyalty/benefits`

   Sandbox and MTF use the Sandbox mTLS certificate set; Production requires the Production credentials. mTLS and JWE configuration otherwise follow the same process across environments.

Note: Production credentials are available for use only after your Production access request is approved and the credentials are activated.

Go live after the Production credentials are activated and your application is configured for the Production environment.

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