為什麼測試地址過不了 AVS 和 ZIP+城市+州 驗證

發佈於 2026-06-26 · 閱讀約 9 分鐘

你為 QA 夾具產生了一個看起來很乾淨的美國地址 — 街道名合理、城市真實、郵遞區號 開頭數字也對得上、電話區碼也匹配。你把它貼到 staging 的結帳頁，結果表單拒絕它： 「您輸入的郵遞區號與城市/州不匹配。」更糟的是支付閘道回傳了 AVS_MISMATCH ，扣款失敗。

這兩種失敗其實都在正常工作。本文解釋背後的兩套系統 — USPS 驅動的「郵遞區號·城市· 州」驗證，與「地址驗證系統」(AVS) — 讓你能圍繞它們的規則設計測試資料，而不是和 它們對著幹。

兩層驗證，先簡短概覽

美國寄送表單通常會讓地址通過兩層獨立驗證：

  1. USPS 可投遞性驗證。確認城市、州、郵遞區號指向同一個 USPS 認可的郵 區，可選地確認街道號和街道名出現在真實的 USPS 投遞路線上。這就是「郵遞區號與城市 /州不匹配」這條錯誤的來源。
  2. AVS — Address Verification System。卡組織（Visa、Mastercard、 Amex、Discover）的驗證：把帳單街道地址的數字部分和帳單郵遞區號與持卡人開戶行的 記錄做比對。這就是支付閘道回應裡 AVS_MISMATCH、 AVS_ZIP_ONLY_MATCH 等碼的來源。

注意這是兩套針對不同資料來源的不同驗證。一個合成地址可以通過第 1 層，但仍然 過不了第 2 層，因為銀行從來沒記錄過持卡人住在那裡。

USPS 郵遞區號比對怎麼運作

USPS 維護著一個資料庫，每個郵遞區號都關聯一個或多個「首選」城市名以及一個州。比如 裸郵遞區號 19801 唯一歸屬於德拉瓦州 Wilmington。如果你把 19801 配上 Dover, DE，驗證就會失敗，因為 Dover 的郵遞區號是 19901 和 19904 — 那是另一個郵區。

USPS 資料庫處理的幾個邊界情況，自己寫比對的常常踩坑：

對測試夾具的現實結論是：城市、州、郵遞區號要從同一個州的記錄中取樣。 美國免稅州地址產生器就是這麼做的 — 如果它挑了德拉瓦， 城市就是德拉瓦的城市，郵遞區號也是那個城市真實的郵遞區號。第 1 層永遠過。

AVS 怎麼運作

AVS 工作在支付網路層。商戶向卡組織發起授權時，帳單地址裡的兩段會被發卡行與自己記錄 比對：

回應是一個字母碼，隨授權回傳。常見值：

碼含義
Y街道和郵遞區號都匹配。
A街道匹配，郵遞區號不匹配。
Z5 位郵遞區號匹配，街道不匹配。
N都不匹配。
U發卡行未回應 / 資訊不可得。
G非美國發卡行，不支援 AVS。

Stripe、Adyen、Braintree、Authorize.Net 等支付閘道都會暴露這個碼，由商戶決定每個值 如何處理 — N 自動拒、A 或 Z 軟拒，依此 類推。

因為 AVS 比對的是銀行裡真實持卡人的記錄，任何合成地址都不可能通過真實的 AVS 驗證。隨機產生的街道和郵遞區號只可能在恰好真有持卡人住那的情況下匹配 — 而這恰恰是 AVS 要識別的情況。

針對每種環境設計能用的測試夾具

一個實戰指南：在不和驗證對著幹的情況下使用合成地址。

1. 單元測試和 UI 演示用「州一致」產生器

表單驗證、版面測試、截圖夾具、種子資料這些場景，你要的是看起來一致的地址，並不需要 通過任何外部 API。本站這樣的小型產生器提供的地址，城市、州、郵遞區號永遠內部匹配。

2. 在支付沙盒裡用官方測試卡 + AVS 測試郵遞區號

Stripe、Braintree、Adyen 都發佈了測試卡與「魔法地址」，在沙盒環境下能穩定 觸發指定的 AVS 回應。比如 Stripe 測試模式下，帳單郵遞區號 42424 一定 回傳 N（不匹配），其他任何 5 位郵遞區號都回傳 Y。AVS 相關 情境用這些有文件的魔法值，而不是泛用合成地址。 

// Stripe 測試模式 —— 確定性 AVS 結果
const billing = {
  line1:      '1 Test Lane',
  postal_code: '42424',  // 強制回傳 AVS code N
};
const intent = await stripe.paymentIntents.create({ ... });

3. 單元測試裡 mock 掉地址驗證呼叫

如果程式碼會呼叫 USPS Address Information API、Smarty（前 SmartyStreets）、Lob、 Google Address Validation 之類，單元測試裡把這些 client stub 掉。合成地址不需要真的 通過 — 它們只是用來跑通你的程式碼路徑。要驗證的是你處理每種文件化回應（包括 partial-match 和 not-found）的程式碼是否正確。

4. 生產端到端測試用真實銀行地址

如果一定要在生產環境用真卡跑端到端測試，請用持卡人真實的帳單地址。繞不過銀行的記 錄。生產環境用合成地址做測試是出名的踩雷點 — 商戶帳戶可能被風控標記。

結帳還提示「郵遞區號不匹配」時怎麼排查

如果你的地址來自免稅州地址產生器但結帳仍報「不匹配」， 十有八九是下面三種之一：

小結

兩層驗證、兩套資料來源、兩種失敗模式。USPS 郵遞區號-城市-州 驗證關心內部一致性 — 一個州一致的合成地址就能滿足。AVS 關心匹配銀行裡真實持卡人的真實 記錄 — 任何合成地址都過不了。按照這兩個原則去設計測試夾具，一大批莫名其 妙的測試失敗工單就不會再出現了。

資料來源與延伸閱讀

本文引用的 AVS 回應碼、USPS 資料庫欄位、支付閘道文件來自以下官方資料。AVS 碼語義因 閘道而異，請以你實際接的閘道為準：

相關閱讀