swagger: '2.0'
info:
  title: Mastercard Bill Payment Validator Account Opening Footprints API
  description: This service is provided on behalf of the Mastercard Remote Payment and Presentment (RPPS) Bill Payment Processing Network, which supports consumer to business "push" bill payments (i.e. those which are not funded by debit/credit card transactions) in the U.S.
  version: '1.0'
  x-artifactId: billpay-api
  contact:
    name: Bill Pay Development Support
    email: Bill_Pay_Development_Support@mastercard.com
host: sandbox.api.mastercard.com
basePath: /billpayAPI/v1
schemes:
- https
consumes:
- application/json
produces:
- application/json
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:
  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
    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: ''
    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}"
  schemas:
    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: []
    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}
    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.
    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
    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'
    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
    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'
    CurrencyCode:
      type: string
      description: Currency code as per ISO 4217
      minLength: 3
      maxLength: 3
      pattern: ^[A-Za-z]{3}$
      example: USD
    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
          exclusiveMaximum: false
          minimum: -1000000000
          exclusiveMinimum: false
          example: 104
        currencyCode:
          $ref: '#/components/schemas/CurrencyCode'
  responses:
    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'
    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'
    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'
  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'