教學 July 22, 2026

恢復漏收嘅 LINE MINI App 付款 Webhook：7 日對帳操作手冊

要恢復漏收嘅 LINE MINI App 付款 Webhook，請喺 7 日內查詢 LINE 官方事件歷史，分頁期間保持原本嘅時間範圍同篩選條件不變，再將每個傳回嘅 purchaseComplete 事件交畀以 orderId 做冪等 key 嘅同一套處理邏輯。購買預留成功唔代表付款完成；事件歷史係故障恢復來源，唔可以取代即時 Webhook 監察。

重點一覽

LINE 嘅事件歷史涵蓋過去 7 日嘅 Webhook 投遞，每頁最多傳回 100 筆紀錄。
status=FAILED 表示 Webhook 投遞失敗，唔代表客戶購買失敗。
預留購買時就記錄 orderId，即時同恢復取得嘅 purchaseComplete 事件都用佢去除重複。
付款恢復同客服訊息路由應該保持分開：兩者使用唔同嘅事件類型、憑證、簽名同營運負責人。

點解預留成功唔等於購買完成

LINE MINI App 應用內購買係一個多步驟嘅官方流程。伺服器會先用 POST https://api.line.me/iap/v1/product/reserve 預留購買，LINE 再傳回 orderId；但用戶仍然可能關閉應用程式、喺應用程式商店取消、失去網絡連線，或者未完成付款。所以，LINE 嘅整合指南要求只可以喺收到購買完成 Webhook 之後，先發放數碼項目。

呢項邊界會將故障判斷拆成四個唔同問題：

問題	應該信任嘅證據
預留 request 係咪成功？	reserve response、已儲存嘅 `orderId` 同 `x-line-request-id`
購買係咪完成？	`purchaseComplete` 事件或官方對帳結果
端點係咪收到即時投遞？	原始 request log 同 Webhook 處理紀錄
業務 handler 係咪只發放一次權益？	以 `orderId` 做 key 嘅冪等紀錄

現有嘅 LINE MINI App 費用同客服 Webhook 指南解釋咗點解付款事件同客戶訊息應該屬於唔同系統。呢份操作手冊由更深入一層嘅情境開始：付款 Webhook 原本應該送達，但端點無法使用或者處理失敗。

點樣恢復漏收嘅 LINE MINI App 付款 Webhook

1. 喺 7 日期限結束前搵出缺口

預留購買時，請儲存以下資料：

內部 checkout ID；
LINE 嘅 orderId；
response header x-line-request-id；
預留時間同預期商品；
purchaseComplete 事件係咪已經套用。

如果預留紀錄超過正常結帳時間仍未解決，就應該發出警示。唔好立即將佢標記為已付款，亦唔好等到第 7 日先開始調查：官方歷史端點只接受過去 7 日內嘅時間範圍。

2. 查詢固定嘅恢復時間範圍

LINE 官方 MINI App API 參考文件記載咗以下恢復端點：

curl --get "https://api.line.me/iap/v1/webhook/events" \
  -H "Authorization: Bearer ${LINE_CHANNEL_ACCESS_TOKEN}" \
  --data-urlencode "startEpochSeconds=1784678400" \
  --data-urlencode "endEpochSeconds=1784700000" \
  --data-urlencode "pageSize=100" \
  --data-urlencode "status=FAILED"

上面嘅 timestamp 係 2026 年 7 月 22 日一段明確嘅示例時間範圍，唔可以直接複製到正式環境。請按照事故發生嘅 UTC 起訖時間產生 epoch 秒數。使用 status=FAILED 可以搵出 LINE 未能完成嘅投遞；如果要對帳該時間範圍內嘅所有投遞，就省略 status。SUCCESS 同 FAILED 描述嘅係投遞狀態，唔係購買結果。

3. 分頁期間保持查詢條件不變

結果會按照 LINE 開始發送每個 Webhook 嘅時間排序。每頁最多包括 100 筆紀錄，而且可能帶有 nextCursor。查詢之後嘅頁面時，請保持 startEpochSeconds、endEpochSeconds、pageSize 同 status 不變，只修改 cursor。

以下 Node.js 示例明確保留咗呢項邊界：

const baseUrl = "https://api.line.me/iap/v1/webhook/events";
const fixedQuery = {
  startEpochSeconds: "1784678400",
  endEpochSeconds: "1784700000",
  pageSize: "100",
  status: "FAILED",
};

let cursor;

do {
  const query = new URLSearchParams(fixedQuery);
  if (cursor) query.set("cursor", cursor);

  const response = await fetch(`${baseUrl}?${query}`, {
    headers: { Authorization: `Bearer ${process.env.LINE_CHANNEL_ACCESS_TOKEN}` },
  });

  if (!response.ok) {
    throw new Error(`LINE event history failed: ${response.status}`);
  }

  const page = await response.json();
  for (const record of page.events) {
    if (record.event.type === "purchaseComplete") {
      await applyPurchaseOnce(record.event.orderId, record.event);
    }
  }

  cursor = page.nextCursor ?? undefined;
} while (cursor);

