swagger: '2.0'
info:
  title: Mastercard Bill Payment Validator Account Opening Payment  Card 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: Payment  Card
paths:
  /service-providers/payment-cards:
    post:
      tags:
      - 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'
  /payment-cards/{payment_card_id}/transaction-footprints:
    get:
      tags:
      - 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:
    post:
      tags:
      - 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:
      - 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'
components:
  responses:
    TransactionHistoryBadRequestError:
      description: This response code is returned when a request is invalid or data in the request is not valid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            TransactionHistoryPaymentCardNotFoundError:
              $ref: '#/components/examples/TransactionHistoryPaymentCardNotFoundError'
            TransactionHistoryInvalidDateRangeError:
              $ref: '#/components/examples/TransactionHistoryInvalidDateRangeError'
            TransactionHistoryInvalidDateFormatError:
              $ref: '#/components/examples/TransactionHistoryInvalidDateFormatError'
    RegisterPaymentCardBadRequestError:
      description: This response code is returned when a request is invalid or data in the request is not valid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            RegisterPaymentCardRequestValidationError:
              $ref: '#/components/examples/RegisterPaymentCardRequestValidationError'
            RegisterPaymentCardUnsupportedCardCurrencyError:
              $ref: '#/components/examples/RegisterPaymentCardUnsupportedCardCurrencyError'
            RegisterPaymentCardInvalidFPANError:
              $ref: '#/components/examples/RegisterPaymentCardInvalidFPANError'
            RegisterPaymentCardRequestDecryptionError:
              $ref: '#/components/examples/RegisterPaymentCardRequestDecryptionError'
    PaymentCardReference:
      description: The response object that contains Payment Card information after a successful registration.
      headers:
        X-MC-Correlation-ID:
          $ref: '#/components/headers/X-MC-Correlation-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PaymentCardReference'
          examples:
            PaymentCardReference:
              $ref: '#/components/examples/PaymentCardReference'
    PaymentCardEnrolmentsBadRequestError:
      description: This response code is returned when a request is invalid, or data in the request is not valid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            PaymentCardEnrolmentsRequestValidationError:
              $ref: '#/components/examples/RegisterPaymentCardRequestValidationError'
            PaymentCardEnrolmentsRequestDecryptionError:
              $ref: '#/components/examples/RegisterPaymentCardRequestDecryptionError'
    HistoricalTransactionFootprints:
      description: This response code is returned when a request is accepted and successfully processed. A corresponding response will be returned for the API caller.
      headers:
        X-MC-Correlation-ID:
          $ref: '#/components/headers/X-MC-Correlation-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HistoricalTransactionFootprints'
          examples:
            HistoricalTransactionFootprints:
              $ref: '#/components/examples/HistoricalTransactionFootprints'
    PaymentCardEnrolments:
      description: The response object that contains the list of payment cards information after batch registration.
      headers:
        X-MC-Correlation-ID:
          $ref: '#/components/headers/X-MC-Correlation-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PaymentCardEnrolments'
          examples:
            PaymentCardEnrolments:
              $ref: '#/components/examples/PaymentCardEnrolments'
    ServiceProviderUnsupportedMediaTypeError:
      description: This response code is returned when the value of provided Content-Type parameter is other than expected.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            ServiceProviderUnsupportedMediaTypeError:
              $ref: '#/components/examples/ServiceProviderUnsupportedMediaTypeError'
    ServiceProviderNotFoundError:
      description: This response code is returned when the server cannot find the account which has been used to call this API.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            ServiceProviderNotFoundError:
              $ref: '#/components/examples/ServiceProviderNotFoundError'
  examples:
    TransactionHistoryInvalidDateRangeError:
      value:
        Errors:
          Error:
          - Source: Service-Provider-Mgmt
            ReasonCode: INVALID_DATE_RANGE
            Description: Requested date range is either invalid or exceeds one year limits. Try again with a valid date range.
            Recoverable: false
            Details: ''
    ServiceProviderUnsupportedMediaTypeError:
      value:
        Errors:
          Error:
          - Source: Service-Provider-Mgmt
            ReasonCode: UNSUPPORTED_MEDIA_TYPE
            Description: Requested media type is not supported, try again with the supported media type.
            Recoverable: false
            Details: ''
    RegisterPaymentCardRequestDecryptionError:
      value:
        Errors:
          Error:
          - Source: Service-Provider-Mgmt
            ReasonCode: CRYPTO_ERROR
            Description: We are unable to decipher your request, kindly verify your request before trying again. If the problem persists then reach out to your Mastercard associate.
            Recoverable: false
            Details: ''
    RegisterPaymentCardInvalidFPANError:
      value:
        Errors:
          Error:
          - Source: Service-Provider-Mgmt
            ReasonCode: INVALID_FPAN
            Description: The card number in the request is either invalid or it does not match with your currently supported account range. Try again with a valid card number or update the supported account range.
            Recoverable: false
            Details: ''
    PaymentCardReference:
      value:
        paymentCardId: c5d88571-ac15-465a-a0d8-1ad1327b9a06
        bin: '534403'
        last4fpan: '9750'
        status: ACTIVE
    RegisterPaymentCardUnsupportedCardCurrencyError:
      value:
        Errors:
          Error:
          - Source: Service-Provider-Mgmt
            ReasonCode: UNSUPPORTED_CURRENCY
            Description: The currency in the request is not supported, try again with a different one.
            Recoverable: false
            Details: ''
    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: ''
    HistoricalTransactionFootprints:
      value:
        count: 2
        offset: 1
        limit: 5
        total: 5
        items:
        - transactionMetadata:
            id: ee421c25-f928-4bf6-b884-3600b76b860d
            traceId: 9f52386ce297173ecfeb9120aabb0805bbeeb1350ce1de640864852e800bd206
            banknetReferenceNumber: MPL0R6B2R
            banknetDate: '0525'
            retrievalRefNumber: MCC000100
            processingCode: '00'
            authCode: 52717Z
            dateAndTime: 2018-07-02T00:00+00:00
            merchantName: ABC Store
            acquiringInstitutionCountryCode: USA
            acquiringInstitutionCode: '12312312312'
            amount: '25.50'
            currencyCode: USD
            indicator: CL
          transactionFootPrint:
            mcc: 3997
            carbonEmissionInGrams: 48.52
            carbonEmissionInOunces: 1.71
            category:
              mainCategory: Leisure & Entertainment
              subCategory: Hotels & Vacation
              sector: Hotels, Motels & Resorts
              sectorCode: '604'
            scoreReference: MCC
        - transactionMetadata:
            id: fdc4626c-f51e-4ba6-9728-c79ac1d9aec8
            traceId: gf55386ce297173ecfeb9120aabb0805bbeeb1350ce1de640864852e8002343
            banknetReferenceNumber: MPL0B6B23
            banknetDate: '0725'
            retrievalRefNumber: MCC000480
            processingCode: '01'
            authCode: K3C161
            dateAndTime: 2019-12-25T00:00+00:00
            merchantName: ABC Store
            acquiringInstitutionCountryCode: USA
            acquiringInstitutionCode: '23423423423'
            amount: '30.00'
            currencyCode: USD
            indicator: CL
          transactionFootPrint:
            mcc: 5962
            carbonEmissionInGrams: 27.98
            carbonEmissionInOunces: 0.99
            category:
              mainCategory: Shopping
              subCategory: Department Store
              sector: Specialty Retail & Services
              sectorCode: '302'
            scoreReference: MCC
        - transactionMetadata:
            id: '9000010131662'
            traceId: af55386ce297173ecfeb9120aabb0805bbeeb1350ce1de640864852e800bd854
            banknetReferenceNumber: MPL0R8C2A
            banknetDate: '0624'
            retrievalRefNumber: '801220'
            processingCode: '00'
            authCode: '16'
            dateAndTime: 2022-01-26T00:00+00:00
            merchantName: Test Sandbox Merchant
            acquiringInstitutionCountryCode: USA
            acquiringInstitutionCode: '12311878333'
            amount: 20
            currencyCode: GBP
            indicator: RFT
          transactionFootprint:
            carbonEmissionInGrams: -3398.54
            carbonEmissionInOunces: -119.88
            transactionId: '9000010131662'
            mcc: '9311'
            category:
              mainCategory: Government Services
              subCategory: Public Services
              sector: Government Services
              sectorCode: '801'
            scoreReference: MCC
    TransactionHistoryInvalidDateFormatError:
      value:
        Errors:
          Error:
          - Source: Service-Provider-Mgmt
            ReasonCode: INVALID_REQUEST_PARAMETER
            Description: One of the request parameters is invalid, try again with correct request.
            Recoverable: false
            Details: 'getPaymentCardTransactionHistory.fromDate: must match "^((?:19|20)[0-9][0-9])-(0?[1-9]|1[012])-(0?[1-9]|[12][0-9]|3[01])$"'
          - Source: Service-Provider-Mgmt
            ReasonCode: INVALID_REQUEST_PARAMETER
            Description: One of the request parameters is invalid, try again with correct request..
            Recoverable: false
            Details: 'getPaymentCardTransactionHistory.fromDate: size must be between 10 and 10'
    TransactionHistoryPaymentCardNotFoundError:
      value:
        Errors:
          Error:
          - Source: Service-Provider-Mgmt
            ReasonCode: INVALID_REQUEST_PARAMETER
            Description: Payment card id - c2c76ec0-4056-44ba-b14f-6654c9ba5722 is/are invalid or not found. Please try again with valid payment card id.
            Recoverable: false
            Details: ''
    PaymentCardEnrolments:
      value:
      - bin: '545502'
        last4fpan: '8351'
        status: ACTIVE
        paymentCardId: 9f12f385-0b47-4cca-9e9d-baced21bca63
      - bin: '545502'
        last4fpan: '0762'
        status: ACTIVE
        paymentCardId: f506521c-38c6-4e87-bf1a-14023ce10d4e
      - bin: '545502'
        last4fpan: '2834'
        status: PENDING
        paymentCardId: 2da9571f-0cf2-458d-bc4b-9218578ce50d
      - bin: '520402'
        last4fpan: '2824'
        errorCode: INVALID_FPAN
    RegisterPaymentCardRequestValidationError:
      value:
        Errors:
          Error:
          - Source: Service-Provider-Mgmt
            ReasonCode: INVALID_REQUEST_PARAMETER
            Description: One of the request parameters is invalid, try again with the correct request.
            Recoverable: false
            Details: ''
  schemas:
    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}
    X-MC-Correlation-ID:
      type: string
      example: X-MC-Correlation-ID:5e4b7f904d2820f688c67ef9fc0035
    TransactionMetadata:
      title: TransactionMetadata
      type: object
      description: Metadata about a transaction.
      required:
      - id
      - retrievalRefNumber
      - processingCode
      - dateAndTime
      - merchantName
      - acquiringInstitutionCountryCode
      - acquiringInstitutionCode
      - amount
      - currencyCode
      - indicator
      properties:
        id:
          title: id
          type: string
          description: A unique ID associated with a transaction.
          maxLength: 100
          minLength: 1
          pattern: ^[\w\-\_]{1,100}
          example: ee421c25-f928-4bf6-b884-3600b76b860d
        traceId:
          title: traceId
          type: string
          description: A unique ID associated with a transaction.
          maxLength: 100
          minLength: 65
          pattern: ([A-Za-z0-9]{10,100})
          example: 9A52386ce297173Ecfeb9120aabb0805bbeeb1350ce1de640864852e800bd2067
        banknetReferenceNumber:
          title: banknetReferenceNumber
          type: string
          description: DE 63, subfield 2 (Banknet Reference Number) is generated by the Authorization Platform for each originating message it routes. The reference number is guaranteed to be a unique value for any transaction within the specified financial network on any processing day.
          maxLength: 13
          minLength: 6
          pattern: ([A-Za-z0-9]{6,13})
          example: MPL0R6B2R
        banknetDate:
          title: banknetDate
          type: string
          description: DE 7 subelement 1 (POS_BANKNET_DATE) is a date when transaction message enters into Mastercard network.
          maxLength: 4
          minLength: 4
          pattern: ([0-9]{4})
          example: '0525'
        retrievalRefNumber:
          title: retrievalRefNumber
          type: string
          description: DE 37 (Retrieval Reference Number) is a document reference number supplied by the system retaining the original source document of the transaction and assists in locating that source document or a copy thereof. DE 37 is made available for use by automated merchant POS systems that may be interconnected into the interchange system. Merchant POS systems may assign a unique receipt or sales document ID to be used to satisfy regulatory or legal requirements when the merchant performs source document capture and truncation. DE 37 may be used to relay source document reference numbers to the issuer at the time each transaction is processed. Number assigned by the acquirer. When present, DE 37 must contain a value other than all zeros or all spaces. DE 37 can have trailing spaces if the transaction is not a Visa or EMV chip transaction.
          maxLength: 12
          minLength: 12
          example: MCC000100120
        processingCode:
          title: processingCode
          type: string
          description: DE 3, subfield 1 (Cardholder Transaction Type Code) describes the specific transaction type.
          maxLength: 2
          minLength: 2
          example: '00'
        authCode:
          title: authCode
          type: string
          description: DE 38 (Authorization ID Response) is a transaction response ID code that the authorizing institution assigns. DE 38 is used to transmit a card issuers authorization code for Authorization transactions.
          maxLength: 6
          minLength: 1
          example: 01423Z
        dateAndTime:
          title: dateAndTime
          type: string
          description: This is the date and time when transaction acquire at the Merchant. (For example, YYYY-MM-DDThh:mmTZD).
          maxLength: 25
          minLength: 22
          example: 2018-07-02T00:00+00:00
        merchantName:
          title: merchantName
          type: string
          description: DE 43 (Card Acceptor Name/Location for All Transactions), subfield 1 (Card Acceptor Name) is the merchant doing business as name.
          maxLength: 25
          minLength: 1
          example: ABC Store
        acquiringInstitutionCountryCode:
          title: acquiringInstitutionCountryCode
          type: string
          description: DE 19 (Acquiring Institution Country Code) is the code of the country where the acquiring institution is located. Refer to the ISO 3166 specification for more information.
          maxLength: 3
          minLength: 3
          example: USA
        acquiringInstitutionCode:
          title: acquiringInstitutionCode
          type: string
          description: DE 32 (Acquiring Institution ID Code) identifies the acquiring institution (for example, merchant bank) or its agent.
          maxLength: 11
          minLength: 11
          example: '12312312312'
        amount:
          title: amount
          type: number
          description: Transaction amount for the given transaction.
          maxLength: 10
          minLength: 1
          example: 25.5
        currencyCode:
          $ref: '#/components/schemas/CurrencyCode'
        indicator:
          title: indicator
          type: string
          description: Transaction type (CLEAR = CL or REFUND = RFT).
          maxLength: 8
          minLength: 2
          example: CL
    PaymentCard:
      title: PaymentCard
      type: object
      description: The request object for registering a new Payment Card. This object will be encrypted before sending it to the server.
      required:
      - fpan
      - cardBaseCurrency
      properties:
        fpan:
          type: string
          minLength: 16
          maxLength: 16
          pattern: ^\d{16}
          description: Original payment card number in full.
          example: '5344035171229750'
        cardBaseCurrency:
          $ref: '#/components/schemas/CurrencyCode'
      example:
        fpan: '5344035171229750'
        cardBaseCurrency: EUR
    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.'
    PaymentCardId:
      type: string
      minLength: 36
      maxLength: 36
      pattern: ^[0-9A-Fa-f\-]{36}
      description: Unique ID provided in the response while registering a payment card.
      example: c5d88571-ac15-465a-a0d8-1ad1327b9a06
    PaymentCardReference:
      title: PaymentCardReference
      type: object
      description: Reference information for a Payment Card generated after a successful registration. This information should be used to perform the further operation for that card.
      required:
      - paymentCardId
      - status
      - bin
      - last4fpan
      properties:
        paymentCardId:
          $ref: '#/components/schemas/PaymentCardId'
        bin:
          type: string
          minLength: 4
          maxLength: 8
          pattern: ^\d{4,8}
          description: First 4 to 8 digits of a payment card number.
          example: '534403'
        last4fpan:
          type: string
          minLength: 4
          maxLength: 4
          pattern: ^\d{4}
          description: Last 4 digits of a payment card number.
          example: '9750'
        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
    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'
    HistoricalTransactionFootprint:
      title: HistoricalTransactionFootprint
      type: object
      description: A single transaction footprint along with transaction info for a corresponding payment transaction.
      required:
      - transactionMetadata
      - transactionFootprint
      properties:
        transactionMetadata:
          $ref: '#/components/schemas/TransactionMetadata'
        transactionFootprint:
          $ref: '#/components/schemas/TransactionFootprint'
    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
    Category:
      title: Category
      type: object
      description: User understandable information about an MCC categorization.
      properties:
        mainCategory:
          title: mainCategory
          type: string
          description: Main category to which an MCC belongs.
          minLength: 5
          maxLength: 100
          pattern: ^[\w\-\_\&\,]+[\w\-\_\&\,\ ]{5,100}
          example: Shopping
        subCategory:
          title: subCategory
          type: string
          description: Sub-category of a category to which an MCC belongs.
          minLength: 5
          maxLength: 100
          pattern: ^[\w\-\_\&\,]+[\w\-\_\&\,\ ]{5,100}
          example: Department Store
        sector:
          title: sector
          type: string
          description: Sector of a category to which an MCC belongs.
          minLength: 5
          maxLength: 100
          pattern: ^[\w\-\_\&\,]+[\w\-\_\&\,\ ]{5,100}
          example: Specialty Retail & Services
        sectorCode:
          title: sectorCode
          type: string
          description: Unique code assigned to each sector.
          minLength: 3
          maxLength: 3
          pattern: ^\d{3}
          example: '302'
    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
          example: 5
        items:
          description: 'List of `HistoricalTransactionFootprint` objects.

            '
          type: array
          minItems: 1
          maxItems: 5000
          items:
            $ref: '#/components/schemas/HistoricalTransactionFootprint'
    CarbonUsage:
      title: CarbonUsage
      type: object
      description: Object to hold carbon usage data.
      properties:
        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
    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'
    Day:
      type: string
      minLength: 10
      maxLength: 10
      pattern: ^((?:19|20)[0-9][0-9])-(0?[1-9]|1[012])-(0?[1-9]|[12][0-9]|3[01])$
      example: '2020-09-19'
    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'
    CurrencyCode:
      type: string
      description: Currency code as per ISO 4217
      minLength: 3
      maxLength: 3
      pattern: ^[A-Za-z]{3}$
    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
  parameters:
    Limit:
      name: limit
      in: query
      description: The number of items you asked the list to be limited to.
      required: false
      example: 50
      schema:
        type: integer
        default: 50
        minimum: 5
        maximum: 50
    PaymentCardId:
      name: payment_card_id
      in: path
      description: Unique ID provided in the response while registering a payment card.
      required: true
      example: 83c0711e-1851-4771-950a-055dded7f168
      schema:
        $ref: '#/components/schemas/PaymentCardId'
    Offset:
      name: offset
      in: query
      description: The number of items you need the start of the list to be offset from.
      required: false
      example: 50
      schema:
        type: integer
        default: 0
        minimum: 0
    ToDate:
      name: to_date
      in: query
      description: End date for searching transaction (Format- YYYY-MM-DD).
      required: true
      example: '2021-05-07'
      schema:
        $ref: '#/components/schemas/Day'
    FromDate:
      name: from_date
      in: query
      description: Start date for searching transaction (Format- YYYY-MM-DD).
      required: true
      example: '2018-05-07'
      schema:
        $ref: '#/components/schemas/Day'
  requestBodies:
    PaymentCards:
      required: true
      description: List of payment cards to be enroled.
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/PaymentCard'
            minItems: 1
            maxItems: 100
            example:
            - fpan: '5455029300268351'
              cardBaseCurrency: EUR
            - fpan: '5455023979760762'
              cardBaseCurrency: USD
            - fpan: '5455023979762834'
              cardBaseCurrency: USD
            - fpan: '5455023979762824'
              cardBaseCurrency: USD
    PaymentCard:
      description: Payment card to be enroled.
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PaymentCard'
  headers:
    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'