Mastercard Footprints API

openapi: 3.2.0
info:
  title: Mastercard Doconomy Aland Index Footprints API
  description: The Doconomy Aland Index API enables issuers to provide their consumers with visibility into the environmental impact based on their spending habits.
  contact:
    name: API Support
    email: apisupport@mastercard.com
    url: https://developer.mastercard.com/support
  version: 1.0.0
servers:
- url: https://sandbox.api.mastercard.com/doconomy
  description: Sandbox
- url: https://api.mastercard.com/doconomy
  description: Production
tags:
- name: Footprints
paths:
  /transaction-footprints:
    post:
      tags:
      - Footprints
      summary: Mastercard Calculate Transaction Footprints
      description: This service calculates carbon emission based on payment transaction amount and the merchant category code. You can send one or more transactions together to get the transaction footprints.
      operationId: FootprintsByTransactionData
      requestBody:
        $ref: '#/components/requestBodies/MCTransactions'
      responses:
        '200':
          $ref: '#/components/responses/MCTransactionFootprints'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '415':
          $ref: '#/components/responses/UnsupportedMediaTypeError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    MCAmount:
      title: Amount
      type: object
      description: Amount object that includes the value and the currency in which a payment transaction has been performed
      required:
      - currencyCode
      - value
      properties:
        value:
          type: number
          description: Actual amount of a payment transaction
          maximum: 1000000000
          minimum: -1000000000
          example: 104
        currencyCode:
          $ref: '#/components/schemas/CurrencyCode'
    TransactionId:
      type: string
      description: A unique id associated with a payment transaction, e.g. 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}
    MCTransactions:
      title: Transactions
      type: object
      description: Request object which holds all the payment transactions from API consumer for calculating transaction footprint.
      required:
      - transactions
      properties:
        transactions:
          minItems: 1
          maxItems: 5000
          type: array
          items:
            $ref: '#/components/schemas/MCTransaction'
          example:
          - transactionId: ee421c25-f928-4bf6-b884-3600b76b860d
            mcc: 3997
            amount:
              value: 100
              currencyCode: USD
          - transactionId: fdc4626c-f51e-4ba6-9728-c79ac1d9aec8
            mcc: 5962
            amount:
              value: 50
              currencyCode: EUR
    MCTransactionFootprint:
      title: TransactionFootprint
      type: object
      description: This object holds the transaction footprint for a payment transaction.
      required:
      - transactionId
      properties:
        transactionId:
          $ref: '#/components/schemas/TransactionId'
        carbonEmissionInGrams:
          title: carbonEmissionInGrams
          type: number
          description: The transaction's CO2 emission in grams
          example: 48.52
        carbonEmissionInOunces:
          title: carbonEmissionInOunces
          type: number
          description: The transaction's CO2 emission in ounces
          example: 1.71
        carbonSocialCost:
          title: carbonSocialCost
          type: object
          description: The transaction's CO2 emission cost
          properties:
            currencyCode:
              title: currencyCode
              type: string
              description: The transaction Currency Code
              example: USD
            value:
              title: value
              type: number
              description: The transaction Currency value
              example: 40.51
          example: example_value
    MCTransactionFootprints:
      title: TransactionFootprints
      type: object
      description: Response object which holds all the transaction footprints corresponding to each transaction in Transactions request.
      required:
      - transactionFootprints
      properties:
        transactionFootprints:
          type: array
          minItems: 1
          maxItems: 5000
          items:
            $ref: '#/components/schemas/MCTransactionFootprint'
          example: []
    MCErrors:
      title: Errors
      type: object
      description: Error object which returns list of Error objects
      required:
      - Error
      properties:
        Error:
          type: array
          items:
            $ref: '#/components/schemas/MCError'
          example: []
    MCError:
      title: Error
      type: object
      description: Error object which contains details about 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 Doconomy-Proxy and Doconomy.
          minLength: 1
          maxLength: 100
          example: Carbon-Calculator-Proxy
        ReasonCode:
          type: string
          description: A unique constant identifying the error case encountered during request processing.
          minLength: 1
          maxLength: 100
          example: UNSUPPORTED_MEDIA_TYPE
        Description:
          type: string
          description: Short description of the ReasonCode field.
          minLength: 10
          maxLength: 1000
          example: Requested media type is not supported, try again with supported media type.
        Recoverable:
          type: boolean
          description: Indicates whether this error will always be returned for this request, or retrying could change the outcome.
          example: true
        Details:
          type: string
          description: (Optional) Where appropriate, indicates detailed information about data received and calculated during request processing, to help the user with diagnosing errors.
          minLength: 0
          maxLength: 5000
          example: Supported media type is application/json.
    MCErrorResponseObject:
      title: ErrorResponse
      type: object
      description: The error response object which gets returned in case of any error.
      required:
      - Errors
      properties:
        Errors:
          $ref: '#/components/schemas/MCErrors'
    MCTransaction:
      title: Transaction
      type: object
      description: This object holds data corresponding to a single payment transaction.
      required:
      - amount
      - mcc
      - transactionId
      properties:
        transactionId:
          $ref: '#/components/schemas/TransactionId'
        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/MCAmount'
    CurrencyCode:
      type: string
      description: Currency code as per ISO 4217
      minLength: 3
      maxLength: 3
      pattern: ^[A-Za-z]{3}$
      example: USD
  responses:
    MCTransactionFootprints:
      description: This response code is returned when a request is accepted and successfuly processed. A corresponding response will be returned for the API caller.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MCTransactionFootprints'
          examples:
            MCTransactionFootprints:
              $ref: '#/components/examples/MCTransactionFootprints'
    BadRequestError:
      description: This response code is returned when one or more request parameters is either missing or is invalid. A caller should update his request as per error details before trying again.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MCErrorResponseObject'
          examples:
            BadRequestError:
              $ref: '#/components/examples/BadRequestError'
    UnsupportedMediaTypeError:
      description: This response code is returned when the MediaType in request is other than application/json.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MCErrorResponseObject'
          examples:
            UnsupportedMediaTypeError:
              $ref: '#/components/examples/UnsupportedMediaTypeError'
  requestBodies:
    MCTransactions:
      description: Request object which holds all the payment transactions from API consumer for calculating transaction footprint.
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MCTransactions'
  examples:
    MCTransactionFootprints:
      value:
        transactionFootprints:
        - transactionId: ee421c25-f928-4bf6-b884-3600b76b860d
          carbonEmissionInGrams: 48.52
          carbonEmissionInOunces: 1.71
          carbonSocialCost:
            currencyCode: USD
            value: 40.5
        - transactionId: fdc4626c-f51e-4ba6-9728-c79ac1d9aec8
          carbonEmissionInGrams: 27.98
          carbonEmissionInOunces: 0.99
          carbonSocialCost:
            currencyCode: EUR
            value: 30.5
    BadRequestError:
      value:
        Errors:
          Error:
          - Source: Carbon-Calculator-Proxy
            ReasonCode: INVALID_REQUEST_PARAMETER
            Description: One of the request parameters is invalid, try again with correct request.
            Recoverable: false
            Details: transactions[0].mcc size must be between 1 and 4
          - Source: Carbon-Calculator-Proxy
            ReasonCode: INVALID_REQUEST_PARAMETER
            Description: One of the request parameters is invalid, try again with correct request.
            Recoverable: false
            Details: transactions[0].mcc must match "^\d{1,4}"
    UnsupportedMediaTypeError:
      value:
        Errors:
          Error:
          - Source: Carbon-Calculator-Proxy
            ReasonCode: UNSUPPORTED_MEDIA_TYPE
            Description: Requested media type is not supported, try again with supported media type.
            Recoverable: false
            Details: ''
externalDocs:
  description: ISO 4217 - Currency Code
  url: https://en.wikipedia.org/wiki/ISO_4217