通知

本頁面概述了傳送防範詐騙交易最新消息的「通知服務」。

簡介

「Fraud Prevention API 通知」解決方案可讓您更緊密地與 Fraud Prevention 功能整合。若發生可能影響您業務的變更， Fraud Prevention 功能會利用標準 POST 訊息，直接將變更詳細資料推播至您的系統。推播通知可讓您隨時接收最新資訊、簡化操作以及確保您的業務免受詐欺。

我們目前支援訂單購買和帳戶畫面事件的通知。因此，如果分析師審查了該交易，您將立即收到含有解決方案和建議行動的通知。

訊息結構描述與詳細資料

本章節將深入研究訊息的架構組成，其中主要由兩個部分組成：信封和通知有效負載。信封包含通知中繼資料，而通知有效負載則包含通知的複雜細節。讓一起我們詳細探索這些元件。

信封物件結構描述

欄位	類型	可能的值	Nullable	樣本	詳情
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` 物件	false	實際通知的有效負載。請參閱下方的有效負載物件結構描述說明。

有效負載物件結構描述

欄位	類型	可能的值	Nullable	樣本	說明
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 格式的 HTTPS 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。

處理訊息

了解立即執行相應措施的重要性。仔細檢查回呼要求的詳細資訊，確保您處理所有是實體、決策和建議補救措施的組合。

無法傳遞的訊息

若傳送訊息至您的端點時遇到問題，我們會建立一個協定，讓系統自動嘗試重新傳送。等待 5 秒後，系統會以指數輪詢方式採取此行動 5 次。

驗證

若要驗證活動，請將標頭中的 signature SHA512 hash 與要求標頭中您使用 API 金鑰、共用密碼和時間戳記自行產生的內容進行比對。

確保驗證 api-key 標頭實際上是您在 Fraud Prevention 上線流程中提供的 API 金鑰。

保護您的共用密碼

請謹慎保管此密碼，因為提供給您的共用密碼，對於防護要求資料的安全非常重要。切勿在任何可公開存取的網站或應用程式程式碼中，加入原始值。若您已獲准整合 Fraud Prevention，便會向您提供共用密碼與 API 金鑰。

回呼要求標頭架構

標頭名稱	樣本值
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);
    }
}