通知

このページでは、不正行為審査トランザクションに関する最新情報を送信する通知サービスの概要について説明します。

概要

Fraud Prevention API 通知は、これまで以上に Fraud Prevention を活用していただくためのソリューションです。パートナー様の事業に影響を及ぼす可能性のある変更が発生した場合、Fraud Prevention は標準的な POST メッセージを使用して、お使いのシステムに変更の詳細を直接お知らせします。このプッシュ通知により、常に最新情報を入手でき、運営を簡素化し、ビジネスを不正行為から保護できます。

現在、注文購入とアカウント審査の両方でイベント通知がサポートされています。そのため、分析スペシャリストがトランザクションを確認した場合、その解決策と推奨される対応が即座に通知されます。

メッセージの構成と詳細

このセクションでは、エンベロープと通知ペイロードという 2 つの主要な部分で構成されるメッセージのアーキテクチャ構成について詳しく説明します。エンベロープには通知メタデータが組み込まれており、通知ペイロードには通知の複雑な詳細が含まれています。これらの構成要素について詳しく見てみましょう。

エンベロープオブジェクトスキーマ

フィールド	タイプ	取り得る値	Null 可能	サンプル	説明
event_name	文字列	`MERCHANTSHIELD_FRAUD`	false	`MERCHANTSHIELD_FRAUD`	イベント名は常に `MERCHANTSHIELD_FRAUD` です。
creation_time	文字列	データ時間 (UTC)	false	2024-01-18T10:29:20.484649887Z	通知イベントが作成された時間。
notification_id	文字列	GUID	false	d72ac517-f0a7-4a65-8547-250cf81ce440	一意の通知 ID。
payload	ペイロード	`Payload` オブジェクト	false	実際の通知ペイロード。以下のペイロードオブジェクトスキーマの説明を参照してください。

ペイロードオブジェクトスキーマ

フィールド	タイプ	取り得る値	Null 可能	サンプル	説明
risk_id	文字列	GUID	false	fdeaf9dc-ac79-4c2f-a148-0e722374aef1	リスクトランザクションの一意の識別子。
entity_type	文字列	`BookingFraud`、`Account`	false	BookingFraud	エンティティタイプ。
entity_id	文字列	GUID	false	be8076bc-d17c-45fa-84e6-0fe6a609f3ac	影響を受ける審査予約またはアカウント乗っ取りトランザクションの参照 ID。
decision	文字列	PASS、FAIL	true	PASS	分析スペシャリストがトランザクションを確認した上で下した決定。
decision_date_time	文字列	データ時間 (UTC)	false	2024-03-07T22:28:33.552Z	アナリストの決定日時 (UTC 形式)。
recommended_actions	文字列の配列	`BookingFraud` エンティティタイプの場合 : `RELEASE`、`CANCEL_FULL_REFUND`、`CANCEL_NO_REFUND` <hr> `Account` エンティティタイプの場合 : `TERMINATE_ACTIVE_SESSIONS`、`HARD_PASSWORD_RESET`	空の場合あり	["CANCEL_FULL_REFUND"]	推奨される是正措置のリスト。
partner_account_id	文字列	GUID	false	ff1fddb1-29ac-41a1-8c0b-6db5932c913d	お使いのパートナーアカウント ID。

各メッセージは JSON のメッセージ本文を持つ HTTP POST リクエストです。

BookingFraud の最新情報の例

{
    "event_name": "MERCHANTSHIELD_FRAUD",
    "creation_time": "2024-01-18T10:29:20.484649887Z",
    "notification_id": "0597ae4c-b6d2-4d47-ba58-36534e04f1cf",
    "payload": {
        "risk_id": "9beabb6d-77b9-474e-852a-3cb9fedabb3a",
        "entity_type": "BookingFraud",
        "entity_id": "1e5092ad-4440-40cf-9a14-0bf76ced339c",
        "decision_date_time": "2024-03-07T22:28:33.552Z",
        "decision": "PASS",
        "recommended_actions": [
            "RELEASE"
        ],
        "partner_account_id": "972edd1c-b50f-4d7e-b5bb-05212aa20d03"
    }
}

アカウント乗っ取りの最新情報の例

{
    "event_name": "MERCHANTSHIELD_FRAUD",
    "creation_time": "2024-01-18T10:29:20.484649887Z",
    "notification_id": "c9235ccb-8716-4ac3-a3ad-ef96042aa32a",
    "payload": {
        "risk_id": "d2f0d5ab-cda1-484e-9507-e0fcf81960dc",
        "entity_type": "Account",
        "entity_id": "13538ba1-df41-446c-8266-4f325e4ef264",
        "decision_date_time": "2024-03-07T22:28:33.552Z",
        "decision": "PASS",
        "recommended_actions": [],
        "partner_account_id": "34f8df88-26f3-48f2-a81b-12fae9306192"
    }
}

統合

メッセージを受信する

