~/教學/STRIPE.md
Claude Code 接 Stripe 前:跟著一筆 20 美元走 Stripe 的 4 站,再叫它補上 vibe coding 結帳常漏的 3 個檢查
卡號只進 Stripe、Radar 先評分、簽章 webhook 說收到錢、斷線重送帶同一把 idempotency key 只扣一次。每一站都對照 2026-11-20 的 Stripe 官方文件,附一段貼給 Claude Code 的話。
叫 Claude Code 把 Stripe 接進你的 App,幾分鐘就有一個能刷的結帳頁。但一筆付款送出去之後,在 Stripe 裡到底發生了什麼,很多 vibe coding 出來的結帳沒有想過,所以該有的檢查也沒補。這篇是 Reels 裡 STRIPE 那支的完整版:我跟著一筆 20 美元的付款,走過它在 Stripe 裡會經過的 4 站(卡號、Radar、webhook、重送),每一站講它在做什麼、官方文件怎麼寫,最後給你一段可以整段貼給 Claude Code 的話,叫它補上 3 個檢查。所有內容都在 2026-11-20 對照 docs.stripe.com 逐頁確認過;影片和這篇都沒有真的扣任何人的錢。
01你會得到什麼:一筆 20 美元在 Stripe 裡走的 4 站

先說結果。看完這篇你會知道一筆付款在 Stripe 裡的 4 站各做了什麼:
- 第 1 站 卡號:輸入框是 Stripe 的元件(Elements 或 Checkout),卡號直接進 Stripe,你的伺服器只拿到 token。
- 第 2 站 Radar:每筆付款先即時評分,高風險的預設直接擋下,連銀行都不會問(outcome 裡寫 not_sent_to_network)。
- 第 3 站 webhook:收到錢,Stripe 用簽過章的事件(Stripe-Signature 標頭)通知你的網站;你的伺服器掛了,正式環境會重試最多 3 天。
- 第 4 站 重送(最常漏):網路一斷、程式再送一次,只要帶同一把 Idempotency-Key,Stripe 回的是第一次的結果,不會扣兩次。
最後一段有一段貼給 Claude Code 的話,叫它補 3 樣:用 Stripe 的卡號元件、每筆扣款帶 idempotency key、驗 webhook 簽章並處理重複事件。Radar 不在清單裡,因為它預設就在跑,不用你寫。

02第 1 站:卡號直接進 Stripe,你的伺服器只拿到 token
客人在卡號欄打字的時候,那個欄位不是你的 HTML input,是 Stripe 的元件。官方 Elements 文件的第一段就寫:Stripe.js 在元件裡把敏感的付款資料換成 token,資料從頭到尾不碰你的伺服器。你的後端拿到的是一個代表這張卡的 token 或 PaymentMethod id,拿它去建立付款。

- 用 Stripe Checkout(Stripe 代管或嵌在你網站上的付款頁)或 Elements(自己排版的付款元件)收卡號。Elements 文件現在建議大多數整合用 Checkout Sessions API 搭 Payment Element。
- 問 Claude:「這個專案的卡號是哪個元件收的?有沒有任何一段程式讀得到完整卡號?」答案如果是自己的表單欄位,請它改成 Checkout 或 Elements。
- Stripe 回傳的卡別、末四碼、到期日可以存進你的資料庫;security guide 說這些不在 PCI 的範圍內。
03第 2 站:Radar 先評分,高風險不送銀行
卡號進了 Stripe,還沒去問銀行之前,先過 Radar。官方文件寫:Radar 的 AI 模型用風險分數即時評估每一筆付款,看的是這筆付款的幾百個風險因子,加上整個 Stripe 網路的資料。評出來分三級:normal、elevated、highest。

