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)