Mastercard Suspected Fraud Management API

swagger: '2.0'
info:
  title: Mastercard Bill Payment Validator Account Opening Suspected  Fraud  Management 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: Suspected  Fraud  Management
paths:
  /mastercard-frauds:
    put:
      tags:
      - Suspected  Fraud  Management
      operationId: updateSuspectedFraud
      description: This endpoint allows the initiator to change an existing suspected fraud record using minimal input parameters for Mastercard built transactions. The initiator can modify both successful and rejected suspected fraud transactions and also modify transactions which are submitted via other channels Online and API.
      summary: Change an Existing Suspected Fraud Record Using Minimal Input Parameters for Mastercard Built Transactions.
      x-mastercard-api-encrypted: true
      requestBody:
        $ref: '#/components/requestBodies/SuspectedFraudChangeRequest'
      responses:
        '200':
          $ref: '#/components/responses/SuspectedFraudChangeResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '429':
          $ref: '#/components/responses/RateLimitExceededError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  responses:
    UnauthorizedError:
      description: Unauthorized request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            UnauthorizedExample:
              $ref: '#/components/examples/UnauthorizedExample'
    RateLimitExceededError:
      description: Too Many Requests.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            RateLimitExceededExample:
              $ref: '#/components/examples/RateLimitExceededExample'
    SuspectedFraudChangeResponse:
      description: Fraud data changed successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Fraud'
          examples:
            200SuspectedFraudDataChanged:
              $ref: '#/components/examples/200SuspectedFraudDataChanged'
            200SuspectedFraudDataChangeError:
              $ref: '#/components/examples/200SuspectedFraudDataChangeError'
    ForbiddenError:
      description: Consent not given.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            ForbiddenExample:
              $ref: '#/components/examples/ForbiddenExample'
    BadRequestError:
      description: Something was wrong with the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            BadRequestRefIdMissing:
              $ref: '#/components/examples/BadRequestRefIdMissing'
  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'.
          example: '2022-05-24T20:34:37'
          maxLength: 19
          minLength: 19
          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
    SafeFraudProvider:
      description: Indicates the originator of the request. Value 10 is for Issuer and 20 for Acquirer.
      example: '10'
      minLength: 2
      maxLength: 2
      pattern: ^(10|20)
      type: string
    Initiator:
      description: Indicates who has submitted the transaction. If only Issuer submitted the transaction then value of this field will be 'ISSUER'. If only Acquirer submitted the transaction then value of this field will be 'ACQUIRER'. If both the parties have submitted the transaction then the value of this field will be 'BOTH'.
      example: BOTH
      minLength: 4
      maxLength: 8
      pattern: ^(ISSUER|ACQUIRER|BOTH)
      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
      type: object
      required:
      - Errors
      properties:
        Errors:
          $ref: '#/components/schemas/Errors'
    CardInPossession:
      description: Flag to indicate if the card holder was in possession of the card at the time the fraud occurred. Possible values are 'Y', 'N' and 'U' (for Unknown). This field is required for Issuer and optional for Acquirer. This is a conditional parameter and is mandatory when operationType value is CONFIRMED_FRAUD.
      example: N
      maxLength: 1
      minLength: 1
      pattern: ^(U|Y|N)
      type: string
    SuspectedFraudChange:
      allOf:
      - $ref: '#/components/schemas/APIDataElement'
      type: object
      required:
      - providerId
      - auditControlNumber
      properties:
        providerId:
          $ref: '#/components/schemas/SafeFraudProvider'
        auditControlNumber:
          description: Unique number generated by FLD application and provided in the response message for a successful suspected fraud record submission (FDA event). This is used as a reference to subsequently modify, delete or convert a suspended to a confirmed fraud record.
          example: '418142102142002'
          minLength: 15
          maxLength: 15
          type: string
        fraudPostedDate:
          description: Date on which the fraud is posted in FLD by the originator. Format is 'YYYYMMDD'.
          example: '20210120'
          minLength: 8
          maxLength: 8
          pattern: ^\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$
          type: string
        fraudTypeCode:
          description: Code identifying the reason the originator submitted the transaction as fraud in FLD. Please refer to [TBD - Table 1](https://developer.mastercard.com/) for possible values.
          example: '04'
          minLength: 2
          maxLength: 2
          type: string
        accountDeviceType:
          description: Indicates if the account uses a magnetic stripe, chip, pin, contactless or any combination thereof. Please refer to [Table 3](https://developer.mastercard.com/fld-fraud-submission/documentation/parameters/annexure-1/#table-3-account-device-type-codes) for possible values. This field is required for Issuer and optional for Acquirer.
          example: '1'
          minLength: 1
          maxLength: 1
          type: string
        cardholderReportedDate:
          description: Date on which the cardholder had reported the fraud. Format is 'YYYYMMDD'.
          example: '20210118'
          minLength: 8
          maxLength: 8
          pattern: ^\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$
          type: string
        cardInPossession:
          $ref: '#/components/schemas/CardInPossession'
        memo:
          description: Brief description by the originator providing some comment supporting the action.
          example: This is a sample FDC minimal request.
          minLength: 1
          maxLength: 1000
          type: string
    Errors:
      title: Errors
      type: object
      required:
      - Error
      properties:
        Error:
          description: Errors array wrapped in an error object.
          items:
            $ref: '#/components/schemas/Error'
          type: array
          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.
          example: '200'
          maxLength: 3
          minLength: 3
          type: string
        responseMessage:
          description: Transaction response description corresponding to the response code.
          example: Success
          maxLength: 100
          minLength: 1
          type: string
        auditControlNumber:
          description: Unique number generated by FLD application and provided in the response message for a successful suspended 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.
          example: '418142102142002'
          maxLength: 15
          minLength: 15
          type: string
        confirmedAuditControlNumber:
          description: Unique number generated by FLD application and provided in the response message for a successful fraud record conversion from Suspected to Confirm fraud. This is used as a reference in the request API to subsequently modify, delete and other operations on confirmed fraud record and is echoed back. This attribute will be absent if the request is not processed by FLD application.
          example: '418142102142023'
          maxLength: 15
          minLength: 15
          type: string
        previousStatus:
          description: Previous status of the transaction in terms of an FDC, FDD and FDE event.
          example: SUSPECTED-SUCCESS
          minLength: 1
          maxLength: 50
          type: string
        currentStatus:
          description: Current status of the transaction in terms of an FDA, FDC, FDD and FDE event.
          example: SUSPECTED-CONFIRMED-SUCCESS
          minLength: 1
          maxLength: 50
          type: string
        channel:
          description: Fraud request submission fld channel name. The value of the channel can be API or ONLINE_PORTAL
          example: API
          minLength: 3
          maxLength: 30
          type: string
        submissionStatus:
          description: Indicates the submission status of the suspected transaction.
          example: NEW
          minLength: 1
          maxLength: 50
          type: string
        fraudOriginator:
          $ref: '#/components/schemas/Initiator'
        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.
          example: M
          minLength: 1
          maxLength: 1
          type: string
        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.
          example: DECLINED
          minLength: 1
          maxLength: 20
          type: string
        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.
          example: 05 - Do not honor
          minLength: 1
          maxLength: 200
          type: string
        errorDetails:
          $ref: '#/components/schemas/ErrorWrapper'
    APIDataElement:
      type: object
      required:
      - icaNumber
      - refId
      - timestamp
      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'.
          example: '2022-05-24T20:34:37'
          maxLength: 19
          minLength: 19
          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
    Error:
      title: ErrorMessage
      type: object
      required:
      - Description
      - ReasonCode
      - Recoverable
      - Source
      properties:
        Source:
          description: The application or component that generated this error.
          example: FLD
          maxLength: 50
          minLength: 3
          type: string
        ReasonCode:
          description: Reason code is a unique constant identifying the error case encountered during request processing.
          example: VALIDATION_ERROR
          maxLength: 100
          minLength: 5
          type: string
        Description:
          description: Human-readable short description of the reasonCode.
          example: Reference Id is not provided.
          maxLength: 250
          minLength: 10
          type: string
        Details:
          description: Optional detailed description provides information about data received and calculated during request processing. This helps the user to diagnose errors.
          example: This is mandatory field while requesting for fraud submission.
          maxLength: 1000
          minLength: 0
          type: string
        Recoverable:
          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: true
          type: boolean
  examples:
    UnauthorizedExample:
      value:
        Errors:
          Error:
          - Source: FLD
            ReasonCode: UNAUTHORIZED_REQUEST
            Description: Unauthorized request
            Recoverable: false
    RateLimitExceededExample:
      value:
        Errors:
          Error:
          - Source: FLD
            ReasonCode: RATE_LIMIT_EXCEEDED
            Description: You have exceeded the service rate limit. Maximum allowed 10 TPS.
            Recoverable: true
    200SuspectedFraudDataChanged:
      value:
        refId: ecb2d942-eabd-42b6-87fd-69c19692bdc6
        timestamp: '2021-03-16T20:34:40'
        responseCode: '000'
        responseMessage: Success
        icaNumber: '1076'
        currentStatus: SUSPECTED-SUCCESS
    BadRequestRefIdMissing:
      value:
        Errors:
          Error:
          - Source: FLD
            ReasonCode: VALIDATION_ERROR
            Description: Reference Id is not provided.
            Recoverable: false
    200SuspectedFraudDataChangeError:
      value:
        refId: ecb2d942-eabd-42b6-87fd-69c19692bdc6
        timestamp: '2021-03-16T20:34:40'
        responseCode: '100'
        responseMessage: Failure
        errorDetails:
          Errors:
            Error:
            - ReasonCode: '60003'
              Description: icaNumber incorrect datatype of attribute value.
    ForbiddenExample:
      value:
        Errors:
          Error:
          - Source: FLD
            ReasonCode: CONSENT_NOT_GIVEN
            Description: User Consent Not Given
            Recoverable: false
    SuspectedFraudChangeExample:
      value:
        refId: ecb2d942-eabd-42b6-87fd-69c19692bdc6
        timestamp: '2021-03-16T20:34:37'
        icaNumber: '1076'
        providerId: '10'
        auditControlNumber: '123111111000025'
        fraudPostedDate: '20210316'
        fraudTypeCode: '01'
        accountDeviceType: '1'
        cardholderReportedDate: '20210314'
        cardInPossession: U
        memo: This is a sample FDC minimal request.
  requestBodies:
    SuspectedFraudChangeRequest:
      description: Change an existing fraud record using minimal input parameters for Mastercard built transactions.
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SuspectedFraudChange'
          examples:
            SuspectedFraudChangeExample:
              $ref: '#/components/examples/SuspectedFraudChangeExample'