通知電文

電文分類

這是我們當前發送的所有事件類型的清單。我們可能會隨時添加更多內容，因此在開發和維護代碼時，您不應假定僅存在這些類型。我們預設為您開通訂閱以下全部類型的事件，如果您想改變訂閱的事件列表，請聯絡我們串接窗口調整。

通知場景	event.type	對應結構	通知描述
結帳交易	session.created	結帳交易結構	結帳建立
	session.expired	結帳交易結構	結帳逾時
	session.pending	結帳交易結構	結帳處理中
	session.succeeded	結帳交易結構	結帳成功
付款交易	trade.succeeded	付款交易結構	付款成功
	trade.failed	付款交易結構	付款失敗
	trade.expired	付款交易結構	付款逾時
	trade.processing	付款交易結構	付款處理中
	trade.cancelled	付款交易結構	取消付款
	trade.customer_action	付款交易結構	付款交易結構
	trade.refund.succeeded	退款交易結構	退款成功
	trade.refund.failed	退款交易結構	退款失敗
會員	customer.created	會員結構	會員建立
	customer.updated	會員結構	會員更新
	customer.deleted	會員結構	會員註銷
付款工具	customer.instrument.binded	指令結構	會員綁定付款工具
	customer.instrument.updated	指令結構	會員更新付款工具
	customer.instrument.unbinded	指令結構	會員解綁付款工具
爭議交易	dispute.chargeback.created	爭議交易結構	爭議建立
	dispute.chargeback.evidence_required	爭議交易結構	待提交抗辯資料
	dispute.chargeback.evidence_under_review	爭議交易結構	已提交抗辯資料
	dispute.chargeback.evidence_returned	爭議交易結構	抗辯資料已退回
	dispute.chargeback.resolved	爭議交易結構	爭議已解決
	dispute.chargeback.cancelled	爭議交易結構	爭議取消
	dispute.chargeback.lost	爭議交易結構	爭議成立
	dispute.chargeback.won	爭議交易結構	爭議不成立
	dispute.chargeback.expired	爭議交易結構	爭議超時
	dispute.chargeback.accepted	爭議交易結構	接受爭議
	dispute.pre-chargeback.created	爭議交易結構	預爭議建立
	dispute.pre-chargeback.in_accept	爭議交易結構	預爭議回覆已接受
	dispute.pre-chargeback.in_reject	爭議交易結構	預爭議回覆已拒絕
	dispute.pre-chargeback.in_expire	爭議交易結構	預爭議逾時未回覆
	dispute.pre-chargeback.accepted	爭議交易結構	預爭議單已接受
	dispute.pre-chargeback.merchant_rejected	爭議交易結構	預爭議單已拒絕
	dispute.fraud.finished	爭議交易結構	欺詐預警
	dispute.retrieval.created	爭議交易結構	調單建立
	dispute.retrieval.finished	爭議交易結構	調單完成
	dispute.retrieval.cancelled	爭議交易結構	調單取消
平台專用	trade.settled	指令結構	子特店結算
平台專用	merchant.kyc.audit	指令結構	子特店審核結果

簽章演算法

SHOPLINE Payments 使用基於雜湊的訊息認證程式碼( HMAC ) 和（SHA-256）產生簽章。

SHOPLINE Payments 可以透過在每個通知 HTTPS 請求的 Hearder 標頭中包含簽名 sign 欄位來承載發送到您的端點的 webhook 通知事件對應簽章字串。這允許您驗證通知訊息是由 SHOPLINE Payments 發送的，同時，SHOPLINE Payments 為每個簽名原文使用店家自己的 signKey 作為加密秘鑰。
為防止「重播攻擊」，SHOPLINE Payments 在 Hearder 中包含一個時間戳 timestamp ，因為這個時間戳是簽名有效載荷的一部分，它也由簽名驗證，所以攻擊者無法在不使簽名無效的情況下更改時間戳記。如果簽名有效但時間戳得太舊，您可以讓您的應用程式拒絕負載。

HTTP 通知數據

Http.header

參數	必填	類型	說明	範例值
apiVersion	是	String	API版本編號，不同版本下報文結構將有差異	V1.2
timestamp	是	String	發送通知的時間戳，精確度為毫秒	1629169157000
sign	是	String	簽章值，見簽章演算法。	873c40ac22fc8bd19674b9b778cc42d2

Http.body(application/json)

參數	必填	類型	說明	範例值
id	是	String	通知訊息唯一 ID	100012122112289889299928
type	是	String	電文分類	trade.succeeded
created	是	Number	通知產生時間，格式為時間戳記。	1695795621307
data	是	Object	通知訊息對應業務時間電文	873c40ac22fc8bd19674b9b778cc42d2

通用以下步驟驗證簽章如下：

第 1 步：從標頭中提取時間戳 {timestamp} 和簽名 {sign} 字段

第 2 步：準備 payload 字串 該 payload 字串是透過以下內容建立：

時間戳timestamp（作為字串）
字元 .
實際的 JSON 電文（即請求http.body整體電文內容）

簽名字串：payload = {timestamp}.{bodyString}

第 3 步：產生預期簽章
使用 SHA256 雜湊函數計算 HMAC。使用店家的signKey簽署金鑰作為金鑰，並使用payload字串作為訊息。

//hmacSha256簽章方式：
sign=hmacSha256(payload, signKey, "UTF_8") // "54cd5b827c0ec938fa072a29b177469c843317b095591dc846767aa338bac600" //註：MD55591dc846767aa338bac600" //

第 4 步：比較簽名
將標頭中的簽名與預期簽名進行比較。對於相等匹配，計算當前時間戳記和接收的時間戳之間的差異，然後確定差異是否在您的容忍範圍內。

範例 Code

//信用卡付款成功的電文 Code 範例
{
    "id": "000100698482394232932302030234328327",
    "type": "trade.succeeded",
    "created": 1718551769058,
    "data": {
        "actionType": "SDK",
        "referenceOrderId": "1600053335",
        "tradeOrderId": "1001001084733463323223973",
        "paymentMsg": null,
        "payment": {
            "paymentSuccessTime": "1718551768922",
            "autoCapture": true,
            "subPaymentMethod": null,
            "paymentBehavior": "Regular",
            "autoConfirm": false,
            "channelDealId": "17185517455610128070000",
            "paymentMethod": "CreditCard",
            "paymentMethodOptions": {
                "installments": {
                    "installPay": null,
                    "count": null,
                    "installDownPay": null
                }
            },
            "paymentCustomerId": "",
            "paymentInstrument": {
                "savePaymentInstrument": false,
                "paymentInstrumentId": null
            },
            "creditCard": {
                "issuerCountry": "TW",
                "last4": "1234",
                "bin": "12345678",
                "type": "CREDIT",
                "category": "BUSINESS SIGNATURE",
                "brand": "Visa",
                "issuer": "HONG KONG AND SHANGHAI BANKING CORP., LTD."
            },
            "paidAmount": {
                "currency": "TWD",
                "value": 10000
            }
        },
        "nextAction": null,
        "additionalData": null,
        "subStatus": "",
        "status": "SUCCEEDED",
        "order": {
            "amount": {
                "currency": "TWD",
                "value": 10000
            },
            "referenceOrderId": "123456789",
            "merchantId": "12345678",
            "createTime": 1718551768994,
            "customer": {
                "customerId": "",
                "referenceCustomerId": "123456789"
            }
        }
    }
}

通知電文

電文分類​

簽章演算法​

HTTP 通知數據​

範例 Code​

電文分類

簽章演算法

HTTP 通知數據

範例 Code