DDPay Notify

Description

本平台開放給 DDPay 呼叫的付款結果通知端點（webhook）。建立線上訂單時會將此網址提供給 DDPay，DDPay 於付款完成（或失敗）後會呼叫此端點；本平台收到後更新對應訂單的付款記錄，並回應 HTTP 200。

若未收到通知，可改用 DDPay Get Order 主動查詢訂單狀態。

Resource

POST /v1/payment/ddpay/{company_id}/{shop_id}/notify

Authorization

呼叫方為 DDPay，非本平台一般 OAuth 2.0 用戶端。請求須帶下列 Header，後端以 HMAC-SHA256 驗證簽章是否相符，驗證失敗回應 HTTP 401：

Header	Description
X-DD-TS	請求時間戳（Unix timestamp），與伺服器時間差超過 5 分鐘視為無效
X-DD-Signature	以門市對應的 DDPay Client Secret 對請求內容計算之簽章

Path Parameters

Name	Type	Description
company_id	string	公司代碼
shop_id	string	門市代碼

Request Body Parameters（DDPay 發送的 Payload）

Name	Type	Description
success	boolean	付款是否成功
ddpayOrderId	string	DDPay 訂單編號
merchantOrderId	string	我方訂單編號
mode	string	結帳模式：sd、ttp、cpm
payment	object｜null	付款資訊，失敗時為 null
payment.amount	number	實際付款金額（元）
payment.service	string	付款服務，如 linepay、jko；感應（TTP）不帶此值
payment.paidAt	integer	付款完成時間（Unix timestamp）
payment.invoiceCarrier	object｜null	電子發票載具（被掃模式有綁載具時帶）
payment.meta	object	金流額外資訊（信用卡交易含核准碼、卡號、卡別等）

Request Example — 線上付款完成（LINE Pay）

{
    "success": true,
    "ddpayOrderId": "250610154305QjDVpx",
    "merchantOrderId": "WG000012345",
    "mode": "sd",
    "payment": {
        "amount": 480,
        "service": "linepay",
        "paidAt": 1749560400,
        "invoiceCarrier": { "type": "3J0002", "no": "/ABC+123" },
        "meta": {}
    }
}

Request Example — 感應靠卡完成

{
    "success": true,
    "ddpayOrderId": "240618122023g4YprV",
    "merchantOrderId": "T000050001",
    "mode": "ttp",
    "payment": {
        "amount": 350,
        "paidAt": 1749560500,
        "meta": {
            "approvalCode": "240826211518lenLjx",
            "cardNo": "123456******1234",
            "cardType": "Visa"
        }
    }
}

Response

收到通知後回傳 HTTP 200 即可，無需 response body。

Error Response

HTTP Status	Description
400	找不到對應訂單記錄
401	簽章驗證失敗或時間戳逾期