applyPurchaseOnce 係業務交易邊界。佢應該以 atomic operation 插入冪等紀錄並發放項目；如果同一個 orderId 已經套用，就唔執行任何動作。由於同一個 Webhook 可能會投遞多次，LINE 嘅應用內購買開發指南亦特別建議使用 orderId 避免重複發放。

4. 對帳歷史同即時處理結果

唔好淨係為恢復工作建立第二套權益發放路徑。請將恢復嘅事件轉換成即時 Webhook 使用嘅同一個內部 command，並將來源記錄為 line_event_history。然後比對：

已預留但內部狀態仲未完成嘅 orderId；
即時 Webhook log；
固定事故時間範圍內嘅歷史紀錄；
冪等紀錄同權益變動。

事件歷史 response 係使用 channel access token 取得。佢唔係原始 HTTP 投遞，所以唔應該預期當中包含原本嘅 x-line-signature header。即時 Webhook 仍然要繼續驗證呢個 header：LINE 會使用 channel secret，對原始 request body 計算 HMAC-SHA256 digest，再將佢編碼成 Base64。

5. 用可以量度嘅檢查點結束事故處理

只要範圍內仲有預留未分類，恢復工作就未完成。每筆預留都要分類成「已完成並套用」「未完成」「已取消」或「轉交人手調查」。請記錄確實嘅 UTC 範圍、篩選條件、頁數、已恢復嘅 orderId，以及最後一次成功執行時間。將輕量對帳工作安排喺 7 日保留期限之前，避免週末故障喺未被發現嘅情況下超出可以查詢嘅期間。

目前嘅事件歷史文件指出，呢個端點會擷取 purchaseComplete 事件，而退款歷史支援會另行規劃。假設同一套恢復路徑亦涵蓋退款之前，請先查閱最新嘅參考文件。

UnifyPort 適合處理咩、唔處理咩

UnifyPort 唔會預留 LINE MINI App 購買、確認應用程式商店付款、恢復 LINE 付款事件、發放數碼項目，亦無法滿足 LINE 嘅審核要求。呢啲工作都應該由 LINE 官方應用內購買流程負責。

UnifyPort 適合處理下一個事件係一般客戶訊息嘅情況。例如，買家付款後因為項目未出現而發訊息查詢。受支援嘅 LINE 帳號可以將呢段對話以標準化嘅 message.received 事件送達。如果 UnifyPort Webhook 端點設定咗 signing_secret，投遞會使用 X-Device-Timestamp 同 X-Device-Signature；呢套簽名機制同 LINE 付款 Webhook 嘅 x-line-signature 並唔相同。

如果想深入了解客戶訊息端嘅重試同冪等處理，請閱讀 Webhook HMAC 重送防護：時間戳、重試同冪等。即使兩個 handler 最後會更新同一套客服或訂單系統，都應該保持分開。

限制同取捨

LINE 官方歷史 API 係恢復 MINI App 購買 Webhook 嘅正確路徑。非官方介面無法延長保留期限，亦無法搵返平台付款紀錄。
7 日回溯唔係長期帳本。請自行保存預留、事件、權益同結算紀錄。
status=FAILED 可以收窄到投遞失敗嘅範圍，但可能會漏咗端點已接受、應用程式之後卻處理失敗嘅投遞。如果故障點喺應用程式而唔係傳輸層，請執行範圍更廣嘅對帳。
應用內購買仍然係日本地區限定、需要審核嘅 MINI App 功能。設計付款流程之前，請確認最新資格；已驗證同未驗證 MINI App 檢查表涵蓋呢項更早期嘅決定。

FAQ

LINE MINI App 付款 Webhook 歷史可以查幾耐？

官方端點接受過去 7 日內嘅 Webhook 歷史。請喺期限前執行恢復，並用自己嘅長期帳本處理更早發生嘅事故。

`status=FAILED` 係咪代表客戶付款失敗？

唔係。佢表示 LINE 嘅 Webhook 投遞失敗。購買狀態同投遞狀態並唔相同；請使用傳回嘅事件，加上預留同權益紀錄對帳訂單。

預留端點傳回 `200` 之後，可以發放項目嗎？

唔可以。預留成功唔保證購買完成。只可以喺處理 purchaseComplete 事件後發放項目，並用 orderId 確保冪等。

歷史恢復會重複投遞同一筆購買嗎？

查詢可能會傳回即時 handler 已經套用嘅事件。請畀兩條路徑呼叫同一個以 orderId 做 key 嘅 atomic idempotent handler，令第二次嘗試唔執行任何動作。

LINE 嘅 `x-line-signature` 同 UnifyPort Webhook 簽名一樣嗎？

唔一樣。LINE 會簽署付款 Webhook 嘅原始 request body，並傳送 Base64 簽名；啟用 signing_secret 後，UnifyPort 會簽署 timestamp 加上原始 request body，並傳送自己嘅 timestamp 同簽名 header。請分別驗證兩套協定。

下一步

請按照官方 LINE MINI App API 參考文件實作並測試恢復查詢，再將工作安排喺 7 日保留期間內。如果另一項需求係接收一般 LINE 客服訊息，請先確保付款路徑穩定，再按照 UnifyPort LINE 授權指南設定獨立嘅訊息路徑。

資料來源

官方事實核對日期：2026 年 7 月 22 日。