# Support
source: https://developer.mastercard.com/carbon-calculator/documentation/support/index.md

## FAQs {#faqs}

Browse the frequently asked questions by topic. Use the categories below to jump to the area you need.

### Getting Started {#getting-started}

The **Carbon Calculator** is the product offered by Mastercard to enable the issuer to help their environmentally conscious consumers understand how their spending behavior impacts carbon emissions. The **Carbon Calculator API** is the set of services that allows the issuer to do so.

For a full description of capabilities and integration options, see the [Overview](https://developer.mastercard.com/carbon-calculator/documentation/index.md).
There are two integration options available depending on how the payment transactions are processed for the payment cards issued by an issuer. You can choose either one of them or both depending upon your situation and need.

Following are these options:

* **Option 1** - Transactions processed by Mastercard.
  * This is the most advanced option which provides many out-of-the-box features. Using this option, an issuer will be able to provide more value to their consumers in less time as compared to Option 2.
* **Option 2.a** - Transactions not processed by Mastercard.
  * This option shall be used when an issuer wants to directly calculate transaction footprints based on consumer's payment transactions.
* **Option 2.b** - Transactions not processed by Mastercard (File based).
  * This option shall be used when an issuer wants to directly calculate transaction footprints using File based scoring for transactions not processed by Mastercard.

For more information, refer to the [homepage](https://developer.mastercard.com/carbon-calculator/documentation/index.md).
You can only try out or test the Carbon Calculator API in the Sandbox environment. To test the API, the following are the pre-requisites:

1. The issuer must have created a project for Carbon Calculator API.
2. The issuer must have been onboarded for Carbon Calculator API with a valid BIN range by Mastercard.
3. The issuer must have access to the Sandbox environment.

Once the above pre-requisites are met, make a `POST /transaction-footprints` request using your sandbox OAuth 1.0a credentials with a valid MCC and transaction amount. You should receive a `200 OK` response with `carbonEmissionInGrams` in the payload.

Refer to the [Quick Start Guide](https://developer.mastercard.com/carbon-calculator/documentation/quick-start-guide/index.md) for the complete step-by-step process including a copy-paste `curl` example.
Tip: To create your project on Mastercard Developers, refer to the [Before You Start](https://developer.mastercard.com/carbon-calculator/documentation/index.md#before-you-start) section for more information. Tip: To test the Carbon Calculator API via Insomnia, refer to the [Test API in Sandbox using Insomnia](https://developer.mastercard.com/carbon-calculator/tutorial/api-testing/index.md) tutorial. The API is free to use in the Sandbox environment with test data. Complete all integration testing in the Sandbox environment before moving to Production. When you are ready to go live, contact your Mastercard representative for Production pricing details.

Note that Mastercard Customer Implementation Services (CIS) may charge for creating a new implementation project. Contact your Mastercard representative for details, or email [carboncalculator@mastercard.com](mailto:carboncalculator@mastercard.com).
If you don't have a Mastercard representative, send a request to [carboncalculator@mastercard.com](mailto:carboncalculator@mastercard.com) for further help.

### Key Concepts {#key-concepts}

Transaction Footprint is a block of information that contains the following data after transaction scoring is done on a payment transaction:

1. Carbon emission (in grams and ounces)
2. Category information (main-category, sub-category, and sector)
Carbon Scoring (or Transaction Scoring) is the process of calculating Transaction Footprints for one or more payment transactions --- that is, determining the carbon emission and category information for each transaction. You can trigger scoring on demand via [Transaction Footprints Calculation](https://developer.mastercard.com/carbon-calculator/documentation/use-cases/txn_footprint_calculation/index.md), or have Mastercard score transactions automatically under Option 1. Merchant Category Code (MCC) is an assigned four-digit number that identifies a merchant's primary business based on annual sales volume. Customers must include a valid MCC in all transaction requests for successful carbon scoring. {#aiia-code}
Instead of relying only on MCC as the category identifier, the AiiA code provides additional mappings to the carbon calculator and supports new ways to categorize transactions and score them. For example, the customer can pass the AiiA Code instead of the MCC.

**Note:** AiiA is Mastercard's open banking acquisition and already has a defined set of categories for its products.

For more information, please reach out to your Mastercard representative. Alternatively, please send a request to [carboncalculator@mastercard.com](mailto:carboncalculator@mastercard.com) for further help.
Bank Identification Number (BIN) is the first 6-digit or 8-digit of the Primary Account Number (PAN), an industry standard that is used to identify the issuer during payment transaction routing. Near real-time means Carbon calculator notifies you as soon as a transaction is authorized and it has been scored. In practice, the transaction footprint is pushed to your registered notification endpoint moments after the transaction occurs.

To receive these notifications, implement the [Transaction Footprint Notification](https://developer.mastercard.com/carbon-calculator/documentation/use-cases/txn_footprint_notification/index.md) use case.
The MCC (Merchant Category Code) is the **primary** identifier used to categorize a transaction and calculate its carbon impact, so a valid four-digit MCC is required in most scoring requests.

However, it is not the only option. You can also pass an **AiiA code** as an alternative categorization, which provides additional mappings for scoring transactions. See the *"What is the AiiA code?"* entry above, or contact [carboncalculator@mastercard.com](mailto:carboncalculator@mastercard.com) for details.

### Authentication \& Environments {#authentication--environments}

The Carbon Calculator API uses **OAuth 1.0a** to authenticate your application. You manage your authentication keys from your [Developer Dashboard](https://developer.mastercard.com/dashboard) after creating a project with the Carbon Calculator API. Each request must be signed with the signing key generated for your project.

For a step-by-step explanation, see [API Basics -- Authentication](https://developer.mastercard.com/carbon-calculator/documentation/api-basics/index.md) and the [Using OAuth 1.0a to Access Mastercard APIs](https://developer.mastercard.com/platform/documentation/security-and-authentication/using-oauth-1a-to-access-mastercard-apis/) guide.
The Carbon Calculator API is available in two environments:

|               Environment                |                  Base URL                   |
|------------------------------------------|---------------------------------------------|
| Sandbox - MTF (Mastercard Test Facility) | `https://sandbox.api.mastercard.com/carbon` |
| Production                               | `https://api.mastercard.com/carbon`         |

Use the sandbox keys generated during project creation to test in Sandbox, and request approval to obtain Production keys when you are ready to go live. For more details, refer to [API Basics -- Environments](https://developer.mastercard.com/carbon-calculator/documentation/api-basics/index.md).
A `401 Unauthorized` response usually indicates an OAuth 1.0a signing problem. Check the following:

1. You are using the signing key that matches the environment you are calling (sandbox key for the Sandbox base URL, production key for the Production base URL).
2. Your `Authorization` header is generated for the exact request URL, HTTP method, and body being sent.
3. The consumer key and `.p12` signing key from your Developer Dashboard project have not expired or been rotated.

For signature generation help, use the Mastercard open-source [client authentication libraries](https://developer.mastercard.com/platform/documentation/security-and-authentication/using-oauth-1a-to-access-mastercard-apis/#client-libraries). For gateway-level `4xx` responses, see the [Gateway Error Codes](https://developer.mastercard.com/platform/documentation/security-and-authentication/gateway-error-codes/) guide.

### Integration \& Scoring {#integration--scoring}

The main difference between Mastercard automated scoring and Customer-provided transactions for scoring is that:

* **Option 1** - Mastercard automated scoring

  * Mastercard can be confident that the assigned MCC category corresponds to the transaction type based on the internal system validation.
* **Option 2** - Customer provide transactions for scoring

  * It relies on customers to assign the correct MCC to the transactions they supply for the Carbon Calculator system.
This functionality is available when integrating with:

* **Option 1** - Mastercard will perform the carbon impact of transactions as and when they occur, so customers must pull the transactions via the [Historical Transaction Footprint](https://developer.mastercard.com/carbon-calculator/documentation/use-cases/historical_txn_footprint/index.md) API.
* **Option 2** - It requires customers to provide the transactions that need to be scored, due to this the Carbon Calculator will not have any historical data to allow customers to retrieve the scores from.
If you already have PANs registered with your account, you are eligible to receive near real-time transaction footprint notifications for them.

You need to implement the `/payment-cards/transaction-footprints/notifications` endpoint.

For more details, refer to the [Transaction Footprint Notification](https://developer.mastercard.com/carbon-calculator/documentation/use-cases/txn_footprint_notification/index.md) use case.
Transaction amounts are submitted with a `currencyCode` expressed as a three-letter [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code (for example, `USD`, `EUR`, `GBP`). Make sure the `amount` and `currencyCode` you send are valid and consistent --- an invalid or unsupported currency will cause the transaction to be rejected during scoring. A `400 Bad Request` (or a scoring error) is typically caused by one of the transaction details being invalid. Check that:

1. The **MCC** is a valid four-digit merchant category code.
2. The **amount** is present and in a valid numeric format.
3. The **currencyCode** is a valid ISO 4217 code.

Every error follows a consistent structure with a `reasonCode`, `description`, and `details` message describing the problem --- for example, `INVALID_TRANSACTION_RECORD_ERROR` or `TRANSACTION_SCORING_ERROR`. For the full list of error codes, resolutions, and the error response format, see [Code and Formats](https://developer.mastercard.com/carbon-calculator/documentation/code-and-formats/index.md).

### Payment Card Management {#payment-card-management}

In the [Add Payment Cards](https://developer.mastercard.com/carbon-calculator/documentation/use-cases/add_payment_card_single_and_bulk/index.md) service, the Carbon Calculator application validates if a requested PAN is already registered for the requesting issuer or not. If the PAN is found to be registered, then the Carbon Calculator will respond with the paymentCardId of the same card along with its status as ACTIVE. During issuer onboarding on Carbon Calculator application by Mastercard, we make sure that only valid BINs are assigned to the issuer. These BINs are assigned only after receiving consent from the issuer.

Now when the issuer invokes the [Add Payment Cards](https://developer.mastercard.com/carbon-calculator/documentation/use-cases/add_payment_card_single_and_bulk/index.md) service, the Carbon Calculator application validates the requested PAN for a valid BIN assigned to the requesting issuer. If the PAN is found to be invalid, then the request is rejected. Otherwise, PAN is allowed to be registered for the issuer.
Call `DELETE /service-providers/payment-cards/{paymentCardId}` using the `paymentCardId` obtained when the card was registered. On success, the card status changes to `DELETED` and all future transaction scoring requests for that PAN will be ignored.

For full request/response details, refer to the [Delete Payment Card](https://developer.mastercard.com/carbon-calculator/documentation/use-cases/delete_payment_cards/index.md) use case.

### Data \& Security {#data--security}

Mastercard takes utmost care while handling sensitive and private consumer data, and the same care has been taken for the Carbon Calculator API implementation.

* **Transport security** --- all traffic is secured using TLS/SSL.
* **Payload encryption** --- endpoints that carry payment-card credentials or PII (such as Add Payment Cards) require request-payload encryption using the Mastercard-provided certificate.
* **Compliance** --- the Carbon Calculator API is [PCI DSS certified](https://www.pcisecuritystandards.org/).

For the authentication, transport, and encryption setup details, see [API Basics](https://developer.mastercard.com/carbon-calculator/documentation/api-basics/index.md).

## Get Help {#get-help}

### Contact us for technical support. {#contact-us-for-technical-support}