App Payment Gateway

Description

APP／PWA 導轉式支付統一入口。目前支援 LINE Pay、街口線上支付、DDPay 線上付款 與 現金（臨櫃付款）。

呼叫後回傳付款導轉網址，前端將消費者導向該網址完成付款。消費者付款結束後會被導回 App Payment Gateway Return，由後端確認實際付款結果並完成訂單確認。

現金（CASH）

現金不經過任何金流，平台直接完成訂單確認，由消費者至門市臨櫃付款。

• 臨櫃付款不可使用星益欣會員點數或票券：amount 大於 0 且訂單使用了點數或票券時回 400，不扣點、不確認訂單；請於選擇臨櫃付款時移除點數與票券

• 點數或票券折抵全額時以 0 元結帳（見下方「應付 0 元的訂單」），此時平台會扣除點數與票券

• 回傳的 payment_url 即為 redirect_url 接上 status=success、order_id、type=CASH，前端照一般流程導轉即可，不會經過 App Payment Gateway Return

• 只有訂單確認成功才回 200；失敗時回 4xx，已扣除的點數與票券會自動退回
• 訂單已完成確認時重複呼叫，直接回 200 與同樣的 payment_url，不會重複扣點或確認
• 僅 KIOSK、PWA、MPOS 下的訂單可使用；其他來源的訂單回 400
• 臨櫃付款的取餐號由前端組好後以 number 帶入，平台原樣用於訂單確認；目前僅 PWA 訂單會採用，未帶入時該訂單不會有取餐號
• 應付 0 元的訂單（點數、票券等折抵全額，或訂單金額本身為 0）也走 CASH，amount 帶 0：平台會核對訂單扣除折抵後應付確實為 0，再扣除點數票券並確認訂單；此時訂單視為已付款，取餐號由平台配發，number 不採用

本 API 僅適用於 APP／PWA 的導轉式付款。KIOSK 現場掃碼付款請改用 Unified Payment Gateway。

星益欣會員的點數與票券

會員系統為星益欣會員的品牌，訂單若使用了會員點數折抵或星益欣會員票券，平台會在向金流建立交易之前， 先向會員中心扣除該筆訂單使用的點數並核銷票券：

• 扣除或核銷失敗（例如點數不足、票券已使用或已過期）時回 400，不會建立金流交易，訊息會說明原因
• 同一筆訂單重新呼叫本 API（例如消費者放棄付款頁後再按一次付款）時，已扣除的點數與票券不會重複扣除
• 付款確定失敗時，平台會自動退回已扣除的點數與票券，詳見 App Payment Gateway Return

前端不需要也不應該自行呼叫會員中心扣點、核銷票券或刪除交易，否則會重複處理。

Resource

POST /v1/payment/app/gateway

Authorization

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

Request Body Parameters

Name	Type	Description
type	string	支付類型 ALLOWED VALUES: LINE_PAY JKO_PAY DD_PAY_SD CASH：現金（臨櫃付款），不經金流直接確認訂單
order_id	string	訂單編號
store_id	string	門市編號
amount	integer	付款金額（元），必須大於 0。 CASH 例外：訂單扣除點數、票券等折抵後應付為 0 時帶 0，平台會自行核對應付金額，不為 0 時回 400。 ⚠️ DD_PAY_SD 例外：向金流請款的金額一律由平台依訂單內容重新計算（含點數折抵），此欄位僅供對帳比對，不影響實際請款金額
redirect_url	string	付款結束後導回的前端結果頁網址。 必須為 http 或 https 絕對網址；此網址會被簽章保護，導回階段無法被竄改
currency	string	付款貨幣(ISO 4217) ALLOWED VALUES: TWD（預設） JPY USD (option)
receipt_info	object	發票資訊。消費者於付款前填寫的統一編號、捐贈碼與載具，會被保存並於付款完成後原樣帶入訂單確認。 未帶入時視為空物件；由於後端在付款導回時無從得知消費者填寫的內容，需開立發票時務必於此帶入 (option)
product_name	string	商品名稱，僅 LINE Pay 使用；未帶入時取門市設定 (option)
product_image_url	string	商品圖片網址，僅 LINE Pay 使用 (option)
payment_service	string	指定 DDPay 付款服務，僅 DD_PAY_SD 適用。未帶入時，DDPay 付款頁會顯示所有可用的付款服務供消費者自行選擇 ALLOWED VALUES: cardpay linepay jko pxpayplus easywallet icashpay pluspay ipassmoney twqr (option)
payment_type	string	指定 DDPay 付款類型，僅 DD_PAY_SD 適用，須與 payment_service 一併帶入（單獨帶入回 400） ALLOWED VALUES: credit apple google linepay jko pxpayplus easywallet icashpay pluspay twqr (option)
number	string	取餐號碼，僅 CASH 使用，最長 10 字元（超過回 400）。臨櫃付款的取餐號由前端組好後帶入，其首碼可由 Get Basic Settings 的 wixgo_counter_pickup_number_prefix 取得；其他支付類型帶入時忽略 (option)

