加簽加密說明 (Signature Generation Rule)

規則說明 (Description)

簽章規則

1. Request Payload 編碼
   • 將字串形式的 request payload 以 UTF-8 編碼，生成 input byte。
2. Secret Key 編碼
   • 將街口提供的 Secret Key 以 UTF-8 編碼，生成 secret key byte。
3. HMAC-SHA256 運算
   • 使用 HMAC-SHA256 演算法，將 input byte 與 secret key byte 計算雜湊值。
4. Digest 轉換
   • 將雜湊結果轉換為 十六進位字串 (hexadecimal string)，作為 digest。

---

Signature Generation Rule

1. Request Payload Encoding
   • Encode the request payload string into bytes using UTF-8, referred to as input byte.
     • Example: Request payload: {"a":1, "b":"13"}
     • UTF-8 bytes (hex representation): 7b2261223a312c202262223a223133227d
2. Secret Key Encoding
   • Encode the provided Secret Key into bytes using UTF-8, referred to as secret key byte.
3. HMAC-SHA256 Hashing
   • Apply HMAC-SHA256 with secret key byte as the key and input byte as the message.
4. Digest Conversion
   • Convert the resulting hash into a hexadecimal string, referred to as digest.

範例 (Example)

發放街口幣 API (Method=Post)

步驟一：

將字串的 request payload以 UTF-8 編碼，request body 範例如下：

{"exchangeId":"testunique1758786827","amount":10,"jkosId": "user123","clientId": "310886000"}

步驟二：

須與街口支付申請平台 secret key，金鑰範例為 secret key = r0odDC1e9LHXDmxuvmOv9bgaWLf2CXB2c4gMheoFucVKNMi1K0Id9zwRHJF1r-kdtAKriKgb11VDlo7Kb8R-FQ，並將 secret key 以UTF-8 編碼

步驟三：

將步驟一產生的字節透過 HMAC-SHA256 演算法，以步驟二的字節作為秘密鑰匙進行加簽，即產生 hexdigest 作為 digest。

{"exchangeId":"testunique1758786827","amount":10,"jkosId":"user123","clientId":"310886000"}
/*
Secret key='r0odDC1e9LHXDmxuvmOv9bgaWLf2CXB2c4gMheoFucVKNMi1K0Id9zwRHJF1r-kdtAKriKgb11VDlo7Kb8R-FQ'
*/
DIGEST: a001fe1b11464109037473e9a0a53f8887d352bdd7dbd5ea699951e7dbeff31a

---

查詢 API (Method=Get)

目前尚未提供，但建議先將 GET parameters 處理好未來方便介接

步驟一：

將字串的 request payload以 UTF-8 編碼，request parameter 範例如下：

clientId=310886000,exchangeId=testunique1758786827

步驟二：

須與街口支付申請平台 secret key，金鑰範例為 secret key = r0odDC1e9LHXDmxuvmOv9bgaWLf2CXB2c4gMheoFucVKNMi1K0Id9zwRHJF1r-kdtAKriKgb11VDlo7Kb8R-FQ，並將 secret key 以 UTF-8 編碼

步驟三：

將步驟一產生的字節透過 HMAC-SHA256 演算法，以步驟二的字節作為秘密鑰匙進行加簽，即產生 hexdigest 作為 digest。

DIGEST: 5b2202771834fd7d0cfd30c58132804ce1d5c2bc04cbae86c6a58e4b93d9ab95

---

簽章驗證工具

sample code

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

Python

import hashlib
import hmac
import logging

class SignatureLogic:
    @staticmethod
    def generate_digest(secret_key, content):
        secret_key = secret_key.encode() if isinstance(secret_key, str) else secret_key
        content = content.encode() if isinstance(content, str) else content
    
        result = hmac.new(
            secret_key,
            msg=content,
            digestmod=hashlib.sha256
        ).hexdigest()
        return result
        

json_str = '{"exchangeId":"testunique1758786827","amount":10,"jkosId": "user123","clientId":"310886000"}'

# Key
secret_key = 'input-your-key'

# 生成簽名
signature = SignatureLogic.generate_digest(secret_key, json_str)
print(signature)

JAVA

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

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

public static String encodeHmacSHA256(String secretKey, String input) {
   SecretKeySpec secret_key = new SecretKeySpec(secretKey.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
   Mac mac = Mac.getInstance("HmacSHA256");   
   mac.init(secret_key);
   byte[] bytes = mac.doFinal(input.getBytes());
   return byteArrayToHexString(bytes);
}

private static String byteArrayToHexString(byte[] b) {
   StringBuilder hs = new StringBuilder();
   String stmp;
   for (int n = 0; b != null && n < b.length; n++) {
   stmp = Integer.toHexString(b[n] & 0XFF);
      if (stmp.length() == 1) {
         hs.append('0');
      }
      hs.append(stmp);
   }
   return hs.toString().toLowerCase();
}