This resume is also available in English.

七、實戰踩坑第 2 / 5 篇 · 全部目錄

專欄 › 七、實戰踩坑 › 第 27 篇

支付常見問題:重複扣款、回呼與對帳

Payment Pitfalls: Double Charges, Callbacks and Reconciliation

支付最怕的不是失敗,而是「不知道有沒有成功」。這篇整理十個常見的金流問題:重複扣款、狀態亂跳、逾時、回呼驗簽與順序、取消競爭、金額、退款、對帳、帳本與敏感資料,並給出一份檢查清單。

  • Payments
  • Microservices
  • Go
  • Database
這篇的步驟
  1. 這篇要解決什麼
  2. 第 1 個問題:重複扣款
  3. 第 2 個問題:狀態亂跳,成功被蓋回失敗
  4. 第 3 個問題:逾時被當成失敗
  5. 第 4 個問題:回呼被偽造、重送、亂序,還比同步回應先到
  6. 第 5 個問題:回呼與使用者取消同時發生
  7. 第 6 個問題:用 float64 算金額
  8. 第 7 個問題:退款與部分退款算錯
  9. 第 8 個問題:沒有對帳,差異累積到無法追
  10. 第 9 個問題:餘額直接改數字,沒有帳本與稽核紀錄
  11. 第 10 個問題:卡號與敏感資料出現在日誌裡
  12. 一張表看完
  13. 重點整理
  14. 下一篇

上一篇〈併發常見問題:從資料競爭到超賣〉看了 Go 程式與資料庫裡各種「同時讀改寫」的問題;這篇接著看併發問題裡代價最高的一種:發生在錢上面的。網路商店的 payment 服務一出錯,不是畫面跑版,而是客戶被扣了兩次款、商家少收了錢,或是帳目對不起來,需要人工一筆一筆追。

這篇要解決什麼

支付流程比一般的服務呼叫多了三個麻煩的特性。第一,它牽涉到外部的金流服務商,對方的系統我們無法控制,網路會斷、回應會慢、通知會重送。第二,它是非同步的:扣款請求送出後,最終結果常常是之後透過回呼(webhook)才知道,同步回應只代表「收到了」。第三,它的錯誤很難撤回:多扣的錢要走退款流程,少記的帳要靠對帳才發現。

所以支付系統的設計目標不是「永遠不出錯」,而是:同一件事做幾次都只算一次(冪等)、任何時刻都知道每一筆錢在哪個狀態(狀態機)、結果不明時絕不亂猜(查詢與對帳)、每一筆變動都留下紀錄(帳本與稽核)。下面十個問題,都是在違反其中一條時發生的。

延續這個系列的例子:order 服務的訂單有 pending、paid、cancelled 三個狀態,金額 Total 以最小貨幣單位存成 int64;payment 服務負責對金流服務商發起扣款,付款本身有自己更細的狀態,成功後再發事件讓訂單變成 paid。每個問題都照「症狀、為什麼、怎麼修」的順序講。

第 1 個問題:重複扣款

症狀

客戶反映同一張訂單被扣了兩次款,信用卡帳單上出現兩筆相同金額;後台看到同一個 order_id 有兩筆成功的付款紀錄,時間只差幾百毫秒或幾秒。

為什麼

重複的請求幾乎無法避免,來源至少有四層:使用者在網路慢時連點付款按鈕,或付款完按上一頁再送一次;前端或 App 的 HTTP 用戶端在逾時後自動重試;api-gateway 或服務之間的重試機制(〈逾時、重試與熔斷〉)在沒收到回應時再送一次;訊息佇列的至少一次投遞讓「發起扣款」的事件被消費兩次。只要其中任何一層把重送當成新的請求,payment 服務就會向金流服務商發起第二筆扣款,而對方看到的是兩個完全合法的請求。

怎麼修

答案是〈冪等與分散式鎖〉教過的冪等鍵,但重點在「端到端」:冪等鍵要在最上游產生,並一路傳到最下游。具體來說,結帳頁面載入時就產生一個代表「這一次付款意圖」的冪等鍵,按鈕送出、前端重試、Gateway 重試都帶同一個值;payment 服務以它為唯一鍵建立付款紀錄;呼叫金流服務商時,也把自己的付款 ID 或冪等鍵當作商店端訂單編號或對方的冪等鍵欄位傳過去,讓對方也能擋掉重複。

CREATE TABLE payments (
  id               bigint      GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  order_id         bigint      NOT NULL,
  idempotency_key  text        NOT NULL UNIQUE,
  amount           bigint      NOT NULL CHECK (amount > 0),   -- 最小貨幣單位
  currency         char(3)     NOT NULL,                      -- ISO 4217,例如 'USD'
  status           text        NOT NULL DEFAULT 'created',
  provider_txn_id  text        UNIQUE,                        -- 金流服務商的交易編號
  refunded_amount  bigint      NOT NULL DEFAULT 0 CHECK (refunded_amount >= 0),
  created_at       timestamptz NOT NULL DEFAULT now(),
  updated_at       timestamptz NOT NULL DEFAULT now(),
  CHECK (refunded_amount <= amount)
);

-- 一張訂單同時最多一筆「還在進行或已成功」的付款
CREATE UNIQUE INDEX payments_one_active_per_order ON payments (order_id)
  WHERE status IN ('created', 'pending', 'unknown', 'succeeded', 'partially_refunded');

-- 建立付款:同一個冪等鍵第二次進來不會新增
INSERT INTO payments (order_id, idempotency_key, amount, currency)
VALUES ($1, $2, $3, $4)
ON CONFLICT (idempotency_key) DO NOTHING
RETURNING id, status;
-- 沒有回傳列:查出既有那一筆,order_id 與金額都相同就回傳它目前的狀態;
-- 不同就代表同一個鍵被拿去做別的事,回 422,不要扣款

這裡有兩道防線。冪等鍵擋住「同一次意圖的重送」;部分唯一索引擋住「不同的冪等鍵卻是同一張訂單」,例如使用者開了兩個分頁各自結帳。兩道都要有,而且都要做在資料庫的約束上,而不是在程式裡先查再寫,否則就回到上一篇的讀改寫競爭。前端也該在送出後把按鈕停用,但那只是改善體驗,不能當作防線。

提示:重複請求進來時,若第一筆還在處理中,回傳「處理中」並讓用戶端稍後查詢,而不是等待或再做一次;已經有結果的,就原樣回傳上次的結果。

第 2 個問題:狀態亂跳,成功被蓋回失敗

症狀

金流服務商後台顯示已成功扣款,我們的付款紀錄卻是 failed,訂單被自動取消,客戶付了錢卻沒收到貨;或者一筆已經全額退款的付款,又被改回 succeeded。

為什麼

付款的狀態來源不只一個:同步回應、回呼、主動查詢、對帳、人工操作。如果每一個來源拿到結果就直接 UPDATE payments SET status = $2 WHERE id = $1,最後的狀態就取決於誰最後寫入,而不是事實。最典型的情況是:第一次嘗試失敗的通知比較晚到,蓋掉了重試成功的結果;或是對帳程式用舊資料覆寫了新的狀態。

怎麼修

明確定義狀態機:哪些狀態可以轉到哪些狀態,其他一律拒絕。

已建立 created 處理中 pending 失敗 failed(終態) 結果不明 unknown 成功 succeeded 部分退款 partially_refunded 已全額退款 refunded(終態) 建立失敗(參數錯、被風控拒絕) 沒有畫出的箭頭一律拒絕:failed 不能變 succeeded,succeeded 不能被晚到的失敗蓋掉

圖:付款從 created 到 pending,結果可能是 succeeded、failed 或暫時的 unknown;只有成功的付款可以退款,failed 與 refunded 是終態。

規則寫成程式碼並配上測試,讓每一條「不准」都有對應的案例:

package payment

import (
	"fmt"
	"testing"
)

type Status string

const (
	Created           Status = "created"
	Pending           Status = "pending"
	Unknown           Status = "unknown" // 逾時或結果不明,等查詢或回呼
	Succeeded         Status = "succeeded"
	Failed            Status = "failed"
	PartiallyRefunded Status = "partially_refunded"
	Refunded          Status = "refunded"
)

// 只列出允許的轉換;沒列到的一律拒絕。
var allowed = map[Status][]Status{
	Created:           {Pending, Failed},
	Pending:           {Succeeded, Failed, Unknown},
	Unknown:           {Succeeded, Failed},
	Succeeded:         {PartiallyRefunded, Refunded},
	PartiallyRefunded: {PartiallyRefunded, Refunded},
}

func CanTransition(from, to Status) bool {
	for _, s := range allowed[from] {
		if s == to {
			return true
		}
	}
	return false
}

func Transition(from, to Status) error {
	if from == to && from != PartiallyRefunded {
		return nil // 重複的通知:已經是這個狀態,當作成功、什麼都不做
	}
	if !CanTransition(from, to) {
		return fmt.Errorf("illegal transition %s -> %s", from, to)
	}
	return nil
}

func TestTransition(t *testing.T) {
	cases := []struct {
		from, to Status
		ok       bool
	}{
		{Pending, Succeeded, true},
		{Unknown, Succeeded, true},
		{Succeeded, Succeeded, true}, // 回呼送了兩次
		{Failed, Succeeded, false},   // 終態不能被翻轉,要人工處理
		{Succeeded, Failed, false},   // 晚到的失敗通知不能蓋掉成功
		{Created, Refunded, false},   // 沒付款就不能退款
		{Succeeded, PartiallyRefunded, true},
	}
	for _, c := range cases {
		err := Transition(c.from, c.to)
		if (err == nil) != c.ok {
			t.Errorf("%s -> %s: err=%v, want ok=%v", c.from, c.to, err, c.ok)
		}
	}
}

程式裡的檢查只是第一層;寫入資料庫時要把「目前狀態」放進 WHERE,例如 UPDATE payments SET status = 'succeeded' WHERE id = $1 AND status IN ('pending', 'unknown'),影響 0 列就重新讀取,判斷是「已經是這個狀態」(重複通知,當作成功)還是「不合法的轉換」(記錄告警,交給人工)。這和上一篇條件式 UPDATE 防超賣是同一個技巧,它讓並發的兩個更新不會互相覆蓋。

設計狀態時有兩個原則。第一,終態不能被自動翻轉:failed 之後如果金流服務商又說成功了,那是需要人工處理的異常,不是一般的狀態轉換。第二,狀態要有「不知道」:unknown 不是失敗,下一個問題會說明為什麼它必須存在。訂單的狀態則保持簡單:付款進入 succeeded 時,透過 Outbox 發出事件讓 order 把訂單從 pending 改成 paid,付款細節留在 payment 服務裡。

第 3 個問題:逾時被當成失敗

症狀

呼叫金流服務商逾時,程式回報「付款失敗」,使用者重新付款一次,結果兩筆都成功了;或是系統自動把訂單取消並把庫存還回去,隔天才發現那筆錢其實已經扣了。

為什麼

逾時只代表「在時限內沒收到回應」,不代表對方沒有處理。請求可能根本沒送到、可能送到但處理失敗、也可能已經扣款成功只是回應在路上遺失。這三種情況在呼叫端看起來完全一樣。把逾時當成失敗,等於在三分之一的可能性下做出錯誤的決定,而這個錯誤的後果是讓客戶多付一次錢,或讓已付款的訂單被取消。

怎麼修

逾時、連線中斷、對方回 5xx 都進入 unknown,絕不直接判定失敗。 進入 unknown 之後:

  1. 用同一個商店端訂單編號或冪等鍵向金流服務商查詢這筆交易的狀態,查到明確結果才轉成 succeeded 或 failed。
  2. 查詢也失敗或對方顯示仍在處理中時,用背景工作以退避的間隔再查,同時等待回呼。
  3. 超過一段時間仍不明,交給隔天的對帳與人工處理;期間訂單維持 pending,不要釋放庫存,也不要讓使用者用新的冪等鍵重新付款。

如果真的需要重試扣款本身,一定要沿用同一個冪等鍵,讓金流服務商把它當成同一筆;如果對方不支援冪等鍵,就不要自動重試扣款,只能先查詢。這也是為什麼〈逾時、重試與熔斷〉強調只有冪等的操作才能自動重試:對支付來說,沒有冪等保證的扣款請求,一律不重試。

給使用者的畫面也要誠實:「付款結果確認中,請勿重複付款,確認後會通知您」,比一個錯誤的「付款失敗,請重試」好得多。

第 4 個問題:回呼被偽造、重送、亂序,還比同步回應先到

症狀

有人直接對回呼網址送了一個「付款成功」的請求,訂單就被標成已付款;同一筆付款寄了兩封成功通知;回呼一直重送,因為我們每次都回 500;或者同步回應說「處理中」,把已經被回呼改成成功的付款改回 pending。

為什麼

回呼網址是公開的,任何人都能對它送請求,所以未驗證的回呼等於任何人都能把訂單標成已付款。即使來源可信,回呼的投遞也和訊息佇列一樣是「至少一次」:金流服務商沒收到 2xx 就會重送,重送間隔可能從幾秒到幾小時;網路與重試讓多個通知的抵達順序不保證等於事件發生的順序;回呼與同步回應走的是不同的路徑,回呼完全可能比同步回應更早到。

訂單服務 支付服務 金流服務商 1. 建立付款(冪等鍵) 2. 扣款請求 3. 回呼:succeeded(先到) pending → succeeded 4. 同步回應:processing(晚到) 已是終態,不往回改 5. 回呼重送:succeeded 狀態相同 → 直接回 200 6. 事件:付款成功(只發一次)

圖:回呼先把付款改成 succeeded,晚到的同步回應不能把它改回處理中;重送的回呼因為狀態相同,直接回 200。

怎麼修

先驗證,再冪等地套用。驗證的部分:用金流服務商提供的方式驗簽,常見的是以共享密鑰對「時間戳記+原始請求內容」做 HMAC,或用對方的公鑰驗證簽章;必須對原始位元組驗簽,而不是先解析成結構再序列化回去;用固定時間的比較函式避免時序攻擊;檢查時間戳記,拒絕太舊的請求以防重放。

package webhook

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"io"
	"net/http"
	"net/http/httptest"
	"strconv"
	"strings"
	"testing"
	"time"
)

const maxSkew = 5 * time.Minute

func sign(secret []byte, ts string, body []byte) string {
	m := hmac.New(sha256.New, secret)
	m.Write([]byte(ts + "."))
	m.Write(body)
	return hex.EncodeToString(m.Sum(nil))
}

// Handler 只負責驗證;通過後才交給 apply(查狀態、冪等地更新)。
func Handler(secret []byte, now func() time.Time, apply func(body []byte) error) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		body, err := io.ReadAll(io.LimitReader(r.Body, 1<<20)) // 先拿原始位元組,不要先解析再序列化
		if err != nil {
			http.Error(w, "bad body", http.StatusBadRequest)
			return
		}
		ts := r.Header.Get("X-Timestamp")
		sec, err := strconv.ParseInt(ts, 10, 64)
		if err != nil || now().Sub(time.Unix(sec, 0)).Abs() > maxSkew {
			http.Error(w, "stale", http.StatusUnauthorized) // 擋重放
			return
		}
		got, err := hex.DecodeString(r.Header.Get("X-Signature"))
		want, _ := hex.DecodeString(sign(secret, ts, body))
		if err != nil || !hmac.Equal(got, want) { // 固定時間比較
			http.Error(w, "bad signature", http.StatusUnauthorized)
			return
		}
		if err := apply(body); err != nil {
			http.Error(w, "retry later", http.StatusInternalServerError) // 讓對方重送
			return
		}
		w.WriteHeader(http.StatusOK)
	})
}

func TestHandler(t *testing.T) {
	secret := []byte("test-secret")
	now := time.Unix(1_800_000_000, 0)
	h := Handler(secret, func() time.Time { return now }, func([]byte) error { return nil })

	body := `{"payment_id":"pay_1","status":"succeeded","amount":1000}`
	ts := strconv.FormatInt(now.Unix(), 10)
	send := func(sig, ts string) int {
		req := httptest.NewRequest(http.MethodPost, "/webhook", strings.NewReader(body))
		req.Header.Set("X-Timestamp", ts)
		req.Header.Set("X-Signature", sig)
		rec := httptest.NewRecorder()
		h.ServeHTTP(rec, req)
		return rec.Code
	}
	if c := send(sign(secret, ts, []byte(body)), ts); c != 200 {
		t.Errorf("valid: %d", c)
	}
	if c := send(sign([]byte("wrong"), ts, []byte(body)), ts); c != 401 {
		t.Errorf("forged: %d", c)
	}
	old := strconv.FormatInt(now.Add(-time.Hour).Unix(), 10)
	if c := send(sign(secret, old, []byte(body)), old); c != 401 {
		t.Errorf("replayed: %d", c)
	}
}

驗證通過之後的 apply 要做到:

  • 不完全相信回呼內容:比對回呼裡的金額、幣別、商店端訂單編號是否與 payments 裡的紀錄一致;對重要的狀態,也可以再用金流服務商的查詢介面確認一次。
  • 用狀態機決定要不要更新:已經是同樣的狀態就什麼都不做並回 200;狀態比較「舊」(例如已成功又收到處理中)就忽略;不合法的轉換記錄下來並告警。同步回應的處理也走同一套規則,所以它晚到時不會把狀態往回改。
  • 把「收到的通知」存起來:每一則回呼原樣寫進一張通知紀錄表(含對方的事件 ID),以事件 ID 做唯一約束去重,日後查問題與對帳都靠它。
  • 快速回應:驗證並寫入資料庫後就回 2xx,寄信、更新訂單這些後續工作透過 Outbox 非同步處理(〈分散式交易:Saga 與 Outbox〉)。處理失敗時回 5xx 讓對方重送,比回 200 卻沒處理好得多。

第 5 個問題:回呼與使用者取消同時發生

症狀

使用者在付款頁停留太久,訂單被逾時取消、庫存也釋放了;幾秒後付款成功的回呼才到,結果變成「訂單已取消,但錢扣了」。或者反過來:使用者剛按下取消,付款成功的回呼同時抵達,兩邊各自更新,最後訂單是 cancelled,付款是 succeeded。

為什麼

取消與付款成功是兩個獨立的事件,各自從不同的路徑進來,彼此並不知道對方。如果兩邊都是「讀出訂單、檢查、寫回」,就是典型的讀改寫競爭;如果兩邊都用條件式更新,資料庫保證只有一邊成功,但輸的那一邊還是要處理現實世界已經發生的事:錢已經扣了,不能只是不理它。

怎麼修

把規則定清楚,並讓兩邊都用條件式更新:

  • 取消訂單:UPDATE orders SET status = 'cancelled' WHERE id = $1 AND status = 'pending'。
  • 付款成功後標記已付款:UPDATE orders SET status = 'paid' WHERE id = $1 AND status = 'pending'。

兩個敘述裡只會有一個影響 1 列。如果付款成功那一邊影響了 0 列,而訂單已經是 cancelled,就代表「付款成功但訂單已取消」,這時要自動發起全額退款(帶冪等鍵),或依業務規則嘗試恢復訂單(前提是庫存還在),並通知使用者。重點是這個分支必須明確寫出來並有測試,而不是讓它落入「不合法轉換、忽略」。

減少這種情況的方法是:訂單逾時取消前,先查詢一次付款狀態;付款頁的有效時間要短於訂單的保留時間;對已經進入 pending 或 unknown 的付款,延後取消訂單直到結果明確。

第 6 個問題:用 float64 算金額

症狀

訂單總額顯示 299.99000000000001;三個商品分別打折後加總,比整張訂單直接打折少了一分錢;對帳時差了幾分,找不到原因。

為什麼

float64 是二進位浮點數,無法精確表示 0.1 這類十進位小數,0.1 + 0.2 會得到 0.30000000000000004。每一次運算都可能多出一點誤差,累積起來在比較、加總與對帳時就會出錯。另一個常見問題是沒有記錄幣別:同樣是 1000,在不同幣別代表的金額差很多,而且各幣別的最小單位位數也不同。

怎麼修

金額一律用整數的最小貨幣單位(例如美元以「分」計)存成 int64,就像 Order.Total 那樣,資料庫也用 bigint;金額永遠和幣別一起傳遞與儲存;需要四捨五入的地方(折扣、稅、匯率換算、分攤)集中在明確的函式裡,並寫清楚採用哪一種捨入規則、餘數分給誰,保證拆開後加總等於原金額。跟金流服務商交換資料時,確認對方的欄位是以最小單位還是以元為單位,不要在 JSON 裡用浮點數傳金額。

這個主題細節很多:什麼時候需要 decimal 型別、各幣別的小數位數、銀行家捨入與一般四捨五入的差別、怎麼分攤才不會差一分錢,下一篇〈Go 處理金額:整數分、decimal、幣別、四捨五入與分攤〉會完整說明。

第 7 個問題:退款與部分退款算錯

症狀