- 高風險(highest):預設直接擋下。Charge 的 outcome 會是 type: blocked、network_status: not_sent_to_network,seller_message 寫 Stripe blocked this charge as too risky。
- 中風險(elevated):預設放行;方案支援的話可以進人工審核佇列。
- 正常(normal):照常送銀行授權。文件也提醒,正常風險的付款還是有可能事後被認定詐騙。
- 分數預設 65 以上算 elevated、75 以上算 high;分數本身只有 Plus、Pro 方案看得到,Standard 看得到等級。
- 擋錯了怎麼辦:在 Dashboard 打開那筆付款,按 Add to allow list。這不會重試那筆付款,但之後同一個付款方式或 email 不會再被擋。
04第 3 站:簽章 webhook 說收到錢,伺服器掛了也重試 3 天
銀行說 OK、錢扣了,Stripe 要通知你的網站。方法是 webhook:Stripe 對你註冊的 HTTPS 網址 POST 一個事件(例如 payment_intent.succeeded 或 checkout.session.completed)。官方文件寫:Stripe 簽每一個 webhook 事件,簽章放在 Stripe-Signature 標頭;用官方函式庫搭配 whsec_ 開頭的 endpoint 金鑰驗證,確認事件不是第三方送來或改過的。

- 在 Dashboard 的 Workbench → Webhooks 建 endpoint,把 whsec_ 金鑰放進環境變數。本機測試跑 stripe listen --forward-to localhost:4242/webhook,它會印出一把測試用的金鑰。
- 驗簽章要用 request 的原始 body;框架如果先把 body 解析或改過,驗證會失敗。
- 先回 2xx,再做出貨、開通這些慢的事。回太慢會被當成逾時失敗。
- 同一個事件可能收到不只一次:把處理過的 event id 記下來,看過的就跳過。
- 事件順序也不保證,不要用 created 時間判斷有沒有處理過,用 event id。

05第 4 站(最常漏):斷線重送,同一把 idempotency key,只扣一次

前三站都是 Stripe 幫你做好的,這一站要你的程式配合。情況是:你的伺服器送出「建立付款」的請求,還沒收到回應就斷線。這時你分不出 Stripe 是沒收到,還是收到了、也扣了、只是回應沒傳回來。程式如果直接再送一次,Stripe 會當成新的一筆。官方文件的解法是 idempotency key:在請求的 Idempotency-Key 標頭帶一組唯一的字串,Stripe 會存下第一次的狀態碼和回應內容,之後同一把 key 再進來,回的是存下來的那份,不會再做一次。

- 每個會扣款的 POST(建立 / 確認 PaymentIntent、建立 Checkout Session)都帶 Idempotency-Key 標頭。API v1 的所有 POST 都接受;GET 和 DELETE 本來就冪等,不用帶。
- 一筆付款一把 key:官方建議 UUID v4,或用訂單、購物車 id 推出來;最長 255 字元,不要放 email 之類的個資。
- 把 key 跟訂單存在一起。斷線重送時用同一把、參數一模一樣,Stripe 回第一次存下來的結果(連 500 都照存),回應會帶 Idempotent-Replayed: true。
- 同一把 key 配不同參數會回錯誤;收到 409 代表同一把 key 的請求還在跑,等一下再用同一把、同樣參數試,不要換新的。
- key 滿 24 小時後可能被清掉,再送會變成新的請求。超過這段時間還不知道結果,就不要再送,先到 Dashboard、API 或 webhook 事件查那筆付款。
06貼給 Claude Code:補上這 3 個檢查

