Mastercard Mastercard API

openapi: 3.2.0
info:
  title: Suspected Fraud Mastercard API
  description: The Suspected Fraud application sends a potentially fraudulent transaction for review to the relevant issuer to determine if the suspected transaction is fraudulent or valid. After the issuer's investigation, the application validates the transaction(s) as Confirmed Fraud or Confirmed Not Fraud.
  contact:
    name: API Support
    email: apisupport@mastercard.com
    url: https://developer.mastercard.com/support
  version: 1.2.11
servers:
- url: https://api.mastercard.com/fld/suspected-frauds
  description: Global Production server (uses live data)
- url: https://api.mastercard.co.in/fld/suspected-frauds
  description: India Production server (uses live data)
- url: https://sandbox.api.mastercard.com/fld/suspected-frauds
  description: Global Sandbox server (testing environment)
- url: https://sandbox.api.mastercard.co.in/fld/suspected-frauds
  description: India Sandbox server (testing environment)
tags:
- name: Mastercard
paths:
  /mastercard-frauds:
    post:
      tags:
      - Mastercard
      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
    put:
      tags:
      - Mastercard
      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:
    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'
    BadRequestError:
      description: Something was wrong with the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            BadRequestRefIdMissing:
              $ref: '#/components/examples/BadRequestRefIdMissing'
    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'
    RateLimitExceededError:
      description: Too Many Requests.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            RateLimitExceededExample:
              $ref: '#/components/examples/RateLimitExceededExample'
    UnauthorizedError:
      description: Unauthorized request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            UnauthorizedExample:
              $ref: '#/components/examples/UnauthorizedExample'
    ForbiddenError:
      description: Consent not given.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            ForbiddenExample:
              $ref: '#/components/examples/ForbiddenExample'
  examples:
    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.'
    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
    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.
    ForbiddenExample:
      value:
        Errors:
          Error:
          - Source: FLD
            ReasonCode: CONSENT_NOT_GIVEN
            Description: User Consent Not Given
            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
    BadRequestRefIdMissing:
      value:
        Errors:
          Error:
          - Source: FLD
            ReasonCode: VALIDATION_ERROR
            Description: Reference Id is not provided.
            Recoverable: false
    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
    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
    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.
    200SuspectedFraudDataChanged:
      value:
        refId: ecb2d942-eabd-42b6-87fd-69c19692bdc6
        timestamp: '2021-03-16T20:34:40'
        responseCode: '000'
        responseMessage: Success
        icaNumber: '1076'
        currentStatus: SUSPECTED-SUCCESS
    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.
    UnauthorizedExample:
      value:
        Errors:
          Error:
          - Source: FLD
            ReasonCode: UNAUTHORIZED_REQUEST
            Description: Unauthorized request
            Recoverable: false
  schemas:
    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
    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'
    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
    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
    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: []
    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
    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
    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'
    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
    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
    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
    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
  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'
    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'