swagger: '2.0'
info:
  title: Mastercard Bill Payment Validator Account Opening Inquiries 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: Inquiries
paths:
  /inquiries:
    post:
      summary: Mastercard Inquiry Request for an Update on an Account.
      tags:
      - Inquiries
      description: An inquiry request is used to receive the most up-to-date account information available from issuers at any time. The parameters provided in the request are used to identify the account inquired. Once a request is received by ABU, a response will be provided back with the account information.
      operationId: accountInquiry
      requestBody:
        $ref: '#/components/requestBodies/InquiryRequest'
      responses:
        '200':
          $ref: '#/components/responses/InquiryResponse'
        '400':
          $ref: '#/components/responses/BadRequestErrorResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /subscription-inquiries:
    post:
      summary: Mastercard Inquire on a Subscription to Determine if an Account Is Already Being Watched or Not.
      tags:
      - Inquiries
      description: An inquiry request is used to check if an account is already being watched or not. Based on the response back, the ABU Integrator can choose to take action if necessary; to subscribe to watch an account or unsubscribe, to stop watching an account.
      operationId: subscriptionInquiry
      requestBody:
        $ref: '#/components/requestBodies/SubscriptionInquiryRequest'
      responses:
        '200':
          $ref: '#/components/responses/SubscriptionInquiryResponse'
        '400':
          $ref: '#/components/responses/BadRequestErrorResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Ica:
      type: string
      minLength: 4
      maxLength: 15
      example: '1111'
      description: A number assigned by Mastercard to a licensed customer to identify the member in transactions. This is used as an identifier for data submitted to ABU.
    SubscriptionInquiry:
      allOf:
      - $ref: '#/components/schemas/CustomerAccount'
      - type: object
    MerchantId:
      type: string
      maxLength: 15
      minLength: 15
      example: '000000000002535'
      description: A merchant ID or payment facilitator ID, previously registered with Mastercard.
    CustomerAccount:
      type: object
      required:
      - requestId
      - customer
      - account
      properties:
        requestId:
          type: string
          maxLength: 64
          minLength: 1
          example: 323e304f-1cfc-4f0d-ac07-e6037ce09925
          description: An identifier established by the customer.
        customer:
          $ref: '#/components/schemas/Customer'
        account:
          $ref: '#/components/schemas/Account'
    Inquiry:
      allOf:
      - $ref: '#/components/schemas/CustomerAccount'
      - type: object
    Customer:
      description: Representation of a customer
      type: object
      allOf:
      - $ref: '#/components/schemas/BaseCustomer'
      - type: object
        properties:
          subMerchantId:
            $ref: '#/components/schemas/SubMerchantId'
    Account:
      description: Representation of an account
      type: object
      allOf:
      - $ref: '#/components/schemas/BaseAccount'
      - type: object
    Expiry:
      type: string
      maxLength: 4
      minLength: 4
      example: '1228'
      description: The expiration date associated to the account number being inquired upon. Must be in MMYY format.
    AccountUpdate:
      type: object
      properties:
        account:
          $ref: '#/components/schemas/Account'
        responseIndicator:
          $ref: '#/components/schemas/ResponseIndicator'
    ResponseIndicator:
      type: string
      pattern: ^(VALID|UNKNOWN|NON_PARTICIPATING|CONTACT|EXPIRY|ACCOUNT_UPDATE)
      example: VALID
      description: 'An indicator to help explain the status of the account being inquired on. Possible values are:

        * `VALID` = Matches the account as reported by the issuer.

        * `UNKNOWN` = Account number is not known to ABU or part of a participating BIN (Bank Identification Number) and/or issuer.

        * `NON_PARTICIPATING` = Account number is not known to ABU or part of a non-participating BIN (Bank Identification Number) and/or issuer.

        * `CONTACT` (C) = Contact the issuer.

        * `EXPIRY` (E) = The card inquired on is expired, updated expiry date returned.

        * `ACCOUNT_UPDATE` (A) = The card inquired on is updated, updated card number and expiry date returned.'
    ErrorWrapper:
      type: object
      required:
      - Errors
      properties:
        Errors:
          $ref: '#/components/schemas/Errors'
    OutSubscriptionInquiry:
      type: object
      properties:
        subscribed:
          type: boolean
          example: true
          description: 'Indicate to the ABU Integrator if they are subscribed to the inquired account. account number for a given merchant. *`subscribed: true`: Customer is subscribed. *`subscribed: false`: Customer is not subscribed.'
    SubMerchantId:
      type: string
      maxLength: 15
      minLength: 15
      example: '000000000000001'
      description: An optional identifier for a sub-merchant of a payment facilitators under a registered merchant ID.
    AccountNumber:
      type: string
      maxLength: 19
      minLength: 13
      example: '5573491171027315'
      description: The account number being inquired upon.
    BaseCustomer:
      description: Properties common to all customer
      type: object
      required:
      - ica
      - merchantId
      properties:
        ica:
          $ref: '#/components/schemas/Ica'
        merchantId:
          $ref: '#/components/schemas/MerchantId'
    Errors:
      type: object
      required:
      - Error
      properties:
        Error:
          $ref: '#/components/schemas/ErrorList'
    OutInquiry:
      allOf:
      - $ref: '#/components/schemas/AccountUpdate'
      - type: object
    BaseAccount:
      description: Properties common to all accounts
      type: object
      required:
      - accountNumber
      - expiryDate
      properties:
        accountNumber:
          $ref: '#/components/schemas/AccountNumber'
        expiryDate:
          $ref: '#/components/schemas/Expiry'
    ErrorList:
      type: array
      minItems: 1
      items:
        $ref: '#/components/schemas/Error'
    Error:
      type: object
      properties:
        Source:
          type: string
          example: Validation
          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.
          maxLength: 100
          minLength: 1
        ReasonCode:
          type: string
          example: ICA_VALUE_REQUIRED
          description: A unique constant identifying the error case encountered during request processing.
          maxLength: 100
          minLength: 1
        Description:
          type: string
          example: ICA required for ABU client eligibility validation
          description: Short description of the ReasonCode field.
          maxLength: 1000
          minLength: 10
        Recoverable:
          type: boolean
          example: false
          description: Indicates whether this error will always be returned for this request, or retrying could change the outcome.
        Details:
          type: string
          description: (Optional) Where appropriate, indicates detailed information about data received and calculated during request processing, to help the customer with diagnosing errors.
          example: ICA is Mandatory
          maxLength: 5000
          minLength: 0
  examples:
    UnauthorizedExample:
      value:
        Errors:
          Error:
          - Source: Security.Credential
            ReasonCode: AUTHENTICATION_FAILED
            Description: Unauthorized Access to Web Service.
            Recoverable: false
            Details: No ICA configured for clientID
    BadRequestExample:
      value:
        Errors:
          Error:
          - Source: Validation
            ReasonCode: ICA_VALUE_REQUIRED
            Description: ICA required for ABU client eligibility validation.
            Recoverable: false
            Details: ICA is mandatory.
    SubscriptionAccountInquirySubscribed:
      value:
        subscribed: true
    AccountInquiryAccountUpdate:
      value:
        responseIndicator: ACCOUNT_UPDATE
        account:
          number: '5573491171029999'
          expiry: '1221'
    AccountInquiryExpiry:
      value:
        responseIndicator: EXPIRY
        account:
          number: '5573491171027315'
          expiry: '1221'
    AccountInquiryUnknown:
      value:
        responseIndicator: UNKNOWN
    AccountInquiryNonParticipating:
      value:
        responseIndicator: NON_PARTICIPATING
    SubscriptionAccountInquiryNotSubscribed:
      value:
        subscribed: false
    AccountInquiryValid:
      value:
        responseIndicator: VALID
    AccountInquiryContact:
      value:
        responseIndicator: CONTACT
  responses:
    UnauthorizedErrorResponse:
      description: Authentication information was missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            UnauthorizedExample:
              $ref: '#/components/examples/UnauthorizedExample'
    SubscriptionInquiryResponse:
      description: The status of a subscription inquiry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OutSubscriptionInquiry'
          examples:
            Subscribed:
              $ref: '#/components/examples/SubscriptionAccountInquirySubscribed'
            Not Subscribed:
              $ref: '#/components/examples/SubscriptionAccountInquiryNotSubscribed'
    BadRequestErrorResponse:
      description: Something was wrong with the request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            BadRequestExample:
              $ref: '#/components/examples/BadRequestExample'
    InquiryResponse:
      description: Customer account inquiry response, account will only be populated if response indicator is of type  `EXPIRY` or `ACCOUNT_UPDATE`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OutInquiry'
          examples:
            Valid:
              $ref: '#/components/examples/AccountInquiryValid'
            Unknown:
              $ref: '#/components/examples/AccountInquiryUnknown'
            Non Participating:
              $ref: '#/components/examples/AccountInquiryNonParticipating'
            Contact:
              $ref: '#/components/examples/AccountInquiryContact'
            Expiry:
              $ref: '#/components/examples/AccountInquiryExpiry'
            Account Update:
              $ref: '#/components/examples/AccountInquiryAccountUpdate'
  requestBodies:
    InquiryRequest:
      description: ABU Integrator sends request to inquire on the account for a specific account.
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Inquiry'
    SubscriptionInquiryRequest:
      description: ABU Integrator subscription request to inquire on a subscription for an account number.
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SubscriptionInquiry'