Unified Payment Gateway

Description

KIOSK 現場付款統一入口。type 固定填入 Get Payments 回傳的 payment_methods[].id，前端不做任何轉換直接帶入。

唯一例外：id 為 CREDIT_CARD 時，一般本地刷卡情境不會呼叫本 API；但若門市啟用 DDPay 感應付款，Get Payments 會回傳合併後的 id: "DD_PAY_TTP"，此時才需呼叫本 API 並帶入 type: "DD_PAY_TTP"。

DDPay 被掃（id: "DD_PAY_CPM"）與感應（id: "DD_PAY_TTP"）皆為單次同步呼叫：被掃由 KIOSK 掃描顧客付款條碼後呼叫本 API，回應即內含付款結果；感應由後端內部輪詢 DDPay 最長 30 秒後才回應（見下方 Error Response 408）。兩者皆無需前端自行重複輪詢本 API。

Resource

POST /v1/payment/unified/gateway

Authorization

採用 OAuth 2.0 Bearer Token，詳細使用流程請參考 Auth Login。

Request Body Parameters

Name	Type	Description
type	string	支付類型，填入 Get Payments 回傳的 id，如 LINE_PAY、JKO_PAY、CREDIT_CARD、DD_PAY_CPM、DD_PAY_TTP
order_id	string	我方訂單編號
store_id	string	門市編號
amount	integer	付款金額（元）
payment_info	object	付款動作所需的額外參數。DDPay 被掃（CPM）必填 payment_info.barcode，帶入 KIOSK 掃描顧客付款畫面所得的條碼值；DDPay 感應（TTP）傳空物件 {} 即可，實際感應動作由 DDPay 終端處理
is_confirm_order	boolean	付款成功後是否自動確認訂單，預設 false (option)
is_receipt	boolean	是否需要開立發票，預設 false (option)
kiosk_id	string	KIOSK 機台編號 (option)

Request Example — DDPay 感應

{
    "type": "DD_PAY_TTP",
    "order_id": "T000050001",
    "store_id": "STORE001",
    "amount": 350,
    "payment_info": {},
    "is_confirm_order": true,
    "kiosk_id": "KSK001"
}

Request Example — DDPay 被掃

{
    "type": "DD_PAY_CPM",
    "order_id": "T000050002",
    "store_id": "STORE001",
    "amount": 120,
    "payment_info": { "barcode": "1234567890" },
    "kiosk_id": "KSK001"
}

Response Body Parameters

Name	Type	Description
confirmed	boolean	付款完成後是否已自動執行訂單確認。true：無需額外動作即完成確認（如信用卡／Apple Pay／Google Pay）；false：需 KIOSK 取得電子發票載具後再另行呼叫確認訂單
payments	array	付款明細清單
payments[].payment_amount	integer	付款金額（元）
payments[].type	string	支付類型，與 request 的 type 一致
payments[].transaction_id	string｜null	交易流水號，付款完成前為 null
payments[].relate_id	string｜null	關聯單號，付款完成前為 null
payments[].service	string｜null	實際支付子服務，僅付款完成後才會有值。ALLOWED VALUES： credit apple google linepay jko pxpayplus easywallet icashpay pluspay twqr 尚未付款、或非 DDPay 付款方式時為 null；DDPay 感應（TTP）付款成功時固定為 credit (option)
electronic_invoice_carrier	string	電子發票載具號碼，無則為空字串

Response Example — 付款完成（同步，DDPay 被掃）

{
    "confirmed": true,
    "payments": [{
        "payment_amount": 350,
        "type": "DD_PAY_CPM",
        "transaction_id": "240826211518lenLjx",
        "relate_id": "240826211518lenLjx|linepay",
        "service": "linepay"
    }],
    "electronic_invoice_carrier": ""
}

Response Example — 付款完成（同步，DDPay 感應）

{
    "confirmed": false,
    "payments": [{
        "payment_amount": 350,
        "type": "DD_PAY_TTP",
        "transaction_id": "070152",
        "relate_id": "260707085815lxjvOg|credit",
        "service": "credit"
    }],
    "electronic_invoice_carrier": ""
}

Error Response

HTTP Status	Description
400	請求參數錯誤或格式不符
401	Authorization token 無效或過期
404	訂單不存在
408	感應付款輪詢逾時仍未取得結果
500	伺服器內部錯誤