Mastercard · Schema

Mastercard Fraud Alert

A fraud alert or confirmed fraud record within the Mastercard ecosystem. Covers both confirmed fraud submissions to the Fraud and Loss Database (FLD), suspected fraud reports, and Ethoca Alerts for collaborative fraud resolution between merchants, acquirers, and issuers.

Credit CardsDigital IdentityFinancial ServicesFraud DetectionOpen BankingPaymentsFortune 500

Properties

Name	Type	Description
alertId	string	Unique identifier for the fraud alert. For Ethoca alerts, this is a 25-character identifier generated by Ethoca.
alertType	string	Classification of the fraud alert indicating its source and certainty level.
alertSource	string	The source system or channel through which the fraud was reported.
refId	string	Unique identification generated by the transaction originator using UUID logic to link request and response messages.
timestamp	string	Timestamp of the fraud report initiation in ISO 8601 format with timezone offset.
icaNumber	string	ICA number of the issuer or acquirer initiating the fraud submission.
acquirerId	string	Acquirer ICA number for the transaction being reported as fraud.
cardNumber	string	Primary Account Number (PAN) used in the fraudulent transaction. Must pass Luhn algorithm validation.
cardProductCode	string	Three-character code identifying the card product type used in the fraudulent transaction.
transactionDate	string	Local date at the merchant location when the fraudulent transaction occurred, in YYYYMMDD format.
transactionAmount	string	Transaction amount at the merchant location without decimal separators.
transactionCurrencyCode	string	ISO 4217 numeric currency code for the transaction amount.
billingAmount	string	Amount on the cardholder statement in billing currency, without decimals.
billingCurrencyCode	string	ISO 4217 numeric currency code for the billing amount.
settlementDate	string	Settlement date of the reported transaction, in YYYYMMDD format.
fraudTypeCode	string	Two-character code identifying the reason the transaction was submitted as fraud (e.g., 01=Lost Card, 02=Stolen Card, 03=Never Received Issue, 04=Fraudulent Application, 05=Counterfeit).
fraudSubTypeCode	string	Single-character code further identifying the fraud reason (e.g., U=Unknown). Mandatory for issuers, optional for acquirers.
fraudPostedDate	string	Date the fraud was posted in FLD by the originator, in YYYYMMDD format. Defaults to system date if not provided.
cardholderReportedDate	string	Date the cardholder reported the fraud, in YYYYMMDD format.
accountDeviceType	string	Indicates if the account uses magnetic stripe, chip, PIN, contactless, or combinations thereof.
cardInPossession	string	Flag indicating if the cardholder was in possession of the card when the fraud occurred. Values: Y (Yes), N (No), U (Unknown).
issuerSCAExemption	string	Issuer Strong Customer Authentication (SCA) Exemption value indicating why SCA was not applied.
transactionIdentifiers	array	One or more identifiers used to locate the transaction in the Mastercard Data Warehouse.
merchant	object
terminal	object
outcome	object
avsResponseCode	string	Address Verification Service response code from the authorization request.
authResponseCode	string	Authorization response code indicating the result of the authorization request.
cvcInvalidIndicator	string	Indicates whether the Card Verification Code was invalid.
memo	string	Brief description by the originator providing context for the fraud report.
providerId	string	Identifier for the fraud data provider (e.g., SafeFraud provider).

View JSON Schema on GitHub

JSON Schema

