Mastercard Carbon Calculator API

openapi: 3.0.3
info:
  title: Mastercard Carbon Calculator API
  description: >-
    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.
  contact:
    name: API Support
    email: [email protected]
    url: https://developer.mastercard.com/support
  version: 1.2.0
externalDocs:
  description: ISO 4217 - Currency Code
  url: https://en.wikipedia.org/wiki/ISO_4217
servers:
  - url: https://sandbox.api.mastercard.com/carbon
    description: Sandbox
  - url: https://api.mastercard.com/carbon
    description: Production
tags:
  - name: Service Provider
    description: APIs for getting and/or updating issuer onboarding details.
  - name: Payment Card
    description: >-
      APIs for payment cards onboarding and retrieving the transaction
      footprints of those cards.
  - name: Environmental Impact
    description: >-
      APIs for calculating carbon emission based on provided payment
      transactions.
  - name: Supported Parameters
    description: APIs for fetching the supported merchants and currencies by the system.
  - name: Engagement Services
    description: >-
      The engagement services use a Climate Profile that enables the users to
      get personalized content based on their lifestyle, knowledge and
      motivation.
paths:
  /service-providers:
    get:
      tags:
        - Service
        - Providers
      summary: Fetches an existing Service Provider
      description: >-
        Allows a registered Service Provider to fetch its information from the
        server.
      operationId: GetServiceProviderById
      responses:
        '200':
          $ref: '#/components/responses/ServiceProvider'
        '404':
          $ref: '#/components/responses/ServiceProviderNotFoundError'
    put:
      tags:
        - Service
        - Providers
      summary: Updates an existing Service Provider details
      description: >-
        Allows a registered Service Provider to update its configuration on the
        server. A Service Provider should call this API first after the
        successful creation of the project on Mastercard Developers before they
        call other APIs.
      operationId: UpdateServiceProvider
      requestBody:
        $ref: '#/components/requestBodies/ServiceProviderConfig'
      responses:
        '200':
          $ref: '#/components/responses/ServiceProvider'
        '400':
          $ref: '#/components/responses/ServiceProviderBadRequestError'
        '404':
          $ref: '#/components/responses/ServiceProviderNotFoundError'
        '415':
          $ref: '#/components/responses/ServiceProviderUnsupportedMediaTypeError'
  /service-providers/payment-cards:
    post:
      tags:
        - Service
        - Providers
        - Payments
        - Payment  Card
      summary: Bulk Registration of Payment Cards
      description: >-
        Allows a registered service provider to add a list of new payment cards
        to its profile.This endpoint uses [Mastercard payload
        encryption](https://mstr.cd/2UPfda0). Refer to the [Payload
        Encryption](https://developer.mastercard.com/carbon-calculator/documentation/tutorials-and-guides/payload-encryption/)
        page for implementation details.
      operationId: BulkRegisterPaymentCards
      x-mastercard-api-encrypted: true
      requestBody:
        $ref: '#/components/requestBodies/PaymentCards'
      responses:
        '200':
          $ref: '#/components/responses/PaymentCardEnrolments'
        '400':
          $ref: '#/components/responses/PaymentCardEnrolmentsBadRequestError'
        '404':
          $ref: '#/components/responses/ServiceProviderNotFoundError'
  /service-providers/payment-cards/{payment_card_id}:
    delete:
      tags:
        - Service
        - Providers
        - Payments
        - Card
      summary: Delete a Payment Card
      description: >-
        Allows a registered Service Provider to delete single Payment Card at a
        time from its profile. Any data associated with a requested
        paymentCardId will also be deleted permanently.


        On the successful response from the server, a Service Provider should
        remove all the requested paymentCardIds from the system.


        Once a request has been received from a Service Provider, data deletion
        will happen immediately.
      operationId: PaymentCardDeletion
      parameters:
        - $ref: '#/components/parameters/PaymentCardId'
      responses:
        '202':
          $ref: '#/components/responses/Accepted'
        '400':
          $ref: '#/components/responses/PaymentCardDeletionsBadRequestError'
        '404':
          $ref: '#/components/responses/PaymentCardByIdNotFoundError'
  /payment-cards/{payment_card_id}/transaction-footprints:
    get:
      tags:
        - Payments
        - Card
        - Transaction
        - Payment  Card
      summary: Fetches Historical Transactions and its Transaction Footprints
      description: >-
        Allows a Service Provider to fetch historical transactions for a payment
        card. Note that a maximum of one year of transactions can be retrieved
        using this API. Also, the payment card has to be registered first using
        /payment-cards service.
      operationId: GetPaymentCardTransactionHistory
      parameters:
        - $ref: '#/components/parameters/PaymentCardId'
        - $ref: '#/components/parameters/FromDate'
        - $ref: '#/components/parameters/ToDate'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          $ref: '#/components/responses/HistoricalTransactionFootprints'
        '400':
          $ref: '#/components/responses/TransactionHistoryBadRequestError'
        '404':
          $ref: '#/components/responses/ServiceProviderNotFoundError'
  /payment-cards/transaction-footprints/aggregates:
    post:
      tags:
        - Payments
        - Transaction
        - Aggregates
      summary: >-
        Fetches carbon score for payment cards and aggregates the same on a
        weekly and monthly basis. The result will be in descending order.
      description: >
        Allows a Service Provider to fetch aggregate carbon score for a single
        or multiple payment cards. A payment card has to be registered first
        using /service-providers/payment-cards endpoint before this endpoint can
        be called. The aggregate can be requested weekly, or monthly. Note that
        **ONLY** cleared transactions will be returned.


        If any of the paymentCardIds is not valid or not registered, then the
        entire request will be rejected, and no aggregate will be returned.


        If no transaction is found for a particular paymentCardId then the
        response will have an empty list against that paymentCardId.


        The date range is valid for 26 weeks for weekly aggregate and 12 months
        for monthly aggregate.
      operationId: GetPaymentCardAggregateTransactions
      requestBody:
        $ref: '#/components/requestBodies/AggregateSearchCriteria'
      responses:
        '200':
          $ref: '#/components/responses/AggregateTransactionFootprints'
        '400':
          $ref: '#/components/responses/AggregateTransactionBadRequestError'
        '404':
          $ref: '#/components/responses/ServiceProviderNotFoundError'
        '415':
          $ref: '#/components/responses/ServiceProviderUnsupportedMediaTypeError'
  /payment-cards:
    post:
      tags:
        - Payments
        - Payment  Card
      summary: Register a Payment Card (to be deprecated)
      description: >-
        Allows a registered Service Provider to add a new Payment Card to its
        profile. This endpoint uses [Mastercard payload
        encryption](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/#mastercard-encryption).
        Refer to the [Payload
        Encryption](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/)
        section for implementation details.
      operationId: RegisterPaymentCard
      x-mastercard-api-encrypted: true
      requestBody:
        $ref: '#/components/requestBodies/PaymentCard'
      responses:
        '200':
          $ref: '#/components/responses/PaymentCardReference'
        '400':
          $ref: '#/components/responses/RegisterPaymentCardBadRequestError'
        '404':
          $ref: '#/components/responses/ServiceProviderNotFoundError'
        '415':
          $ref: '#/components/responses/ServiceProviderUnsupportedMediaTypeError'
  /payment-card-enrolments:
    post:
      tags:
        - Payments
        - Card
        - Payment  Card
      summary: Batch Registration of Payment Cards (to be deprecated)
      description: >-
        Allows a registered Service Provider to add a list of new Payment Cards
        **(at most maximum of 100 payment cards)** to its profile. This endpoint
        uses [Mastercard payload
        encryption](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/#mastercard-encryption).
        Refer to the [Payload
        Encryption](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/)
        section for implementation details.
      operationId: BatchRegisterPaymentCards
      x-mastercard-api-encrypted: true
      requestBody:
        $ref: '#/components/requestBodies/PaymentCards'
      responses:
        '200':
          $ref: '#/components/responses/PaymentCardEnrolments'
        '400':
          $ref: '#/components/responses/PaymentCardEnrolmentsBadRequestError'
        '404':
          $ref: '#/components/responses/ServiceProviderNotFoundError'
        '415':
          $ref: '#/components/responses/ServiceProviderUnsupportedMediaTypeError'
  /payment-card-deletions:
    post:
      tags:
        - Payments
        - Card
        - Deletions
      summary: Delete one or more Payment Cards (to be deprecated)
      description: >
        Allows a registered Service Provider to delete one or more Payment Cards
        from its profile. Any data associated with a requested paymentCardId
        will also be deleted permanently.


        On the successful response from the server, a Service Provider should
        remove all the requested paymentCardIds from the system.


        Once a request has been received from a Service Provider, data deletion
        will happen immediately.
      operationId: PaymentCardDeletions
      requestBody:
        $ref: '#/components/requestBodies/PaymentCardIds'
      responses:
        '202':
          $ref: '#/components/responses/Accepted'
        '400':
          $ref: '#/components/responses/PaymentCardDeletionsBadRequestError'
        '404':
          $ref: '#/components/responses/PaymentCardDeletionsNotFoundError'
        '415':
          $ref: '#/components/responses/ServiceProviderUnsupportedMediaTypeError'
  /transaction-footprints:
    post:
      tags:
        - Transaction
        - Environmental  Impact
      summary: Calculate Transaction Footprints
      description: >-
        Calculates carbon emission based on the payment transaction amount, the
        merchant category code and the AIIA code. You can send **one or more
        transactions** together to get the transaction footprints. <br> Below is
        the approach to deliver **MCC** or **AIIA** based scoring. <li><b>If
        only `mcc` field provided in the request with required fields :</b> MCC
        based scoring will be delivered.</li>
         <li><b>If `type` and `additionalInformation` field provided in the request with required fields :</b> AIIA based scoring will be delivered.</li>
      operationId: FootprintsByTransactionData
      requestBody:
        $ref: '#/components/requestBodies/Transactions'
      responses:
        '200':
          $ref: '#/components/responses/TransactionFootprintsData'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '415':
          $ref: '#/components/responses/UnsupportedMediaTypeError'
  /supported-currencies:
    get:
      tags:
        - Currencies
      summary: Provide Supported Currencies
      description: >-
        Provides the list of currencies supported by the application. While
        sending a transaction amount in the Amount object, 'currencyCode' should
        be from one of the supported currencies. It is recommended to cache this
        list and use it for checking before sending transactions for footprint
        calculation. Generally this list doesn't change that often, but it is
        recommended to refresh this data every 24-hours.
      operationId: GetSupportedCurrencies
      responses:
        '200':
          $ref: '#/components/responses/SupportedCurrencies'
  /supported-merchant-categories:
    get:
      tags:
        - Merchants
        - Categories
      summary: Provide Supported MCCs
      description: >-
        Provides a list of merchant category codes supported by the application.
        While sending transaction data in the Transaction object, 'mcc' should
        be from one of the supported merchant categories. It is recommended to
        cache this list and use it for checking before sending transactions for
        footprint calculation. Generally this list doesn't change that often,
        but it is recommended to refresh this data every 24-hours.
      operationId: GetSupportedMerchantCategories
      responses:
        '200':
          $ref: '#/components/responses/SupportedMerchantCategories'
  /surveys:
    get:
      tags:
        - Surveys
      summary: A survey that can be answered by the user.
      description: >-
        The Survey API offers essential features for seamless onboarding onto
        the Engagement Services platform, enabling integration with diverse
        surveys designed to fine-tune a climate profile. In response, the API
        furnishes a comprehensive set of survey questions, inviting user input
        to gather valuable insights and data.
      operationId: getSurvey
      responses:
        '200':
          $ref: '#/components/responses/Survey'
        '404':
          $ref: '#/components/responses/ServiceProviderNotFoundError'
  /profiles:
    put:
      operationId: updateUserProfile
      description: >-
        The Profile Service employs a sophisticated algorithm to compute a
        detailed climate profile, drawing upon the responses gathered through a
        survey obtained from the Surveys Service. This process involves a
        meticulous analysis of user-provided answers to generate a comprehensive
        and nuanced representation of their climate preferences and
        perspectives. See (https://surveyjs.io/survey-creator)
      summary: >-
        Calculates a climate profile based on the answers from a survey obtained
        from the Surveys Service.
      tags:
        - Profiles
      requestBody:
        $ref: '#/components/requestBodies/ProfileRequest'
      responses:
        '200':
          $ref: '#/components/responses/Profile'
        '400':
          $ref: '#/components/responses/ProfilePayloadBadRequestError'
        '404':
          $ref: '#/components/responses/ServiceProviderNotFoundError'
  /insights:
    put:
      operationId: updateUserInsights
      description: >-
        The Insights service delivers insights and other suggestions that can
        inform you about what you can do to reduce your footprint.
      summary: Get insights based on the contents of your climate profile.
      tags:
        - Insights
      parameters:
        - $ref: '#/components/parameters/Branding'
        - $ref: '#/components/parameters/Heading'
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Version'
        - $ref: '#/components/parameters/Language'
      requestBody:
        $ref: '#/components/requestBodies/InsightsRequest'
      responses:
        '200':
          $ref: '#/components/responses/Insights'
        '400':
          $ref: '#/components/responses/MissingInsightAttributesBadRequestError'
        '404':
          $ref: '#/components/responses/ServiceProviderNotFoundError'
  /insights/{id}:
    put:
      operationId: getInsightsById
      description: >-
        Fetches a given Insight and marks it as viewed in your profile. Issuer
        has to save the profile locally and send it in future communication with
        Engagement Services
      summary: Fetches an Insight details based on provided Insight id
      tags:
        - Insights
      parameters:
        - $ref: '#/components/parameters/Branding'
        - $ref: '#/components/parameters/Language'
        - $ref: '#/components/parameters/Version'
        - $ref: '#/components/parameters/InsightsId'
      requestBody:
        $ref: '#/components/requestBodies/InsightsByIdRequest'
      responses:
        '200':
          $ref: '#/components/responses/InsightsByIdResponse'
        '400':
          $ref: '#/components/responses/MissingInsightAttributesBadRequestError'
        '404':
          $ref: '#/components/responses/InsightNotFoundError'
  /benchmarks:
    get:
      operationId: getBenchmarksForCountry
      description: >-
        Returns a benchmark for a specific country for the year 2020, monthly or
        yearly
      summary: Get benchmarks for a specific country, monthly or yearly
      tags:
        - Benchmarks
      parameters:
        - $ref: '#/components/parameters/Period'
        - $ref: '#/components/parameters/CountryCode'
      responses:
        '200':
          $ref: '#/components/responses/Benchmarks'
        '400':
          $ref: '#/components/responses/BenchmarkBadRequestError'
        '404':
          $ref: '#/components/responses/BenchmarkNotFoundError'
components:
  headers:
    Location:
      description: The URL to check on status of resource
      schema:
        type: string
    X-MC-Correlation-ID:
      description: >-
        This id is unique per request and is used to co-relate a request to its
        response. Customers must share this id while raising any incident for
        this API.
      schema:
        $ref: '#/components/schemas/X-MC-Correlation-ID'
  schemas:
    Surveys:
      type: object
      properties:
        surveysPayload:
          $ref: '#/components/schemas/SurveyData'
    Profile:
      type: object
      properties:
        profile:
          $ref: '#/components/schemas/ClimateProfile'
      required:
        - profileResponsePayload
    X-MC-Correlation-ID:
      type: string
      example: X-MC-Correlation-ID:5e4b7f904d2820f688c67ef9fc0035
    PaymentCardEnrolments:
      title: PaymentCardEnrolments
      type: array
      minItems: 1
      maxItems: 500
      description: >-
        List of payment card enrolments corresponding to each of the payment
        cards. This information should be used to identify the success and
        failure enrolments and take appropriate next steps.
      items:
        $ref: '#/components/schemas/PaymentCardEnrolment'
    PaymentCardEnrolment:
      title: PaymentCardEnrolment
      type: object
      description: The response object which contains Payment Card information.
      properties:
        paymentCardId:
          $ref: '#/components/schemas/PaymentCardId'
        bin:
          type: string
          minLength: 4
          maxLength: 8
          pattern: ^\d{4,8}
          description: >-
            First 4 to 8 digits of BIN will be present in response only in case
            of success already exists card and if valid supported FPAN bin
            range.
          example: '545502'
        last4fpan:
          type: string
          minLength: 4
          maxLength: 4
          pattern: ^\d{4}
          description: >-
            Last 4 digits of a payment card number will be present only if the
            card number in the request is valid.
          example: '8351'
        status:
          type: string
          minLength: 6
          maxLength: 7
          description: >-
            Status of a Payment Card on the server. Possible values are ACTIVE &
            PENDING. The cards that are in PENDING state will move to ACTIVE
            state in background as soon as their enrolment is complete. The
            paymentCardId will remain same.
          example: ACTIVE
        errorCode:
          title: errorCode
          type: string
          minLength: 10
          maxLength: 30
          example: INVALID_FPAN
          description: >-
            Error code in case of registration failed. Possible values are,

            * INVALID_FPAN = The card number in the request is either invalid or
            does not match with your currently supported account range. Try
            again with a valid card number or update the supported account
            range.

            * INVALID_CARD_BASE_CURRENCY = The card base currency in the request
            is either invalid or does not match with your currently supported
            card base currency range. Try again with a valid card base currency.

            * UNSUPPORTED_CURRENCY = The currency in the request is not
            supported, try again with a different one.
    CurrencyCode:
      type: string
      description: Currency code as per ISO 4217
      minLength: 3
      maxLength: 3
      pattern: ^[A-Za-z]{3}$
    TransactionId:
      type: string
      description: >-
        A unique ID associated with a payment transaction, For example, original
        payment transaction ID. The same ID will be returned in the response
        corresponding to its payment transaction.
      minLength: 1
      maxLength: 100
      pattern: ^[\w\-\_]{1,100}
    Transactions:
      title: Transactions
      type: array
      description: >-
        List of payment transactions from API consumer for calculating
        transaction footprint.
      minItems: 1
      maxItems: 5000
      items:
        $ref: '#/components/schemas/TransactionData'
      example:
        - transactionId: ee421c25-f928-4bf6-b884-3600b76b860d
          mcc: 3997
          cardBrand: OTH
          amount:
            currencyCode: USD
            value: 123
          profile:
            traits:
              knowledge: 0.65
              lifestyle: 0.445
              motivated: 0.683
            userAttributes:
              demo: 66
              diet: 256
              lifestyle: 4
              energy: 12288
              transport: 36933
              country: AX
            created: '2024-01-31T10:57:36.161Z'
            surveys:
              key1:
                key2: 1
                key3: 2
            persona: '3'
            benchmarks:
              key1:
                key2: 1
                key3: 2
            comparisons:
              key1:
                key2: 1
                key3: 2
            insights:
              key1:
                key2: 1
                key3: 2
            version: '1.0'
        - transactionId: fdc4626c-f51e-4ba6-9728-c79ac1d9aec8
          mcc: 3000
          cardBrand: OTH
          amount:
            currencyCode: USD
            value: 10.35
        - transactionId: 0218BC0251FEB8F8E063C6979E0AE0DD
          mcc: 1234
          cardBrand: OTH
          amount:
            currencyCode: USD
            value: 123
        - transactionId: odc4626c-f51e-4ba6-9728-c79ac1d9aec9
          mcc: 3997
          type: AIIA
          amount:
            value: 100
            currencyCode: USD
          cardBrand: OTH
          additionalInformation:
            - key: aiiaCode
              value: '101'
    TransactionData:
      title: TransactionData
      type: object
      description: >-
        Object which holds information about payment transaction for carbon
        scoring and other properties.
      allOf:
        - $ref: '#/components/schemas/Transaction'
    Transaction:
      title: Transaction
      type: object
      description: A single payment transaction for carbon scoring.
      required:
        - transactionId
        - amount
      properties:
        transactionId:
          $ref: '#/components/schemas/TransactionId'
        type:
          $ref: '#/components/schemas/Type'
        mcc:
          type: string
          description: >-
            Merchant category code of a payment transaction that uniquely
            defines a merchant business.
          minLength: 1
          maxLength: 4
          pattern: ^\d{1,4}
          example: '3997'
        amount:
          $ref: '#/components/schemas/Amount'
        profile:
          $ref: '#/components/schemas/ClimateProfile'
        additionalInformation:
          type: array
          items:
            $ref: '#/components/schemas/AdditionalInformation'
    CardBrand:
      title: CardBrand
      type: string
      minLength: 1
      maxLength: 3
      pattern: ^(MA|OTH|NC)$
      example: MA
      description: >-
        Brand type of the payment card through which transaction done. Possible
        values are,

        * MA = Mastercard branded payment card.

        * OTH = Payment card brand other than Mastercard.

        * NC = Non card based transaction.
    Amount:
      title: Amount
      type: object
      description: The value and the currency of a payment transaction.
      required:
        - currencyCode
        - value
      properties:
        value:
          type: number
          description: Actual amount of a payment transaction
          maximum: 1000000000
          exclusiveMaximum: false
          minimum: -1000000000
          exclusiveMinimum: false
          example: 100
        currencyCode:
          $ref: '#/components/schemas/CurrencyCode'
    TransactionFootprintsData:
      title: TransactionFootprintsData
      type: array
      description: >-
        List of transaction footprints corresponding to each transaction in
        Transactions request.
      minItems: 1
      maxItems: 5000
      items:
        $ref: '#/components/schemas/TransactionFootprintData'
    TransactionFootprintData:
      title: TransactionFootprintData
      type: object
      description: >-
        A single transaction footprint calculated for a corresponding
        transaction.
      allOf:
        - $ref: '#/components/schemas/TransactionFootprint'
      properties:
        cardBrand:
          $ref: '#/components/schemas/CardBrand'
        scoreStatus:
          type: string
          example: SUCCESS
          description: >-
            scoreStatus defines the status of carbon scoring for a given
            transaction. Possible values are,

            * SUCCESS = Transaction is scored successfully.

            * FAILURE = Transaction scoring is failed.
          minLength: 5
          maxLength: 7
        errorCode:
          type: string
          example: INVALID_MCC
          description: >-
            A unique constant identifying the error case encountered during
            carbon scoring for a given transaction.
          minLength: 1
          maxLength: 100
        errorMessage:
          type: string
          example: >-
            MCC Provided in the request is Invalid. Kindly Request again with
            valid MCC.
          description: Short description of the errorCode field.
          minLength: 10
          maxLength: 1000
        profile:
          $ref: '#/components/schemas/ClimateProfile'
        classification:
          title: Classification
          type: object
          description: Classification for this transaction.
          properties:
            type:
              $ref: '#/components/schemas/ClassificationType'
            id:
              type: string
              example: '5411'
              description: specifies Id of Classification
          required:
            - id
            - type
        spendingAreaId:
          type: number
          description: Spending area id
          example: 30
    ClassificationType:
      type: string
      minLength: 3
      maxLength: 5
      pattern: ^(mcc|docc|MCC|plaid)$
      example: MCC
      description: |-
        Classification for this transaction. Possible values are,
        * mcc * docc * MCC * plaid
    TransactionFootprint:
      title: TransactionFootprint
      type: object
      description: >-
        A single transaction footprint calculated for a corresponding payment
        transaction.
      required:
        - transactionId
        - mcc
      allOf:
        - $ref: '#/components/schemas/CarbonUsage'
        - type: object
          properties:
            transactionId:
              $ref: '#/components/schemas/TransactionId'
            mcc:
              type: string
              description: >-
                Merchant category code of a payment transaction that uniquely
                defines a merchant business (same as in request).
              minLength: 1
              maxLength: 4
              pattern: ^\d{1,4}
            category:
              $ref: '#/components/schemas/Category'
            scoreReference:
              type: string
              description: >-
                Score Reference defines transaction scoring type, based on which
                score has been generated. Possible values are MCC or AIIA.
              minLength: 3
              maxLength: 4
    AggregateSearchCriteria:
      title: AggregateSearchCriteria
      type: object
      description: >-
        Request object which holds the criteria (that is, list of payment card
        IDs and aggregate type) for retrieving aggregate transactions.
      required:
        - paymentCardIds
        - aggregateType
      properties:
        paymentCardIds:
          type: array
          items:
            $ref: '#/components/schemas/PaymentCardId'
          minItems: 1
          maxItems: 5
          example: c5d88571-ac15-465a-a0d8-1ad1327b9a06
          description: Unique ID provided in the response while registering a payment card.
        aggregateType:
          type: integer
          minimum: 1
          maximum: 3
          example: 1
          description: >
            Aggregate type for which aggregate needs to be calculated. Supported
            values are:

            <li> 1 = Weekly Transactions aggregated for last 26 weeks <li> 2 =
            Monthly transactions aggregated for last 12 months <li> 3 = Monthly
            category-wise transactions aggregated for last 12 months
        crossPANAggregate:
          type: string
          minLength: 1
          maxLength: 1
          pattern: ^(?:Y|N|y|n)$
          example: 'Y'
          description: >
            Wheter to retrieve cross PAN aggregate carbon footprint or not.
            Supported values are:

            <li> Y = Retrieve cross PAN aggregate. <li> N = Do not retrieve
            cross PAN aggregate. <br> If not provided then default will be
            considered as 'N'.
        fromDate:
          $ref: '#/components/schemas/Day'
        toDate:
          $ref: '#/components/schemas/Day'
      example:
        aggregateType: 1
        crossPANAggregate: 'Y'
        paymentCardIds:
          - 328b62d4-287c-4c9f-a05d-6d4a67f208d8
          - b86fd2ba-c095-4acb-b9df-f3805655ba24
        fromDate: '2020-07-01'
        toDate: '2020-08-30'
    HistoricalTransactionFootprints:
      title: HistoricalTransactionFootprints
      description: >-
        Response object which holds all the transaction footprints for
        historical transactions.
      properties:
        count:
          description: The number of items in this batch (the size of the item array).
          type: integer
          example: 2
        offset:
          description: >-
            The number of items you asked the start of the list to be offset
            from.
          type: integer
          minimum: 0
          example: 1
        limit:
          description: The number of items you asked the list to be limited to.
          type: integer
          minimum: 5
          maximum: 50
          example: 5
        total:
          description: The total number of items in the collection.
          type: integer

# --- truncated at 32 KB (141 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mastercard/refs/heads/main/openapi/mastercard-carbon-calculator-api-openapi.yml