# Carbon Calculator
source: https://developer.mastercard.com/carbon-calculator/documentation/index.md

## Overview {#overview}

The Carbon Calculator API enables issuers to provide their consumers with visibility into the environmental impact based on their spending.

This API allows the issuer to calculate the carbon footprint based on consumers' payment transactions using their Mastercard cards. This API can be used inside a banking application or website to provide meaningful and actionable insights.

#### Key Features {#key-features}

* [Payment card registration](https://developer.mastercard.com/carbon-calculator/documentation/use-cases/add_payment_card_single_and_bulk/index.md) to register a consumer's payment cards with the Carbon Calculator API.
* [Payment card deletion](https://developer.mastercard.com/carbon-calculator/documentation/use-cases/delete_payment_cards/index.md) to delete the registered consumer's payment card.
* Receiving near real-time [transaction footprint notification](https://developer.mastercard.com/carbon-calculator/documentation/use-cases/txn_footprint_notification/index.md) for registered payment cards.
* Access to [historical](https://developer.mastercard.com/carbon-calculator/documentation/use-cases/historical_txn_footprint/index.md) and [aggregate](https://developer.mastercard.com/carbon-calculator/documentation/use-cases/aggregate_txn_footprint/index.md) transaction footprints notification for registered payment cards.
* [Transaction footprint calculations](https://developer.mastercard.com/carbon-calculator/documentation/use-cases/txn_footprint_calculation/index.md) based on payment transactions.
* [Payment card registration (to be deprecated)](https://developer.mastercard.com/carbon-calculator/documentation/use-cases/add_payment_card/index.md) to register a consumer's payment card with the Carbon Calculator API.
* [Payment cards deletion (to be deprecated)](https://developer.mastercard.com/carbon-calculator/documentation/use-cases/delete_payment_cards_deprecated/index.md) to delete the registered consumer's payment cards.
* [Payment cards - Profiles](https://developer.mastercard.com/carbon-calculator/documentation/use-cases/payment_cards_profiles/index.md) to store climate profile of the user with payment card.
* [Engagement Services - Surveys](https://developer.mastercard.com/carbon-calculator/documentation/use-cases/engagement-services/surveys/index.md) return a SurveyJS (<https://surveyjs.io/survey-creator>) compatible onboarding survey with questions to capture consumers' lifestyle choices and refine a climate profile.
* [Engagement Services - Profiles](https://developer.mastercard.com/carbon-calculator/documentation/use-cases/engagement-services/profiles/index.md) to generate climate profiles based on survey answers and enable profile-based transaction scoring.
* [Engagement Services - Insights](https://developer.mastercard.com/carbon-calculator/documentation/use-cases/engagement-services/insights/index.md) to get insights for reducing carbon footprint based on consumers' climate profile.
* [Engagement Services - Personas](https://developer.mastercard.com/carbon-calculator/documentation/use-cases/engagement-services/personas/index.md) returns a list of personas, and one of them is assigned to the profile during profile creation.
* [Engagement Services - Benchmarks](https://developer.mastercard.com/carbon-calculator/documentation/use-cases/engagement-services/benchmarks/index.md) to get the country-based consumption figures based on the given country.
* [Engagement Services - Comparisons](https://developer.mastercard.com/carbon-calculator/documentation/use-cases/engagement-services/comparisons/index.md) fetches comparisons data by comparing tonnes of Co2 with any day to day life examples.

<br />

### Quickstart {#quickstart}

Get up and running with the service in less than 20 minutes

[Launch](https://developer.mastercard.com/carbon-calculator/documentation/quick-start-guide/index.md)

### Reference app {#reference-app}

Utilize the Spring Boot Application that shows simple usage of the API

[Learn more](https://developer.mastercard.com/carbon-calculator/documentation/reference-app/index.md)

### Experience Design Guide {#experience-design-guide}

Access the full product journeys including white label Figma flows

[Learn more](https://developer.mastercard.com/carbon-calculator/documentation/experience-design-guide/index.md)

## How It Works {#how-it-works}

There are two integration options depending on how payment transactions are processed for the payment cards issued by the issuer. You can choose either one or both options as required.

* **Option 1** - Transactions processed by Mastercard.
* **Option 2.a** - Transactions not processed by Mastercard (through API)
* **Option 2.b** - Transactions not processed by Mastercard (through File Transfer)

<br />

Let's understand these options in detail.

### Option 1 {#option-1}

This is the most advanced option, which provides out-of-the-box features. Using this option, the issuer provides more value to their consumers in minimal time as compared to [Option 2.a](https://developer.mastercard.com/carbon-calculator/documentation/index.md#option-2-a).

This option requires the issuer to register their consumers' PAN with the Carbon Calculator API. After successful registration, Mastercard does the following:

* Notifies the issuer of a transaction footprint for near real-time transactions.
* Calculates the transaction footprint for past payment transactions.

<br />

The following diagram shows a high-level data flow between the issuer, consumer, and Mastercard for the carbon calculation. ![Integration Option 1](https://static.developer.mastercard.com/content/carbon-calculator/Images/landingpage/Option_24.png)

**Workflow**:

1. Consumers initiate the registration process through the issuer's application or website.
2. The issuer onboards the consumers by registering their PAN [registering the consumers' PAN](https://developer.mastercard.com/carbon-calculator/documentation/use-cases/add_payment_card/index.md) with the Carbon Calculator API.
3. The Carbon Calculator API receives real-time authorization and clears transactions for carbon scoring.
4. The API notifies the issuer of the [transaction footprint in the near real-time](https://developer.mastercard.com/carbon-calculator/documentation/use-cases/txn_footprint_notification/index.md).
5. The issuer presents the near real-time carbon score with actionable insights to their consumers.
6. The issuer can get the transaction score by calling [historical](https://developer.mastercard.com/carbon-calculator/documentation/use-cases/historical_txn_footprint/index.md) and [aggregate](https://developer.mastercard.com/carbon-calculator/documentation/use-cases/aggregate_txn_footprint/index.md) transaction footprints from the Carbon Calculator API.
7. The issuer presents the historical and aggregate transaction footprints to their consumers.
8. Consumers view their historical and aggregate transaction footprints on the issuer application.

### Option 2.a {#option-2a}

This option is used when the issuer wants to directly calculate transaction footprints based on consumers' payment transactions using the Carbon Calculator APIs for instant scoring.

The following diagram shows a high-level flow between the issuer, consumers, and Mastercard for the carbon calculation.
![Integration Option 2](https://static.developer.mastercard.com/content/carbon-calculator/Images/landingpage/Option_21.png)

**Workflow**:

1. The issuer collects consumers' payment transactions and sends them to the Carbon Calculator API for [carbon scoring calculation](https://developer.mastercard.com/carbon-calculator/documentation/use-cases/txn_footprint_calculation/index.md).
2. The API calculates the carbon score and sends it back to the issuer.
3. The issuer processes the carbon scores into meaningful data.
4. The issuer presents the carbon score with actionable insights to their consumers.

### Option 2.b {#option-2b}

This option is used when an issuer wants to directly calculate transaction footprints based on consumers' payment transactions using the Mastercard File Exchange for batch scoring of transactions.

The following diagram shows a high-level flow between the issuer, consumers, and Mastercard for the carbon calculation.
![Integration Option 3](https://static.developer.mastercard.com/content/carbon-calculator/Images/landingpage/Option_22.png)

**Workflow**:

1. The issuer collects the consumer's payment transactions and uploads them in a raw CSV file through the Mastercard File Exchange Process for [file based scoring](https://developer.mastercard.com/carbon-calculator/documentation/use-cases/file_based_scoring/index.md).
2. The issuer can upload up to a max of **15 CSV files with every 1,00,000 transactions** in one day for calculating carbon score in bulk.
3. The Carbon Calculator API downloads the file from the File Exchange to calculate the carbon score.
4. The Carbon Calculator API uploads scored CSV files to File Exchange.
5. The issuer can download the file from File Exchange.

## Before You Start {#before-you-start}

Note: Following are the mandatory values you need to provide at the time of project creation in the sandbox.

#### If you want to opt for option 1: {#if-you-want-to-opt-for-option-1}

* Customer ID (CID) - Make sure to use a **valid Customer ID** assigned by Mastercard, which remains the same across all Mastercard systems.
* BIN Range
* Legal Name

#### If you want to opt for option 2.a: {#if-you-want-to-opt-for-option-2a}

* Customer ID (CID) - Make sure to use a **valid Customer ID** assigned by Mastercard, which remains the same across all Mastercard systems.
* Legal Name

#### If you want to opt for option 2.b: {#if-you-want-to-opt-for-option-2b}

* Customer ID (CID) - Make sure to use a **valid Customer ID** assigned by Mastercard, which remains the same across all Mastercard systems.
* Legal Name
* SenderId - Customer logical name or logical address of the service provider which has been configured in [Mastercard File Exchange Onboarding Guide](https://trc-techresource.mastercard.com/r/bundle/m_fxusg_en-us/page/d/en-US/pvd1747164178802.html).

To start using the Carbon Calculator API, you must first create a project and then add the API to it. Follow these steps to [create a Sandbox Project](https://developer.mastercard.com/carbon-calculator/tutorial/sandbox-access/index.md) in Tutorials. Once access is granted, by using the [view service provider details](https://developer.mastercard.com/carbon-calculator/documentation/use-cases/service_provider_details/index.md) API in the Sandbox environment, you can test authentication and validate your connectivity. You should also do end-to-end integration testing based on your integration model in this environment before moving to Production. Follow these steps for [integration and testing](https://developer.mastercard.com/carbon-calculator/tutorial/api-testing/index.md) in the tutorials to test the API.

Once you are ready to go live, follow these steps to [request your Production access](https://developer.mastercard.com/carbon-calculator/tutorial/production-access/index.md). A contractual agreement needs to be signed before your production access is approved, and you can access the APIs.
Tip: If you don't have a Mastercard representative, send a request to [carboncalculator@mastercard.com](mailto:carboncalculator@mastercard.com) for further help.

## Good to Know {#good-to-know}

* For information regarding how each API works, refer to the [Use Cases](https://developer.mastercard.com/carbon-calculator/documentation/use-cases/index.md) section.
* When you are ready to use the APIs, refer to the [API Basics](https://developer.mastercard.com/carbon-calculator/documentation/api-basics/index.md) page for API authentication, encryption, and environment details.
* To understand the request and response formats of the APIs, their models, and examples, refer to the [API Reference](https://developer.mastercard.com/carbon-calculator/documentation/api-reference/index.md) section.

## Next Steps {#next-steps}

To get started, a [Reference Application](https://developer.mastercard.com/carbon-calculator/documentation/reference-app/index.md) is created. However, if you want to build your application, refer to the [Quick Start Guide](https://developer.mastercard.com/carbon-calculator/documentation/quick-start-guide/index.md) section.