{
  "$id": "https://github.com/api-evangelist/mastercard/blob/main/json-schema/fraud-alert.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Mastercard Fraud Alert",
  "description": "A fraud alert or confirmed fraud record within the Mastercard ecosystem. Covers both confirmed fraud submissions to the Fraud and Loss Database (FLD), suspected fraud reports, and Ethoca Alerts for collaborative fraud resolution between merchants, acquirers, and issuers.",
  "type": "object",
  "required": [
    "alertId",
    "alertType",
    "cardNumber",
    "transactionDate",
    "transactionAmount"
  ],
  "properties": {
    "alertId": {
      "type": "string",
      "description": "Unique identifier for the fraud alert. For Ethoca alerts, this is a 25-character identifier generated by Ethoca.",
      "minLength": 1,
      "maxLength": 36,
      "examples": ["A4IM9K2MIYL9F2BPF9TWUIXTU"]
    },
    "alertType": {
      "type": "string",
      "description": "Classification of the fraud alert indicating its source and certainty level.",
      "enum": [
        "CONFIRMED_FRAUD",
        "SUSPECTED_FRAUD",
        "ETHOCA_ALERT",
        "CUSTOMER_DISPUTE"
      ]
    },
    "alertSource": {
      "type": "string",
      "description": "The source system or channel through which the fraud was reported.",
      "enum": [
        "FLD_API",
        "FLD_FILE_UPLOAD",
        "FLD_ONLINE",
        "GFT",
        "ETHOCA"
      ]
    },
    "refId": {
      "type": "string",
      "description": "Unique identification generated by the transaction originator using UUID logic to link request and response messages.",
      "format": "uuid",
      "examples": ["ecb2d942-eabd-42b6-87fd-69c19692bdc6"]
    },
    "timestamp": {
      "type": "string",
      "description": "Timestamp of the fraud report initiation in ISO 8601 format with timezone offset.",
      "format": "date-time",
      "examples": ["2024-02-02T02:34:37-06:00"]
    },
    "icaNumber": {
      "type": "string",
      "description": "ICA number of the issuer or acquirer initiating the fraud submission.",
      "minLength": 3,
      "maxLength": 7,
      "examples": ["1076"]
    },
    "acquirerId": {
      "type": "string",
      "description": "Acquirer ICA number for the transaction being reported as fraud.",
      "minLength": 3,
      "maxLength": 7,
      "examples": ["5450"]
    },
    "cardNumber": {
      "type": "string",
      "description": "Primary Account Number (PAN) used in the fraudulent transaction. Must pass Luhn algorithm validation.",
      "pattern": "^[0-9]{12,19}$",
      "minLength": 12,
      "maxLength": 19,
      "examples": ["5505135664572870000"]
    },
    "cardProductCode": {
      "type": "string",
      "description": "Three-character code identifying the card product type used in the fraudulent transaction.",
      "minLength": 3,
      "maxLength": 3,
      "examples": ["MSI"]
    },
    "transactionDate": {
      "type": "string",
      "description": "Local date at the merchant location when the fraudulent transaction occurred, in YYYYMMDD format.",
      "pattern": "^\\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$",
      "minLength": 8,
      "maxLength": 8,
      "examples": ["20240115"]
    },
    "transactionAmount": {
      "type": "string",
      "description": "Transaction amount at the merchant location without decimal separators.",
      "pattern": "^[0-9]+$",
      "minLength": 1,
      "maxLength": 12,
      "examples": ["10350"]
    },
    "transactionCurrencyCode": {
      "type": "string",
      "description": "ISO 4217 numeric currency code for the transaction amount.",
      "pattern": "^[0-9]{3}$",
      "minLength": 3,
      "maxLength": 3,
      "examples": ["826"]
    },
    "billingAmount": {
      "type": "string",
      "description": "Amount on the cardholder statement in billing currency, without decimals.",
      "pattern": "^[0-9]+$",
      "minLength": 1,
      "maxLength": 12
    },
    "billingCurrencyCode": {
      "type": "string",
      "description": "ISO 4217 numeric currency code for the billing amount.",
      "pattern": "^[0-9]{3}$",
      "minLength": 3,
      "maxLength": 3
    },
    "settlementDate": {
      "type": "string",
      "description": "Settlement date of the reported transaction, in YYYYMMDD format.",
      "pattern": "^\\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$",
      "minLength": 8,
      "maxLength": 8
    },
    "fraudTypeCode": {
      "type": "string",
      "description": "Two-character code identifying the reason the transaction was submitted as fraud (e.g., 01=Lost Card, 02=Stolen Card, 03=Never Received Issue, 04=Fraudulent Application, 05=Counterfeit).",
      "minLength": 2,
      "maxLength": 2,
      "examples": ["04"]
    },
    "fraudSubTypeCode": {
      "type": "string",
      "description": "Single-character code further identifying the fraud reason (e.g., U=Unknown). Mandatory for issuers, optional for acquirers.",
      "minLength": 1,
      "maxLength": 1,
      "examples": ["U"]
    },
    "fraudPostedDate": {
      "type": "string",
      "description": "Date the fraud was posted in FLD by the originator, in YYYYMMDD format. Defaults to system date if not provided.",
      "pattern": "^\\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$",
      "minLength": 8,
      "maxLength": 8,
      "examples": ["20240120"]
    },
    "cardholderReportedDate": {
      "type": "string",
      "description": "Date the cardholder reported the fraud, in YYYYMMDD format.",
      "pattern": "^\\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$",
      "minLength": 8,
      "maxLength": 8,
      "examples": ["20240118"]
    },
    "accountDeviceType": {
      "type": "string",
      "description": "Indicates if the account uses magnetic stripe, chip, PIN, contactless, or combinations thereof.",
      "minLength": 1,
      "maxLength": 1,
      "examples": ["1"]
    },
    "cardInPossession": {
      "type": "string",
      "description": "Flag indicating if the cardholder was in possession of the card when the fraud occurred. Values: Y (Yes), N (No), U (Unknown).",
      "enum": ["Y", "N", "U"],
      "examples": ["N"]
    },
    "issuerSCAExemption": {
      "type": "string",
      "description": "Issuer Strong Customer Authentication (SCA) Exemption value indicating why SCA was not applied.",
      "minLength": 1,
      "maxLength": 2,
      "examples": ["09"]
    },
    "transactionIdentifiers": {
      "type": "array",
      "description": "One or more identifiers used to locate the transaction in the Mastercard Data Warehouse.",
      "items": {
        "$ref": "#/$defs/TransactionIdentifier"
      }
    },
    "merchant": {
      "$ref": "#/$defs/FraudMerchant"
    },
    "terminal": {
      "$ref": "#/$defs/FraudTerminal"
    },
    "outcome": {
      "$ref": "#/$defs/AlertOutcome"
    },
    "avsResponseCode": {
      "type": "string",
      "description": "Address Verification Service response code from the authorization request.",
      "minLength": 1,
      "maxLength": 1,
      "examples": ["U"]
    },
    "authResponseCode": {
      "type": "string",
      "description": "Authorization response code indicating the result of the authorization request.",
      "minLength": 2,
      "maxLength": 2,
      "examples": ["01"]
    },
    "cvcInvalidIndicator": {
      "type": "string",
      "description": "Indicates whether the Card Verification Code was invalid.",
      "minLength": 1,
      "maxLength": 1
    },
    "memo": {
      "type": "string",
      "description": "Brief description by the originator providing context for the fraud report.",
      "maxLength": 1000,
      "examples": ["Cardholder reported unauthorized online purchase."]
    },
    "providerId": {
      "type": "string",
      "description": "Identifier for the fraud data provider (e.g., SafeFraud provider).",
      "maxLength": 20
    }
  },
  "$defs": {
    "TransactionIdentifier": {
      "type": "object",
      "description": "An identifier used to locate a transaction within the Mastercard Data Warehouse.",
      "properties": {
        "banknetReferenceNumber": {
          "type": "string",
          "description": "Banknet Reference Number, a unique transaction identifier in the Mastercard network.",
          "maxLength": 9
        },
        "systemTraceAuditNumber": {
          "type": "string",
          "description": "System Trace Audit Number for transaction identification.",
          "maxLength": 6
        },
        "authorizationCode": {
          "type": "string",
          "description": "Authorization code from the issuer.",
          "maxLength": 6
        },
        "switchSerialNumber": {
          "type": "string",
          "description": "Switch serial number assigned during processing.",
          "maxLength": 22
        }
      }
    },
    "FraudMerchant": {
      "type": "object",
      "description": "Merchant information associated with the fraudulent transaction.",
      "properties": {
        "merchantId": {
          "type": "string",
          "description": "Card acceptor unique identification number assigned by the acquirer.",
          "maxLength": 15,
          "examples": ["A42E51982100100"]
        },
        "merchantName": {
          "type": "string",
          "description": "Name of the card acceptor.",
          "maxLength": 22,
          "examples": ["BANKNEWPORT"]
        },
        "merchantCity": {
          "type": "string",
          "description": "City in which the merchant is located.",
          "maxLength": 13,
          "examples": ["PHOENIX"]
        },
        "merchantStateProvinceCode": {
          "type": "string",
          "description": "State or province code where the merchant is located.",
          "maxLength": 3,
          "examples": ["AZ"]
        },
        "merchantCountryCode": {
          "type": "string",
          "description": "ISO 3166-1 alpha-3 country code of the merchant.",
          "minLength": 3,
          "maxLength": 3,
          "examples": ["USA"]
        },
        "merchantPostalCode": {
          "type": "string",
          "description": "Postal code at the merchant location.",
          "maxLength": 10,
          "examples": ["85001"]
        },
        "merchantCategoryCode": {
          "type": "string",
          "description": "Four-digit MCC classifying the merchant business type.",
          "pattern": "^[0-9]{4}$",
          "minLength": 4,
          "maxLength": 4,
          "examples": ["6011"]
        }
      }
    },
    "FraudTerminal": {
      "type": "object",
      "description": "Terminal information from the fraudulent transaction.",
      "properties": {
        "terminalId": {
          "type": "string",
          "description": "Unique code identifying the terminal at the merchant location.",
          "maxLength": 8,
          "examples": ["5055D305"]
        },
        "terminalAttendanceIndicator": {
          "type": "string",
          "description": "Indicates if the terminal was attended at the time of the transaction.",
          "maxLength": 1
        },
        "terminalOperatingEnvironment": {
          "type": "string",
          "description": "Operating environment of the terminal.",
          "maxLength": 1
        },
        "terminalCapabilityIndicator": {
          "type": "string",
          "description": "Terminal capability to read card data.",
          "maxLength": 1
        },
        "cardholderPresenceIndicator": {
          "type": "string",
          "description": "Whether the cardholder was present at the point of transaction.",
          "maxLength": 1
        },
        "cardPresenceIndicator": {
          "type": "string",
          "description": "Whether the card was present at the point of transaction.",
          "maxLength": 1
        },
        "catLevelIndicator": {
          "type": "string",
          "description": "Cardholder Activated Terminal level indicator.",
          "maxLength": 1
        },
        "posEntryMode": {
          "type": "string",
          "description": "Point of service entry mode for card data capture.",
          "maxLength": 3
        }
      }
    },
    "AlertOutcome": {
      "type": "object",
      "description": "Outcome of an Ethoca alert indicating the action taken by the merchant or partner.",
      "required": [
        "outcome",
        "refundStatus"
      ],
      "properties": {
        "outcome": {
          "type": "string",
          "description": "The resolution outcome of the alert.",
          "enum": [
            "STOPPED",
            "PARTIALLY_STOPPED",
            "PREVIOUSLY_CANCELLED",
            "MISSED",
            "NOT_FOUND",
            "ACCOUNT_SUSPENDED",
            "TOO_LATE",
            "OTHER",
            "RESOLVED",
            "RESOLVED_PREVIOUSLY_REFUNDED",
            "UNRESOLVED_DISPUTE"
          ]
        },
        "refundStatus": {
          "type": "string",
          "description": "Indicates whether a refund was issued as part of the alert resolution.",
          "enum": [
            "FULL_REFUND",
            "PARTIAL_REFUND",
            "NO_REFUND",
            "CREDIT_ISSUED"
          ]
        },
        "refundAmount": {
          "type": "string",
          "description": "Amount refunded to the cardholder, without decimal separators.",
          "pattern": "^[0-9]+$"
        },
        "amountStopped": {
          "type": "string",
          "description": "Amount prevented from being charged due to the alert action.",
          "pattern": "^[0-9]+$"
        },
        "comments": {
          "type": "string",
          "description": "Additional comments provided with the outcome.",
          "maxLength": 1024
        },
        "actionTimestamp": {
          "type": "string",
          "description": "Timestamp when the outcome action was taken.",
          "format": "date-time"
        },
        "status": {
          "type": "string",
          "description": "Processing status of the outcome submission.",
          "enum": ["SUCCESS", "FAILURE"]
        }
      }
    }
  }
}