標籤 API

發行項
07/29/2024

本文說明卷標 API 如何讓您將資訊傳送至 Microsoft Dynamics 365 Fraud Protection 中的報告和監視儀錶板。

卷標 API 可讓您將詐騙或非詐騙訊號傳送至詐騙保護。此數據用於模型定型、模型效能評估及報告。卷標 API 是一般 API，會使用個別交易或事件識別碼，或使用者或付款方式等實體來標記評量事件。

交易或事件的常見標籤案例

客戶升級的任何詐騙交易
您的檢閱小組所識別的詐騙活動或帳戶濫用
任何離線分析（例如行為分析或探索到現有詐騙案件的連線）
接收的 TC40/SAFE 訊號
根據最新的可用資訊將其識別為非詐騙之後，撤銷先前的詐騙訊號
收到的退款/退款
爭議後退款逆轉

我們建議您使用退款和退款 API 來提供與退款和退款相關的資訊。如需支援事件的詳細資訊，請參閱 Dynamics 365 Fraud Protection Service。

帳戶或付款方式詳細數據

檢閱小組識別的詐騙帳戶或付款方式資訊
客戶升級的帳戶接管案例

API 架構

屬性	類型	描述
labelObjectType	列舉預期值：PURCHASE、ACCOUNTCREATION、ACCOUNTLOGIN、ACCOUNT、PI、EMAIL	這個屬性會指出您想要標記標籤的頻率。例如，您可能想要將單一交易標示為詐騙，或想要將所有用戶帳戶的交易標示為詐騙。根據物件類型，Fraud Protection 會將相關的交易或事件標示為詐騙或非詐騙。例如，如果 labelObjectType 值為 PURCHASE、 ACCOUNTCREATION 或 ACCOUNTLOGIN，則詐騙保護會標記特定交易。如果值為 ACCOUNT 或 PI，則詐騙保護會標幟與使用者帳戶或付款方式相關的所有交易。
labelObjectId	String	對應至 labelObjectType 屬性值的標識碼。詐騙保護會使用此值來尋找相關的交易和事件。標籤類型的識別元如下所示：購買： purchaseId ACCOUNTCREATION： signupId ACCOUNTLOGIN： loginId 帳戶： userId PI： merchantPaymentInstrumentId 這個屬性非常重要，因為詐騙保護會用它來識別原始評估事件。因此，值必須符合原始交易或事件標識符。
labelSource	String	標籤資訊來源。如果檢閱小組識別詐騙標籤，則有些建議的值為 ManualReview ，如果客戶抱怨錯誤拒絕的交易，則 CustomerEscalation （換句話說，誤判為誤判）。 TC40/SAFE 數據是標籤數據的另一個來源。
isFraud	布林值	此屬性指出標籤為詐騙或非詐騙。如果未提供任何值，則 Fraud Protection 會使用 true 做為預設值。
reasonText	String	標記詐騙或非詐騙的原因。如果您有標籤來源的資訊有限，您可以放心地忽略原因。或者，視卷標工作流程而定，您可以將某些案例對應至其中一些值。
labelReasonCodes	String	從付款處理器收到的標準化原因碼或原因碼。如果您沒有原因詳細數據，可以放心地忽略此屬性。一些建議的值包括處理器回應碼、銀行回應碼、詐騙退款、帳戶接管、付款方式詐騙、帳戶詐騙、濫用、易記詐騙、帳戶認證外洩，以及通過的帳戶保護檢查。
labelState	String	您要傳送的標籤種類。特別是如果您要反轉先前的詐騙訊號或誤判，則會使用這個屬性。在這兩種情況下，您會將isFraud設定為 false。不過，狀態有助於識別誤判標籤。
處理器	String	付款處理器的名稱。
eventTimeStamp	DateTime （ISO 8601 格式）	標籤辨識的時間戳。如果 API 直接與標籤偵測程式整合，而且只要檢閱代理程式將交易標示為詐騙，您就會呼叫標籤 API，此值可以是目前的時間戳。當有多個標籤時，這個值對於判斷事件順序特別重要。例如，如果購買或帳戶建立交易標示為詐騙，但稍後標示為非詐騙，則詐騙保護會參考此值來判斷這兩個標籤中的哪一個較新，因此正確無誤。
effectiveStartDate	DateTime （ISO 8601 格式）	有效的開始和結束日期旨在擴充大於一筆交易的標籤（且通常具有 labelObjectType 值為 ACCOUNT）的標籤，以限制這些標籤對特定時間範圍的影響。例如，在帳戶入侵案例中，這些日期會指定您想要標記交易或事件的時間範圍。
effectiveEndDate	DateTime （ISO 8601）格式	有效的開始和結束日期旨在擴充大於一筆交易的標籤（且通常具有 labelObjectType 的 ACCOUNT 值），以限制該卷標對特定時間範圍的影響。例如，在帳戶入侵案例中，這些日期會指定您想要標記交易或事件的時間範圍。
總數	雙重	詐騙金額總計。如果沒有可用的金額，您可以略過此值。例如，在帳戶建立和登入案例中，可能沒有相關聯的金額。在購買案例中，詐騙保護會使用交易金額。
貨幣	String	與金額相關的三個字元國際標準化組織（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"
    }
}

共用方式為