復原漏收的 LINE MINI App 付款 Webhook：7 天對帳操作手冊

若要復原漏收的 LINE MINI App 付款 Webhook，請在 7 天內查詢 LINE 官方事件歷史，分頁時維持原始時間範圍與篩選條件不變，再將每個傳回的 purchaseComplete 事件交給以 orderId 為冪等鍵的同一套處理邏輯。購買預留成功不代表付款完成；事件歷史是故障復原來源，不能取代即時 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 後，才能發放數位項目。

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

問題	應信任的證據
預留請求是否成功？	reserve 回應、已儲存的 orderId 與 x-line-request-id
購買是否完成？	purchaseComplete 事件或官方對帳結果
端點是否收到即時投遞？	原始請求 log 與 Webhook 處理紀錄
業務 handler 是否只發放一次權益？	以 orderId 為鍵的冪等紀錄

既有的 LINE MINI App 費用與客服 Webhook 指南說明了付款事件與顧客訊息為何應分屬不同系統。這份操作手冊從更深入一層的情境開始：付款 Webhook 原本應該送達，但端點無法使用或處理失敗。

如何復原漏收的 LINE MINI App 付款 Webhook

1. 在 7 天期限結束前找出缺口

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

• 內部 checkout ID；
• LINE 的 orderId；
• 回應 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"

上述時間戳記是 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 是業務交易邊界。它應以原子操作插入冪等紀錄並發放項目；若同一個 orderId 已經套用，則不執行任何動作。由於同一個 Webhook 可能投遞多次，LINE 的應用程式內購買開發指南也特別建議使用 orderId 避免重複發放。

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

不要只為復原作業建立第二套權益發放路徑。請將復原的事件轉換成即時 Webhook 所使用的同一個內部命令，並將來源記錄為 line_event_history。接著比對：

1. 已預留但內部狀態尚未完成的 orderId；
2. 即時 Webhook log；
3. 固定事件時間範圍內的歷史紀錄；
4. 冪等紀錄與權益異動。

事件歷史回應是使用 channel access token 取得的。它不是原始 HTTP 投遞，因此不應預期其中包含原始的 x-line-signature header。即時 Webhook 仍須持續驗證這個 header：LINE 會使用 channel secret 對原始請求 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 為鍵的原子冪等 handler，讓第二次嘗試不執行任何動作。

LINE 的 x-line-signature 與 UnifyPort Webhook 簽章相同嗎？

不同。LINE 會簽署付款 Webhook 的原始請求 body，並傳送 Base64 簽章；啟用 signing_secret 後，UnifyPort 會簽署時間戳記加上原始請求 body，並傳送自己的時間戳記與簽章 header。請分別驗證兩套協定。

下一步

請依照官方 LINE MINI App API 參考文件實作並測試復原查詢，再將工作排程在 7 天保留期間內。如果另一項需求是接收一般 LINE 客服訊息，請先讓付款路徑穩定，再依照 UnifyPort LINE 授權指南設定獨立的訊息路徑。

資料來源

• LINE MINI App API 參考文件：應用程式內購買與 Webhook 事件歷史
• 整合 LINE MINI App 應用程式內購買功能
• LINE MINI App 應用程式內購買開發指南

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