Skip to content

Jkos Online Pay

Description

街口線上支付付款。

Resource

POST /v1/payment/jkos/online/entry

Authorization

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

Request Body Parameters

Name Type Description
store_id string 門市編號
order_id string 訂單編號
currency string 付款貨幣(ISO 4217)，請帶入 “TWD”、”JPY” 或 “USD”
total_price string 訂單原始金額。(金額必須送大於0元)
final_price string 訂單實際消費金額。(金額必須送大於0元)
result_display_url string 消費者付款完成後，將消費者導向此網址。
(option)
use_self_jkos_params boolean 使用自己帶的金流參數
(option)
jkos_store_id string 街口線上支付商店編號
(option)
jkos_api_key string 街口線上支付API金鑰
(option)
jkos_secret_key string 街口線上支付加密金鑰
(option)

Request Example

{
    "store_id": "MYYJ01",
    "order_id": "MYYJ01250505006",
    "currency": "TWD",
    "total_price": 100,
    "final_price": 100,
    "result_display_url": "https://result.com",
    "use_self_jkos_params": true,
    "jkos_store_id": "2166480e-15ab-11f0-94d5-005056b665e9",
    "jkos_api_key": "TJxSPLd78-AUTG8bisnaAAdduAwzJyEM",
    "jkos_secret_key": "cAel-zb6Nd75Jj3tdddIYXE8kAXKJnWLRSFpEINRgLqddS_cCPLf63YeLFw8Y0N78_QTshvl6JlxEOhBQCevlg"
}

Response Body Parameters

Name Type Description
result Result 請參照 API 回覆代碼
message string 結果訊息或失敗理由
result_object Result Object 細節

Response Body Parameters - Result

Status Code Description
000 交易成功
100 訂單不存在
101 此訂單號已付款
103 退款金額錯誤
105 1. remain_amount 金額不正確
2. refund_amount 金額不一致（當refund_amount與先前同refund_order_id請求不一致）
108 1. 店家收款額度已達上限
2. 用戶在該店家每日交易已達限額
113 因退款金額大於店家累計未請款金額，故退款失敗
200 失敗；參數錯誤
201 失敗；參數錯誤
922 退款總金額超過原訂單金額
999 其他

Response Body Parameters - Result Object

Name Type Description
refund_tradeNo string 付款導向網址
debit_amount string 付款 QRCode 圖檔
redeem_amount string QRCode / payment_url 失效時間

Response Example - Http Code 200

{
    "result": "000",
    "message": null,
    "result_object": {
        "payment_url": "https://uat-onlinepay.jkopay.app/web/paymentRouter?j=OL%231%3aENT%23cWlGMHpFSXRVbzhUTWFtR1YwQkRUdz09%3aS%232166480e-15ab-11f0-94d5-005056b665e9%3aA%23100%3aCUR%23TWD%3aSRC%23REDIRECT_MWEB%3aUNRDM%230.00%3aFX%230%3aTA%23100%3aTCUR%23TWD%3aFXR%231.00%3aUR%231%3aD%23D&s=2e0247d00c3c25e7e9777519d087e4ed32e7b75a9aae9687caeb65446162fdf0",
        "qr_img": "https://uat-onlinepay.jkopay.app/external/qr?j=OL%231%3aENT%23cWlGMHpFSXRVbzhUTWFtR1YwQkRUdz09%3aS%232166480e-15ab-11f0-94d5-005056b665e9%3aA%23100%3aCUR%23TWD%3aSRC%23REDIRECT_MWEB%3aUNRDM%230.00%3aFX%230%3aTA%23100%3aTCUR%23TWD%3aFXR%231.00%3aUR%231%3aD%23D&s=2e0247d00c3c25e7e9777519d087e4ed32e7b75a9aae9687caeb65446162fdf0",
        "qr_timeout": "2025-05-05 17:09:04"
    }
}

Response Example - Http Code 200

{   "result": "WX0000",
    "message": "訂單交易成功，請勿重複建立"
}

Response Example - Http Code 202

{   "result": "WX0001",
    "message": "訂單付款處理中，請勿重複建立"
}

JKOS 線上支付 API 流程圖：ENTRY（建立訂單）

sequenceDiagram
    participant User as 消費者
    participant Client as Client
    participant Omni as 全通路平台
    participant DB as 全通路資料庫
    participant JKOS as JKOS

    User->>Client: 點餐並選擇街口支付
    Client->>Omni: 請求建立JKOS線上支付訂單

    Omni ->>Omni: 檢查金流參數
    alt 檢查金流參數失敗
        Omni -->> Client: Response(400, 金流參數錯誤訊息)
    else
        Omni -->> Omni: Response(204)
    end

    Omni->>DB: 查詢 weborder02 確認是否已付款
    alt weborder02 有付款資訊
        alt 主要付款方式付款成功
            Omni -->> Client: Response(200, {result=WX0000, message=訂單交易成功，請勿重複建立})
        else 尚未付款
            Omni ->> DB: delete_weborder02()
        end
    else 沒有付款資訊
        Omni -->> Omni: Response(204)
    end

    Omni->>JKOS: 查詢 JKOS 訂單狀態
    JKOS-->>Omni: Response(200, 訂單資訊)

    alt 訂單已付款
        Omni -->> Client: Response(200, {result=WX0000, message=訂單交易成功，請勿重複建立})
    else 訂單付款處理中
        Omni -->> Client: Response(202, {result=WX0001, message=訂單付款處理中，請勿重複建立})
    else 查無訂單
        Omni -->> Omni: Response(204)
    end

    Omni->>DB: 寫入預設 weborder02
    Omni->>Omni: 處理向金流方的請求參數
    Omni->>JKOS: 發起訂單建立請求
    JKOS-->>Omni: 回傳 QRCode 與交易資訊
    Omni-->>Client: 回傳付款資訊 (QRCode + timeout)