Mastercard Benchmarks API

openapi: 3.2.0
info:
  title: Mastercard Carbon Calculator Benchmarks 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: apisupport@mastercard.com
    url: https://developer.mastercard.com/support
  version: 1.2.0
servers:
- url: https://sandbox.api.mastercard.com/carbon
  description: Sandbox
- url: https://api.mastercard.com/carbon
  description: Production
tags:
- name: Benchmarks
paths:
  /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:
  examples:
    BenchmarksResponseData:
      value:
        benchmarksPayload:
          id: US
          emission:
            yearly: 1.425
          parisAgreement:
            yearly: 1.66
    InvalidPeriodError:
      value:
        Errors:
          Error:
          - Source: Carbon-Calculator
            ReasonCode: INVALID_REQUEST_PARAMETER
            Description: One of the request parameters is invalid, try again with correct request.
            Recoverable: false
            Details: 'Period: Accepted values are ''month'' and ''year'''
    BenchmarkBadRequestError:
      value:
        Errors:
          Error:
          - Source: Carbon-Calculator
            ReasonCode: BAD_REQUEST
            Description: One of the request parameters is invalid, try again with correct request.
            Recoverable: false
            Details: country is a required field
    CountryCodeNotFoundError:
      value:
        Errors:
          Error:
          - Source: Carbon-Calculator
            ReasonCode: INVALID_REQUEST_PARAMETER
            Description: One of the request parameters is invalid, try again with correct request.
            Recoverable: false
            Details: country code not found
    InvalidCountryCodeError:
      value:
        Errors:
          Error:
          - Source: Carbon-Calculator
            ReasonCode: BAD_REQUEST
            Description: One of the request parameters is invalid, try again with correct request.
            Recoverable: false
            Details: Country code is invalid
    NoDataEmissionResponseData:
      value:
        benchmarksPayload:
          id: VU
          emission:
            data: No emissions records for this country
          parisAgreement:
            yearly: 3.498
    ServiceProviderNotFoundError:
      value:
        Errors:
          Error:
          - Source: Service-Provider-Mgmt
            ReasonCode: ACCOUNT_NOT_FOUND
            Description: We cannot find the account which you are using to access this service. Kindly register your account or contact your Mastercard associate if you have already registered with us earlier.
            Recoverable: false
            Details: ''
  responses:
    BenchmarkBadRequestError:
      description: This response code is returned when one or more request parameters is either missing or is invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            BadRequestError:
              $ref: '#/components/examples/BenchmarkBadRequestError'
            InvalidCountryCodeError:
              $ref: '#/components/examples/InvalidCountryCodeError'
            CountryCodeNotFoundError:
              $ref: '#/components/examples/CountryCodeNotFoundError'
            InvalidPeriodError:
              $ref: '#/components/examples/InvalidPeriodError'
    Benchmarks:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Benchmark'
          examples:
            BenchmarksResponse:
              $ref: '#/components/examples/BenchmarksResponseData'
            NoDataEmissionResponseData:
              $ref: '#/components/examples/NoDataEmissionResponseData'
    BenchmarkNotFoundError:
      description: This response code is returned when one or more request parameters is either missing or is invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            ServiceProviderNotFoundError:
              $ref: '#/components/examples/ServiceProviderNotFoundError'
  schemas:
    Benchmark:
      type: object
      properties:
        benchmarksPayload:
          $ref: '#/components/schemas/BenchmarksData'
    BenchmarksData:
      title: benchmarks
      type: object
      description: benchmark data.
      properties:
        id:
          type: string
          description: id of benchmark
          example: US
        emission:
          type: object
          description: Emissions for this country yearly or monthly in metric tons, atleast one property will appear among yearly, monthly or data.
          properties:
            yearly:
              description: Yearly emissions for this country in metric tons
              type: number
              example: 1.425
            monthly:
              description: Monthly emissions for this country in metric tons
              type: number
              example: 0.678
            data:
              description: If no data exists for this country
              type: string
              example: No emissions records for this country
          minProperties: 1
        parisAgreement:
          type: object
          description: Emissions meeting the 2030 goal stated in the Paris agreement in metric tons, atleast one property will appear among yearly or monthly.
          properties:
            yearly:
              description: Yearly emissions goal for reaching the Paris agreement in metric tons
              type: number
              example: 1.66
            monthly:
              description: Monthly emissions goal for reaching the Paris agreement in metric tons
              type: number
              example: 0.425
          minProperties: 1
      required:
      - emission
      - id
      - parisAgreement
    ErrorWrapper:
      title: ErrorWrapper
      type: object
      description: The error response object gets returned in case of any error.
      required:
      - Errors
      properties:
        Errors:
          $ref: '#/components/schemas/Errors'
    CountryCode:
      description: ISO 3166-1 alpha-2 format country code
      pattern: ^[A-Z]{2}$
      type: string
    Error:
      title: Error
      type: object
      description: Error object which contains details about the error.
      required:
      - Source
      - ReasonCode
      - Description
      - Recoverable
      properties:
        Source:
          type: string
          description: The application name that generated this error. Every error message that is generated and returned by the gateway will have this field equal to Gateway. Other possible values are 'Carbon-Calculator' and 'Service-Provider'.
          minLength: 1
          maxLength: 100
          example: Service-Provider-Mgmt
        ReasonCode:
          type: string
          description: A unique constant identifying the error case encountered during request processing.
          minLength: 1
          maxLength: 100
          example: INVALID_REQUEST_PARAMETER
        Description:
          type: string
          description: Short description of the ReasonCode field.
          minLength: 10
          maxLength: 1000
          example: One of the request parameters is invalid, try again with correct request.
        Recoverable:
          type: boolean
          description: Indicates whether this error will always be returned for this request, or retrying could change the outcome.
          example: false
        Details:
          type: string
          description: (Optional) Where appropriate, indicates detailed information about data received and calculated during the request processing, to help the user with diagnosing errors.
          minLength: 0
          maxLength: 5000
          example: paymentCardId size must be between 36 and 36
    Errors:
      title: Errors
      type: object
      description: Error object which returns a list of Error objects.
      required:
      - Error
      properties:
        Error:
          $ref: '#/components/schemas/ErrorList'
    ErrorList:
      type: array
      minItems: 1
      items:
        $ref: '#/components/schemas/Error'
    Period:
      enum:
      - MONTH
      - YEAR
      type: string
  parameters:
    CountryCode:
      name: country
      in: query
      description: for specific country user wants to see benchmark
      required: true
      example: US
      schema:
        $ref: '#/components/schemas/CountryCode'
    Period:
      name: period
      in: query
      description: period in which user wants to see benchmark for specific country
      required: false
      example: month / year
      schema:
        $ref: '#/components/schemas/Period'
externalDocs:
  description: ISO 4217 - Currency Code
  url: https://en.wikipedia.org/wiki/ISO_4217