GCP帳號開戶服務 GCP結算系統與第三方支付對接

第一章：把「結算」想清楚，先定義真相

GCP帳號開戶服務 很多團隊談 GCP 結算系統與第三方支付對接時，第一反應是「呼叫 API、解析回傳、寫入資料庫」。這樣做能跑，但不一定能對。真正的難點往往藏在三個地方：第一，交易的狀態到底由誰定義；第二，金額在不同系統之間如何保持一致；第三，當出現重試、延遲、或部分成功時，系統如何仍然可追溯。

結算系統不是純粹的帳本，它是一套能回答問題的流程：某筆訂單什麼時候被支付、支付結果是否確定、金額如何入帳、手續費由誰負擔、退款何時生效、對帳差異如何定位。你若在對接時只關心「成功回來了」，就會在後續對帳或稽核時付出更高成本。

因此，建議把對接拆成「流程設計」與「工程落地」。流程設計決定資料流與狀態機；工程落地決定幂等、重試、日誌與告警。下面的內容會以這個順序展開。

第二章：系統角色與資料邊界

在對接前，先把角色切清楚。常見角色包括：商戶系統、結算系統（可在 GCP 上）、第三方支付平台、以及外部清算/銀行通道。

對接時，結算系統通常扮演「收斂交易真相」的角色：它接收第三方支付的通知與查詢結果，將支付事件落到內部交易狀態，並推動後續入帳或撥付。商戶系統提供訂單與商品資訊；第三方支付提供支付結果與清算明細；結算系統則維護一致的帳務口徑。

2.1 交易主鍵：用什麼識別一筆錢

你需要至少三個關鍵識別：商戶訂單號、支付方交易號（第三方提供）、以及結算側交易號（你內部生成）。它們之間必須保持關聯，否則發生重送或查詢時難以定位。

實務上常見做法：

• 商戶訂單號：來自業務端，通常是唯一。
• 第三方交易號：支付完成後第三方返回，用於後續退款/查詢。
• 內部結算交易號：用於你自己的狀態機、對帳報表與入帳流水。

注意：對接時不要只存一個號碼。當第三方通知延遲、或你的請求超時時，你必須能用「查詢條件」還原交易。

GCP帳號開戶服務 2.2 金額口徑：總額、實收、手續費與稅

一筆交易通常會出現多種金額：

• 應付總額：訂單金額。
• 支付實收：第三方扣除/含稅後實際打到你方口徑的金額（依平台規則）。
• 手續費：由誰負擔、怎麼計算。
• 退款金額：部分退款或全額退款。
• 淨額/可結算金額：用於後續對帳與結算。

你需要建立明確欄位並在入帳時使用同一套口徑。常見失誤是：退款時拿訂單原額直接抵扣，忽略手續費或實收差異，導致對帳永遠差一點點。

2.3 狀態邊界：支付狀態與結算狀態分開

支付狀態描述「錢是否被成功扣款/放款」，結算狀態描述「你的帳務是否完成結算/入帳」。兩者不同步是正常的：支付成功可能還沒到結算窗口；退款申請可能先是「退款中」，最後才變成「退款完成」。

因此建議維護兩層狀態，並用事件驅動更新。例如：

• PaymentStatus：INIT、PENDING、PAID、FAILED、REFUNDING、REFUNDED
• SettlementStatus：UNPROCESSED、READY、BOOKED、SETTLED、REVERSED（對應沖正/撤銷）

這樣做的好處是：你能解釋對帳差異，因為「支付已確定但尚未入帳」或「入帳完成但退款尚未結清」都能被狀態表達。

第三章：對接架構：用事件思維而不是請求思維

第三方支付對接通常包含兩類互動：同步請求（例如發起支付/退款）與非同步通知（例如支付完成通知、退款結果通知）。工程上你可能會做同步等待，但狀態收斂依賴通知與查詢。

建議採用「事件思維」：所有對接回來的信息都先進事件表或訊息隊列，再由後台流程處理並更新狀態。這能避免你在 webhook 回調裡做太多事造成延遲或失敗。

3.1 Webhook/通知：先驗簽，再落庫，再回應

第三方通知到達後，處理順序應該固定：

1. GCP帳號開戶服務 驗證來源：簽名驗證、時間戳/nonce 防重。
2. 解析 payload：取得商戶訂單號、第三方交易號、事件類型、金額、狀態。
3. 幂等判定：判斷此事件是否已處理。
4. 落事件記錄：寫入事件表（包含原始 payload 摘要或完整內容，視安全要求）。
5. 回應第三方：快速回 HTTP 200，避免重送風暴。
6. 後台異步處理：由 worker 依事件更新 PaymentStatus/SettlementStatus。

這樣你就把「外部的不確定性」隔離在事件層，內部流程能穩定運行。