同一筆付款被退了兩次款;部分退款加起來超過原付款金額;客服在後台點了退款,畫面顯示成功,但金流服務商那邊其實失敗了,客戶一直沒收到錢。

為什麼

退款本身就是另一筆支付操作,第 1 到第 4 個問題在它身上全部會再發生一次:重複點擊與重試、逾時不明、非同步的結果通知。再加上部分退款需要累計,「讀出已退金額、加上這次、檢查有沒有超過、寫回」又是一個讀改寫。

怎麼修

把退款當成獨立的資源:建立 refunds 表,每筆退款有自己的冪等鍵、金額、狀態(pending、succeeded、failed、unknown)與金流服務商的退款編號。發起退款時,用一個條件式更新同時完成檢查與預留額度:

UPDATE payments SET refunded_amount = refunded_amount + $2 WHERE id = $1 AND status IN ('succeeded', 'partially_refunded') AND refunded_amount + $2 <= amount

影響 0 列就代表狀態不允許或金額超過;成功後才呼叫金流服務商。退款確定失敗時把額度加回去;確定成功時再依累計金額把付款轉成 partially_refunded 或 refunded。客服介面要顯示的是退款的真實狀態,而不是「已送出」。另外,很多金流服務商的退款不是立即完成,也可能有退款期限或不支援部分退款,這些規則要在發起前檢查,而不是讓請求送出後才失敗。

第 8 個問題:沒有對帳,差異累積到無法追

症狀

月底結算時,系統記錄的收款總額和金流服務商撥款的金額對不起來;有幾筆付款我們這邊是 unknown,一直沒人處理;有幾筆對方顯示成功,我們這邊卻完全沒有紀錄。

為什麼

即使冪等、狀態機、回呼都做得正確,兩個獨立的系統仍然會產生差異:回呼全部重送失敗、程式在某個版本有錯、人工在對方後台直接操作、時區與日界不同、手續費從撥款中扣除。沒有定期比對,這些差異只會在月底一次爆出來,而時間越久,越難找到原因與當事人。

怎麼修

建立每日對帳:每天取得金流服務商的對帳檔(或用 API 拉取前一日的交易明細),與內部的付款與退款紀錄,依交易編號逐筆配對。

內部付款紀錄 昨日 00:00–24:00 金流服務商對帳檔 同一時區、同一日界 依交易編號配對 一致 標記已對帳 我方有、對方無 多半是未完成 對方有、我方無 漏收回呼 金額或狀態不同 最需要細查 差異佇列:查詢狀態 → 補記或退款 → 仍不明則人工 每一筆處理都寫稽核紀錄

圖:兩邊依交易編號配對後分成四類,一致的標記已對帳,其餘三類進入差異佇列逐筆處理。

配對的結果大致分成四類,每一類都有對應的處理方式:

類型               內部紀錄            金流服務商        常見原因                         處理方式
MATCHED            succeeded 1000     成功 1000         —                               標記已對帳
MISSING_REMOTE     succeeded          (沒有)           日界或時區不同;誤判為成功          隔日再比對;仍沒有就查詢單筆並修正
MISSING_LOCAL      (沒有)或 unknown  成功              回呼全部失敗;逾時後沒有追蹤         查詢確認後補記狀態;訂單已取消則退款
MISMATCH           succeeded 1000     成功 900 或已退款   金額被改、部分退款未同步;手續費      逐筆調查,修正紀錄並寫稽核紀錄

幾個實作上的要點:兩邊的資料要用相同的時區與日界切分,並且把前後一段時間的交易也拿進來比,避免跨午夜的交易被誤判為缺少;手續費、撥款與退款要分開比對,不要只比總額;對帳程式本身要冪等,同一天重跑結果相同;差異處理要有負責人與期限,每一次修正都寫稽核紀錄,而不是直接改資料庫。長期來看,差異的數量與類型也是一個很好的監控指標,突然增加通常代表某個環節壞了。

第 9 個問題:餘額直接改數字,沒有帳本與稽核紀錄

症狀

使用者錢包的餘額和他的交易明細加總對不上;餘額出現負數;客服或工程師為了修資料直接改了某個帳戶的餘額,之後沒有人說得出那筆錢從哪裡來、到哪裡去。

為什麼

