# Generate payload for card registration in the Carbon Calculator program
source: https://developer.mastercard.com/mastercard-processing-mastercard/documentation/use-cases/gen-payload-card-registration-cc/index.md

## Overview {#overview}

The use case describes the process for a cardholder to register one or more cards in the Mastercard Carbon Calculator.

**Preconditions:**

* The issuer is de-scoped from the PCI DSS regulation (that is, the issuer operates as a PAN-less issuer).
* The issuer is onboarded to Mastercard Carbon Calculator and obtained the required API keys.
* The card has been issued through the Mastercard Processing Core APIs and stored in the Mastercard Processing Card Management System (CMS) with a corresponding `cardContractId` and `cardContractNumber` (PAN).

## Sequence diagram {#sequence-diagram}

Diagram gen-payload-card-registration-cc

### Explanation {#explanation}

1. The cardholder logs into the issuer mobile application or website and is presented with an option to receive insights about the carbon footprint of their transactions.   
   The cardholder provides consent to register and enable carbon footprint tracking.
2. The mobile application sends the registration request to the issuer server to enroll one or more cards in Carbon Calculator.
3. The issuer server sends the `POST` request to the Mastercard Processing - Mastercard Services API `/cards/searches` endpoint with the following properties:
   * `Client-Encryption-Key` header: contains the Client Encryption Key, which you generated when requesting access to the Mastercard Carbon Calculator API in Mastercard Developers.
   * `requestType` = `CARBON_CALCULATOR`: specifies for which Mastercard program the encrypted payload will be generated.
   * `carbonCalculatorProfiles`: array containing the following information for each card:
     * `id` required by the `/service-providers/payment-cards` Carbon Calculator API endpoint. Note: If the `id` is not provided in the request, Mastercard Processing - Mastercard Services API will set `id` = `cardContractId` inside the encrypted payload (step 5).
     * `Currency` required by the `/service-providers/payment-cards` Carbon Calculator API endpoint
     * `cardContractId`: It is the card contract identifier stored in the Mastercard Processing (MP) CMS that is generated and returned during the Mastercard Processing Core `createCardContract` API call. Note: A single request can contain up to 100 cards.
4. The Mastercard Processing - Mastercard Services API retrieves the PAN from the Mastercard Processing CMS for each `cardContractId` sent in step 3. Tip: Ensure that the card is active. Mastercard Processing does not verify the card status when retrieving the PAN from the CMS.
5. The Mastercard Processing - Mastercard Services API generates an encrypted payload using the `Client-Encryption-Key`. The payload includes:
   * All properties provided in the request (excluding `cardContractId`).
   * The `fpan` that is obtained in step 4. Tip: The Mastercard Processing - Mastercard Services API returns a JWE structure (`encryptedData`, `encryptedKey`, `publicKeyFingerprint`, `oaepHashingAlgorithm`, `iv`) that should be passed as-is (unchanged) to the Carbon Calculator API.
6. The Mastercard Processing - Mastercard Services API responds to the issuer server with HTTP status code `200` and the encrypted payload generated in step 5. Note: If multiple cards are included in the request and some are not found in the Mastercard Processing CMS, the API returns a `failedCards` object.  
   This object contains `cardContractId` that helps you to identify which cards are inside the generated encrypted payload.
7. The issuer server takes the encrypted `carbonCalculatorPayload` object received in step 6 and sends a `POST` request to the `/service-providers/payment-cards` endpoint of the Carbon Calculator API to register the cards.
8. The Carbon Calculator validates the request and returns a response containing:
   * `id`: The identifier echoed from the request.
   * `paymentCardId`: A unique identifier generated for the valid PAN. This ID is used in subsequent interactions with the Carbon Calculator (for example, during [transaction footprint notification](https://developer.mastercard.com/carbon-calculator/documentation/use-cases/txn_footprint_notification/) in step 11).
   * `bin`: The Bank Identification Number of the card.
   * `last4Fpan`: The last four digits of the fpan.
   * `status`: The registration status of the payment card.
   * `errorCode`: Returned if the provided fpan cannot be registered.
9. The cardholder makes a payment. The merchant sends the transaction authorization through the acquirer to the Mastercard Switch, where the transaction is successfully processed.
10. The Carbon Calculator receives the authorization transaction data in real time and calculates the carbon footprint of the transaction.
11. The Carbon Calculator sends the `POST` `/payments-cards/transaction-footprints/notifications` request to the issuer endpoint. The request includes the `paymentCardId`, transaction details, and the carbon emission value.
12. The issuer server forwards the transaction footprint information to the issuer mobile application.
13. The mobile application notifies the cardholder in near real time, either through a push notification or an in-app message, informing them about the carbon emissions of their transaction.  

Refer to [Sandbox testing](https://developer.mastercard.com/mastercard-processing-mastercard/documentation/testing/index.md) for more information on how to execute the use case in the Sandbox environment.

## Endpoints {#endpoints}

**Mastercard Carbon Calculator**

[POST /service-providers/payment-cards](https://developer.mastercard.com/carbon-calculator/documentation/api-reference/)  

[POST /payments-cards/transaction-footprints/notifications](https://developer.mastercard.com/carbon-calculator/documentation/api-reference/)

**Mastercard Processing - Mastercard Services**

API Reference: `POST /service-providers/payment-cards`