回調安全性

本文件概述了我們支付閘道解決方案中可用於保護回調端點的安全機制。當支付事件發生時，我們的系統透過 HTTP 請求傳送回調至客戶端的後端。為了確保這些回調的完整性、真實性和安全性，我們提供了三種互補的安全方法：

1. 標頭中的簽名驗證

2. IP 白名單

3. 透過 API 進行交易驗證

用戶端可根據其安全需求，實施其中一種或多種方法。

---

1. 標頭簽名驗證

概述

每個回調請求的簽章標頭中都包含一個加密簽章。此簽章是使用 HMAC-SHA256 將要求正文與秘密密鑰串列後產生的。客戶可以驗證此簽章，以確保回調來自我們的付款閘道，且未被竄改。

簽章產生

簽章的計算方式如下：

• 演算法： HMAC-SHA256

• 輸入： JSON stringified 請求正文

• 鑰匙： 客戶端特定的 apiSecret

• 輸出： 十六進位字串

回撥請求格式

• 方法： POST (預設，可設定)

• 標頭：

  • 內容類型：application/json

  • 簽章： 簽署

• 本體： 包含付款事件詳細資訊的 JSON 有效負載

• 逾時： 5000ms（預設，可設定）

驗證範例

以下是以各種程式語言驗證簽章的實作範例。

TypeScript

using System.Security.Cryptography;
using System.Text;

public class SignatureVerifier
{
    public static bool VerifySignature(string body, string signature, string apiSecret)
    {
        using (var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(apiSecret)))
        {
            byte[] hashBytes = hmac.ComputeHash(Encoding.UTF8.GetBytes(body));
            string computedSignature = BitConverter.ToString(hashBytes).Replace("-", "").ToLower();
            return computedSignature == signature;
        }
    }
}

PHP

function verifySignature($body, $signature, $apiSecret) {
    $computedSignature = hash_hmac('sha256', json_encode($body), $apiSecret);
    return hash_equals($computedSignature, $signature);
}

Java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class SignatureVerifier {
    public static boolean verifySignature(String body, String signature, String apiSecret) 
            throws Exception {
        Mac mac = Mac.getInstance("HmacSHA256");
        SecretKeySpec secretKeySpec = new SecretKeySpec(apiSecret.getBytes("UTF-8"), "HmacSHA256");
        mac.init(secretKeySpec);
        byte[] hashBytes = mac.doFinal(body.getBytes("UTF-8"));
        String computedSignature = bytesToHex(hashBytes);
        return computedSignature.equalsIgnoreCase(signature);
    }

    private static String bytesToHex(byte[] bytes) {
        StringBuilder result = new StringBuilder();
        for (byte b : bytes) result.append(String.format("%02x", b));
        return result.toString();
    }
}

C#

using System.Security.Cryptography;
using System.Text;

public class SignatureVerifier
{
    public static bool VerifySignature(string body, string signature, string apiSecret)
    {
        using (var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(apiSecret)))
        {
            byte[] hashBytes = hmac.ComputeHash(Encoding.UTF8.GetBytes(body));
            string computedSignature = BitConverter.ToString(hashBytes).Replace("-", "").ToLower();
            return computedSignature == signature;
        }
    }
}

最佳實作

• 安全地儲存 apiSecret (例如，在環境變數中)。

• 使用安全的比較函數 (例如 PHP 中的 hash_equals)，以防止定時攻擊。

• 以 401 Unauthorized 回應拒絕缺失或無效簽章的要求。

---

2. IP 白名單

概述

為了將回呼要求限制為可信來源，我們提供了一組固定的 IP 位址，回呼將從這些 IP 位址發出。用戶端可在防火牆或應用程式邏輯中將這些 IP 列為白名單。請聯繫 AkashicPay 支援團隊以獲取需要白名單的 IP 列表，電子郵件地址：[e-mail]。

最佳做法

• 設定您的環境以使用適當的 IP 清單 (測試網路或主網路)。

• 定期檢查我們文件中 IP 清單的更新。

• 記錄並監控來自非白名單 IP 的要求，以進行安全稽核。

---

3. 透過 API 進行交易驗證

概述

客戶端可以使用 L1 或 L2 交易哈希值查詢我們的 Transaction Detail API，從而獨立驗證付款事件。此方法確認回調中引用的付款事件的有效性。

API 端點

基本領域

• 正式環境：https://api.akashicscan.com

• 測試環境: https://api.testnet.akashicscan.com

端點

• L2 哈希值驗證： GET /api/v0/transactions/transfer?l2Hash=<L2_HASH> 範例: https://api.akashicscan.com/api/v0/transactions/transferl2Hash=AS123...

• L1 哈希值驗證： GET /api/v0/transactions/hash?txHash=<L1_HASH> 範例: https://api.akashicscan.com/api/v0/transactions/hash?txHash=0x123...

回應格式

• 狀態： 成功時為 200 OK

• 本體： 包含交易詳細資訊的 JSON 物件（結構依實作而定）

• 錯誤： 4xx/5xx 狀態代碼，失敗時會顯示錯誤訊息

最佳做法

• 根據您的環境 (測試環境或正式環境) 使用適當的網域。

• 針對瞬間網路故障實施重試邏輯。

• 快取成功的驗證，以減少 API 呼叫（如適用）。

---

安全考慮

• 對所有回調端點使用 HTTPS，以加密傳輸中的資料。

• 實施速率限制以防止濫用。

• 記錄所有驗證失敗，以便監控和審計。

• 確保 apiSecret 和其他敏感憑證的安全。