Mastercard
Mastercard Suspected Fraud Submission API

The Suspected Fraud Submission API from Mastercard — 1 operation(s) for suspected fraud submission.
Documentation GitHub OpenAPI
OpenAPI Specification

swagger: '2.0'
info:
  title: Mastercard Bill Payment Validator Account Opening Suspected  Fraud  Submission 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  Submission
paths:
  /mastercard-frauds:
    post:
      tags:
      - Suspected  Fraud  Submission
      operationId: submitSuspectedFraud
      description: This endpoint allows the initiator to add a new suspected fraud record using minimal input parameters for Mastercard built transactions. To submit a transaction as suspected fraud, a match has to be found in the Mastercard transaction data repository(Data Warehouse).
      summary: Add a New Suspected Fraud Record Using Minimal Input Parameters for Mastercard Built Transactions.
      x-mastercard-api-encrypted: true
      requestBody:
        $ref: '#/components/requestBodies/SuspectedFraudRequest'
      responses:
        '201':
          $ref: '#/components/responses/SuspectedFraudResponse'
        '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'
    SuspectedFraudResponse:
      description: Fraud submitted successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Fraud'
          examples:
            200SuspectedFraudDataAdded:
              $ref: '#/components/examples/200SuspectedFraudDataAdded'
            200SuspectedFraudDataAddedByAcquirer:
              $ref: '#/components/examples/200SuspectedFraudDataAddedByAcquirer'
            200SuspectedFraudDataAddedByIssuer:
              $ref: '#/components/examples/200SuspectedFraudDataAddedByIssuer'
            200SuspectedFraudDataAddError:
              $ref: '#/components/examples/200SuspectedFraudDataAddError'
    RateLimitExceededError:
      description: Too Many Requests.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            RateLimitExceededExample:
              $ref: '#/components/examples/RateLimitExceededExample'
    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
    SuspectedFraud:
      allOf:
      - $ref: '#/components/schemas/APIDataElement'
      type: object
      required:
      - cardNumber
      - fraudPostedDate
      - fraudTypeCode
      - providerId
      - transactionAmount
      - transactionDate
      - transactionIdentifiers
      properties:
        providerId:
          $ref: '#/components/schemas/SafeFraudProvider'
        transactionIdentifiers:
          $ref: '#/components/schemas/TransactionIdentifier'
        cardNumber:
          description: Cardholder account number used in the fraudulent transaction. Card number to be verified through Luhn's algorithm.
          example: '5505135664572870000'
          maxLength: 19
          minLength: 12
          type: string
        transactionAmount:
          description: Transaction amount at the merchant location (without any decimals).
          example: '10350'
          maxLength: 12
          minLength: 1
          type: string
        transactionDate:
          description: Local date at the merchant location when the transaction occurred. Format is 'YYYYMMDD'.
          example: '20210115'
          maxLength: 8
          minLength: 8
          pattern: ^\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$
          type: string
        fraudPostedDate:
          description: Date on which the fraud is posted in FLD by the originator. Format is 'YYYYMMDD'.
          example: '20210120'
          maxLength: 8
          minLength: 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: '01'
          maxLength: 2
          minLength: 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'
          maxLength: 1
          minLength: 1
          type: string
        cardholderReportedDate:
          description: Date on which the cardholder had reported the fraud. Format is 'YYYYMMDD'.
          example: '20210118'
          maxLength: 8
          minLength: 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 FDA minimal request.
          maxLength: 1000
          minLength: 1
          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
    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'
    TransactionIdentifier:
      description: Contains the a single or dual message transaction identifier values used for searching the respective transaction. Acquirer Reference Number, Banknet Reference Number, Trace Id and Serial Id values are captured.
      type: object
      properties:
        acqRefNum:
          description: Contains Acquirer Reference Number for a transaction.
          example: '01111114365000000011327'
          minLength: 23
          maxLength: 23
          type: string
        banknetRefNum:
          description: Contains Banknet Reference Number for a transaction.
          example: 756QR7
          minLength: 6
          maxLength: 9
          type: string
        traceId:
          description: Contains Trace Id  for a transaction.
          example: '650099'
          minLength: 6
          maxLength: 6
          type: string
        serialId:
          description: Contains Serial Id for a transaction.
          example: '550000099'
          minLength: 9
          maxLength: 9
          type: string
    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
    200SuspectedFraudDataAddedByIssuer:
      value:
        refId: ecb2d942-eabd-42b6-87fd-69c19692bdc6
        timestamp: '2021-03-16T20:34:40'
        responseCode: '000'
        responseMessage: Success
        icaNumber: '1076'
        auditControlNumber: '123111111000025'
        currentStatus: SUSPECTED-SUCCESS
        fraudOriginator: ACQUIRER
    200SuspectedFraudDataAddError:
      value:
        refId: ecb2d942-eabd-42b6-87fd-69c19692bdc6
        timestamp: '2021-03-16T20:34:40'
        responseCode: '100'
        responseMessage: Failure
        errorDetails:
          Errors:
            Error:
            - ReasonCode: '60004'
              Description: 'CardNumber attribute value length not in range. Minimum Length:12 and Maximum Length: 19.'
    200SuspectedFraudDataAddedByAcquirer:
      value:
        refId: ecb2d942-eabd-42b6-87fd-69c19692bdc6
        timestamp: '2021-03-16T20:34:40'
        responseCode: '000'
        responseMessage: Success
        icaNumber: '1076'
        auditControlNumber: '123111111000025'
        currentStatus: SUSPECTED-SUCCESS
        fraudOriginator: ISSUER
    BadRequestRefIdMissing:
      value:
        Errors:
          Error:
          - Source: FLD
            ReasonCode: VALIDATION_ERROR
            Description: Reference Id is not provided.
            Recoverable: false
    SuspectedFraudExample:
      value:
        refId: ecb2d942-eabd-42b6-87fd-69c19692bdc6
        timestamp: '2021-03-16T20:34:37'
        icaNumber: '1076'
        providerId: '10'
        transactionIdentifiers:
          acqRefNum: '01111114365000000011327'
          banknetRefNum: 756QR7
          traceId: '650099'
          serialId: '550000099'
        cardNumber: '5505135664572870008'
        transactionAmount: '5505'
        transactionDate: '20200713'
        fraudPostedDate: '20210316'
        fraudTypeCode: '01'
        accountDeviceType: '1'
        cardholderReportedDate: '20210314'
        cardInPossession: U
        memo: This is a sample FDA minimal request.
    200SuspectedFraudDataAdded:
      value:
        refId: ecb2d942-eabd-42b6-87fd-69c19692bdc6
        timestamp: '2021-03-16T20:34:40'
        responseCode: '000'
        responseMessage: Success
        icaNumber: '1076'
        auditControlNumber: '123111111000025'
        currentStatus: SUSPECTED-SUCCESS
    ForbiddenExample:
      value:
        Errors:
          Error:
          - Source: FLD
            ReasonCode: CONSENT_NOT_GIVEN
            Description: User Consent Not Given
            Recoverable: false
  requestBodies:
    SuspectedFraudRequest:
      description: Add a new suspected fraud record using minimal input parameters for Mastercard built transactions.
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SuspectedFraud'
          examples:
            SuspectedFraudExample:
              $ref: '#/components/examples/SuspectedFraudExample'
Mastercard Suspected Fraud Submission API

Documentation

Specifications

Code Examples

Other Resources

OpenAPI Specification
