~/教學/LEDGER.md

文章 / 做 App

Claude 寫的 Stripe 結帳可能扣兩次款:上線前叫它補上這 4 樣(idempotency key、Radar、webhook)

程式重送付款請求又沒帶 idempotency key,客人就可能被扣兩次。這篇整理 Stripe 結帳該有的 4 樣東西,每一樣都對照官方文件,附上可以直接貼給 Claude Code 的指令。

Claude Code 幾分鐘就能把 Stripe 結帳接好,平常測也都正常。會出事的是網路不穩的那一刻:付款請求送出去,還沒收到回應就斷線,程式不知道到底扣了沒,就把同一筆再送一次,Stripe 收到兩筆。這篇是 Reels 裡 LEDGER 那支的完整版:我把一筆 20 美元的付款會經過的四個關卡整理出來,每一關講它在做什麼、Stripe 官方文件怎麼寫,還有可以直接貼給 Claude Code 的指令,讓它幫你檢查並補上。

01先看結果:同一筆訂單,重送也只扣一次

刷卡通知示意:同一筆訂單 #1042 的第二筆扣款被劃掉,合計回到 −$20.00,蓋上「只扣 1 次」
示意畫面:同一筆訂單不該出現第二筆扣款。下面四樣補上,重送也只扣一次。

看完這篇你會拿到:Stripe 結帳上線前該檢查的 4 樣東西、每一樣的白話解釋和官方文件出處,以及 3 段可以直接貼給 Claude Code 的指令(一段整體檢查、一段補 idempotency key、一段加 webhook)。真正擋住「扣兩次」的是第 2 樣。

  1. 卡號直接給 Stripe,不經過你的伺服器。
  2. 每一筆會扣款的請求都帶一把 idempotency key,重送時用同一把。
  3. 讓 Radar 檢查付款有沒有詐騙。
  4. 用簽章過的 webhook 確認收款,不要只靠成功頁。
網路紀錄示意:POST /v1/payment_intents 沒有回應,重送時沒帶 key,Stripe 收到 2 筆付款
示意:程式自己重送、又沒帶 key,Stripe 只能把它當成新的一筆。

為什麼會扣兩次?不是 Stripe 的錯,也不是銀行的錯。請求逾時的時候,你的程式分不出來 Stripe 是「沒收到」還是「收到了、也扣了,只是回應沒傳回來」。如果它直接把同一筆付款請求再送一次,Stripe 沒辦法知道這是重送,就會當成一筆新的付款。

02第 1 樣:卡號直接給 Stripe,不經過你的伺服器

先整個檢查一遍(一句話版本)
請檢查這個專案的 Stripe 結帳有沒有做到這 4 件事,缺的幫我補上,並告訴我你改了哪些檔案:
1. 卡號只由 Stripe 的 Checkout 或 Elements 收,不經過我的伺服器。
2. 每個會建立或確認扣款的請求都帶 Idempotency-Key,重送時用同一把。
3. 付款有經過 Radar 檢查。
4. 用驗證過簽章的 webhook 確認收款,不是只靠成功頁。
Stripe 官方 security guide,標出 directly to Stripe without it passing through your servers
官方文件:付款資料直接送到 Stripe,不經過你的伺服器。

用 Stripe Checkout 或 Elements 來收卡號。官方的 Checkout 文件列了三種介面:Full page(Stripe 代管的付款頁,或嵌在你的網站裡)、Embedded form(嵌在你網站上的表單)和 Elements(自己排版的付款元件)。三種都是由 Stripe 的欄位收卡號,直接送到 Stripe。Stripe 的 security guide 寫得很直接:用這類低風險的整合,付款資料會直接送到 Stripe、不經過你的伺服器,你要負擔的 PCI 合規義務也會比較少。

  1. 問 Claude:「這個專案的卡號是從哪個元件收的?有沒有任何一段程式會讀到完整卡號?」
  2. 如果答案不是 Checkout 或 Elements,請它改成其中一種。
  3. Stripe 回傳的卡別、末四碼和到期日可以存在你的資料庫,官方說這些不在 PCI 的範圍內。

03第 2 樣:每筆付款帶一把 idempotency key

Stripe 官方 Idempotent requests 文件,標出 Retries with the same key return the saved response
官方文件:同一把 key 的重送,拿回的是第一次存下來的結果。

idempotency key 是你在 POST 請求的 Idempotency-Key 標頭裡附上的一組唯一的識別碼。Stripe 會把「第一次用這把 key 的請求」的結果存起來;之後同一把 key 再進來,它回的是存下來的那個結果,而不是再做一次。所以斷線後的重送,拿到的是第一筆付款,不會變成第二筆扣款。被重播的回應會帶一個標頭 Idempotent-Replayed: true,可以用它確認。

  1. 一筆付款產生一把 key:官方建議用 UUID v4,或用訂單、購物車編號推出來。key 最長 255 個字元,不要放 email 之類的個資。
  2. 所有會建立或確認扣款的請求都帶上(建立 / 確認 PaymentIntent、建立 Checkout Session)。
  3. 把 key 跟訂單存在一起,每次重送都用同一把、參數也要一樣。同一把 key 配上不同參數,Stripe 會回錯誤。
  4. key 滿 24 小時後可能被清掉,所以帶 key 的重送只在這段時間內做。超過還不知道結果,就不要再送,先去查那筆付款(Dashboard、API 或 webhook 事件)。
  5. 如果收到 409,代表同一把 key 的另一個請求還在執行:等一下,用同一把 key、同樣的參數再試,不要換新的 key。
