Skip to content

App Payment Gateway Return

Description

APP／PWA 導轉式支付的統一回收端點。

消費者於金流端付款結束後，會由金流把瀏覽器導回此網址。此網址由 App Payment Gateway 在建立交易時產生並帶給金流， 前端不需自行組裝或呼叫。

後端收到導回後不直接採信導回結果，而是主動向金流確認實際付款狀態：

  • LINE Pay：導回僅代表消費者已完成授權，後端必須再請款才算完成。 後端會先向 LINE Pay 查詢該筆付款請求的狀態，確認可授權後才執行請款； 若查得款項已完成，則不重複扣款，僅補記並完成訂單確認
  • 街口線上支付：導回不帶交易結果，故此時主動查詢該筆交易的真實狀態
  • DDPay 線上付款：導回不帶交易結果，故此時主動查詢該筆訂單的付款狀態。尚未付款的訂單在 DDPay 端查不到，此情況一律視為處理中而非失敗

確認付款成功後即完成訂單確認，最後將消費者導回建立交易時指定的前端結果頁。

星益欣會員的點數與票券退回

建立交易時已扣除的星益欣會員點數與票券（見 App Payment Gateway），只在付款確定失敗時自動退回：

  • 會退回：LINE Pay 付款已取消、逾時、失敗或授權已過期；街口訂單不存在等不可能再付款的狀態；DDPay 訂單已取消、付款失敗或已逾期
  • 不會退回：付款處理中、平台當下無法確認結果、街口尚未付款（QR Code 失效前消費者仍可付款）、付款成功但訂單確認失敗（款項已收）
  • 消費者若已重新發起付款，舊交易的失敗不會退回新交易使用的點數與票券
  • 回傳給前端的 status 不受退回結果影響

未經導回的交易由系統排程補救：LINE Pay、街口線上支付與 DDPay 線上付款在付款確定失敗後，同樣會退回點數與票券。

⚠️ 會員中心只允許退回 5 分鐘內扣除的點數與票券。超過時退回會失敗、點數與票券維持扣除狀態，需由門市或客服人工處理。

訂單確認會沿用建立交易時帶入的發票設定與發票資訊（統一編號、捐贈碼、載具），因此需開立發票時，務必於 App Payment Gateway 的 receipt_info 帶入——本端點由金流導向，無法取得消費者填寫的內容。

導回是不可靠通道（消費者可能中途關閉頁面）。街口另有不經過瀏覽器的付款結果通知 作為保底；LINE Pay、DDPay 線上付款與街口線上支付都由系統排程定期補救未完成的交易 （街口的付款結果通知也未送達時，同樣由排程補救）。 因此即使消費者未被成功導回，款項與訂單仍會被正確處理。

補救的範圍： * 已授權但尚未請款、或已付款但尚未入帳的交易：訂單建立後 2 天內 * 已付款但訂單確認失敗的交易：只補救當天建立的訂單。跨日仍未確認的訂單不會自動送出，需由門市或客服人工處理

Resource

GET /v1/payment/app/gateway/return

Authorization

不需 Bearer Token。此端點由消費者的瀏覽器導向，身分與訂單資訊全部來自網址中 帶有簽章的 state 參數；簽章驗證失敗一律拒絕，且不會導向任何網址。

Query Parameters

Name Type Description
state string 由 App Payment Gateway 建立交易時簽發，內含訂單與導回資訊。有效期 15 分鐘
transactionId string 由 LINE Pay 導回時自動附加
(option)
orderId string 由 LINE Pay 導回時自動附加
(option)
cancel string 消費者於 DDPay 付款頁選擇取消時自動附加，值為 1。平台仍會主動查詢一次付款狀態（消費者可能已付款才按取消），確認未付款才回報失敗
(option)

Response

成功處理後回應 302，Location 為建立交易時指定的 redirect_url，並附加以下查詢參數：

Name Type Description
status string 處理結果
ALLOWED VALUES:
  • success：付款成功，訂單已確認
  • pending：付款尚未完成，或平台當下無法確定結果。款項若已授權，平台會於背景自動完成請款與訂單確認，前端不應提示付款失敗，也不應引導消費者重新付款，請改為提示處理中並稍後查詢訂單狀態
  • failed：已確定付款未完成或已取消
order_id string 訂單編號
type string 支付類型

Response Example — 302 Location

https://pwa.example.com/order/result?status=success&order_id=ZJ00126091100001&type=LINE_PAY

Error Response

HTTP Status Description
400 state 缺漏、遭竄改或已逾期。此時不會導向任何網址

冪等性

同一筆訂單重複導回（例如消費者重新整理頁面），或導回與金流的付款結果通知同時抵達時， 付款只會被入帳一次、訂單只會被確認一次，折抵金額也不會被重複計算。

街口線上支付與 DDPay 線上付款的款項已由其他途徑記錄、但訂單尚未完成確認時（例如付款結果通知已記錄款項、 確認訂單卻失敗），導回時會補完成訂單確認；確認失敗回 pending。

APP／PWA 支付閘道流程圖：接收付款結果

sequenceDiagram
    participant User as 消費者
    participant Omni as 全通路平台
    participant Pay as 金流（LINE Pay／街口）
    participant Order as 訂單服務

    Pay->>User: 付款結束
    User->>Omni: GET /v1/payment/app/gateway/return?state=...

    Omni->>Omni: 驗證 state 簽章與有效期
    alt 驗證失敗
        Omni-->>User: Response(400)
    end

    Omni->>Omni: 檢查該筆是否已付款
    alt 已付款（重複導回，或付款結果通知已先記錄款項）
        opt 訂單尚未確認（街口、DDPay）
            Omni->>Order: 確認訂單
            alt 確認失敗
                Omni-->>User: Response(302, status=pending)
            end
        end
        Omni-->>User: Response(302, status=success)
    end

    alt LINE Pay
        Omni->>Pay: 請款
        Pay-->>Omni: 請款結果
    else 街口線上支付
        Omni->>Pay: 查詢交易狀態
        Pay-->>Omni: 交易狀態
    end

    alt 付款成功
        Omni->>Omni: 更新付款記錄
        Omni->>Order: 確認訂單
        Omni-->>User: Response(302, status=success)
    else 付款處理中或結果未確定
        Omni-->>User: Response(302, status=pending)
    else 已確定付款未完成
        opt 星益欣會員訂單已扣除點數或票券，且付款確定失敗
            Omni->>Omni: 退回點數與票券
        end
        Omni-->>User: Response(302, status=failed)
    end