加簽加密說明 (Signature Generation Rule)

規則說明 (Description)

HMAC-SHA256 簽章產生規則：

取得請求內容
- 根據請求類型，選擇適當的內容作為輸入資料：
  - GET 請求：使用 Query String（URL 查詢參數）作為簽章輸入。
  - POST / PUT / PATCH 等請求：使用 Request Body 內容作為簽章輸入。
- 將該內容轉換為 UTF-8 編碼的 byte 陣列，稱為 input byte。
取得密鑰
- 街口提供的 Secret key 也需轉換為 UTF-8 編碼的 byte 陣列，稱為 secret key byte。
產生 HMAC-SHA256 簽章
- 使用 HMAC-SHA256 演算法，輸入參數如下：
  - 輸入資料（message）：input byte
  - 金鑰（key）：secret key byte
  - 輸出格式：32-byte (256-bit) 的雜湊值
轉換為 16 進位格式
- 將 HMAC-SHA256 的輸出轉換為小寫 16 進位字串（hex），稱為 digest。

POST 請求範例 – Entry API (Method=Post)

步驟一：

請求 Body：作為 input byte

{"platform_order_id":"demo-order-001","store_id":"35f12dff-1581-11e9-a054-00505684fd45","currency": "TWD","total_price":10,"final_price":10,"unredeem":10,"result_display_url":"https://display.com","result_url":"https://result-callback.xxx/xxx"}

步驟二：

須與街口支付申請平台Secret Key金鑰
- Secret key 範例：
  r0odDC1e9LHXDmxuvmOv9bgaWLf2CXB2c4gMheoFucVKNMi1K0Id9zwRHJF1r-kdtAKriKgb11VDlo7Kb8R-FQ
將 Secret key 以UTF-8 編碼

步驟三：

將步驟一產生的 UTF-8 編碼byte陣列，作為HMAC-SHA256演算法的輸入資料
將步驟二產生的 UTF-8 編碼byte陣列，作為HMAC-SHA256演算法的密鑰
利用HMAC-SHA256演算法進行加簽，產生字串，稱為 digest

DIGEST: 5591d94a4057387bfdd984a79945a2941affe59404a73e7b9a380f9cc97c78b4

GET 請求範例 – Inquiry API (Method=Get)

步驟一：

請求 URL：

https://api.example.com/inquiry?platform_order_ids=test123&auth_no=123

Query String 作為 input byte

platform_order_ids=test123&auth_no=123

步驟二：

須與街口支付申請平台Secret Key金鑰
- Secret key 範例：
  r0odDC1e9LHXDmxuvmOv9bgaWLf2CXB2c4gMheoFucVKNMi1K0Id9zwRHJF1r-kdtAKriKgb11VDlo7Kb8R-FQ
將 Secret key 以UTF-8 編碼

步驟三：

將步驟一產生的 UTF-8 編碼byte陣列，作為HMAC-SHA256演算法的輸入資料
將步驟二產生的 UTF-8 編碼byte陣列，作為HMAC-SHA256演算法的密鑰
利用HMAC-SHA256演算法進行加簽，產生字串，稱為 digest

DIGEST: ea567f866bb1cb08ec8d429eb2cbb674e885b4e9129e2a99882e6b6c4fa43361

簽章驗證工具

請求類型：

請求內容：(input byte)

Secret Key：

簽名結果：

sample code

Python

import hashlib
import hmac
import json

def generate_signature(payload, secret_key, is_get_request=False):
    # 判斷使用 Query String（GET）或 Request Body（POST/PUT/PATCH）
    input_data = payload if is_get_request else json.dumps(payload, separators=(',', ':'))
    
    # 轉換成 UTF-8 編碼的 byte 陣列
    input_bytes = input_data.encode('utf-8')
    secret_bytes = secret_key.encode('utf-8')

    # 計算 HMAC-SHA256 雜湊
    signature = hmac.new(secret_bytes, input_bytes, hashlib.sha256).hexdigest()

    return signature

# 測試範例
secret_key = "r0odDC1e9LHXDmxuvmOv9bgaWLf2CXB2c4gMheoFucVKNMi1K0Id9zwRHJF1r-kdtAKriKgb11VDlo7Kb8R-FQ"
payload_get = "platform_order_ids=test123&auth_no=123"
payload_post = {"platform_order_id":"demo-order-001","store_id":"35f12dff-1581-11e9-a054-00505684fd45","currency": "TWD","total_price":10,"final_price":10,"unredeem":10,"result_display_url":"https://display.com","result_url":"https://result-callback.xxx/xxx"}

print("GET 簽名:", generate_signature(payload_get, secret_key, is_get_request=True))
print("POST 簽名:", generate_signature(payload_post, secret_key))

.NET Core (C#)

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

class Program
{
    static string GenerateSignature(string payload, string secretKey)
    {
        // 轉換成 UTF-8 編碼的 byte 陣列
        byte[] inputBytes = Encoding.UTF8.GetBytes(payload);
        byte[] secretBytes = Encoding.UTF8.GetBytes(secretKey);

        // 計算 HMAC-SHA256 雜湊
        using (HMACSHA256 hmac = new HMACSHA256(secretBytes))
        {
            byte[] hashBytes = hmac.ComputeHash(inputBytes);
            return BitConverter.ToString(hashBytes).Replace("-", "").ToLower();
        }
    }

    static void Main()
    {
        string secretKey = "r0odDC1e9LHXDmxuvmOv9bgaWLf2CXB2c4gMheoFucVKNMi1K0Id9zwRHJF1r-kdtAKriKgb11VDlo7Kb8R-FQ";
        string payloadGet = "platform_order_ids=test123&auth_no=123";
        string payloadPost = JsonSerializer.Serialize(new {"platform_order_id":"demo-order-001","store_id":"35f12dff-1581-11e9-a054-00505684fd45","currency": "TWD","total_price":10,"final_price":10,"unredeem":10,"result_display_url":"https://display.com","result_url":"https://result-callback.xxx/xxx"});

        Console.WriteLine("GET 簽名: " + GenerateSignature(payloadGet, secretKey));
        Console.WriteLine("POST 簽名: " + GenerateSignature(payloadPost, secretKey));
    }
}

PHP

參考工具：https://www.tehplayground.com/uEl6FSUO5YaJHHVH

$sig = hash_hmac('sha256', $string, $secret)

secretkey：
r0odDC1e9LHXDmxuvmOv9bgaWLf2CXB2c4gMheoFucVKNMi1K0Id9zwRHJF1r-kdtAKriKgb11VDlo7Kb8R-FQ

input:
platform_order_ids=test123,demo-order-001

result:
7778b95890af17c5b41e8cef957f4769e7bfecc79e9f9ee555923293ebd8e880

JAVA

參考工具：https://reurl.cc/M0YKXk