标签 API

项目
07/29/2024

本文介绍如何使用标签 API 将信息发送到 Microsoft Dynamics 365 欺诈保护中的报告和监视仪表板。

使用标签 API 可以将欺诈或非欺诈信号发送到欺诈保护。此数据用于模型训练、模型性能评估和报告。标签 API 是一种常规 API，它通过使用单个事务或事件 ID 或实体（如用户或付款方式）来标记评估事件。

事务或事件的常见标签方案

客户升级的任何欺诈易
审查团队识别的欺诈活动或帐户滥用行为
任何脱机分析（例如行为分析或发现与现有欺诈案件的连接）
接收的 TC40/SAFE 信号
根据最新可用信息将其标识为非欺诈信号后，撤销以前的欺诈信号
收到的退款/退款
争议后退款逆转

建议使用退款和退款 API 提供与退款和退款相关的信息。有关支持事件的详细信息，请参阅 Dynamics 365 欺诈保护服务。

帐户或付款方式详细信息

审查团队识别的欺诈帐户或付款方式信息
客户升级的帐户接管方案

API 架构

属性	类型	描述
labelObjectType	Enum 预期值：PURCHASE、ACCOUNTCREATION、ACCOUNTLOGIN、ACCOUNT、PI、EMAIL	此属性指示要标记标签的频率。例如，你可能想要将单个交易标记为欺诈，或者你可能想要将所有用户帐户的交易标记为欺诈。根据对象类型，欺诈保护会将相关的交易或事件标记为欺诈或非欺诈。例如，如果 labelObjectType 值为 PURCHASE、 ACCOUNTCREATION 或 ACCOUNTLOGIN，则欺诈保护标签特定交易。如果值为 ACCOUNT 或 PI，则欺诈保护会标记与用户帐户或付款方式相关的所有交易。
labelObjectId	字符串	对应于 labelObjectType 属性值的标识符。欺诈保护使用此值查找相关的交易和事件。标签对象类型的 ID 如下所示： PURCHASE： purchaseId ACCOUNTCREATION： signupId ACCOUNTLOGIN： loginId 帐户： userId PI： merchantPaymentInstrumentId 此属性非常重要，因为欺诈保护使用它来标识原始评估事件。因此，该值必须与原始事务或事件 ID 匹配。
labelSource	字符串	标签信息的来源。如果评审团队标识欺诈标签，则某些建议的值为 ManualReview ，如果客户抱怨虚假拒绝的交易（换句话说为误报），则 CustomerEscalation 。 TC40/SAFE 数据是标签数据的另一个源。
isFraud	布尔	此属性指示标签是欺诈还是非欺诈。如果未提供任何值，则欺诈保护使用 true 作为默认值。
reasonText	字符串	标记欺诈或非欺诈行为的原因。如果标签源的信息有限，则可以安全地忽略原因。或者，根据标签工作流，可以将某些方案映射到其中一些值。
labelReasonCodes	字符串	从付款处理器收到的规范化原因代码或原因代码。如果没有原因详细信息，可以安全地忽略此属性。一些建议的值是处理器响应代码、银行响应代码、欺诈退款、帐户接管、付款方式欺诈、帐户欺诈、滥用、友好欺诈、帐户凭据泄露和通过的帐户保护检查。
labelState	字符串	要发送的标签类型。尤其在反转以前的欺诈信号或误报时使用此属性。在这两种情况下，将 isFraud 设置为 false。但是，状态可以帮助识别误报标签。
处理器	字符串	付款处理器的名称。
eventTimeStamp	DateTime （ISO 8601 格式）	标签标识的时间戳。如果 API 直接与标签检测过程集成，并且一旦评审代理将事务标记为欺诈，则该值可以是当前时间戳。当有多个标签时，此值对于确定事件顺序尤其重要。例如，如果购买或帐户创建交易标记为欺诈，但后来标记为非欺诈，则欺诈保护将引用此值来确定两个标签中的哪一个是最近，因此是正确的。
effectiveStartDate	DateTime （ISO 8601 格式）	有效开始日期和结束日期旨在扩充大于一个事务的标签（通常具有 accountObjectType 值）以将这些标签的影响限制为特定时间范围。例如，在帐户泄露方案中，这些日期指定要为其标记事务或事件的时间范围。
effectiveEndDate	DateTime （ISO 8601）格式	有效的开始日期和结束日期旨在扩充大于一个事务（通常具有 accountObjectType 值的标签）以将标签的影响限制到特定时间范围。例如，在帐户泄露方案中，这些日期指定要为其标记事务或事件的时间范围。
金额	双精度	欺诈总额。如果没有可用金额，则可以跳过此值。例如，在帐户创建和登录方案中，可能没有关联的金额。在购买方案中，欺诈保护将使用交易金额。
货币	字符串	与金额相关的国际标准化组织（ISO）货币代码的三个字符。

常见方案的示例 API 有效负载

方案 1

评审团队通过查看付款信息识别了可疑交易。

{
    "labelObjectType": "PURCHASE",
    "labelObjectId": "<purchase transaction Id, i.e., purchaseId>",
    "labelSource": "ManualReview",
    "isFraud": true,
    "labelState": "Fraud",
    "eventTimeStamp": "2022-10-04T16:24:36.045Z",
    "_metadata": {
        "trackingId": "<guid or identifier>",
        "merchantTimeStamp": "2022-10-04T20:44:14.706Z"
    }
}

方案 2

用户失去对其帐户的访问权限，恶意参与者使用该用户的凭据登录。稍后，用户恢复了其凭据，并报告了已泄露的时间间隔。

{
    "labelObjectType": "ACCOUNT",
    "labelObjectId": "<userId>",
    "labelSource": "CustomerEscalation",
    "isFraud": true,
    "reasonText": "AccountCompromise",
    "labelState": "Fraud",
    "eventTimeStamp": "2022-10-04T12:21:46.326Z",
    "effectiveStartDate": "2022-10-03T10:00:00.000Z",
    "effectiveEndDate": "2022-10-04T12:16:00.000Z",
    "_metadata": {
        "trackingId": "<guid or identifier>",
        "merchantTimeStamp": "2022-10-04T12:21:46.326Z"
    }
}

方案 3

你阻止了可疑的用户登录，后来用户调用了支持团队来解除阻止。如果支持团队审阅证据，确认用户是合法用户，并取消阻止用户，则必须发送具有 FalsePositive 状态的标签。

{
    "labelObjectType": "ACCOUNT",
    "labelObjectId": "<userId>",
    "labelSource": "CustomerEscalation",
    "isFraud": false,
    "reasonText": "AccountCompromise",
    "labelState": "FalsePositive",
    "eventTimeStamp": "2022-10-04T16:21:46.326Z",
    "_metadata": {
        "trackingId": "<guid or identifier>",
        "merchantTimeStamp": "2022-10-04T16:21:46.326Z"
    }
}

通过