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

## Overview {#overview}

Use this guide to get started with the Carbon Calculator API. It will walk you through the steps to create a project, generate your credentials, make your first API call in the sandbox environment and promote your project to production.

## Sandbox checklist {#sandbox-checklist}

| # |      Step      |                                                                                                                       What to do                                                                                                                       |
|---|----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 1 | Access         | Get access to the Carbon Calculator API on [Mastercard Developers](https://developer.mastercard.com/) and create your project.                                                                                                                         |
| 2 | Credentials    | Create a Sandbox project to generate your OAuth 1.0a `.p12` key file, and record your consumer key, key alias, and keystore password.                                                                                                                  |
| 3 | Environment    | Confirm you are using the Sandbox base URL `https://sandbox.api.mastercard.com/carbon` and that your project is still in Sandbox mode.                                                                                                                 |
| 4 | Authentication | Configure your `.p12` key and consumer key for OAuth 1.0a request signing, and confirm which key alias and keystore password you will use.                                                                                                             |
| 5 | Encryption     | Complete payload encryption setup in [API Basics](https://developer.mastercard.com/carbon-calculator/documentation/api-basics/index.md) before testing card-credential flows such as Add Payment Cards (Option 1).                                     |
| 6 | First call     | Send your first Sandbox request using the Sandbox base URL and OAuth 1.0a signing.                                                                                                                                                                     |
| 7 | Production     | After Sandbox validation is complete, follow [Promote from Sandbox to Production](https://developer.mastercard.com/carbon-calculator/documentation/quick-start-guide/index.md#step-4-promote-from-sandbox-to-production) to request Production access. |

Tip: **Postman Collections Quick Start** : If you are already ready to start making calls you can head over to our [Postman Collections page](https://developer.mastercard.com/carbon-calculator/documentation/postman-collection/index.md) to leverage Sandbox and Production environments without having to write code.

## Step 1: Accessing the API on Mastercard Developers {#step-1-accessing-the-api-on-mastercard-developers}

1. Navigate to [Mastercard Developers](https://developer.mastercard.com/) and click sign up 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.
4. To gain access to these services, you will need to submit an access request form. Once submitted, you will receive an email confirmation approving or denying your access.

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

### Pre-requisites: {#pre-requisites}

The following values are required when creating a project in the sandbox.

**If you want to opt for Option 1:**   

* BIN Range
* Customer ID
* Legal Name

**If you want to opt for Option 2.a:**   

* Customer ID
* Legal Name

**If you want to opt for Option 2.b:**   

* Customer ID
* Legal Name
* Sender ID - Customer logical name or logical address of the service provider which has been configured in NGFT(Next Gen File Transfer).

Note:   

* Ensure you use a valid Customer ID assigned by Mastercard, which remains the same across all Mastercard systems.
* Ensure that a BIN is not mapped to multiple Customer IDs.

To generate your Sandbox and Production credentials you must create a new Mastercard Developers project. Generating Sandbox credentials will give you access to our Sandbox, which has rich, mocked data, that will help you understand the API.

Follow these steps to create a Sandbox Carbon Calculator Project:

1. Go to your dashboard by clicking the [My Projects](https://developer.mastercard.com/dashboard) option in the menu.
2. You can create a new project by clicking the **Create New Project** button, in the upper right portion of the screen as shown in the screenshot below. ![Create Project](https://static.developer.mastercard.com/content/carbon-calculator/Images/tutorials/create_project.png)
3. In the **Project Details** page, enter a descriptive name for your project.
4. Answer "Yes" if you are creating this project on behalf of a client. Select "No" if you are not. After choosing "Yes", two new fields will appear. Please enter your client company name and client legal business address before proceeding. Note: Check Yes if you are creating an API integration project for a customer. For example, you could be an integrator, a processor, or a service provider and the customer could be a merchant, issuer, or acquirer.
5. Provide the client company name and client company address (if applicable).
6. In the **Select your API service** field, select **Carbon Calculator**.
7. Provide the **commercial countries** for the project. This field represents where your client is doing business. Click the **Proceed** button as shown in the screenshot. Note: If you are creating a project on-behalf of a client, the Commercial countries represent where your client is doing business. ![Select API](https://static.developer.mastercard.com/content/carbon-calculator/Images/tutorials/select-api-and-country.png)
8. Enter your **Customer Name**. This does not have to be a legal name. For example, "ABC Bank".
9. Enter your **Customer ID (CID)**. This is a unique Service Provider identifier assigned by Mastercard which remains the same across all Mastercard systems.
10. Enter the (comma-separated) **Sandbox BIN Range**, you want to use for the Carbon Calculator API. For example, "534403, 518145, 518152, 5403, 5424".
11. Enter your **Sender Id**. This is customer logical name or logical address of the service provider which has been configured in NGFT(Next Gen File Transfer). For example, "filebasedscoring@service_provider_name".
12. Enter your **Cardholder Base** . This is the total volume of card holders for whom the cards have been issued. This can be updated later using [Update Service Provider Details API](https://developer.mastercard.com/carbon-calculator/documentation/use-cases/update_service_provider_details/index.md).
13. Proceed to create your 'Project Credentials'. Create a **key alias** and **keystore password**, note this.
14. When the project has successfully created the Sandbox .P12 access credentials will be available for download as shown in the screenshot below.
15. Click the **Download key file** button to download a zip file containing the .p12 file required for OAuth authentication in Sandbox. ![Select API](https://static.developer.mastercard.com/content/carbon-calculator/Images/tutorials/sandbox_download_keys.png)
16. Once you complete this flow you will land on the Project page. From the Project page take note of your:  
    a. Sandbox and Production status ('Ready/Not Requested')  
    b. Sandbox and Production credentials: authentication consumer key and client encryption key fingerprint. ![Select API](https://static.developer.mastercard.com/content/carbon-calculator/Images/tutorials/project_page.png)
17. Once your onboarding process is completed, you will be notified by email and will be able to make API calls in the sandbox environment.
18. Contact the [API Support](mailto:apisupport@mastercard.com) team or email at [carboncalculator@mastercard.com](mailto:carboncalculator@mastercard.com) with any questions or feedback.

Note:   

* **OAuth Key** - When you call our APIs you will need to include an OAuth1.0a Authentication header. You use the private part of this API Signing Key to generate this OAuth header, so that the Mastercard API server can authenticate your access to the APIs.
* **Consumer Key** - Consumer Key is associated with the API Signing Key and is required in the OAuth authorization header. Consumer keys are 97-character identifiers for client applications consuming Mastercard APIs. The consumer key appears in the OAuth1.0a authorization header sent with each request.
* **Encryption Key** - Mastercard will use the public part of this encryption key to encrypt request payloads containing payment card credentials. You will need the corresponding private part to decrypt these payloads.
* You are required to capture Keystore password and key alias shown on the screen. The keystore password is used in conjunction with the .p12 file and Client ID for OAuth authentication.

## Step 3: Integrate \& Make your first API call {#step-3-integrate--make-your-first-api-call}

### Generate your own API client {#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).

### Testing the service {#testing-the-service}

You can test our service using three different methods:

1. Using Postman: If you are using Postman, please follow our [Postman Tutorial](https://developer.mastercard.com/platform/tutorial/use-postman-for-mastercard-apis/)
2. Using Insomnia: If you are using Insomnia, please follow our [Insomnia Tutorial](https://developer.mastercard.com/platform/tutorial/use-insomnia-rest-client-for-mastercard-apis/)
3. Using our Reference Application: If you are using our reference application, please go to our [Reference Application](https://developer.mastercard.com/carbon-calculator/documentation/reference-app/index.md) page.

For more information on testing, see our [Integration and Testing](https://developer.mastercard.com/carbon-calculator/documentation/integration-and-testing/index.md) page.

### Make your First API Call {#make-your-first-api-call}

Once your sandbox credentials are ready, you can validate connectivity immediately. The example below calls the Transaction Footprints endpoint --- the most common starting point. Import below curl command into a tool like Insomnia to start testing.
Note: Authentication is handled via OAuth 1.0a. The curl below does not include the `Authorization` header --- use a tool like [Insomnia](https://insomnia.rest/) with the [Mastercard Insomnia Plugin](https://github.com/Mastercard/insomnia-plugin-mastercard-auth), refer [How to setup Insomnia](https://developer.mastercard.com/carbon-calculator/tutorial/api-testing/step1/index.md). For a full OAuth 1.0a signing guide, see [Using OAuth 1.0a to Access Mastercard APIs](https://developer.mastercard.com/platform/documentation/security-and-authentication/using-oauth-1a-to-access-mastercard-apis/).
* Bash

```bash
curl -X POST "https://sandbox.api.mastercard.com/carbon/transaction-footprints" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "transactionId": "fdc4626c-f51e-4ba6-9728-c79ac1d9aec8",
      "mcc": "3000",
      "cardBrand": "OTH",
      "amount": {
        "currencyCode": "USD",
        "value": 10.35
      }
    }
  ]'
```

**Expected 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"
    }
  }
]
```

Note: For a detailed step-by-step guide, see [Generating and Configuring a Mastercard API Client.](https://developer.mastercard.com/platform/documentation/generating-and-configuring-a-mastercard-api-client/)

## Step 4: Promote from Sandbox to Production {#step-4-promote-from-sandbox-to-production}

After successfully testing in the sandbox environment, you are ready to move your project to production. Follow below steps to move to production.

1. Click the **Request Production Access** button, in the Production section of the screen.
   ![Select API](https://static.developer.mastercard.com/content/carbon-calculator/Images/tutorials/request_production_access.png)

2. Provide the required **Service details** as explained in creating a sandbox project.

3. Enter a descriptive name for the key, which identifies its purpose and environment, in the **Key Alias** field.

4. Enter a password used to encrypt the keys that the customer will receive, in the **Keystore Password** field.
   ![Select API](https://static.developer.mastercard.com/content/carbon-calculator/Images/tutorials/production_keyalias.png)

5. Save your **key alias** and **keystore password** for future reference.

6. Proceed to generate your Additional Credentials (such as Mastercard Encryption keys and Client Encryption keys) by selecting **Update Project** .
   ![Select API](https://static.developer.mastercard.com/content/carbon-calculator/Images/tutorials/additional_credential.png)

7. Production keys are generated and your project updated. Confirm and download your Production keys.
   ![Select API](https://static.developer.mastercard.com/content/carbon-calculator/Images/tutorials/production_download_keys.png)

8. Once you complete this process, the Mastercard API Support Team will review and approve your request for production access.

9. You will receive an email from Mastercard Developers to your registered email address, depending upon the outcome of the review.

Note: Typically, it takes 3-5 working days to review and approve the Carbon Calculator APIs production access request. If you have not received a response after 5 working days, escalate by emailing [carboncalculator@mastercard.com](mailto:carboncalculator@mastercard.com) with the subject: `[ESCALATION] Production Access - <Your Project Name>`.

### API Consumer Onboarding {#api-consumer-onboarding}

* Using the production keys, you can validate [view service provider details](https://developer.mastercard.com/carbon-calculator/documentation/use-cases/service_provider_details/index.md) API by referring [Integration and testing](https://developer.mastercard.com/carbon-calculator/documentation/integration-and-testing/index.md) section to test authentication and validate your connectivity.
* In case of failure, email at [carboncalculator@mastercard.com](mailto:carboncalculator@mastercard.com).

### File Exchange Onboarding Process {#file-exchange-onboarding-process}

* This [tutorial](https://trc-techresource.mastercard.com/r/bundle/m_fxusg_en-us/page/d/en-US/pvd1747164178802.html) explains the steps to onboard customers on Next Generation File Transfer (NGFT)'s file exchange process.

## Next Steps {#next-steps}

Tip: **Onboarding path:** [API Basics](https://developer.mastercard.com/carbon-calculator/documentation/api-basics/index.md) → **Quick Start Guide (you are here)** → [Integration \& Testing](https://developer.mastercard.com/carbon-calculator/documentation/integration-and-testing/index.md) → [Use Cases](https://developer.mastercard.com/carbon-calculator/documentation/use-cases/index.md)  
**Next step →** [Integration and Testing](https://developer.mastercard.com/carbon-calculator/documentation/integration-and-testing/index.md) to validate your setup in the sandbox.  
**Ready to run calls?** Follow the [Sandbox Access](https://developer.mastercard.com/carbon-calculator/tutorial/sandbox-access/index.md) and [API Testing](https://developer.mastercard.com/carbon-calculator/tutorial/api-testing/index.md) tutorials.