3.2 查詢機制：用於「通知缺失」或「狀態不確定」

現實中總會遇到：通知丟失、網路抖動、第三方延遲回調。為此需要查詢機制。

常見策略：

• 同步請求後若超時：進入 PENDING，並啟動定時查詢。
• 若通知到達但資訊不完整：補查詢。
• 每日/每小時任務：對 PaymentStatus 長時間停留在 PENDING 的交易做補償查詢。

查詢返回要同樣走幂等與狀態機校驗，避免「查詢結果比通知更早到/更晚到」造成狀態回退。

第四章：狀態機與幂等策略——對帳能不能過，取決於這裡

如果你只用「收到通知就把狀態改成對方給的值」，會在重送或延遲時出現錯亂。例如：先收到「支付成功」，後又收到一個延遲的「支付失敗」（同一訂單可能在第三方內有狀態流轉）。正確做法是：狀態機要能處理事件的順序不保證。

4.1 幂等：以事件唯一鍵為核心

幂等的關鍵在「你如何判斷一個事件已處理」。常見唯一鍵包括：

• 第三方事件 id（若有）。
• 第三方交易號 + 事件類型 + 事件時間戳。
• 你內部對同一退款請求生成的 request id。

建議做法：建立事件表，事件唯一鍵加唯一約束。worker 處理事件時先查唯一鍵是否存在，再決定是否更新狀態。

4.2 狀態遷移：用「允許轉移表」而不是自由覆蓋

狀態機設計可以落在程式層，也可以落在資料層。最重要的是：規範允許的轉移。例如：

• INIT -> PENDING：發起支付。
• PENDING -> PAID：支付成功通知。
• PENDING -> FAILED：支付失敗通知。
• PAID -> REFUNDING：發起退款。
• REFUNDING -> REFUNDED：退款完成通知。

若收到不允許的轉移事件，你不能直接覆蓋。應該記錄並進入「待人工或待補償」的狀態，或依規則忽略。例如：已經 REFUNDED 的交易，不應再被一個遲到的 REFUNDING 事件改回去。

4.3 部分成功與重試：退款最容易踩坑

退款對接常遇到部分成功：例如平台返回「已受理退款請求，但實際退款分批進行」，或平台對同一退款請求允許重試。若你不做幂等，會出現重複退款申請。

GCP帳號開戶服務 建議：

• 退款請求要有唯一 request id，重試時帶同一 id。
• 退款完成以通知或查詢結果為準，不以你發出請求的時間為準。
• 記錄退款明細（退款批次、退款單號、退款金額、狀態），並將其與原始支付交易關聯。

同時，在對帳層面要清楚：部分退款如何影響已入帳金額。你通常需要沖回原先入帳的那部分，並記錄沖正流水，否則帳務會逐次偏移。

第五章：入帳與對帳設計——讓差異可計算、可追溯

對帳是結算系統最終價值之一。你要能回答：某天/某批次的交易，為什麼結算結果與第三方清算明細不同。

5.1 入帳的觸發點：用 SettlementStatus 驅動

支付成功事件本身不等於入帳。入帳通常要滿足條件：

• PaymentStatus 已到 PAID（或 REFUNDED 之後可觸發沖正）。
• 金額字段完整且符合規則（例如幣別一致、手續費存在）。
• 防重：SettlementStatus 未達到 BOOKED/SETTLED。

建議讓入帳由後台 worker 根據 SettlementStatus 執行，這樣 webhook 回調不承擔重任。

GCP帳號開戶服務 5.2 對帳粒度：日對帳 vs 批次對帳

常見對帳粒度有兩種：按日彙總、按清算批次彙總。按日彙總易做管理，但在退款延遲時會跨天，造成你需要追溯。

更穩健的方式是：以第三方清算單/對帳文件的批次作為基準，結算系統先彙總到相同批次，再計算差異。日對帳可以作為報表層的視圖，而不是作為主要對帳依據。

5.3 差異類型：分門別類，才能快修

建議把對帳差異拆成可歸因類型，例如：

• 漏處理：某些交易未入帳（狀態卡住或通知缺失）。
• GCP帳號開戶服務 金額口徑差：實收/手續費字段映射錯誤。
• 匯率或幣別問題：多幣別結算時尤其常見。
• 退款沖正未完成：退款完成但沖正流水缺失。
• 狀態回退：狀態機允許錯誤轉移造成重覆入帳。

每一類差異應該對應具體的排查路徑，否則你每次對帳都像在猜。

第六章：GCP 落地建議——把穩定性做進去

談 GCP 不需要玄學，核心是選對元件來承接「事件、任務、可觀測性」。常見落地思路是：用消息/事件觸發工作流程，使用可靠儲存承接狀態與日誌，並在告警層面建立閾值。

6.1 事件處理：隊列與 worker 的責任邊界

建議把 webhook 接收與事件處理解耦：

