Labels API

この記事では、ラベル API を使用して、Microsoft Dynamics 365 Fraud Protection のレポートおよび監視ダッシュボードに情報を送信する方法について説明します。

ラベル API を使用すると、不正行為や不正行為以外のシグナルを Fraud Protection に送信できます。 このデータは、モデルのトレーニング、モデルのパフォーマンス評価、およびレポートに使用されます。 ラベル API は、個々のトランザクション ID またはイベント ID、またはユーザーや支払い方法などのエンティティを使用して評価イベントにラベルを付けた一般的な API です。

トランザクションまたはイベントの一般的なラベル シナリオ

• 顧客によってエスカレートされた不正なトランザクション
• レビュー チームによって特定された不正なアクティビティまたはアカウントの不正使用
• オフライン分析 (行動分析や既存の不正行為への検出された接続など)
• 受信した TC40/SAFE 信号
• 利用可能な最新の情報に基づいて不正行為以外として識別された後の以前の不正行為シグナルの反転
• 受け取ったチャージバック/払い戻し
• 紛争後のチャージバックの取り消し

チャージバックと払い戻し API を使用して、チャージバックと払い戻しに関連する情報を提供することをお勧めします。 サポートされているイベントの詳細については、「 Dynamics 365 Fraud Protection Serviceを参照してください。

アカウントまたは支払い方法の詳細

• レビュー チームによって識別される不正なアカウントまたは支払い方法の情報
• 顧客によってエスカレートされるアカウント引き継ぎシナリオ

API スキーマ

属性	Type	説明
labelObjectType	列挙型 想定される値: PURCHASE、ACCOUNTCREATION、ACCOUNTLOGIN、ACCOUNT、PI、EMAIL	この属性は、ラベルにフラグを設定する範囲を示します。 たとえば、1 つのトランザクションを不正としてマークしたり、すべてのユーザー アカウントのトランザクションを不正としてマークしたりできます。 不正防止は、オブジェクトの種類に応じて、関連するトランザクションまたはイベントを不正行為または不正行為以外としてフラグ付けします。 たとえば、labelObjectType値が PURCHASE、ACCOUNTCREATION、または ACCOUNTLOGIN の場合、Fraud Protection は特定のトランザクションにラベルを付けます。 値が ACCOUNT または PI の場合、Fraud Protection は、ユーザー アカウントまたは支払い方法に関連するすべてのトランザクションにフラグを設定します。
labelObjectId	String	labelObjectType 属性の値に対応する識別子。 不正アクセス防止では、この値を使用して関連するトランザクションとイベントを検索します。 ラベル オブジェクトの種類の ID は次のとおりです。 PURCHASE: purchaseId ACCOUNTCREATION: signupId ACCOUNTLOGIN: loginId ACCOUNT: userId PI: merchantPaymentInstrumentId 不正アクセス防止では、この属性を使用して元の評価イベントを識別するため、この属性は非常に重要です。 したがって、値は元のトランザクションまたはイベント ID と一致する必要があります。
labelSource	String	ラベル情報のソース。 提案される値の一部は、 ManualReview レビュー チームによって不正アクセスラベルが識別された場合、および顧客が誤って拒否されたトランザクション (つまり、誤検知) について苦情を申し立てた場合に CustomerEscalation です。 TC40/SAFE データは、ラベル データのもう 1 つのソースです。
isFraud	Boolean	この属性は、ラベルが不正行為か非不正行為かを示します。 値が指定されていない場合、Fraud Protection では既定値として true が使用されます。
reasonText	String	不正行為または不正行為以外のラベルを付ける理由。 ラベル ソースに関する情報が限られている場合は、理由を無視しても問題ありません。 または、ラベル ワークフローに応じて、一部のシナリオをこれらの値の一部にマップすることもできます。
labelReasonCodes	String	支払処理者から受け取る正規化された理由コードまたは理由コード。 理由の詳細がない場合は、この属性を無視しても問題ありません。 推奨される値には、 Processor 応答コード、 Bank 応答コード、 Fraud Refund、 Account Takeover、 Payment Instrument Fraud、 Account Fraud、 Abuse、 Friendly Fraud、 Account Credentials Leaked、および Passed Account Protection Checks。
labelState	String	送信するラベルの種類。 この属性は、以前の不正シグナルまたは誤検知を逆にしている場合に特に使用されます。 どちらの場合も、 isFraud を false に設定します。 ただし、状態は誤検知ラベルを識別するのに役立ちます。
プロセッサ	String	支払いプロセッサの名前。
eventTimeStamp	DateTime (ISO 8601 形式)	ラベルで識別されるタイムスタンプ。 API がラベル検出プロセスと直接統合されていて、レビュー エージェントがトランザクションに不正としてフラグを設定するとすぐにラベル API を呼び出す場合、値は現在のタイムスタンプにすることができます。 この値は、複数のラベルがある場合にイベントの順序を決定するために特に重要です。 たとえば、購入またはアカウント作成トランザクションに不正アクセスのラベルが付いているが、後で不正ではないというラベルが付いている場合、Fraud Protection はこの値を参照して、2 つのラベルのうちどれがより新しく、したがって正しいかを判断します。
effectiveStartDate	DateTime (ISO 8601 形式)	有効な開始日と終了日は、1 つのトランザクションより広いラベル (通常は labelObjectType ACCOUNT の値) を強化して、ラベルの影響を特定の期間に限定することを目的としています。 たとえば、アカウント侵害のシナリオでは、これらの日付は、トランザクションまたはイベントにラベルを付ける期間を指定します。
effectiveEndDate	DateTime (ISO 8601) 形式	有効な開始日と終了日は、1 つのトランザクションより広いラベル (通常は labelObjectType ACCOUNT の値) を強化して、そのラベルの影響を特定の期間に制限することを目的としています。 たとえば、アカウント侵害のシナリオでは、これらの日付は、トランザクションまたはイベントにラベルを付ける期間を指定します。
量	倍精度浮動小数点型	詐欺の合計金額。 使用できる量がない場合は、この値をスキップできます。 たとえば、アカウントの作成とサインインのシナリオでは、関連付けられた金額がない可能性があります。 購入シナリオでは、Fraud Protection はトランザクション量を使用します。
通貨	String	金額に関連する 3 文字の国際標準化機構 (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"
    }
}