swagger: '2.0'
info:
  title: Mastercard Bill Payment Validator Account Opening Products 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: Products
  description: Handles Products
paths:
  /products/searches:
    post:
      tags:
      - Products
      description: Returns the product information using the card number provided for the requested date. If no date is provided, then current date will be used.
      summary: Search products
      operationId: searchProducts
      requestBody:
        $ref: '#/components/requestBodies/ProductSearch'
      responses:
        '200':
          $ref: '#/components/responses/SearchProducts'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
components:
  responses:
    UnauthorizedError:
      description: Unauthorized - Access Not Granted
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            UnauthorizedExample:
              $ref: '#/components/examples/UnauthorizedExample'
    SearchProducts:
      description: Returns Products that match the search criteria
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SearchProducts'
    BadRequestError:
      description: Something was wrong with the request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            BadRequestExample:
              $ref: '#/components/examples/BadRequestExample'
  schemas:
    Products:
      type: object
      properties:
        effectiveDate:
          description: Date for which benefits are to be determined. Defaults to the current date if not provided. Date is in YYYY-MM-DD format
          type: string
          example: '2022-12-15'
          pattern: ^\d{4}-\d{2}-\d{2}$
        cardNumber:
          description: Full card number or BIN number
          type: string
          example: '5308780000000000'
          minLength: 6
          maxLength: 19
      required:
      - cardNumber
    Errors:
      description: Object that contains the list of errors
      type: object
      required:
      - Error
      properties:
        Error:
          $ref: '#/components/schemas/ErrorList'
    ErrorWrapper:
      description: A top level object for errors
      type: object
      required:
      - Errors
      properties:
        Errors:
          $ref: '#/components/schemas/Errors'
    SearchProducts:
      type: object
      properties:
        icaBusinessName:
          description: Name of Issuer
          type: string
          example: Bank Group
          minLength: 0
          maxLength: 60
        icaCode:
          description: ICA code of the issuer
          type: string
          example: '7379'
        icaRegion:
          description: The geographical region of card issuer
          type: string
          example: US
          minLength: 2
          maxLength: 40
          pattern: '[A-Z]+'
        icaCountry:
          description: The country of the card issuer
          type: string
          example: USA
          maxLength: 3
          minLength: 3
          pattern: '[A-Z]+'
        icaState:
          description: The state of the card issuer
          type: string
          example: SOUTH DAKOTA
          minLength: 0
          maxLength: 300
        icaLegalName:
          description: This is the ICAs Legal name for MPI, MasterCard's Licensing database
          type: string
          example: Bank Group, N.A.
          minLength: 0
          maxLength: 300
        parentICACode:
          description: Code for Parent Issuer
          type: string
          example: '7379'
          minLength: 4
          maxLength: 9
        data:
          description: Array of Products
          type: array
          items:
            $ref: '#/components/schemas/Product'
    ErrorList:
      description: The list of errors
      type: array
      minItems: 1
      items:
        $ref: '#/components/schemas/Error'
    Product:
      type: object
      properties:
        productCode:
          description: 3 alpha character code of MasterCard Product. This is required if the BIN or card number has multiple Products associated with it.
          type: string
          example: MCC
          minLength: 3
          maxLength: 3
          pattern: ^[A-Z]{3}$
        productName:
          description: Name that corresponds to the Mastercard product
          type: string
          example: Mixed Product
          minLength: 1
          maxLength: 100
    Error:
      description: A single error
      type: object
      properties:
        Source:
          type: string
          minLength: 0
          maxLength: 200
          description: Information about where the error happened
          example: ELIGIBILITY_BENEFITS_API
        ReasonCode:
          type: string
          minLength: 0
          maxLength: 200
          description: An error code
          example: BAD_REQUEST
        Description:
          type: string
          minLength: 0
          maxLength: 10000
          description: A description of the error
          example: We couldn't handle your request
        Recoverable:
          type: boolean
          description: Indicates if the request can be presented again for processing
          example: false
        Details:
          type: string
          minLength: 0
          maxLength: 10000
          description: More details about the error
          example: Invalid JSON payload
  examples:
    UnauthorizedExample:
      value:
        Errors:
          Error:
          - Source: Gateway
            ReasonCode: DECLINED
            Description: Unauthorized - Access Not Granted
            Recoverable: false
            Details: null
    BadRequestExample:
      value:
        Errors:
          Error:
          - Source: Benefits Eligibility Service
            ReasonCode: BENEFITINFO_VAL_001
            Description: Validation Error  BIN Number should be numeric.
            Recoverable: false
  requestBodies:
    ProductSearch:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Products'