swagger: '2.0'
info:
  title: Mastercard Bill Payment Validator Account Opening Ica 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: Ica
paths:
  /fraud-statuses/icas/{ica}:
    get:
      tags:
      - Ica
      operationId: fraudRequestStatus
      description: This endpoint allows the initiator to get the status of an existing fraud record using combination of ICA, Ref ID & ACN, for both Mastercard and Issuer built transactions. The initiator can get status of fraud transaction submitted via any channel GFT, File upload, Online & API.
      summary: Get Status of an Existing Fraud Record for Both Mastercard and Issuer Built Transactions.
      parameters:
      - $ref: '#/components/parameters/ICA'
      - $ref: '#/components/parameters/Ref_Id'
      - $ref: '#/components/parameters/ACN'
      responses:
        '200':
          $ref: '#/components/responses/FraudStatusResponse'
        '400':
          $ref: '#/components/responses/FraudStatusBadRequestError'
        '429':
          $ref: '#/components/responses/RateLimitExceededError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    FraudBase:
      type: object
      properties:
        refId:
          description: Unique identification generated by the transaction originator using UUID logic to unambiguously link a request and response message.
          example: ecb2d942-eabd-42b6-87fd-69c19692bdc6
          maxLength: 36
          minLength: 36
          type: string
        timestamp:
          description: Timestamp of the request initiation by the originator in the format 'YYYY-MM-DDThh:mm:ss:mmm+hh:mm'. The value of '+hh:mm' portion should always be '-05:00' or '-06:00' reflecting CST time.
          example: '2022-05-24T20:34:37+6:00'
          maxLength: 25
          minLength: 25
          type: string
        icaNumber:
          description: ICA number of the Issuer or Acquirer or Provider initiating the fraud submission request.
          example: '1076'
          maxLength: 7
          minLength: 3
          type: string
    ErrorWrapper:
      description: Object containing the list of combination of error reason codes and their corresponding description (can provide up to 5 errors for a record). It will be absent if the request is processed by FLD application successfully.
      title: Error Response
      required:
      - Errors
      type: object
      properties:
        Errors:
          $ref: '#/components/schemas/Errors'
    Errors:
      title: Errors
      required:
      - Error
      type: object
      properties:
        Error:
          type: array
          description: Errors array wrapped in an error object
          items:
            $ref: '#/components/schemas/Error'
          example: []
    Fraud:
      allOf:
      - $ref: '#/components/schemas/FraudBase'
      - type: object
        required:
        - responseCode
        - responseMessage
        properties:
          responseCode:
            description: Response code indicating success or failure of the transaction at an API level. Errors at a record level will be handled through 'errorDetails' element associated with each record.
            type: string
            minLength: 3
            maxLength: 3
            example: '000'
          responseMessage:
            description: Transaction response description corresponding to the response code.
            type: string
            minLength: 1
            maxLength: 100
            example: Success
          icaNumber:
            description: ICA number of the originator provided in the request API which is echoed back. This attribute will be absent if the request is not processed by FLD application.
            type: string
            minLength: 3
            maxLength: 7
            example: '1076'
          auditControlNumber:
            description: Unique number generated by FLD application and provided in the response message for a successful fraud record submission ('FDA' event). This is used as a reference in the request API to subsequently modify, delete or convert a suspended to a confirmed fraud record and is echoed back. This attribute will be absent if the request is not processed by FLD application.
            type: string
            minLength: 15
            maxLength: 15
            example: '418142102142002'
          duplicateAuditControlNumbers:
            description: List of existing Audit Control Number which matches the request submitted for Mastercard-built or Issuer-built. This attribute will appear in case of the records already present while trying to submit or update the existing record.
            type: array
            items:
              type: string
            minItems: 1
            maxItems: 5
            uniqueItems: true
          matchLevelIndicator:
            description: Indicates if it is a Mastercard-built or Issuer-built record. Possible values are 'M' for Mastercard built record and 'I' for Issuer built record. This attribute will be absent if the request is not processed by FLD application.
            type: string
            minLength: 1
            maxLength: 1
            example: M
          financialTransactionIndicator:
            description: Indicates if the fraud record is being submitted against a financial transaction (having a clearing record) or a declined auth transaction (without a clearing record). Possible values are 'APPROVED' for financial transactions (having a clearing record) and 'DECLINED' for declined auth transactions (without a clearing record). This attribute will be absent if the request is not processed by FLD application.
            type: string
            minLength: 1
            maxLength: 20
            example: DECLINED
          authorizationResponse:
            description: Provides the 'Auth Response Code' and 'Auth Response Code Description' combination if 'Financial Transaction Indicator' value is 'DECLINED'. This attribute will be absent for all other scenarios.
            type: string
            minLength: 1
            maxLength: 200
            example: 05 - Do not honor
          previousStatus:
            description: Previous status of the transaction in terms of an FDC, FDD and FDE event.
            type: string
            minLength: 1
            maxLength: 50
            example: CONFIRMED-REJECTED
          currentStatus:
            description: Current status of the transaction in terms of an FDA, FDC, FDD and FDE event.
            type: string
            minLength: 1
            maxLength: 50
            example: CONFIRMED-SUCCESS
          channel:
            description: Fraud request submission fld channel name.
            type: string
            minLength: 1
            maxLength: 50
            example: Online
          errorDetails:
            $ref: '#/components/schemas/ErrorWrapper'
    Error:
      title: ErrorMessage
      required:
      - Description
      - ReasonCode
      type: object
      properties:
        Source:
          type: string
          description: The application or component that generated this error.
          minLength: 3
          maxLength: 50
          example: FLD
        ReasonCode:
          type: string
          description: Reason code is a unique constant identifying the error case encountered during request processing.
          minLength: 5
          maxLength: 100
          example: VALIDATION_ERROR
        Description:
          type: string
          description: Human-readable short description of the reasonCode
          minLength: 10
          maxLength: 250
          example: Reference Id is not provided
        Details:
          type: string
          description: Optional detailed description provides information about data received and calculated during request processing.  This helps the user to diagnose errors.
          minLength: 0
          maxLength: 1000
          example: This is mandatory field while requesting for fraud submission.
        Recoverable:
          type: boolean
          description: Recoverable flag indicates whether this error is always returned for this request, or retrying could change the outcome.  For example, 'true' or 'false'.
          example: false
  parameters:
    ACN:
      name: acn
      in: query
      schema:
        type: string
        minLength: 15
        maxLength: 15
        example: '418142102142002'
      description: Refers to the ACN of the fraud record whose status is to be fetched. This is optional parameter for record submitted through APIs.
    ICA:
      name: ica
      in: path
      required: true
      schema:
        type: string
        minLength: 3
        maxLength: 7
      example: '1076'
      description: Refers to the ICA of the fraud record which needs to be searched for its status. It is mandatory parameter along with Ref ID or ACN..
    Ref_Id:
      name: ref_id
      in: query
      schema:
        type: string
        minLength: 36
        maxLength: 36
        example: ecb2d942-eabd-42b6-87fd-69c19692bdc6
      description: Refers to the reference ID of the API call which was used to submit fraud record. This is optional parameter if ACN is present in the request.
  examples:
    RateLimitExceededExample:
      value:
        Errors:
          Error:
          - Source: fld
            ReasonCode: RATE_LIMIT_EXCEEDED
            Description: You have exceeded the service rate limit. Maximum allowed 10 TPS.
            Recoverable: true
            details: null
    FraudStatusNoParamRefIdAcnExample:
      value:
        ica: '1076'
        responseCode: '100'
        responseMessage: Failure
        errorDetails:
          Errors:
            Error:
            - ReasonCode: '60002'
              Description: ref_id or acn (Audit Control Number) attribute or attribute value is missing or incorrect.
    BadRequestInvalidRefId:
      value:
        Errors:
          Error:
          - Source: fld
            ReasonCode: VALIDATION_ERROR
            Description: ref_id incorrect datatype of attribute value.
            Recoverable: false
    BadRequestInvalidIca:
      value:
        Errors:
          Error:
          - Source: fld
            ReasonCode: VALIDATION_ERROR
            Description: ica incorrect datatype of attribute value.
            Recoverable: false
    BadRequestInvalidACN:
      value:
        Errors:
          Error:
          - Source: fld
            ReasonCode: VALIDATION_ERROR
            Description: acn (Audit Control Number) incorrect datatype of attribute value.
            Recoverable: false
    FraudStatusConfirmed:
      value:
        refId: ecb2d942-eabd-42b6-87fd-69c19692bdc6
        timestamp: '2021-03-16T20:34:40-06:00'
        icaNumber: '1076'
        responseCode: '000'
        responseMessage: Success
        auditControlNumber: '123111111000025'
        channel: EXT_API
        currentStatus: CONFIRMED-SUCCESS
        matchLevelIndicator: M
        financialTransactionIndicator: DECLINED
        authorizationResponse: 05 - Do not honor
    FraudStatusNoRecordExample:
      value:
        refId: ecb2d942-eabd-42b6-87fd-69c19692bdc6
        timestamp: '2021-03-16T20:34:40-06:00'
        responseCode: '200'
        responseMessage: Failure
        auditControlNumber: '123111111000025'
        errorDetails:
          Errors:
            Error:
            - ReasonCode: '60127'
              Description: Record searched could not be found. Correct the input parameter and resubmit.
    FraudStatusSuspended:
      value:
        refId: ecb2d942-eabd-42b6-87fd-69c19692bdc6
        timestamp: '2021-03-16T20:34:40-06:00'
        icaNumber: '1076'
        responseCode: '000'
        responseMessage: Success
        auditControlNumber: '123111111000025'
        channel: EXT_API
        currentStatus: CONFIRMED-SUSPENDED
        errorDetails:
          Errors:
            Error:
            - ReasonCode: '30100'
              Description: Potential Duplicate Data Found, Record is suspended.
    FraudStatusDeleted:
      value:
        refId: ecb2d942-eabd-42b6-87fd-69c19692bdc6
        timestamp: '2021-03-16T20:34:40-06:00'
        icaNumber: '1076'
        responseCode: '000'
        responseMessage: Success
        auditControlNumber: '123111111000025'
        channel: EXT_API
        currentStatus: CONFIRMED-DELETED
    FraudStatusRejected:
      value:
        timestamp: '2021-03-16T20:34:40-06:00'
        icaNumber: '1076'
        responseCode: '000'
        responseMessage: Success
        auditControlNumber: '123111111000025'
        channel: Online
        currentStatus: CONFIRMED-REJECTED
        errorDetails:
          Errors:
            Error:
            - ReasonCode: '20806'
              Description: Required field [Fraud Posted Date] is missing. Record is rejected.
            - ReasonCode: '20828'
              Description: Required field [Fraud Type Code] is missing. Record is rejected.
            - ReasonCode: '20903'
              Description: Audit control number (ACN) is not unique. Record is rejected.
            - ReasonCode: '21006'
              Description: Invalid Fraud Posted Date, format should be YYYYMMDD. Record is rejected.
            - ReasonCode: '41200'
              Description: Unable to match transaction in data warehouse. Record is rejected.
  responses:
    RateLimitExceededError:
      description: Too Many Requests.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            RateLimitExceededExample:
              $ref: '#/components/examples/RateLimitExceededExample'
    FraudStatusBadRequestError:
      description: Something was wrong with the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            BadRequestInvalidIca:
              $ref: '#/components/examples/BadRequestInvalidIca'
            BadRequestInvalidRefId:
              $ref: '#/components/examples/BadRequestInvalidRefId'
            BadRequestInvalidACN:
              $ref: '#/components/examples/BadRequestInvalidACN'
    FraudStatusResponse:
      description: Fraud request status in the system.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Fraud'
          examples:
            FraudStatusConfirmed:
              $ref: '#/components/examples/FraudStatusConfirmed'
            FraudStatusSuspended:
              $ref: '#/components/examples/FraudStatusSuspended'
            FraudStatusDeleted:
              $ref: '#/components/examples/FraudStatusDeleted'
            FraudStatusRejected:
              $ref: '#/components/examples/FraudStatusRejected'
            FraudStatusNoRecordExample:
              $ref: '#/components/examples/FraudStatusNoRecordExample'
            FraudStatusNoParamRefIdAcnExample:
              $ref: '#/components/examples/FraudStatusNoParamRefIdAcnExample'