• 接收端：只做驗簽、落事件、回應。
• worker：負責狀態機、入帳、沖正、推送後續流程。

這樣即使第三方通知量大，你也能透過 worker 擴縮容控制吞吐，避免接收端超時。

6.2 資料一致性：交易表與事件表的關係

你至少需要兩類表：

• 交易主表：存 PaymentStatus、SettlementStatus、金額口徑、關聯主鍵。
• 事件/流水表：存 webhook payload 摘要、處理狀態、唯一鍵、錯誤原因。

事件處理成功後才更新主表。這樣你能重放事件或定位失敗原因。若你只有主表，遇到問題時只能回憶，無法重建事實。

6.3 可觀測性：日誌不是寫了就算

對接系統的日誌要能解決三個問題：

• 這筆交易發生了什麼（事件順序）。
• 為什麼更新失敗（錯誤原因）。
• 會不會重覆（幂等與重試）。

建議在日誌中加入交易號、第三方交易號、事件唯一鍵、worker 執行 id。並且對「狀態不允許轉移」這類邏輯告警設定為高優先級，因為它通常代表程式規則需要調整或第三方行為異常。

第七章：退款與撤銷——把時間線寫成可執行的規則

退款是對接的高風險點，因為它往往涉及多次金額變動、跨系統延遲、以及入帳後的沖正。

7.1 退款請求流程：先建單，再請求，再收斂

GCP帳號開戶服務 一筆退款建議流程如下：

1. 商戶提出退款：產生退款單號、退款請求唯一 request id。
2. 結算系統寫入退款主表：狀態設為 REFUNDING，記錄退款金額與關聯支付交易。
3. 發起第三方退款 API：帶 request id。
4. 接收第三方通知或查詢：更新退款狀態。
5. 執行沖正入帳：根據已入帳明細沖回相應金額與手續費口徑，並落入流水。

注意：沖正要依賴「退款完成」的最終狀態，而不是依賴「你發出請求」或「第三方回覆已受理」。

7.2 部分退款：流水拆分，而不是整筆抵銷

部分退款要做兩件事：更新退款明細的累計狀態，並對入帳明細進行對應比例或對應金額沖正。你要保證沖正金額精準對上第三方退款通知的金額字段，否則對帳差異會在後續擴大。

7.3 撤銷與退款反向：狀態機再一次出場

有些支付平台提供撤銷、拒付或反向退款等能力。你仍要把它們映射到狀態機：哪些狀態允許撤銷，哪些不允許。尤其是已經 SETTLED 的交易，撤銷往往需要進入補償流程並保持帳務可追溯。

第八章：驗收與上線：用清單降低風險

對接不是「通過聯調就結束」，而是要在上線後能自我修復、能快速定位。驗收階段可以用清單導向。

8.1 必測場景清單

• 正常支付成功通知：狀態與入帳一致。
• GCP帳號開戶服務 通知延遲：先查詢/後通知，狀態不反覆。
• 通知重送：同一事件重複處理不會重複入帳。
• GCP帳號開戶服務 同步請求超時：進入 PENDING，後續查詢收斂。
• 支付失敗：不應入帳。
• 退款全額成功：退款完成後沖正流水正確。
• 退款部分成功：累計退款與沖正金額對得上。
• 退款通知重送：不重複沖正。
• 幣別/手續費欄位缺失或異常：系統如何降級與告警。

8.2 性能與吞吐：不是追求極限，是確保穩定

對接系統在某些時段可能集中通知，例如活動促銷。你需要確認：

• 接收端不超時（回應第三方快）。
• worker 能在合理時間內消化事件。
• 資料庫索引覆蓋幂等查詢與狀態更新。

更重要的是建立指標：事件積壓數、處理失敗率、狀態卡住比例。沒有指標，上線後就只能靠猜。

8.3 稽核與資料保留：為了未來的追問

當客訴或稽核來臨時，你需要在短時間內回答：一筆交易為什麼是這個結果。建議保留：

• 第三方通知原始 payload（或其可驗證摘要）。
• 事件處理結果與時間線。
• 入帳/沖正的流水明細與關聯鍵。
• 對帳差異計算依據與版本。

這些不是為了「看起來完整」，而是為了讓錯誤能在事後被證明與修復。

結語：把對接做成一套可驗證的系統

GCP 結算系統與第三方支付對接，真正的難點不在於連線與參數，而在於如何建立「可驗證的真相」。當你把狀態機做對、把幂等設計做穩、把入帳與對帳口徑定清楚，再加上可觀測性與補償流程，對接就不會只是短期跑通，而能在長期運行中保持可靠。

如果要一句話概括：讓外部事件進來，但不要讓外部事件決定你的帳務。你的系統應該用規則收斂、用流水證明、用對帳定位，這才是結算系統的核心能力。