對帳:金流對帳單怎麼對才可靠
Reconciliation: Matching Payment Provider Statements Reliably
兩個系統記同一筆錢,遲早會對不起來。這篇從取得與保存對帳單、解析與日界,到逐筆配對、差異分類與處理、帳本與撥款核對,再到告警與月結,用 Go 寫一個可測試的對帳套件。
這篇的步驟
上一篇〈支付防重複與事故應變:從按鈕到金流商,出事時怎麼止血〉從按鈕一路擋到金流商,並整理了出事時的止血步驟。但不管防線做得多好,總會有幾筆漏網之魚:回呼全部重送失敗、某個版本的程式寫錯狀態、有人在金流商後台手動退款、手續費和合約不一樣。這些問題都不會讓程式出錯,只會讓帳慢慢對不起來,而唯一能把它們找出來的,是對帳。
〈支付常見問題:重複扣款、回呼與對帳〉的第 8、9 個問題已經簡短介紹過每日對帳與複式記帳。這篇把它展開成完整的做法:對帳單怎麼抓、怎麼保存、怎麼解析才不會被編碼和時區騙;配對的鍵是什麼、一對多怎麼辦;差異分成哪幾類、哪一類要半夜叫人起床;差異怎麼追蹤到結案、為什麼絕對不能直接改金額;最後怎麼讓帳本、對帳單和銀行撥款三方對起來。
這篇要解決什麼
延續整個系列的例子:網路商店 example.com/shop 的 payment 服務把付款與退款存在 PostgreSQL,金額一律是最小貨幣單位的 int64。每次向金流商發起扣款,都用付款嘗試的 ID(例如 pay_1001)當商店訂單編號(各家叫法不同,常見的有 merchant trade no、merchant reference、order id);金流商則回給我們它自己的交易編號。金流商每天提供一份對帳單,並在約定的撥款日把扣掉手續費後的淨額匯進我們的銀行帳戶。
這篇會一步一步做到:
- 說清楚對帳要比對哪幾方、多久做一次、誰負責。
- 可靠地取得對帳單:排程、重試、原始檔不可改寫、匯入可以重跑。
- 解析對帳單:BOM、CSV 引號、編碼、金額轉整數,以及最容易出錯的時區與日界。
- 逐筆配對:鍵、一對多、手續費、退款與拒付、狀態對照。
- 差異分類:哪一類只是時間差、哪一類代表使用者已經被扣款。
- 差異處理:差異表、生命週期、自動結案規則、調整分錄、冪等的修正動作。
- 帳本與銀行撥款的核對,以及營運上的告警、重跑、資料保存與月結。
程式碼放在 internal/recon 套件裡,全部可以編譯,並用 go test -race 測過。
提示:各家金流商的對帳單格式差很多,有的是每天一個 CSV 放在 SFTP,有的要呼叫 API 下載,有的是固定寬度的文字檔,欄位名稱與日界的定義也不同。這篇用一個常見的 CSV 格式當例子,實際對接時一定要以你的金流商提供的文件為準。
第 1 步:對帳是什麼、不是什麼
三方對帳
一筆付款的錢,會在三個地方留下紀錄:
- 我們的紀錄:
payment服務的付款與退款、訂單狀態。 - 金流商的對帳單:它認為哪些交易成功、金額多少、收了多少手續費、哪天撥款。
- 銀行的入帳:金流商實際匯進來多少錢。
對帳就是把這三方兩兩比對。我們的紀錄與對帳單逐筆比:每一筆付款都應該在對帳單上找到同一筆,金額、幣別、狀態都相同。對帳單與銀行入帳整批比:某個撥款日的淨額(付款總額減退款、拒付與手續費)應該等於那天銀行實際收到的金額。中間還有一個帳本:每一筆成功的付款、手續費、退款與撥款都寫成複式分錄,所以帳本裡「應收金流商」這個帳戶的餘額,必須和「金流商已經確認、但還沒撥給我們的淨額」一致。
圖:我們的紀錄和對帳單逐筆比、對帳單和銀行撥款整批比,三者都要和帳本對得起來。
對帳不是什麼
- 不是監控的替代品。 對帳通常是隔天才做,發現時錢已經扣了一天。回呼失敗、
unknown太多這類問題,要靠即時的指標與告警(〈可觀測性:日誌、指標、追蹤〉)先發現;對帳是最後一道網。 - 不是修資料的捷徑。 對帳找到差異後,修正一定要走正規的動作:查詢金流商、補記狀態、退款、寫調整分錄,而不是直接
UPDATE payments SET amount = ...。 - 不是只比總額。 總額相同不代表每筆都對,一筆多收 100 元、另一筆少收 100 元,總額剛好相同。總額只是一個快速的初步檢查。
每天一次,還是即時?
大部分金流商的對帳單是每天產生一份,涵蓋前一天的交易,所以「每日對帳」是最常見的節奏。有些金流商也提供交易查詢 API,可以做到接近即時的比對,例如每小時把最近的付款拿去查一次。兩者不衝突:即時查詢讓問題更早被發現(這其實就是上一篇補查 pending 的做法),每日對帳則以金流商正式產出的對帳單為準,是月結與會計使用的依據。
誰負責
對帳牽涉工程、財務與客服,最常見的失敗不是技術問題,而是沒有人負責:差異表裡躺了三個月的紀錄沒人看。上線前要講清楚:對帳程式失敗時誰收告警(工程),差異的第一線判斷由誰做(通常是財務或營運),需要查程式或補資料時交給誰(工程),需要聯絡使用者時誰處理(客服),以及誰能核准沖銷(主管)。
第 2 步:可靠地取得對帳單
排程抓檔與重試
對帳單通常在固定時間之後才會出現,例如「每天上午幾點後可下載前一天的檔案」,但實際上常常晚到。抓檔程式要:
- 在預期時間之後開始抓,抓不到就退避重試(〈逾時、重試與熔斷〉),超過一個期限(例如中午)還沒有才告警,而不是第一次失敗就叫人。
- 每一次嘗試都寫一筆執行紀錄:哪一個對帳日、從哪裡抓、抓到哪個檔案、幾筆、成功或失敗、錯誤訊息。沒有這張表,就無法回答「11 月 14 日那份到底有沒有匯入過」。
- 抓到的檔案如果有壓縮或加密,解開的步驟也要記錄並可以重跑。
原始檔不可改寫
對帳單是證據。抓下來的檔案要原封不動地存起來,通常放在物件儲存,並記下 SHA-256 雜湊、大小與抓取時間。之後所有的處理都從這份原始檔重新算出來,任何人都不能直接修改它:解析程式有錯,就修程式後重跑;金流商說檔案有錯,就請它重發一份,新舊兩份都留著。物件儲存可以開啟版本控制或「寫入後不可刪除」的保存設定,讓這件事不只是約定。
暫存表:可以重跑的匯入
解析後的每一列先寫進暫存表,再拿去配對。匯入一定要冪等(〈冪等與分散式鎖〉):排程重試、人工重跑、兩個程序同時跑,結果都要和跑一次相同。做法是:
- 每一列的唯一鍵是「檔案雜湊+行號」,同一份檔案匯入第二次不會多出列。
- 匯入某個對帳日時,在同一個交易裡先刪掉這一天的暫存列,再寫入這份檔案的列。這樣金流商重發的更正版(雜湊不同)會整天取代舊版,而不是和舊版混在一起。
- 同一個對帳日的匯入用 advisory lock 串起來,避免兩個交易交錯執行,留下兩個版本混在一起的結果。
CREATE TABLE statement_files (
sha256 char(64) PRIMARY KEY,
provider text NOT NULL,
recon_day date NOT NULL,
name text NOT NULL,
object_key text NOT NULL, -- 物件儲存裡的位置,例如 recon/raw/2026/11/14/<sha256>.csv
byte_size bigint NOT NULL,
fetched_at timestamptz NOT NULL DEFAULT now(),
superseded_by char(64) REFERENCES statement_files (sha256) -- 被哪一份更正版取代
);
CREATE TABLE ingestion_runs (
id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
provider text NOT NULL,
recon_day date NOT NULL,
file_sha256 char(64) REFERENCES statement_files (sha256),
status text NOT NULL CHECK (status IN ('running', 'staged', 'matched', 'failed')),
row_count int,
error text,
started_at timestamptz NOT NULL DEFAULT now(),
finished_at timestamptz
);
CREATE TABLE statement_lines (
file_sha256 char(64) NOT NULL REFERENCES statement_files (sha256),
line_no int NOT NULL,
provider text NOT NULL,
recon_day date NOT NULL,
merchant_trade_no text NOT NULL,
provider_txn_id text NOT NULL,
kind text NOT NULL CHECK (kind IN ('payment', 'refund', 'chargeback')),
status text NOT NULL CHECK (status IN ('succeeded', 'failed')),
amount bigint NOT NULL CHECK (amount > 0), -- 最小貨幣單位
fee bigint NOT NULL,
currency char(3) NOT NULL,
transacted_at timestamptz NOT NULL,
settlement_date date NOT NULL,
PRIMARY KEY (file_sha256, line_no)
);
CREATE INDEX statement_lines_day ON statement_lines (provider, recon_day);
CREATE INDEX statement_lines_trade_no ON statement_lines (merchant_trade_no);
-- 匯入一個對帳日:$1 provider、$2 recon_day、$3 這份檔案的 sha256
BEGIN;
SELECT pg_advisory_xact_lock(hashtext('recon:' || $1 || ':' || $2::text));
DELETE FROM statement_lines WHERE provider = $1 AND recon_day = $2;
-- 每一列一個 INSERT,或用 COPY 一次寫入;重跑同一份檔案時不會多出列
INSERT INTO statement_lines (file_sha256, line_no, provider, recon_day, merchant_trade_no,
provider_txn_id, kind, status, amount, fee, currency, transacted_at, settlement_date)
VALUES ($3, $4, $1, $2, $5, $6, $7, $8, $9, $10, $11, $12, $13)
ON CONFLICT (file_sha256, line_no) DO NOTHING;
UPDATE statement_files SET superseded_by = $3
WHERE provider = $1 AND recon_day = $2 AND sha256 <> $3 AND superseded_by IS NULL;
COMMIT;上面的 SQL 為了說明把所有參數寫在一起;實際程式裡 INSERT 會對每一列執行一次(或改用 COPY),交易與連線的用法見〈database/sql、交易與連線池〉。
圖:抓檔、保存原始檔、解析、寫入暫存表之後,才做合計檢查、逐筆配對、寫入差異表與告警;每一次執行都留下紀錄。
解析的陷阱:BOM、引號與編碼
CSV 看起來很簡單,實際上幾乎每一個坑都會遇到:
- BOM。 用試算表軟體另存的 UTF-8 檔案,開頭常常有三個位元組的 BOM(
EF BB BF)。不處理的話,第一個欄位名稱會變成merchant_trade_no,用名稱找欄位就找不到。 - 引號。 欄位裡有逗號或換行時會用雙引號包起來,例如
"1,000"。千萬不要用strings.Split(line, ",")自己切,要用encoding/csv;它也會正確處理引號裡的換行,這時「第幾行」和「第幾列」就不一樣了。 - 編碼。 有些系統輸出的不是 UTF-8,而是 Big5 或其他編碼。先檢查
utf8.Valid,不是 UTF-8 就整個檔案拒絕,交給轉碼步驟(例如golang.org/x/text/encoding)處理,而不是讓亂碼的商店訂單編號流進配對,變成一堆「對方有、我方無」。 - 欄位順序。 用標題列的名稱找欄位,不要寫死第幾欄;金流商哪天加一個欄位,程式也不會讀錯。必要欄位缺少時,整個檔案拒絕。
- 金額。 對帳單上的金額通常是十進位字串,例如
12.50或1,000。直接轉成最小貨幣單位的整數,全程不經過float64;小數位數超過幣別允許的範圍就報錯,不要偷偷捨入。新台幣在 ISO 4217 的小數位數是 2,但很多金流商以整數元表示,1,000要換成100000(以分計);這種換算放在解析這一層做,下一篇會完整說明。 - 符號。 有些對帳單把退款寫成負數,有些寫正數再用類型欄位區分。解析時統一成「金額永遠為正、方向看種類」。
- 狀態。 金流商的狀態字串(
SUCCESS、PAID、FAILED……)在解析時就對照成我們的詞彙;遇到不認得的值,整個檔案停下來,而不是猜。
最後一條原則:有一列解析失敗,整個檔案都不匯入。跳過壞掉的列看起來比較「有彈性」,實際上是讓那一筆從對帳裡消失,之後再也沒有人會發現。
時區與日界
這是對帳最常見、也最難察覺的問題。我們的商店在台北,習慣把「11 月 14 日」定義成台北時間 00:00 到 24:00;金流商的對帳單卻可能用 UTC 切日,或用它自己所在地的時區。台北時間的午夜是 UTC 的 16:00,所以一筆在台北時間 11 月 15 日 00:00:30 付款的交易,會出現在金流商 11 月 14 日(UTC)的檔案裡。
圖:付款 A 在兩邊都屬於 11/14;付款 B 在台北是 11/15,但在 UTC 的檔案裡是 11/14。
要做的事有三件:
- 選定一種對帳日的定義,寫進文件。 例如「對帳日 = 交易時間換成 Asia/Taipei 之後的日曆日」。所有報表、差異、月結都用同一個定義。
- 解析時把時間帶上正確的時區。 對帳單的時間欄位如果沒有時區資訊,就用金流商文件寫的時區(
time.ParseInLocation),再換到約定的時區取日期。 - 比對時把前後一天也拿進來。 即使日界定義一致,我們記錄的時間(建立付款的時間)和金流商的交易時間仍然可能差幾秒,剛好跨過午夜。所以前一天沒配對到、但仍在等待的紀錄,要帶到隔天再比一次(第 5 步的自動結案規則)。
台灣沒有日光節約時間,但如果你的業務在有日光節約時間的地區,一天可能是 23 或 25 小時,更不能用「加 24 小時」來算日界,一律用時區資料庫換算。
解析程式
ParseCSV 處理上面所有的陷阱:去掉 BOM、檢查 UTF-8、用欄位名稱找欄位、金額轉成整數、狀態對照、時間帶時區,任何一列有錯就整個檔案拒絕,錯誤訊息帶上行號。
// Package recon 把金流商的對帳單與我們自己的付款紀錄逐筆比對。
package recon
import (
"bytes"
"encoding/csv"
"errors"
"fmt"
"io"
"strconv"
"strings"
"time"
"unicode/utf8"
)
// Kind 是對帳單上一列的交易種類。付款、退款、拒付各自一列,不互相抵銷。
type Kind string
const (
Payment Kind = "payment"
Refund Kind = "refund"
Chargeback Kind = "chargeback"
)
// Row 是對帳單的一列;金額一律換成最小貨幣單位的 int64。
type Row struct {
Line int // 這一列在檔案中的起始行號,和檔案雜湊一起當唯一鍵
TradeNo string // 我們送出的商店訂單編號(付款嘗試 ID 或退款 ID)
ProviderTxnID string // 金流商的交易編號
Kind Kind
Status string // 已對應到我們的詞彙:succeeded 或 failed
Amount int64 // 交易總額(gross),一律為正,方向看 Kind
Fee int64 // 這一筆的手續費;退款退回手續費時可能是負數
Currency string // ISO 4217
At time.Time // 交易時間,已帶上時區
SettleDate string // 撥款日 YYYY-MM-DD
}
// ErrBadRow 表示對帳單內容不符合預期;整個檔案都不匯入,而不是跳過壞的列。
var ErrBadRow = errors.New("recon: bad statement")
// exponents 是幣別的小數位數(ISO 4217);完整的處理見下一篇。
var exponents = map[string]int{"TWD": 2, "USD": 2, "JPY": 0}
// statusMap 把金流商的狀態字串對到我們的詞彙;不認得的一律報錯,不要猜。
var statusMap = map[string]string{"SUCCESS": "succeeded", "PAID": "succeeded", "FAILED": "failed"}
var columns = []string{"merchant_trade_no", "provider_txn_id", "type", "status",
"amount", "fee", "currency", "transacted_at", "settlement_date"}
// ParseCSV 解析一份對帳單。providerTZ 是對帳單時間欄位所用的時區(由金流商的文件決定)。
func ParseCSV(data []byte, providerTZ *time.Location) ([]Row, error) {
data = bytes.TrimPrefix(data, []byte("\xef\xbb\xbf")) // Excel 存的 UTF-8 常帶 BOM
if !utf8.Valid(data) {
return nil, fmt.Errorf("%w: not UTF-8, convert the encoding first", ErrBadRow)
}
cr := csv.NewReader(bytes.NewReader(data))
header, err := cr.Read()
if err != nil {
return nil, fmt.Errorf("%w: header: %v", ErrBadRow, err)
}
idx := make(map[string]int, len(header))
for i, h := range header {
idx[strings.ToLower(strings.TrimSpace(h))] = i
}
for _, c := range columns {
if _, ok := idx[c]; !ok {
return nil, fmt.Errorf("%w: missing column %q", ErrBadRow, c)
}
}
var rows []Row
for {
rec, err := cr.Read()
if err == io.EOF {
return rows, nil
}
if err != nil {
return nil, fmt.Errorf("%w: %v", ErrBadRow, err)
}
line, _ := cr.FieldPos(0) // 引號裡有換行時,這仍是這一列開始的行號
get := func(c string) string { return strings.TrimSpace(rec[idx[c]]) }
r, err := parseRow(get, providerTZ)
if err != nil {
return nil, fmt.Errorf("%w: line %d: %v", ErrBadRow, line, err)
}
r.Line = line
rows = append(rows, r)
}
}
func parseRow(get func(string) string, tz *time.Location) (Row, error) {
r := Row{
TradeNo: get("merchant_trade_no"),
ProviderTxnID: get("provider_txn_id"),
Kind: Kind(strings.ToLower(get("type"))),
Currency: strings.ToUpper(get("currency")),
SettleDate: get("settlement_date"),
}
switch r.Kind {
case Payment, Refund, Chargeback:
default:
return Row{}, fmt.Errorf("unknown type %q", r.Kind)
}
if r.TradeNo == "" || r.ProviderTxnID == "" {
return Row{}, errors.New("missing merchant_trade_no or provider_txn_id")
}
var ok bool
if r.Status, ok = statusMap[strings.ToUpper(get("status"))]; !ok {
return Row{}, fmt.Errorf("unknown status %q", get("status"))
}
exp, ok := exponents[r.Currency]
if !ok {
return Row{}, fmt.Errorf("unknown currency %q", r.Currency)
}
var err error
if r.Amount, err = parseMinor(get("amount"), exp); err != nil {
return Row{}, err
}
if r.Amount < 0 && r.Kind != Payment {
r.Amount = -r.Amount // 有些對帳單把退款寫成負數;方向統一由 Kind 表達
}
if r.Amount <= 0 {
return Row{}, fmt.Errorf("amount must be positive, got %q", get("amount"))
}
if r.Fee, err = parseMinor(get("fee"), exp); err != nil {
return Row{}, err
}
if r.At, err = time.ParseInLocation(time.DateTime, get("transacted_at"), tz); err != nil {
return Row{}, fmt.Errorf("transacted_at: %v", err)
}
if _, err = time.Parse(time.DateOnly, r.SettleDate); err != nil {
return Row{}, fmt.Errorf("settlement_date: %v", err)
}
return r, nil
}
// parseMinor 把 "1,234.5" 這類十進位字串換成最小單位的整數,全程不經過 float64。
// 小數位數超過幣別允許的就報錯,而不是偷偷捨入。
func parseMinor(s string, exp int) (int64, error) {
t := strings.ReplaceAll(s, ",", "") // 千分位:欄位有加引號時才可能出現
neg := strings.HasPrefix(t, "-")
whole, frac, _ := strings.Cut(strings.TrimPrefix(t, "-"), ".")
if whole == "" || len(frac) > exp || strings.ContainsAny(whole+frac, "+-") {
return 0, fmt.Errorf("invalid amount %q", s)
}
n, err := strconv.ParseInt(whole+frac+strings.Repeat("0", exp-len(frac)), 10, 64)
if err != nil {
return 0, fmt.Errorf("invalid amount %q", s)
}
if neg {
n = -n
}
return n, nil
}
// Day 依「對帳日」的定義回傳交易屬於哪一天:先換到約定的時區,再取日曆日。
func Day(t time.Time, loc *time.Location) string {
return t.In(loc).Format(time.DateOnly)
}幾個細節:cr.FieldPos(0) 回傳的是這一列在檔案中開始的行號,引號裡有換行時也正確,它和檔案雜湊一起當暫存表的唯一鍵,之後要回頭查原始檔也找得到。parseMinor 先拿掉千分位,再把整數部分與補齊位數的小數部分接起來,用 strconv.ParseInt 一次轉換,溢位時也會回傳錯誤。exponents 只放了範例需要的三個幣別,完整的幣別處理留給下一篇。
測試把 BOM、引號裡的千分位、大寫的類型、負數的退款、日界以及各種壞檔案都涵蓋到:
package recon
import (
"errors"
"strings"
"testing"
"time"
)
// 台灣沒有日光節約時間,測試用固定時區,不依賴機器上的時區資料庫。
var taipei = time.FixedZone("Asia/Taipei", 8*60*60)
const header = "merchant_trade_no,provider_txn_id,type,status,amount,fee,currency,transacted_at,settlement_date\n"
func TestParseCSVHandlesBOMQuotingAndNegativeRefunds(t *testing.T) {
data := "\xef\xbb\xbf" + header +
`pay_1001,T9001,payment,SUCCESS,"1,000",28,TWD,2026-11-14 02:00:00,2026-11-16` + "\n" +
`"pay_1002","T9002",PAYMENT,success,"12.50",0.36,USD,2026-11-14 03:00:00,2026-11-16` + "\n" +
`ref_1001,T9003,refund,SUCCESS,-200,0,TWD,2026-11-14 04:00:00,2026-11-16` + "\n"
rows, err := ParseCSV([]byte(data), time.UTC)
if err != nil {
t.Fatal(err)
}
want := []struct {
trade string
kind Kind
amount int64
fee int64
line int
}{
{"pay_1001", Payment, 100000, 2800, 2}, // TWD 1,000 元 = 100000(以分計)
{"pay_1002", Payment, 1250, 36, 3},
{"ref_1001", Refund, 20000, 0, 4}, // 負數的退款轉成正數,方向看 Kind
}
if len(rows) != len(want) {
t.Fatalf("got %d rows, want %d", len(rows), len(want))
}
for i, w := range want {
r := rows[i]
if r.TradeNo != w.trade || r.Kind != w.kind || r.Amount != w.amount || r.Fee != w.fee || r.Line != w.line {
t.Errorf("row %d = %+v, want %+v", i, r, w)
}
}
}
func TestDayCutOff(t *testing.T) {
// 對帳單用 UTC;我們的對帳日定義成台北時間的日曆日
data := header +
"pay_1,T1,payment,SUCCESS,100,0,TWD,2026-11-14 15:59:59,2026-11-16\n" +
"pay_2,T2,payment,SUCCESS,100,0,TWD,2026-11-14 16:00:00,2026-11-17\n"
rows, err := ParseCSV([]byte(data), time.UTC)
if err != nil {
t.Fatal(err)
}
if got := Day(rows[0].At, taipei); got != "2026-11-14" {
t.Errorf("23:59:59 Taipei: day %s", got)
}
if got := Day(rows[1].At, taipei); got != "2026-11-15" {
t.Errorf("00:00:00 Taipei: day %s", got)
}
if got := Day(rows[1].At, time.UTC); got != "2026-11-14" {
t.Errorf("same row, provider's UTC day: %s", got)
}
}
func TestParseCSVRejectsWholeFile(t *testing.T) {
ok := "pay_1,T1,payment,SUCCESS,100,0,TWD,2026-11-14 01:00:00,2026-11-16\n"
cases := map[string]struct{ data, msg string }{
"missing column": {"merchant_trade_no,amount\npay_1,100\n", `missing column "provider_txn_id"`},
"unknown status": {header + ok + "pay_2,T2,payment,PROCESSING,100,0,TWD,2026-11-14 01:00:00,2026-11-16\n", "line 3: unknown status"},
"too many digits": {header + "pay_2,T2,payment,SUCCESS,10.005,0,USD,2026-11-14 01:00:00,2026-11-16\n", `line 2: invalid amount "10.005"`},
"negative charge": {header + "pay_2,T2,payment,SUCCESS,-100,0,TWD,2026-11-14 01:00:00,2026-11-16\n", "line 2: amount must be positive"},
"bad time": {header + "pay_2,T2,payment,SUCCESS,100,0,TWD,2026/11/14 01:00,2026-11-16\n", "line 2: transacted_at"},
"not utf-8": {header + "pay_2,T2,payment,SUCCESS,100,0,TWD,2026-11-14 01:00:00,2026-11-16,\xa4\xa4\n", "not UTF-8"},
"field count": {header + ok + "pay_2,T2,payment\n", "wrong number of fields"},
}
for name, c := range cases {
t.Run(name, func(t *testing.T) {
rows, err := ParseCSV([]byte(c.data), time.UTC)
if !errors.Is(err, ErrBadRow) || !strings.Contains(err.Error(), c.msg) {
t.Fatalf("err = %v, want %q", err, c.msg)
}
if rows != nil {
t.Fatalf("got %d rows from a bad file", len(rows))
}
})
}
}TestDayCutOff 用的是 time.FixedZone,因為台灣沒有日光節約時間,固定時差就足夠,測試也不依賴執行環境裡有沒有時區資料庫。正式程式裡建議用 time.LoadLocation("Asia/Taipei"),並在主程式匯入 time/tzdata,讓容器映像檔裡沒有時區資料時也能運作。
冪等的匯入
Ingest 把「保存原始檔、解析、整天取代暫存資料」串起來。它依賴一個小小的 Store 介面,正式環境的實作是物件儲存加上前面的 SQL,測試用記憶體版本。
package recon
import (
"context"
"crypto/sha256"
"encoding/hex"
"fmt"
"time"
)
// Store 是匯入需要的儲存操作:正式環境是物件儲存加 PostgreSQL,測試用記憶體版。
type Store interface {
// PutRaw 保存原始檔;同一個雜湊已經存在就什麼都不做,原始檔永遠不改寫。
PutRaw(ctx context.Context, sum, name string, data []byte) error
// ReplaceDay 在同一個交易裡刪掉這個對帳日的暫存列,再寫入這個檔案的每一列,
// 每列以「檔案雜湊+行號」為唯一鍵。
ReplaceDay(ctx context.Context, day, sum string, rows []Row) error
}
// Ingest 匯入某個對帳日的對帳單,回傳檔案的 SHA-256。
// 同一個檔案重跑幾次結果都一樣;更正版(雜湊不同)會整天取代舊的暫存資料。
func Ingest(ctx context.Context, s Store, day, name string, data []byte, providerTZ *time.Location) (string, error) {
h := sha256.Sum256(data)
sum := hex.EncodeToString(h[:])
// 先存原始檔再解析:解析失敗時,證據也已經留下來了
if err := s.PutRaw(ctx, sum, name, data); err != nil {
return "", fmt.Errorf("recon: save raw %s: %w", name, err)
}
rows, err := ParseCSV(data, providerTZ)
if err != nil {
return sum, fmt.Errorf("recon: parse %s: %w", name, err)
}
if err := s.ReplaceDay(ctx, day, sum, rows); err != nil {
return sum, fmt.Errorf("recon: stage %s: %w", name, err)
}
return sum, nil
}注意順序:先存原始檔再解析。如果反過來,解析失敗的檔案就不會留下來,事後想看「那份壞掉的檔案到底長怎樣」也找不到。
package recon
import (
"bytes"
"context"
"fmt"
"sync"
"testing"
"time"
)
// memStore 是 Store 的記憶體版本,行為和 PostgreSQL 版一致:原始檔只寫一次、每天整批取代。
type memStore struct {
mu sync.Mutex
raw map[string][]byte
days map[string]map[string]Row // 對帳日 → "雜湊:行號" → 列
}
func newMemStore() *memStore {
return &memStore{raw: map[string][]byte{}, days: map[string]map[string]Row{}}
}
func (m *memStore) PutRaw(_ context.Context, sum, _ string, data []byte) error {
m.mu.Lock()
defer m.mu.Unlock()
if _, ok := m.raw[sum]; !ok {
m.raw[sum] = bytes.Clone(data)
}
return nil
}
func (m *memStore) ReplaceDay(_ context.Context, day, sum string, rows []Row) error {
staged := make(map[string]Row, len(rows))
for _, r := range rows {
staged[fmt.Sprintf("%s:%d", sum, r.Line)] = r
}
m.mu.Lock()
defer m.mu.Unlock()
m.days[day] = staged
return nil
}
func TestIngestIsIdempotent(t *testing.T) {
ctx := context.Background()
s := newMemStore()
v1 := []byte(header +
"pay_1,T1,payment,SUCCESS,100,0,TWD,2026-11-14 01:00:00,2026-11-16\n" +
"pay_2,T2,payment,SUCCESS,250,0,TWD,2026-11-14 02:00:00,2026-11-16\n")
// 排程重試與人工重跑可能同時發生:同一個檔案匯入八次,結果要和一次相同
var wg sync.WaitGroup
for range 8 {
wg.Go(func() {
if _, err := Ingest(ctx, s, "2026-11-14", "2026-11-14.csv", v1, time.UTC); err != nil {
t.Error(err)
}
})
}
wg.Wait()
if len(s.raw) != 1 || len(s.days["2026-11-14"]) != 2 {
t.Fatalf("raw files %d, staged rows %d; want 1 and 2", len(s.raw), len(s.days["2026-11-14"]))
}
// 金流商重發更正版:原始檔兩份都留著,暫存資料整天換成新版
v2 := []byte(header + "pay_1,T1,payment,SUCCESS,100,0,TWD,2026-11-14 01:00:00,2026-11-16\n")
sum2, err := Ingest(ctx, s, "2026-11-14", "2026-11-14.v2.csv", v2, time.UTC)
if err != nil {
t.Fatal(err)
}
day := s.days["2026-11-14"]
if _, ok := day[sum2+":2"]; len(s.raw) != 2 || len(day) != 1 || !ok {
t.Fatalf("after correction: raw %d, staged %v", len(s.raw), day)
}
}
func TestIngestKeepsRawEvenWhenParsingFails(t *testing.T) {
s := newMemStore()
_, err := Ingest(context.Background(), s, "2026-11-14", "bad.csv", []byte("not,a,statement\n"), time.UTC)
if err == nil || len(s.raw) != 1 || len(s.days) != 0 {
t.Fatalf("err %v, raw %d, days %d", err, len(s.raw), len(s.days))
}
}第一個測試讓八個 goroutine 同時匯入同一份檔案,配合 -race 檢查 memStore 沒有資料競爭,並確認結果和匯入一次相同;接著匯入更正版,確認原始檔兩份都留著,暫存資料只剩新版。第二個測試確認解析失敗時原始檔仍然留下、暫存資料沒有被動到。
第 3 步:逐筆配對
配對的鍵
配對要用兩邊都有、而且不會變的鍵。最好的選擇是我們自己產生、送給金流商的商店訂單編號:它在送出前就已經存在資料庫裡,即使回呼全部遺失、我們從來沒拿到金流商的交易編號,也還是能配對。金流商的交易編號是第二把鑰匙,用來分辨「同一個商店訂單編號底下的兩筆不同交易」。
這也是為什麼前幾篇一直強調:商店訂單編號要用付款嘗試的 ID,而不是訂單 ID。同一張訂單第一次付款失敗、第二次成功,會有兩個付款嘗試,送出的編號不同,對帳時才分得開。
一對多
不是每一筆都能一對一:
- 部分退款。 一筆付款可以有多筆退款。每一筆退款要有自己的 ID,並當作退款的商店端編號送出;配對時退款和付款分開配,鍵是「種類+編號」。有些金流商的退款列只帶原始付款的編號加上自己的退款交易編號,這時就以「原始編號+退款交易編號」當鍵,並檢查同一筆付款的退款合計不超過原金額。
- 分批撥款。 一天的交易可能分好幾批撥款,或是一筆撥款涵蓋好幾天。撥款的比對是以「撥款日」或撥款批號為單位的整批比對(第 6 步),不和逐筆配對混在一起。
- 拒付(chargeback)。 持卡人向發卡銀行爭議,錢被扣回去。這是金流商那邊發生的事,我們這邊一開始不會有對應的紀錄,所以它一定以「只有對方有」的形式出現,而且通常有回覆期限。
金額、幣別、手續費
- 金額一律用最小貨幣單位的整數比較,而且幣別也要相同;
1000 TWD和1000 JPY不是同一個金額。 - 對帳單常見兩種寫法:總額(gross)加上手續費欄位,或直接給淨額(net)。逐筆配對要用總額,因為我們記的是使用者付了多少;如果只有淨額,就用「淨額+手續費」還原總額。
- 手續費可能逐筆收(每筆 2.8%)、整批收(每次撥款收一筆固定費用)或兩者都有。逐筆的手續費在配對時和我們依合約算出的預期值比;整批的費用在撥款核對時比。費率計算一樣有捨入的問題,留給下一篇。
狀態對照
金流商的狀態比我們少,也比我們粗:對帳單上通常只有成功與失敗,有的只列成功的交易。我們這邊則有 pending、unknown 這類「還不知道」的狀態。對照的原則是:
- 對方說成功、我們也是
succeeded:一致。 - 對方說成功、我們是
failed、pending或unknown:狀態不一致,而且使用者已經被扣款,最危險的一種。 - 我們是
pending或unknown、對方沒有:還在路上,交給上一篇的補查程式,不算對帳差異。 - 我們是
failed、對方沒有:正常,失敗的交易不一定出現在對帳單上。
Match 把上面所有規則寫成程式。它是純函式,不碰資料庫,所以很容易測;呼叫端負責準備兩邊的資料:
package recon
import (
"cmp"
"fmt"
"slices"
)
// Ours 是我們這邊的一筆紀錄:付款嘗試或退款。
type Ours struct {
ID string // 付款嘗試 ID 或退款 ID,送給金流商當商店訂單編號
Kind Kind
Status string // succeeded / failed / pending / unknown
Amount int64 // 最小貨幣單位
Currency string
ExpectedFee int64 // 依合約費率算出的預期手續費
}
// DiffKind 是差異的種類。
type DiffKind string
const (
MissingAtProvider DiffKind = "missing_at_provider" // 我們成功、對方沒有
MissingInOurs DiffKind = "missing_in_ours" // 對方有、我們完全沒有
StatusMismatch DiffKind = "status_mismatch"
AmountMismatch DiffKind = "amount_mismatch" // 金額或幣別不同
FeeMismatch DiffKind = "fee_mismatch"
Duplicate DiffKind = "duplicate" // 對方同一個商店訂單編號出現兩次
)
// Discrepancy 是一筆差異;Urgent 代表使用者可能已被扣款,我們卻沒有記成成功。
type Discrepancy struct {
Kind DiffKind
Key string
Ours *Ours
Theirs *Row
Urgent bool
Note string
}
// Result 是一次配對的結果。
type Result struct {
Matched int
Diffs []Discrepancy
}
func key(k Kind, tradeNo string) string { return string(k) + "/" + tradeNo }
// Match 逐筆配對。ours 要包含對帳日當天、對帳單上出現的編號與之前未結案的紀錄,
// 跨日的交易才不會被誤判為缺少。
func Match(ours []Ours, theirs []Row) Result {
mine := make(map[string]*Ours, len(ours))
for i := range ours {
mine[key(ours[i].Kind, ours[i].ID)] = &ours[i]
}
seen := make(map[string]*Row, len(theirs))
var res Result
add := func(d Discrepancy) { res.Diffs = append(res.Diffs, d) }
for i := range theirs {
t := &theirs[i]
k := key(t.Kind, t.TradeNo)
if first, dup := seen[k]; dup {
// 交易編號相同 = 同一列被送了兩次,該在匯入時去掉;不同 = 對方真的有兩筆交易
add(Discrepancy{Kind: Duplicate, Key: k, Theirs: t,
Urgent: t.ProviderTxnID != first.ProviderTxnID && t.Status == "succeeded",
Note: fmt.Sprintf("first %s, again %s", first.ProviderTxnID, t.ProviderTxnID)})
continue
}
seen[k] = t
o, ok := mine[k]
switch {
case !ok:
add(Discrepancy{Kind: MissingInOurs, Key: k, Theirs: t, Urgent: t.Status == "succeeded"})
case o.Status != t.Status:
add(Discrepancy{Kind: StatusMismatch, Key: k, Ours: o, Theirs: t, Urgent: t.Status == "succeeded",
Note: fmt.Sprintf("ours %s, provider %s", o.Status, t.Status)})
case o.Amount != t.Amount || o.Currency != t.Currency:
add(Discrepancy{Kind: AmountMismatch, Key: k, Ours: o, Theirs: t,
Note: fmt.Sprintf("ours %d %s, provider %d %s", o.Amount, o.Currency, t.Amount, t.Currency)})
case o.ExpectedFee != t.Fee:
add(Discrepancy{Kind: FeeMismatch, Key: k, Ours: o, Theirs: t,
Note: fmt.Sprintf("expected %d, charged %d", o.ExpectedFee, t.Fee)})
default:
res.Matched++
}
}
for k, o := range mine {
// pending、unknown 還在路上,交給補查程式;failed 本來就可能不出現在對帳單上
if _, ok := seen[k]; !ok && o.Status == "succeeded" {
add(Discrepancy{Kind: MissingAtProvider, Key: k, Ours: o})
}
}
slices.SortFunc(res.Diffs, func(a, b Discrepancy) int {
return cmp.Or(cmp.Compare(a.Key, b.Key), cmp.Compare(a.Kind, b.Kind))
})
return res
}ours 要怎麼準備?只拿「對帳日當天」的紀錄是不夠的,因為跨日的交易會被誤判。實務上用三個條件取聯集:對帳日當天建立的紀錄、這份對帳單上出現的所有商店訂單編號(不論哪天建立),以及前幾天還沒結案的「對方沒有」的紀錄:
-- recon_our_records 是把 payments 與 refunds 合在一起的檢視,id 就是送給金流商的商店訂單編號
SELECT id, kind, status, amount, currency, expected_fee
FROM recon_our_records
WHERE (created_at AT TIME ZONE 'Asia/Taipei')::date = $2 -- 對帳日當天
OR id = ANY ($3::text[]) -- 這份對帳單上出現的編號
OR id IN (SELECT split_part(match_key, '/', 2) -- 之前還沒結案的「對方沒有」
FROM recon_discrepancies
WHERE provider = $1 AND kind = 'missing_at_provider'
AND state IN ('open', 'investigating'));第 4 步:把差異分類
Match 產生的差異分成六類,每一類的意義與緊急程度都不一樣:
圖:先看兩邊是否都有,再依狀態、金額、手續費依序檢查;深色框代表使用者可能已被扣款,當天就要處理。
| 類型 | 情況 | 常見原因 | 緊急程度 |
|---|---|---|---|
missing_at_provider | 我們是成功,對帳單上沒有 | 跨日的時間差;我們誤判成功;對方漏列 | 先等一天,隔天仍沒有才查 |
missing_in_ours | 對帳單上成功,我們完全沒有 | 回呼全部失敗;在金流商後台手動建立;程式錯誤 | 緊急:使用者已被扣款 |
status_mismatch | 兩邊都有,狀態不同 | 逾時後判成失敗,其實成功;回呼處理錯誤 | 對方成功時緊急 |
amount_mismatch | 金額或幣別不同 | 部分退款沒同步;幣別換算;資料被改 | 當天調查 |
fee_mismatch | 手續費和合約不同 | 費率調整沒通知;捨入方式不同;卡別不同 | 不急,但要和金流商確認 |
duplicate | 同一個商店訂單編號在對帳單上出現兩次 | 交易編號相同=檔案重複列;不同=重複扣款 | 交易編號不同且成功時緊急 |
「只有對方有」和「狀態不同而對方成功」是最危險的兩類:使用者的錢已經被扣了,我們卻沒有出貨,或訂單已經被取消。處理方式和上一篇的補查一樣:先用商店訂單編號向金流商查詢單筆,確認成功後依訂單現況決定補記成功並出貨,或是退款;兩者都要冪等,不能因為對帳重跑就退兩次款。
「只有我們有」大多是時間差,不需要馬上告警,但不能永遠等下去。如果隔天、後天的對帳單上仍然沒有,就要向金流商查詢:也許是我們把逾時誤判成功(那就是嚴重的程式錯誤),也許是對方漏列。
測試把每一種類型都放進同一組資料裡,確認分類、排序與緊急標記:
package recon
import (
"slices"
"testing"
)
func TestMatchClassifiesDifferences(t *testing.T) {
ours := []Ours{
{ID: "pay_1", Kind: Payment, Status: "succeeded", Amount: 100000, Currency: "TWD", ExpectedFee: 2800},
{ID: "pay_2", Kind: Payment, Status: "succeeded", Amount: 50000, Currency: "TWD"}, // 對方沒有
{ID: "pay_3", Kind: Payment, Status: "failed", Amount: 30000, Currency: "TWD"}, // 對方卻扣款成功
{ID: "pay_4", Kind: Payment, Status: "succeeded", Amount: 20000, Currency: "TWD"},
{ID: "pay_5", Kind: Payment, Status: "succeeded", Amount: 10000, Currency: "TWD", ExpectedFee: 280},
{ID: "pay_6", Kind: Payment, Status: "pending", Amount: 10000, Currency: "TWD"}, // 還在路上,不算差異
{ID: "ref_1", Kind: Refund, Status: "succeeded", Amount: 20000, Currency: "TWD"},
}
theirs := []Row{
{TradeNo: "pay_1", ProviderTxnID: "T1", Kind: Payment, Status: "succeeded", Amount: 100000, Currency: "TWD", Fee: 2800},
{TradeNo: "pay_3", ProviderTxnID: "T3", Kind: Payment, Status: "succeeded", Amount: 30000, Currency: "TWD"},
{TradeNo: "pay_4", ProviderTxnID: "T4", Kind: Payment, Status: "succeeded", Amount: 2000, Currency: "TWD"},
{TradeNo: "pay_5", ProviderTxnID: "T5", Kind: Payment, Status: "succeeded", Amount: 10000, Currency: "TWD", Fee: 300},
{TradeNo: "pay_7", ProviderTxnID: "T7", Kind: Payment, Status: "succeeded", Amount: 9900, Currency: "TWD"}, // 我們沒有
{TradeNo: "pay_1", ProviderTxnID: "T8", Kind: Payment, Status: "succeeded", Amount: 100000, Currency: "TWD"}, // 第二筆
{TradeNo: "ref_1", ProviderTxnID: "R1", Kind: Refund, Status: "succeeded", Amount: 20000, Currency: "TWD"},
}
res := Match(ours, theirs)
type got struct {
key string
kind DiffKind
urgent bool
}
var diffs []got
for _, d := range res.Diffs {
diffs = append(diffs, got{d.Key, d.Kind, d.Urgent})
}
want := []got{
{"payment/pay_1", Duplicate, true},
{"payment/pay_2", MissingAtProvider, false},
{"payment/pay_3", StatusMismatch, true},
{"payment/pay_4", AmountMismatch, false},
{"payment/pay_5", FeeMismatch, false},
{"payment/pay_7", MissingInOurs, true},
}
if !slices.Equal(diffs, want) {
t.Fatalf("diffs\n got %v\nwant %v", diffs, want)
}
if res.Matched != 2 {
t.Errorf("matched = %d, want 2", res.Matched)
}
}
func TestTotalsAndNet(t *testing.T) {
rows := []Row{
{Kind: Payment, Status: "succeeded", Amount: 100000, Fee: 2800, Currency: "TWD"},
{Kind: Payment, Status: "succeeded", Amount: 50000, Fee: 1400, Currency: "TWD"},
{Kind: Payment, Status: "failed", Amount: 70000, Currency: "TWD"}, // 失敗的不計入
{Kind: Refund, Status: "succeeded", Amount: 20000, Fee: -560, Currency: "TWD"},
{Kind: Payment, Status: "succeeded", Amount: 1250, Fee: 36, Currency: "USD"},
}
ours := []Ours{
{Kind: Payment, Status: "succeeded", Amount: 100000, ExpectedFee: 2800, Currency: "TWD"},
{Kind: Payment, Status: "succeeded", Amount: 50000, ExpectedFee: 1400, Currency: "TWD"},
{Kind: Refund, Status: "succeeded", Amount: 20000, ExpectedFee: -560, Currency: "TWD"},
}
theirs := SumRows(rows)
diff := CompareTotals(SumOurs(ours), theirs)
if want := []string{"payment USD: ours 0/0/0, provider 1/1250/36"}; !slices.Equal(diff, want) {
t.Errorf("CompareTotals = %q, want %q", diff, want)
}
// 150000 − 20000 − (2800 + 1400 − 560) = 126360
if got := Net(theirs, "TWD"); got != 126360 {
t.Errorf("Net TWD = %d, want 126360", got)
}
}pay_6 是 pending、對方沒有,所以不出現在差異裡;pay_1 在對帳單上出現兩次而且交易編號不同,第二次被標成 duplicate。TestTotalsAndNet 用到的合計函式在第 6 步說明。
第 5 步:處理差異
差異表
每一筆差異都寫進一張表,並且有狀態、負責人與完整的歷史。對帳每天重跑時,同一個差異只會有一筆「未結案」的紀錄,靠部分唯一索引保證:
CREATE TABLE recon_discrepancies (
id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
provider text NOT NULL,
recon_day date NOT NULL, -- 第一次發現的對帳日
match_key text NOT NULL, -- 例如 payment/pay_1001
kind text NOT NULL,
urgent boolean NOT NULL DEFAULT false,
our_amount bigint,
their_amount bigint,
currency char(3),
state text NOT NULL DEFAULT 'open'
CHECK (state IN ('open', 'investigating', 'resolved', 'written_off')),
resolution text, -- matched_later / booked / refunded / adjusted / written_off
owner text,
note text,
first_seen_at timestamptz NOT NULL DEFAULT now(),
last_seen_at timestamptz NOT NULL DEFAULT now(),
resolved_at timestamptz,
CHECK ((state IN ('resolved', 'written_off')) = (resolved_at IS NOT NULL))
);
-- 同一個差異,未結案的只能有一筆;每天重跑時更新 last_seen_at,而不是新增
CREATE UNIQUE INDEX recon_discrepancies_one_open
ON recon_discrepancies (provider, match_key, kind)
WHERE state IN ('open', 'investigating');
-- 每一次變更都寫一筆事件,只新增不修改
CREATE TABLE recon_discrepancy_events (
id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
discrepancy_id bigint NOT NULL REFERENCES recon_discrepancies (id),
actor text NOT NULL, -- 人員帳號,或 system:recon
action text NOT NULL, -- opened / seen_again / assigned / note / resolved / written_off
from_state text,
to_state text,
detail jsonb NOT NULL DEFAULT '{}',
at timestamptz NOT NULL DEFAULT now()
);
-- 寫入一筆差異:已經有未結案的就更新最後出現時間
INSERT INTO recon_discrepancies
(provider, recon_day, match_key, kind, urgent, our_amount, their_amount, currency, note)
VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
ON CONFLICT (provider, match_key, kind) WHERE state IN ('open', 'investigating')
DO UPDATE SET last_seen_at = now(),
urgent = recon_discrepancies.urgent OR EXCLUDED.urgent
RETURNING id;生命週期
圖:差異從 open 開始,指派後進入 investigating,修正後 resolved;確定追不回來的經主管核准後 written_off。時間差造成的差異隔天配對成功就自動結案。
- open:剛被發現,還沒有人處理。
- investigating:已經指派負責人,正在查。
- resolved:已經修正,
resolution記錄怎麼修的(補記、退款、寫調整分錄、隔天自動配對成功)。 - written_off:確定追不回來,或金額小到追的成本高於金額本身,經過核准後沖銷。沖銷也是寫分錄,不是刪紀錄。
每一次狀態變更、指派、補充說明都寫一筆事件。三個月後稽核問「這筆 990 元為什麼沖銷」,要能回答是誰、什麼時候、根據什麼決定的。
自動結案:時間差
跨日造成的 missing_at_provider 是最大宗,也最不值得人看。規則很簡單:這次對帳的開始時間之後,如果某一筆「對方沒有」沒有再被列出來,表示它今天配對成功了,就自動結案並寫事件:
-- $1 provider、$2 這次對帳開始的時間
WITH done AS (
UPDATE recon_discrepancies
SET state = 'resolved', resolution = 'matched_later', resolved_at = now()
WHERE provider = $1 AND kind = 'missing_at_provider'
AND state = 'open' AND last_seen_at < $2
RETURNING id
)
INSERT INTO recon_discrepancy_events (discrepancy_id, actor, action, from_state, to_state)
SELECT id, 'system:recon', 'resolved', 'open', 'resolved' FROM done;這條規則能成立,前提是 ours 一定包含前幾天未結案的紀錄(第 3 步的查詢),而且這次對帳成功跑完;對帳中途失敗時不能執行,否則所有沒被重新列出的差異都會被誤判成已解決。同樣的道理,告警要看年齡:missing_at_provider 第一天不告警,超過兩個對帳日還沒結案才告警。
人工檢查的介面
差異表最後是給人看的。一個好用的檢查畫面至少要有:
- 依緊急程度、年齡、金額排序,緊急的永遠在最上面。
- 一筆差異打開後,並排顯示我們的紀錄(付款、訂單、回呼紀錄、狀態變更歷史)與對帳單的原始那一列(可以連到原始檔與行號)。
- 「向金流商查詢」按鈕,結果寫進事件。
- 修正動作做成按鈕(補記成功、發起退款、寫調整分錄、申請沖銷),每個動作都要填原因;沖銷需要第二個人核准。
- 個人資料預設遮蔽(見第 7 步)。
修正的原則:不改金額,寫分錄
對帳發現金額不對時,最直覺的做法是把 payments.amount 改成對帳單上的數字。不要這樣做。 改掉之後,原本的值就消失了,帳本裡已經寫好的分錄也和它對不上,下一次有人查帳時,什麼都說不清楚。
正確的做法是延續〈支付常見問題:重複扣款、回呼與對帳〉第 9 個問題的複式記帳:原本的分錄不動,寫一筆調整分錄把差額補上或沖回,分錄的冪等鍵用差異的 ID,並在差異的事件裡記下分錄編號。例如金流商實際收的手續費比預期多 20 分:
-- 冪等鍵 = 差異 ID,同一筆差異只會調整一次
INSERT INTO journal_entries (idempotency_key, kind)
VALUES ('recon-adjust-' || $1, 'recon_adjustment')
ON CONFLICT (idempotency_key) DO NOTHING
RETURNING id;
-- 有回傳 id 才寫分錄列:借 手續費支出 20、貸 應收金流商 20
-- $1 剛建立的分錄 id、$2 手續費支出帳戶、$3 應收金流商帳戶
INSERT INTO ledger_lines (entry_id, account_id, debit, credit)
VALUES ($1, $2, 20, 0), ($1, $3, 0, 20);journal_entries 與 ledger_lines 的定義在上面那篇裡;kind 在那裡是自由文字,這裡多了一種 recon_adjustment。
修正動作要冪等
對帳每天重跑,人也可能重複按按鈕。每一個會動到錢的修正動作都要有冪等鍵:
- 退款:冪等鍵用「差異 ID+動作」,例如
recon-refund-1234,並且同樣送給金流商當退款的商店端編號;重跑時金流商也會擋掉重複。 - 補記成功並出貨:走正常的狀態機條件式更新(
WHERE status IN ('pending', 'unknown', 'failed')),出貨用 Outbox 送事件(〈分散式交易:Saga 與 Outbox〉);條件不成立就表示已經有人處理過。 - 調整分錄:如上,冪等鍵用差異 ID。
第 6 步:和帳本與銀行撥款對起來
先比合計,再逐筆
逐筆配對之前,先做一次合計檢查:兩邊依「種類+幣別」算筆數、金額與手續費合計。合計對不上,代表一定有差異,逐筆配對會告訴你是哪幾筆;合計對得上,也不代表沒有問題,但如果合計差了一大截(例如對帳單只有平常的一半),通常是檔案不完整或抓錯日期,應該先停下來檢查檔案,而不是產生幾千筆差異。
package recon
import (
"cmp"
"fmt"
"maps"
"slices"
)
// TotalsKey 把合計依交易種類與幣別分開;不同幣別的金額絕對不能加在一起。
type TotalsKey struct {
Kind Kind
Currency string
}
// Totals 是成功交易的筆數、總額與手續費合計。
type Totals struct {
Count int
Amount int64
Fee int64
}
// SumRows 加總對帳單上成功的列。
func SumRows(rows []Row) map[TotalsKey]Totals {
m := map[TotalsKey]Totals{}
for _, r := range rows {
if r.Status != "succeeded" {
continue
}
k := TotalsKey{r.Kind, r.Currency}
t := m[k]
t.Count, t.Amount, t.Fee = t.Count+1, t.Amount+r.Amount, t.Fee+r.Fee
m[k] = t
}
return m
}
// SumOurs 加總我們這邊成功的紀錄,手續費用預期值。
func SumOurs(ours []Ours) map[TotalsKey]Totals {
m := map[TotalsKey]Totals{}
for _, o := range ours {
if o.Status != "succeeded" {
continue
}
k := TotalsKey{o.Kind, o.Currency}
t := m[k]
t.Count, t.Amount, t.Fee = t.Count+1, t.Amount+o.Amount, t.Fee+o.ExpectedFee
m[k] = t
}
return m
}
// CompareTotals 列出兩邊合計不一致的項目,依固定順序排列。
func CompareTotals(ours, theirs map[TotalsKey]Totals) []string {
keys := slices.Collect(maps.Keys(ours))
for k := range theirs {
if _, ok := ours[k]; !ok {
keys = append(keys, k)
}
}
slices.SortFunc(keys, func(a, b TotalsKey) int {
return cmp.Or(cmp.Compare(a.Kind, b.Kind), cmp.Compare(a.Currency, b.Currency))
})
var out []string
for _, k := range keys {
if a, b := ours[k], theirs[k]; a != b {
out = append(out, fmt.Sprintf("%s %s: ours %d/%d/%d, provider %d/%d/%d",
k.Kind, k.Currency, a.Count, a.Amount, a.Fee, b.Count, b.Amount, b.Fee))
}
}
return out
}
// Net 是對方這批應撥給我們的淨額:付款 − 退款 − 拒付 − 全部手續費。
func Net(t map[TotalsKey]Totals, currency string) int64 {
n := t[TotalsKey{Payment, currency}].Amount -
t[TotalsKey{Refund, currency}].Amount -
t[TotalsKey{Chargeback, currency}].Amount
for k, v := range t {
if k.Currency == currency {
n -= v.Fee
}
}
return n
}Net 算的是這批交易金流商應該撥給我們的淨額:付款總額減掉退款與拒付,再減掉所有手續費。退款退回手續費時,手續費是負數,減掉負數就等於加回來。不同幣別的金額絕對不加在一起,所以合計的鍵一定帶幣別。
測試 TestTotalsAndNet(在上面的 match_test.go 裡)確認失敗的交易不計入、只有一邊有的幣別也會被列出,以及淨額的計算:150000 − 20000 − (2800 + 1400 − 560) = 126360。
帳本裡的四種分錄
要讓帳本和對帳單、銀行對起來,帳本至少要有這幾個帳戶:應收金流商(金流商收了錢、還沒撥給我們)、銀行存款、手續費支出、營收(或給商家的應付款),以及退款相關的帳戶。一筆付款從頭到尾會寫四種分錄:
| 事件 | 借 | 貸 | 例(分) |
|---|---|---|---|
| 付款成功 | 應收金流商 | 營收 | 100000 |
| 金流商收手續費 | 手續費支出 | 應收金流商 | 2800 |
| 部分退款 | 營收(或銷貨退回) | 應收金流商 | 20000 |
| 撥款進銀行 | 銀行存款 | 應收金流商 | 77200 |
撥款之後,這一批在「應收金流商」上的借貸剛好抵銷成 0。所以三方對帳可以化成一句話:每個撥款日,應收金流商在帳本上的減少,等於對帳單上這一批的淨額,也等於銀行實際入帳的金額。
對帳單與銀行入帳
銀行端的資料可以來自銀行的對帳單或入帳通知,存在 bank_deposits。以撥款日比較兩邊的淨額:
-- $1 provider;銀行入帳存在 bank_deposits (provider, value_date, amount, currency, reference)
WITH stmt AS (
SELECT settlement_date, currency,
sum(CASE kind WHEN 'payment' THEN amount ELSE -amount END) - sum(fee) AS net
FROM statement_lines
WHERE provider = $1 AND status = 'succeeded'
GROUP BY settlement_date, currency
), bank AS (
SELECT value_date AS settlement_date, currency, sum(amount) AS net
FROM bank_deposits
WHERE provider = $1
GROUP BY value_date, currency
)
SELECT settlement_date, currency, s.net AS statement_net, b.net AS bank_net
FROM stmt s FULL JOIN bank b USING (settlement_date, currency)
WHERE s.net IS DISTINCT FROM b.net
ORDER BY settlement_date, currency;這個查詢只是起點,實務上有幾個常見的差異來源:撥款遇到假日會延後,銀行的入帳日和對帳單上的撥款日不同(如果金流商提供撥款批號,用批號對比用日期可靠);整批收取的費用、匯費或保留款(reserve)會從撥款中扣掉,要在對帳單或撥款明細裡找到對應的列;拒付可能在之後的撥款裡扣回。每一種都應該有明確的處理規則,而不是每個月由人手算。
帳本與對帳單的每日合計
最後,帳本這邊也做一樣的合計,和對帳單的合計比:
-- 帳本:某個對帳日,「應收金流商」帳戶依分錄種類的筆數與淨變動($1 帳戶、$2 對帳日)
SELECT e.kind, count(*) AS entries, sum(l.debit - l.credit) AS net_change
FROM journal_entries e
JOIN ledger_lines l ON l.entry_id = e.id
WHERE l.account_id = $1
AND (e.created_at AT TIME ZONE 'Asia/Taipei')::date = $2
GROUP BY e.kind
ORDER BY e.kind;
-- 對帳單:同一個對帳日,依種類的筆數與合計($1 provider、$2 對帳日)
SELECT kind, count(*) AS lines, sum(amount) AS amount, sum(fee) AS fee
FROM statement_lines
WHERE provider = $1 AND recon_day = $2 AND status = 'succeeded'
GROUP BY kind
ORDER BY kind;帳本的分錄時間是我們記帳的時間(例如收到回呼的時候),不一定和交易時間同一天,這也是一種時間差。比較常見的做法是在分錄上另外存一個「業務日期」欄位,用交易時間換算的對帳日填入,合計時用它,而不是用 created_at。
第 7 步:營運
每日報表
每次對帳跑完,產生一份簡短的報表:對帳日、檔案與雜湊、兩邊的筆數與合計、配對成功筆數、各類差異的筆數與金額、自動結案筆數、未結案差異依年齡的分布。報表本身也存起來,月結時直接引用。
指標與告警
對帳程式也要被監控,和其他服務一樣輸出指標(〈可觀測性:日誌、指標、追蹤〉):
- 對帳單沒有準時到:超過約定時間仍沒有成功的
ingestion_runs,告警給工程。 - 對帳失敗:解析錯誤、合計差異過大,告警給工程。
- 緊急差異 > 0:
missing_in_ours、對方成功的status_mismatch、重複扣款,有一筆就告警,因為每一筆都代表一個被扣了錢卻沒拿到東西的使用者。 - 未結案差異依年齡:例如
missing_at_provider超過兩個對帳日、任何差異超過七天,告警給負責人。 - 未結案差異的金額:依幣別分開算,超過門檻告警。
- 差異數量的趨勢:平常每天兩三筆,今天突然五十筆,通常代表某個環節壞了(新版程式、金流商改格式),比任何單一差異都值得注意。
指標的標籤只放種類、幣別、年齡區間這類低基數的值,不要放商店訂單編號。
重跑與回補
- 重跑某一天:因為原始檔不改寫、匯入與差異寫入都冪等,重跑就是「用同一份原始檔再跑一次」,結果應該相同。這也是修好解析程式後回補的方式。
- 回補一段期間:例如新接一家金流商,或發現某個月的檔案漏抓。依日期順序逐日跑,每一天都寫執行紀錄;不要一次載入整個月再配對,否則跨日的時間差規則不會正確運作。
- 重跑不能產生副作用:配對與分類是純計算;會動到錢的修正動作都有冪等鍵,重跑不會再退一次款。
資料保存、權限與個人資料
對帳單裡通常有個人資料:持卡人姓名、部分遮蔽的卡號、Email、電話、IP。處理原則:
- 原始檔放在權限受控的物件儲存,只有對帳程式與少數人能讀;存取要留紀錄。
- 暫存表只放對帳需要的欄位,個人資料不進暫存表,需要時從原始檔查。
- 檢查畫面預設遮蔽,需要看完整內容時要有理由並留紀錄。
- 日誌只記商店訂單編號、金額、差異種類,不記整列內容。
- 保存期限依會計與法規要求決定,到期後依政策刪除或封存;完整卡號與安全碼本來就不應該出現在對帳單裡,出現了要通報金流商。
月結
月底時,對帳的工作是讓財務能關帳:
- 確認這個月每一天都有成功的對帳執行,沒有缺漏的日期。
- 所有緊急差異都已結案;其他未結案的差異列成清單,附上原因與預計處理時間,金額小的依政策沖銷。
- 這個月的撥款全部和銀行入帳對上;跨月的撥款(月底的交易下個月才撥款)列為應收餘額,並和帳本上應收金流商的餘額一致。
- 關帳後,這個月的資料不再改動;之後發現的問題,以下個月的調整分錄處理,並在差異的事件裡註明。
執行測試
$ go vet ./...
$ go test -race ./...
ok example.com/shop/internal/recon 1.084s常見陷阱
- 用
strings.Split切 CSV。 遇到引號裡的逗號就錯位。用encoding/csv,並用欄位名稱找欄位。 - 用
float64解析金額。strconv.ParseFloat("0.29", 64) * 100轉回整數可能變成 28。直接解析成整數。 - 跳過壞掉的列。 那一筆從此消失。有錯就整個檔案拒絕。
- 兩邊用不同的日界。 每天都有一小撮「對方沒有」,而且永遠消不掉。先定義對帳日,再加上跨日帶到隔天的規則。
- 第一天就對「對方沒有」告警。 告警疲乏後,真正緊急的那一筆也沒人看。依類型與年齡分級。
- 直接改金額或刪差異。 帳本與事件紀錄是唯一能解釋過去的東西。寫調整分錄、狀態改成結案。
- 修正動作不冪等。 對帳重跑一次,就多退一次款。
- 只比總額。 一多一少剛好抵銷。合計只是初步檢查。
- 對帳失敗時仍執行自動結案。 沒被列出不代表已解決,可能只是沒跑到。
重點整理
- 對帳是三方的:我們的紀錄和對帳單逐筆比、對帳單和銀行撥款整批比,三者都要和帳本對得起來。
- 對帳單是證據:原始檔原封不動地保存並記錄雜湊,所有結果都能從原始檔重新算出來。
- 匯入要冪等:暫存表以「檔案雜湊+行號」為鍵,一個對帳日在同一個交易裡整批取代,更正版直接取代舊版。
- 解析要嚴格:處理 BOM、引號與編碼,金額直接轉成最小單位的整數,狀態對照不認得就停,有一列錯就整個檔案拒絕。
- 先定義對帳日,再處理時區:時間帶上正確時區、換到約定時區取日期,跨日的紀錄帶到隔天再比。
- 用自己產生的商店訂單編號當配對鍵,付款、退款、拒付分開配;先比合計,再逐筆配對。
- 差異要分類分級:「對方成功、我們沒有成功」是使用者已被扣款,當天處理;時間差隔天自動結案。
- 差異要有狀態、負責人與事件紀錄;修正寫調整分錄,不改金額;會動到錢的修正都要冪等。
上線前可以逐項確認:
- 文件寫清楚對帳日的定義(時區與日界)、每一方的資料來源,以及各角色的負責人。
- 抓檔有排程、退避重試與「逾時未到」告警,每次執行都寫進
ingestion_runs。 - 原始檔存在物件儲存,記錄 SHA-256,不可改寫;更正版另存一份並標記取代關係。
- 解析用
encoding/csv、處理 BOM、檢查 UTF-8、用欄位名稱找欄位,金額不經過float64,錯一列就整檔拒絕,並有對應的測試。 - 暫存表以「檔案雜湊+行號」為鍵,一個對帳日在同一個交易裡整批取代,同一天的匯入有鎖。
- 配對鍵是商店訂單編號(付款嘗試 ID、退款 ID),並涵蓋前後一天與未結案的紀錄。
- 合計檢查(筆數、金額、手續費,依種類與幣別)在逐筆配對之前執行,差距過大就停下來。
- 差異表有狀態、負責人、事件紀錄與部分唯一索引;時間差有自動結案規則,對帳失敗時不執行。
- 緊急差異有一筆就告警;其他差異依年齡與金額告警。
- 修正一律寫調整分錄;退款、補記、沖銷都有冪等鍵;沖銷需要第二個人核准。
- 撥款以撥款日或批號和銀行入帳比對,應收金流商的餘額和帳本一致。
- 原始檔與檢查畫面的個人資料有權限控管、預設遮蔽與存取紀錄,並有保存期限。
- 月結前確認每天都有成功的對帳、緊急差異全部結案、跨月撥款列為應收。
下一篇
對帳時最難纏的差異,往往不是整筆不見,而是差了一兩分錢:手續費依費率乘出來有零頭,我們四捨五入、金流商無條件捨去;一筆折扣分攤到三個商品,退其中一件時退多少;新台幣在對帳單上是整數元,我們內部卻以分計。這些都是「怎麼處理金額」的問題。下一篇〈Go 處理金額:整數分、decimal、幣別、四捨五入與分攤〉從 float64 為什麼不行講起,建立帶幣別的金額型別,並把捨入與分攤做到一分錢都不差。