通知の受信を開始するには、エンドポイントを立ち上げ、そのエンドポイントに送られる POST メッセージを受信できるようにする必要があります。エンドポイントは次の条件を満たす必要があります。

公衆アクセスが可能である
HTTPS および TLS 1.2 以上が有効になっている
最新のほとんどのアプリケーションで信頼されている有効な TLS 証明書を構成する (自己署名証明書は信頼されない場合があります)

Fraud Prevention 統合コンサルタントと協力して設定し、次の情報を入力します。

メッセージを処理するエンドポイントの URL

今後、統合をテストするためのセルフサービスツールが提供される予定です。それまでは、統合コンサルタントがテスト予約をサポートし、受信を希望するオフラインイベントに対する通知を受信していることを確認します。

設定に関する重要な注意事項

Fraud Prevention ではクラウドベースのサーバーを使用しています。さまざまな IP アドレスからプッシュされる通知を受信できるように、受信者のエンドポイントを構成してください。
エンドポイントの URL を変更する場合は、新しい URL がプッシュ通知を受信できるようになるまで、元の URL を有効にしておく必要があります。該当する変更を行う前に、Fraud Prevention 担当者にご連絡ください。
通知に使用できるURLは 1 つだけです。

ヘッダー名	サンプル値
x-eg-notification-signature	Sha256=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-eg-notification-timestamp	13536472536
api-key	c05b7b59-0a29-4cb1-9b09-d36954c9a605

署名ステップに対するハッシュの検証

signed_payload 文字列を用意します。
- signed_payload 文字列は連結して作成されます。
  x-eg-notification-timestamp ヘッダーからの文字列としてのタイムスタンプ
  . 文字。
  実際の JSON ペイロード (つまりリクエスト本文)
想定される署名を決定します。
- SHA256 ハッシュ関数で HMAC を計算します。エンドポイントの署名シークレットをキーとして使用し、signed_payload 文字列をメッセージとして使用します。
署名の比較: ヘッダーの署名を想定される署名と比較します。等価一致の場合は、現在のタイムスタンプと受信したタイムスタンプの差を計算し、その差が許容範囲内であるかどうかを判断します。

Java の例

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Base64;

public class TestApplication {

    public static final String HMAC_SHA_256 = "HmacSHA256";

    public static void main(String[] args){

        // extracted data from the notification request payload
        // x-eg-notification-timestamp: 1634021234
        String eg_timestamp_header_value = "timestamp_header_value";
        // x-eg-notification-signature: SHA256=signature_header_value
        String eg_signature_header_value = "signature_header_value";
        // api-key: api_key_to_validate
        String api_key_header_value = "api_key_to_validate";
        // json payload
        String json_payload = "json_payload";

        // your api key
        String api_key = "your_api_key";
        // signing secret from the secret store
        String your_endpoints_signing_secret = "your_endpoints_signing_secret";


        if (!api_key.equals(api_key_header_value)) {
            throw new RuntimeException("Failure! Api key does not match expected value!");
        }

        try {
            // Prepare the `signed_payload` string
            String signed_payload = eg_timestamp_header_value + "." + json_payload;

            // Determine the expected signature
            String expected_signature = generate_hmac(signed_payload,
                    your_endpoints_signing_secret);

            if (!eg_signature_header_value.equals(expected_signature)) {
                throw new RuntimeException("Failure! Signature does not match expected value!");
            }

            System.out.println("Success! The generated signature matches the expected value.");
        } catch (NoSuchAlgorithmException | InvalidKeyException e) {
            System.err.println("Error generating HMAC: " + e.getMessage());
        }
    }

    /**
     * Generates a hashed message authentication code using the HMAC-SHA256 algorithm.
     * This method may throw an Exception when the HMAC-SHA256 algorithm is not supported
     * or the secret key is invalid.
     *
     * @param message The message to be encoded
     * @param secret The secret key
     * @return The Base64 encoded HMAC
     */
    public static String generate_hmac(String message, String secret)
            throws NoSuchAlgorithmException, InvalidKeyException {
        Mac sha256_hmac = Mac.getInstance(HMAC_SHA_256);
        SecretKeySpec secret_key_spec = new SecretKeySpec(secret.getBytes(), HMAC_SHA_256);
        sha256_hmac.init(secret_key_spec);
        byte[] hmac = sha256_hmac.doFinal(message.getBytes());
        return Base64.getEncoder().encodeToString(hmac);
    }
}

通知

このページでは、不正行為審査トランザクションに関する最新情報を送信する通知サービスの概要について説明します。

概要

メッセージの構成と詳細

エンベロープオブジェクトスキーマ

ペイロードオブジェクトスキーマ

統合

メッセージを受信する

設定に関する重要な注意事項

メッセージを処理する

配信不能メッセージ

検証

共有秘密を保護する

コールバックリクエストヘッダーの構造

署名ステップに対するハッシュの検証

Java の例

このページでは、不正行為審査トランザクションに関する最新情報を送信する通知サービスの概要について説明します。

** Java の例**

Java の例