Request Example

{
    "type": "LINE_PAY",
    "order_id": "00003026091700009",
    "store_id": "000030",
    "amount": 1,
    "currency": "TWD",
    "redirect_url": "https://pwa.example.com/checkout/confirm?orderId=00003026091700009&paymentType=LINE_PAY&device_id=d043275951&authkey={authkey}&acckey={acckey}",
    "receipt_info": {
        "carrier": "",
        "carrier_type": "",
        "tax_ID_number": "24436074",
        "npoban": "",
        "amount": 1,
        "invrec_namt": 0,
        "invrec_uamt": 0,
        "invoice_tax": 0,
        "receipt_number": "",
        "take_number": false,
        "totalAmount": 1
    }
}

redirect_url 可自行附加 query string，導回時平台會在其後接上 status、order_id、type 三個參數（原有的 query string 會被保留）。此網址會連同其 query string 一併受簽章保護。

⚠️ 請勿於 redirect_url 中帶入 authkey、acckey 等憑證。該網址會出現在瀏覽器網址列、 瀏覽記錄與 Referer 標頭中，憑證會因此外流；上例中的 {authkey} / {acckey} 僅為格式示意。

receipt_info 為原樣透傳，平台不解析、不補值，因此除下表欄位外的其他欄位（如上例的 amount、totalAmount、take_number 等）皆可一併帶入，會完整傳遞至訂單確認。

Request Body Parameters - Receipt Info

消費者於付款前填寫，內容會原樣帶入付款完成後的訂單確認。

Name	Type	Description
tax_ID_number	string	統一編號 (option)
npoban	string	捐贈碼 (option)
carrier_type	string	買方載具類別 (option)
carrier	string	買方載具 (option)

Response Body Parameters

Name	Type	Description
type	string	支付類型，與 request 一致
payment_url	string	付款導轉網址，前端將消費者導向此處；CASH 為接上結果參數的 redirect_url
app_url	string｜null	開啟 App 付款畫面的網址，僅 LINE Pay 提供；其餘為 null
qr_image_url	string｜null	付款 QRCode 圖檔網址，僅街口提供；其餘為 null
transaction_id	string｜null	金流端交易編號，LINE Pay 與 DDPay 提供；街口為 null
expired_at	string｜null	付款 QRCode 失效時間，僅街口提供；其餘為 null

Response Example — LINE Pay

{
    "type": "LINE_PAY",
    "payment_url": "https://web-pay.line.me/web/wait?transactionReserveId=xxx",
    "app_url": "line://pay/payment/xxx",
    "qr_image_url": null,
    "transaction_id": "2026091100001234567",
    "expired_at": null
}

Response Example — 街口線上支付

{
    "type": "JKO_PAY",
    "payment_url": "https://onlinepay.jkopay.app/web/paymentRouter?j=xxx",
    "app_url": null,
    "qr_image_url": "https://onlinepay.jkopay.app/external/qr?j=xxx",
    "transaction_id": null,
    "expired_at": "2026-09-11 17:09:04"
}

Response Example — DDPay 線上付款

{
    "type": "DD_PAY_SD",
    "payment_url": "https://web-pay.ddpay.ai/checkout/250610154305QjDVpx",
    "app_url": null,
    "qr_image_url": null,
    "transaction_id": "250610154305QjDVpx",
    "expired_at": null
}

