swagger: '2.0'
info:
  title: Mastercard Bill Payment Validator Account Opening Benchmarks 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: 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:
  schemas:
    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'
    Errors:
      title: Errors
      type: object
      description: Error object which returns a list of Error objects.
      required:
      - Error
      properties:
        Error:
          $ref: '#/components/schemas/ErrorList'
    Period:
      enum:
      - MONTH
      - YEAR
      type: string
    ErrorList:
      type: array
      minItems: 1
      items:
        $ref: '#/components/schemas/Error'
    CountryCode:
      description: ISO 3166-1 alpha-2 format country code
      pattern: ^[A-Z]{2}$
      type: string
    Benchmark:
      type: object
      properties:
        benchmarksPayload:
          $ref: '#/components/schemas/BenchmarksData'
    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
  responses:
    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'
    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'
  examples:
    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'''
    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: ''
    BenchmarksResponseData:
      value:
        benchmarksPayload:
          id: US
          emission:
            yearly: 1.425
          parisAgreement:
            yearly: 1.66
    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
    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
    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
  parameters:
    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'
    CountryCode:
      name: country
      in: query
      description: for specific country user wants to see benchmark
      required: true
      example: US
      schema:
        $ref: '#/components/schemas/CountryCode'