把下面這段整段貼進 Claude Code。它會先檢查專案現在的寫法,再補缺的,最後給你 diff。
請檢查這個專案的 Stripe 結帳,依 Stripe 官方文件補上這 3 個檢查,改完給我 diff,並說明每一項是在哪個檔案做的: 1. 卡號元件:卡號只能由 Stripe Checkout 或 Elements 收,直接送到 Stripe;我的伺服器只能拿到 token / PaymentMethod id。找出任何會讀到完整卡號的程式碼,改掉。 2. Idempotency-Key:每一個會建立或確認扣款的 Stripe POST 請求([例如建立 / 確認 PaymentIntent、建立 Checkout Session])都要帶 Idempotency-Key。一筆[訂單 / 購物車]只產生一把(UUID v4,或由訂單 id 推出來,不放個資),跟訂單存在一起;前端逾時重送或背景工作重跑時都用同一把、參數不變。超過 24 小時還不知道結果就先查那筆付款,不要再送。 3. Webhook:用 Stripe 官方函式庫,拿 request 的原始 body、Stripe-Signature 標頭和環境變數裡的 whsec_ 金鑰驗證簽章,驗不過回 400。先回 200 再處理訂單;記下處理過的 event id,同一事件收到第二次就跳過。訂單只能由驗過簽章的事件標成已付款,不能只靠成功頁。 不要動 Radar 的設定(它預設就開著)。最後告訴我怎麼在 sandbox 用測試卡 4242 4242 4242 4242 和 stripe listen、stripe trigger 走一遍,包括故意連按兩下付款,和故意讓 webhook 先回 500。
Claude 改完之後,自己在 sandbox 走一遍:
- 用測試卡 4242 4242 4242 4242,到期日任意未來日期(例如 12/34),CVC 任意 3 碼,付一次。
- 故意連按兩下付款、故意在送出後斷網再重送:Dashboard 裡應該只有一筆付款。
- 讓 webhook 先回 500 再回 200,看訂單有沒有被標兩次;sandbox 會重試三次。
- 想看 Radar 擋人的樣子:測試卡 4100 0000 0000 0019 的 risk level 是 highest,Radar 一定會擋,回來的 error code 是 fraud。
- 延伸:Claude 寫的 Stripe 結帳可能扣兩次款,上線前叫它補上這 4 樣 — 我 11 月的 LEDGER 那篇:整體檢查、補 key、加 webhook 三段分項指令
- Stripe API:Idempotent requests — Idempotency-Key、255 字元、24 小時
- Stripe:Receive Stripe events in your webhook endpoint — Stripe-Signature、重試三天、重複事件
- Stripe:Testing(測試卡) — 4242 4242 4242 4242、4100 0000 0000 0019
07要注意
- SDK 的重試和你自己的重送是兩回事。Stripe 官方 SDK 自動重試時會自己帶 key(次數看 SDK 和版本,例如 max_network_retries);但客人連按兩下、前端逾時後再送、排程跑兩次,是跨越不同次呼叫的重送,SDK 管不到,要你的程式產生、保存、每次都帶同一把 key。
- key 不是永久的。API v1 的 key 保留至少 24 小時,之後可能被清掉,清掉後同一把 key 會變成新的請求。超過 24 小時還不知道結果,不要用舊 key 也不要用新 key 再送,先查那筆付款。API v2 的規則不同(重播行為不一樣、保留 30 天),用 v2 看它自己的說明。
- webhook 事件會重複。同一個事件可能送兩次;Stripe 也可能為同一件事產生兩個不同的 Event 物件,這種要用 data.object 的 id 加 event.type 來認。處理訂單的函式要能跑很多次都不出錯。
- Radar 從 Standard 起每筆被檢查的交易都收費(Lite 沒有這條)。方案也決定你看得到什麼:Standard 有風險等級,分數和自訂規則要 Plus 以上。費率以 Radar 定價頁和你的 Dashboard 為準。
- 測試環境和正式環境的重試不一樣:正式環境最多重試三天、指數退避;sandbox 只重試三次、幾小時內。同一個 endpoint 的測試和正式 whsec_ 也是兩把。
- 驗簽章時官方函式庫預設容許簽章時間和現在差 5 分鐘,不要把容許值設成 0(那等於關掉時間檢查);伺服器時間要對準 NTP。Stripe 每次重送都會重新簽,時間戳也是新的。
- 我沒有為這支影片跑真的結帳,沒有扣到任何人的錢。影片裡的 $20 方塊、兩張請求卡是示意;有網址列的文件畫面和 Checkout 示範頁才是 Stripe 官方頁面的截圖。
- 不要把正式環境的 secret key 貼進對話或寫進程式碼,放環境變數;官方建議用只開必要權限的 restricted key。
資料來源
- Stripe:Stripe Web Elements(tokenizes sensitive payment details within an Element)
- Stripe:Integration security guide(低風險整合、PCI、可存的卡片資料)
- Stripe:Transaction risk prevention(即時評分、風險等級、not_sent_to_network)
- Stripe:How Radar works(方案比較、每筆檢查收費)
- Stripe:Receive Stripe events in your webhook endpoint(Stripe-Signature、自動重試、重複事件)
- Stripe API:Idempotent requests
- Stripe:Advanced error handling(SDK 重試、persist a key for the operation、24 小時)
- Stripe:Testing(測試卡)
下一支 Reel 想學什麼?
我每天測 Claude 和 AI 工具,把真的有用的做成 Reel。追蹤 @vivianlin.tech,新教學一出來就看得到。