如果系統只有一個 balance 欄位,每次儲值、付款、退款都直接加減它,那麼這個數字就是唯一的真相,而它沒有歷史:任何一次重複執行、讀改寫競爭或手動修改都會讓它悄悄變錯,事後無法重算,也無法證明它是對的。

怎麼修

採用複式記帳:每一筆交易寫成一組分錄,每一列記錄某個帳戶的借方或貸方,一筆交易的借方合計必須等於貸方合計。錢不會憑空出現或消失,只會從一個帳戶移到另一個帳戶。

分錄 帳戶 借方(分) 貸方(分) T1 儲值 平台銀行存款 10000 — T1 儲值 用戶錢包 — 10000 T2 付款 用戶錢包 3000 — T2 付款 商家應付款 — 3000 合計 13000 13000 用戶錢包餘額 = 貸方 10000 − 借方 3000 = 7000,由分錄算得、可隨時重算

圖:儲值與付款各寫兩列分錄,借貸相等;用戶錢包的餘額由分錄算出,可以隨時重算驗證。

CREATE TABLE accounts (
  id       bigint  GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  owner    text    NOT NULL,           -- 例如 user:7、merchant:9、platform:bank
  currency char(3) NOT NULL,
  balance  bigint  NOT NULL DEFAULT 0  -- 由分錄推得的快取值,隨時可以重算
);

CREATE TABLE journal_entries (
  id              bigint      GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  idempotency_key text        NOT NULL UNIQUE,   -- 同一筆業務事件只記一次
  kind            text        NOT NULL,          -- topup / payment / refund
  created_at      timestamptz NOT NULL DEFAULT now()
);

CREATE TABLE ledger_lines (
  entry_id   bigint NOT NULL REFERENCES journal_entries (id),
  account_id bigint NOT NULL REFERENCES accounts (id),
  debit      bigint NOT NULL DEFAULT 0 CHECK (debit >= 0),
  credit     bigint NOT NULL DEFAULT 0 CHECK (credit >= 0),
  CHECK ((debit = 0) <> (credit = 0))            -- 每一列只能是借或貸其中一邊
);

-- 付款 3000 分:錢包(帳戶 7)付給商家應付款(帳戶 9),全部在同一個交易裡
BEGIN;
UPDATE accounts SET balance = balance - 3000 WHERE id = 7 AND balance >= 3000;
-- 影響 0 列 = 餘額不足,ROLLBACK
INSERT INTO journal_entries (idempotency_key, kind) VALUES ('pay-order-1001', 'payment') RETURNING id;
-- 假設回傳的 id 是 42
INSERT INTO ledger_lines (entry_id, account_id, debit, credit) VALUES (42, 7, 3000, 0), (42, 9, 0, 3000);
UPDATE accounts SET balance = balance + 3000 WHERE id = 9;
COMMIT;

-- 每日檢查:找出借貸不平衡的分錄(應該永遠是空的)
SELECT entry_id FROM ledger_lines GROUP BY entry_id HAVING sum(debit) <> sum(credit);

規則可以歸納成幾條:不寫分錄就不准改餘額,兩者在同一個資料庫交易裡完成;餘額只是分錄的快取,定期用分錄重算並比對;扣款用條件式更新防止餘額變負,和上一篇防超賣完全相同;分錄只新增不修改,寫錯了就再寫一筆反向分錄沖銷,而不是刪除或更新;每一筆分錄帶冪等鍵,重複的事件不會記兩次。

稽核紀錄是另一層:任何人工操作(調整餘額、手動改狀態、強制退款)都要記下是誰、在什麼時間、為什麼、改了什麼、改之前與之後的值,並且和分錄一樣只能新增。人工調整本身也應該透過寫分錄來完成,而不是直接改 balance。

第 10 個問題:卡號與敏感資料出現在日誌裡

症狀

搜尋日誌時看到完整的信用卡號、有效期限或安全碼;追蹤系統的 span 屬性裡有整個付款請求的內容;錯誤回報服務收到了含有卡號的請求本文。

為什麼

為了除錯,很多服務會在中介層把請求與回應的完整內容寫進日誌(〈net/http 與中介層〉的請求日誌),或在錯誤時把整個結構印出來。日誌、追蹤與錯誤回報通常會被複製到好幾個系統、保存很久、開放給很多人查看,任何一處出現卡號,這些系統就全部落入支付卡產業資料安全標準(PCI DSS)的稽核範圍,而且一旦外洩就是嚴重的資安事件。