貼給 Claude Code:補上 idempotency key(把[]換成你的情況)
請檢查這個專案裡的 Stripe 付款程式,找出可能重複扣款的地方:
1. 列出所有會建立或確認扣款的請求([例如:建立 / 確認 PaymentIntent、建立 Checkout Session])。
2. 每一個都要帶 Idempotency-Key:一筆[訂單 / 購物車]只產生一次(UUID v4,或用訂單編號推出來,不要放個資),跟訂單存在一起,每次重送都用同一把、參數不變。
3. 付款按鈕按下後先停用;前端逾時重送時用同一把 key,不要產生新的。
4. 給我看 diff,並說明還有哪裡的重送可能變成第二筆扣款。

04第 3 樣:讓 Radar 檢查詐騙

Stripe 官方 How Radar works 文件,標出 Radar screens all payment attempt types
官方文件:Radar 會檢查所有類型的付款嘗試。

Radar 是 Stripe 的防詐騙功能。官方文件說,Radar 會檢查所有類型的付款嘗試(成功、被拒、被擋下、標記待審核的都算),涵蓋它支援的付款方式。方案有 Lite、Standard、Plus、Pro 四種:越高的方案多了自訂規則、風險分數、人工審核等功能。

05第 4 樣:用簽章 webhook 確認收款,不靠成功頁

Stripe 官方 Fulfill orders 文件,標出 it's not guaranteed customers visit that page
官方文件:不能只靠成功頁,因為客人不一定會看到那一頁。

不要因為客人「到了成功頁」就把訂單標成已付款。Stripe 的 fulfillment 文件講得很白:不能只靠結帳後的到達頁來出貨,因為不保證客人會看到那一頁,他可能付款成功,卻在頁面載入前斷線。正確的做法是讓 Stripe 直接通知你的伺服器:付款完成時會送出 checkout.session.completed 事件,而且每個事件都帶簽章,放在 Stripe-Signature 標頭裡。

  1. 在 Stripe Dashboard 的 Workbench → Webhooks 建立 webhook endpoint;本機測試可以用 stripe listen --forward-to localhost:4242/webhook。
  2. 每個事件都用官方函式庫驗證簽章:要用 request 的原始 body、Stripe-Signature 標頭,和 whsec_ 開頭的簽章金鑰。框架如果改動了原始 body,驗證會失敗。
  3. 先快速回 2xx,再做出貨、開通這些比較久的事。正式環境送失敗的事件,Stripe 會重試最多三天。
  4. 處理訂單的函式要能重複執行也不出錯:同一個事件可能送來不只一次,把處理過的事件 ID 記下來。
  5. 成功頁也可以順便觸發同一個處理函式(官方建議兩邊都做,因為 webhook 有時會慢一點),但不能只靠它。
貼給 Claude Code:加上驗證簽章的 webhook
請幫這個專案加上 Stripe webhook:
1. 監聽 checkout.session.completed(如果有收延遲入帳的付款方式,再加 checkout.session.async_payment_succeeded)。
2. 用 Stripe 官方函式庫,拿 request 的原始 body、Stripe-Signature 標頭和環境變數裡的 whsec_ 金鑰驗證簽章。
3. 先快速回 200,再處理訂單;處理訂單的函式要能被同一個 session 呼叫很多次也不出錯(記下已處理的事件 ID)。
4. 不要只靠成功頁把訂單標成已付款。
5. 告訴我怎麼用 stripe listen 和 stripe trigger 在本機測試。

06要注意

  1. 這篇的內容都來自 Stripe 官方文件,我在 2026 年 11 月 9 日逐頁核對過,講的是 API v1 的行為。API v2 的 idempotency 規則不一樣(官方說重播行為不同、保留 30 天),用 v2 的話請看它自己的說明。
  2. 我沒有為這支影片跑真的結帳,也沒有真的扣到任何人的錢。影片和文章裡的刷卡通知、網路紀錄、方塊都是示意畫面;有網址列的文件畫面才是 Stripe 官方文件的截圖。
  3. 「重送也只扣一次」的前提是:同一把 key、同樣的參數、在 key 還沒被清掉的時間內。超過 24 小時還不知道結果,先查清楚那筆付款,不要直接再扣一次。
  4. 上線前先在 Stripe 的 sandbox 用測試卡(4242 4242 4242 4242)走一遍,故意連按兩下付款、故意斷線,看訂單和扣款是不是都只有一筆。
  5. 不要把正式環境的 secret key 貼進對話或寫進程式碼,放在環境變數裡。

資料來源

延伸閱讀