Jkos Online Pay Result

Description

接收 JKOS Online PAY 付款結果。

此 API 是給街口支付呼叫的。

當全通路向街口請求付款成功後，街口會打這支 API 把付款結果送給全通路。

付款成功時，除記錄款項外亦會接續完成訂單確認。此行為僅適用於支援街口線上支付的點餐來源；其餘來源僅記錄款項、不進行訂單確認，並於系統記錄中標註略過原因。

此通知不經過消費者的瀏覽器，是街口線上支付的保底通道：即使消費者付款後未被成功導回前端，款項與訂單仍會被正確處理。此通知也未送達時，由系統排程定期向街口查詢並補記款項與完成訂單確認。

同一筆訂單的付款結果可能同時經由此通知、消費者導回與系統排程送達，平台保證款項只記錄一次：

同一筆訂單正在由其他途徑處理時，直接回應成功、不重複處理（由正在處理的途徑完成）
款項已記錄過（例如街口重送通知）時不再重複記錄，僅在訂單尚未確認時補完成訂單確認

此 API URL 的 company_id、shop_id 是全通路請求街口付款(Jkos Online Entry) API 時就設定好，並以 result_url 傳給街口，街口帶給全通路時就知道是哪間公司門市，不須額外請街口相關人員設定。

Resource

POST /v1/payment/jkos/online///result

Request Body Parameters

Name	Type	Description
transaction	Transaction	交易內容

Request Body Parameters - Transaction

Name	Type	Description
platform_order_id	string	訂單編號
status	Status	訂單狀態代碼
tradeNo	string	街口端交易序號
trans_time	boolean	交易時間
currency	string	付款貨幣[ISO 4217]，請帶入TWD
final_price	string	訂單實際消費金額
redeem_amount	string	折抵金額=街口幣折抵+官方街口券折抵+店家街口券折抵
redeem_detail	Redeem Detail	街口線上支付加密金鑰 (option)
debit_amount	string	付款方式扣款金額（折抵後金額）
invoice_vehicle	string	街口帳戶發票載具 (option)
channel_type	string	支付工具類型： account: 儲值帳戶 bank: 銀行帳戶 creditcard: 信用卡
transaction_seq	string	街口線上支付加密金鑰 (option)

Response Body Parameters - Status

Status Code	Description
0	交易成功
1	付款處理中
101	此訂單號尚未付款
102	此訂單號不存在

Request Body Parameters - Redeem Detail

Name	Type	Description
jko_coin_amount	integer	街口幣折抵
official_coupon_amount	integer	官方街口券折抵
store_coupon_amount	integer	店家街口券折

Request Example

POST /v1/payment/jkos/online/18090377/000030/result

{
    "transaction": {
        "platform_order_id": "00003025050900011",
        "status": 0,
        "tradeNo": "J0081521125050800003",
        "trans_time": "2025-05-08 11:50:57",
        "currency": "TWD",
        "final_price": "20",
        "redeem_amount": "6",
        "redeem_detail": {
            "jko_coin_amount": 6,
            "official_coupon_amount": 0,
            "store_coupon_amount": 0
        },
        "debit_amount": "8",
        "invoice_vehicle": "/7692CV2",
        "channel_type": "account",
        "transaction_seq": "S20250508000009"
    }
}

Response Example - Http Code 200

{}

接收 JKOS Online PAY 付款結果流程圖

sequenceDiagram
    participant JKOS as 街口支付
    participant Omni as 全通路平台

    JKOS->>Omni: POST /jkos/online/{company_id}/{shop_id}/result

    alt 同一筆訂單正在由消費者導回或系統排程處理
        Omni-->>JKOS: Response(200, {})
    end

    Omni->>Omni: 確認款項是否已記錄
    alt 款項已記錄
        opt 訂單尚未確認
            Omni->>Omni: 依點餐來源決定是否確認訂單
        end
        Omni-->>JKOS: Response(200, {})
    end

    Omni->>Omni: 判斷是否使用店家街口券
    alt 未使用街口券
        Omni->>Omni: 記錄款項
    else 有使用街口券
        Omni->>Omni: 判斷券認列為支付方式 or 商品
        alt 為支付方式
            Omni->>Omni: 將折抵金額攤提至各品項，並記錄街口券付款
        else 為商品
            Omni->>Omni: 加入街口券商品，並更新訂單實付金額
        end
        Omni->>Omni: 依實付金額更新發票金額
        Omni->>Omni: 記錄款項
    end
    Omni->>Omni: 依點餐來源決定是否確認訂單
    Omni-->>JKOS: Response(200, {})