Response Example — 現金

{
    "type": "CASH",
    "payment_url": "https://pwa.example.com/checkout/confirm?status=success&order_id=00003026091700009&type=CASH",
    "app_url": null,
    "qr_image_url": null,
    "transaction_id": null,
    "expired_at": null
}

Response Example — 訂單已付款

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

Error Response

HTTP Status	Description
400	請求參數錯誤、導回網址格式不符、金流端建立交易失敗、DD_PAY_SD 的訂單經折抵後應付金額為 0（無需付款），或星益欣會員點數／票券扣除失敗；CASH 另含訂單來源不支援現金結帳、訂單確認失敗、臨櫃付款使用了點數或票券，以及 amount 帶 0 但訂單仍有應付金額
401	Authorization token 無效或過期
404	訂單不存在
409	CASH：同一筆訂單正在處理中，請稍後再試
500	伺服器內部錯誤

APP／PWA 支付閘道流程圖：建立交易

sequenceDiagram
    participant User as 消費者
    participant PWA as PWA 前端
    participant Omni as 全通路平台
    participant Pay as 金流（LINE Pay／街口／DDPay）
    participant Member as 星益欣會員中心

    User->>PWA: 選擇付款方式
    PWA->>Omni: POST /v1/payment/app/gateway

    Omni->>Omni: 驗證參數與導回網址格式
    alt 參數不合法
        Omni-->>PWA: Response(400, 錯誤訊息)
    end

    Omni->>Omni: 確認訂單存在
    alt 訂單不存在
        Omni-->>PWA: Response(404)
    end

    Omni->>Omni: 確認訂單是否已付款
    alt 已付款
        Omni-->>PWA: Response(200, {result=WX0000})
    end

    opt 星益欣會員訂單使用點數或票券，且尚未扣除
        Omni->>Member: 扣除點數、核銷票券
        Member-->>Omni: 結果
        alt 扣除失敗
            Omni-->>PWA: Response(400, 失敗原因)
        end
    end

    Omni->>Omni: 產生帶簽章的導回網址
    Omni->>Omni: 建立付款記錄（未付款）
    Omni->>Pay: 建立交易（帶入我方導回網址）
    alt 建立交易失敗
        Omni->>Member: 退回本次扣除的點數與票券
        Omni-->>PWA: Response(400)
    end
    Pay-->>Omni: 回傳付款導轉資訊

    Omni->>Omni: 記錄金流端交易編號
    Omni-->>PWA: Response(200, 導轉資訊)
    PWA->>User: 導向付款網址

APP／PWA 支付閘道流程圖：現金（CASH）

參數驗證、訂單存在與已付款檢查同上圖。

sequenceDiagram
    participant PWA as PWA 前端
    participant Omni as 全通路平台
    participant Member as 星益欣會員中心

    PWA->>Omni: POST /v1/payment/app/gateway（type=CASH）

    alt amount 大於 0、訂單未確認且使用點數或票券
        Omni-->>PWA: Response(400, 臨櫃結帳不允許使用點數或票券)
    end
    alt 訂單來源不支援現金結帳
        Omni-->>PWA: Response(400)
    end
    alt 同一筆訂單處理中
        Omni-->>PWA: Response(409)
    end

    alt 訂單已確認
        Omni-->>PWA: Response(200, payment_url)
    else 訂單未確認
        opt amount 為 0
            Omni->>Omni: 核對訂單扣除折抵後應付金額
            alt 應付金額不為 0
                Omni-->>PWA: Response(400)
            end
        end
        opt 星益欣會員訂單使用點數或票券，且尚未扣除
            Omni->>Member: 扣除點數、核銷票券
            alt 扣除失敗
                Omni-->>PWA: Response(400, 失敗原因)
            end
        end
        Omni->>Omni: 確認訂單（現金、臨櫃付款）
        alt 確認失敗且訂單仍未確認
            Omni->>Member: 退回本次扣除的點數與票券
            Omni-->>PWA: Response(400)
        end
        Omni-->>PWA: Response(200, payment_url)
    end
    PWA->>PWA: 導向 payment_url（結果頁）