怎麼修

最根本的做法是讓卡號根本不經過我們的伺服器:使用金流服務商提供的託管付款頁或嵌入式的託管欄位,卡號由使用者的瀏覽器直接送到金流服務商,我們只拿到一個代表這張卡或這次付款的 token。這能大幅縮小需要符合 PCI DSS 的範圍。其他配套包括:

  • 日誌採用允許清單,只記錄明確列出的欄位(付款 ID、訂單 ID、金額、狀態、錯誤碼),而不是整個請求本文;〈可觀測性:日誌、指標、追蹤〉裡的結構化日誌很適合這樣做。
  • 在型別上替敏感值實作 slog.LogValuer 或 String(),讓它被印出來時自動遮蔽。
  • 回呼的原始內容若需要保存,存在權限受控的表裡,而不是一般日誌。
  • 回呼的簽章密鑰、金流服務商的 API 金鑰放在秘密管理中(〈設定與優雅關閉〉),不寫進程式碼與映像檔,並定期輪替。
  • 安全碼(CVV)在任何情況下都不能儲存。

一張表看完

#問題為什麼會發生怎麼避免
1重複扣款連點、用戶端與 Gateway 重試、訊息重送端到端冪等鍵、唯一約束、每張訂單一筆有效付款
2狀態亂跳多個來源直接覆寫狀態明確的狀態機、條件式 UPDATE、終態不翻轉
3逾時當失敗逾時時結果其實不明進入 unknown、查詢、同一冪等鍵重試、對帳
4回呼偽造、重送、亂序公開網址、至少一次投遞、路徑不同驗簽與時間戳記、比對內容、依狀態機冪等套用
5回呼與取消競爭兩個獨立事件各自讀改寫兩邊條件式更新、輸的一方明確處理(自動退款)
6float64 金額二進位浮點無法精確表示小數int64 最小單位、帶幣別、集中且明確的捨入
7退款算錯退款同樣會重複、逾時、非同步退款獨立成資源、冪等鍵、條件式累計
8沒有對帳兩個系統必然產生差異每日依交易編號配對、差異佇列、稽核紀錄
9餘額沒有帳本單一數字沒有歷史、無法重算複式記帳、借貸相等、只新增不修改
10敏感資料外洩日誌與追蹤記錄整個請求託管付款欄位、日誌允許清單、遮蔽與秘密管理

重點整理

上線前可以把下面這份清單逐項確認:

  • 冪等鍵在結帳頁產生,一路傳到 payment 與金流服務商;資料庫有唯一約束,每張訂單最多一筆有效付款。
  • 付款與退款都有明確的狀態機,所有寫入都用帶目前狀態的條件式 UPDATE,並有測試覆蓋每條禁止的轉換。
  • 逾時、斷線、5xx 一律進入 unknown,有查詢與背景追蹤;沒有冪等保證的扣款請求絕不自動重試。
  • 回呼驗簽(原始位元組、固定時間比較、時間戳記)、比對金額與幣別、以事件 ID 去重,並且能處理晚到、重送、亂序與先於同步回應抵達。
  • 「付款成功但訂單已取消」有明確的處理路徑(自動退款或恢復訂單)與測試。
  • 金額是 int64 最小單位並帶幣別,捨入與分攤集中在明確的函式裡。
  • 退款有自己的冪等鍵與狀態,累計退款以條件式更新防止超退。
  • 每日對帳依交易編號配對,差異有佇列、負責人與期限。
  • 錢包與餘額採複式記帳,不寫分錄不改餘額,分錄只新增,定期檢查借貸平衡並重算餘額。
  • 人工操作都有稽核紀錄;卡號不經過自己的伺服器,日誌只記允許清單裡的欄位,密鑰放在秘密管理中。

下一篇

這篇把十個常見問題各自修好,但真實的重複交易很少只出在一個地方:使用者連點、App 逾時重送、閘道重試、佇列重送,任何一層沒擋住都可能多出一筆交易單;而真的出事時,先做什麼、後做什麼,決定了損失有多大。下一篇〈支付防重複與事故應變:從按鈕到金流商,出事時怎麼止血〉從按鈕一路追到金流商,逐層擋住重複,再整理支付事故的預防、告警與應變步驟。