# Integration and Testing
source: https://developer.mastercard.com/carbon-calculator/documentation/integration-and-testing/index.md

## Ready to Begin Testing? {#ready-to-begin-testing}

Tip: We recommend that you begin testing in the sandbox.

**This page is your testing and validation reference** --- how to run the call from an API client, confirm the response is correct, and resolve errors when it isn't.

## Methods of Testing Sandbox/Production {#methods-of-testing-sandboxproduction}

### 1. Reference application {#1-reference-application}

> * Our Spring Boot Reference Application acts as an API client and allows you to integrate different operations.
> * For detailed steps, follow our [Reference Application Page](https://developer.mastercard.com/carbon-calculator/documentation/reference-app/index.md).

### 2. Postman {#2-postman}

> * [Postman Collections](https://www.postman.com/product/collections/) opens in a new tab is an API client that allows developers to test your API's calls in sandbox and production environments without writing any code. This makes sharing pre-formed API requests with partners extremely easy, and permits partners to run individual API requests or those within a folder or the entire collection.
> * For detailed steps, follow our [Postman Collections Page](https://developer.mastercard.com/carbon-calculator/documentation/postman-collection/index.md).

### 3. Insomnia {#3-insomnia}

> * [Insomnia](https://insomnia.rest/) is an open-source API client that developers use to quickly and easily send REST requests to Mastercard APIs. API Consultancy \& Standards developed an [Insomnia Plugin](https://github.com/Mastercard/insomnia-plugin-mastercard) for handling API authentication.
> * Follow our [Insomnia Tutorial](https://developer.mastercard.com/platform/tutorial/use-insomnia-rest-client-for-mastercard-apis/) to learn how to test the Carbon calculator API using Insomnia.
>
> 👉 Download our Insomnia Collection here:
> [Insomnia_collection_2025.yaml](https://static.developer.mastercard.com/content/carbon-calculator/uploads/Insomnia_collection_2025.yaml) (31KB)

## Step 1: Set up {#step-1-set-up}

Your onboarding (project creation, credentials, encryption keys) is covered in the [Quick Start Guide](https://developer.mastercard.com/carbon-calculator/documentation/quick-start-guide/index.md). Before testing, make sure you have the following ready:

* **Client** --- a tool like [Insomnia](https://insomnia.rest/) (with the [Mastercard plugin](https://github.com/Mastercard/insomnia-plugin-mastercard)) or Postman, so you can test without writing code.
* **Authentication** --- OAuth 1.0a, signed with your `.p12` key and consumer key. Your client's Mastercard plugin adds the `Authorization` header for you.
* **Encryption** --- only endpoints carrying payment-card data or PII (such as Add Payment Cards) need payload encryption; See [API Basics](https://developer.mastercard.com/carbon-calculator/documentation/api-basics/index.md) if you need it.
* **Base URL** --- point your client to the correct environment:

| Environment |                  Base URL                   |
|-------------|---------------------------------------------|
| Sandbox     | `https://sandbox.api.mastercard.com/carbon` |
| Production  | `https://api.mastercard.com/carbon`         |

## Step 2: The test call {#step-2-the-test-call}

Use `POST /transaction-footprints` --- a simple, unencrypted endpoint that is ideal for a first validation request.

**Request body**

```json
[
  {
    "transactionId": "fdc4626c-f51e-4ba6-9728-c79ac1d9aec8",
    "mcc": "3000",
    "cardBrand": "OTH",
    "amount": {
      "currencyCode": "USD",
      "value": 10.35
    }
  }
]
```

**Response --- `200 OK`**

```json
[
  {
    "transactionId": "fdc4626c-f51e-4ba6-9728-c79ac1d9aec8",
    "mcc": "3000",
    "scoreReference": "MCC",
    "carbonEmissionInGrams": 11941.95,
    "carbonEmissionInOunces": 421.24,
    "category": {
      "mainCategory": "Transport",
      "subCategory": "Flights",
      "sector": "Flights",
      "sectorCode": "351"
    }
  }
]
```

## Step 3: Validate the response {#step-3-validate-the-response}

Validate a response against the API's documented contract:

* **HTTP status** --- a `2xx` status means success: `200 OK` for read and scoring operations, or `201 Created` when a new resource (such as a registered card) is created. A `4xx` or `5xx` status indicates an error. See [Codes and Formats](https://developer.mastercard.com/carbon-calculator/documentation/code-and-formats/index.md) for the full list.
* **Error structure** --- a successful response contains **no** `Errors.Error[]` object in the body; a failed one does (see Step 4).
* **Response fields** --- check the body against that operation's response schema in the [API Reference](https://developer.mastercard.com/carbon-calculator/documentation/api-reference/index.md), which defines the exact fields each endpoint returns.

Note: **Example --- `POST /transaction-footprints`:** a valid response is a `200 OK` array with one object per transaction you sent, each containing a numeric `carbonEmissionInGrams`, a resolved `category`, and a `scoreReference`.

## Step 4: Troubleshoot errors {#step-4-troubleshoot-errors}

When a call fails, the API returns a standard error object. Read the `ReasonCode` for the type of error and the `Details` field for exactly what to fix:

```json
{
  "Errors": {
    "Error": [
      {
        "Source": "Carbon-Calculator",
        "ReasonCode": "INVALID_REQUEST_PARAMETER",
        "Description": "One of the request parameters is invalid, try again with correct request.",
        "Recoverable": false,
        "Details": "transactions[0].mcc size must be between 1 and 4"
      }
    ]
  }
}
```

|         Reason code         |                                            What it means \& what to do                                            |
|-----------------------------|-------------------------------------------------------------------------------------------------------------------|
| `INVALID_REQUEST_PARAMETER` | A field is invalid or missing --- read `Details` and correct the highlighted field.                               |
| `INVALID_FPAN`              | The card is invalid or outside your registered BIN range --- check the PAN and your onboarded BINs.               |
| `ACCOUNT_NOT_FOUND`         | Onboarding is not complete --- contact [carboncalculator@mastercard.com](mailto:carboncalculator@mastercard.com). |
| `ACCOUNT_SUSPENDED`         | Your account is temporarily suspended --- contact your Mastercard associate to reactivate it.                     |
| `CRYPTO_ERROR`              | Request decryption failed --- confirm you encrypted the payload with the correct Mastercard certificate.          |
| `INVALID_DATE_RANGE`        | The date range is invalid or exceeds the one-year limit --- correct the date values and retry.                    |
| `PAYMENT_CARD_NOT_FOUND`    | No card matches the `paymentCardId` in the path --- verify the ID from your Add Payment Card response.            |

For the full list of error codes and resolution tips, see [Codes and Formats](https://developer.mastercard.com/carbon-calculator/documentation/code-and-formats/index.md). For in-depth, endpoint-by-endpoint test scenarios, follow the [Carbon Calculator API Testing](https://developer.mastercard.com/carbon-calculator/tutorial/api-testing/index.md) tutorial.

## Next Steps {#next-steps}

Tip: **Onboarding path:** [API Basics](https://developer.mastercard.com/carbon-calculator/documentation/api-basics/index.md) → [Quick Start Guide](https://developer.mastercard.com/carbon-calculator/documentation/quick-start-guide/index.md) → **Integration \& Testing (you are here)** → [Use Cases](https://developer.mastercard.com/carbon-calculator/documentation/use-cases/index.md)  
**Next step →** [Use Cases](https://developer.mastercard.com/carbon-calculator/documentation/use-cases/index.md) to map your business scenarios to specific API endpoints.  
**Ready to run calls?** Fork the [Postman Collections](https://developer.mastercard.com/carbon-calculator/documentation/postman-collection/index.md), download the [Reference Application](https://developer.mastercard.com/carbon-calculator/documentation/reference-app/index.md), or follow the [API Testing](https://developer.mastercard.com/carbon-calculator/tutorial/api-testing/index.md) tutorial. For error-code details see [Codes and Formats](https://developer.mastercard.com/carbon-calculator/documentation/code-and-formats/index.md).