~/教學/STRIPE.md

文章 / 做 App

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 站

Reels 畫面:筆電上是 Stripe 官方 Checkout 示範頁的卡號欄和 Pay 按鈕,桌上一顆 $20 方塊,標題下四個空的 ①②③④ 站牌
Reels 畫面:開頭就是 Stripe 自己的 Checkout 示範頁,四個站牌等著一站一站填滿。

先說結果。看完這篇你會知道一筆付款在 Stripe 裡的 4 站各做了什麼:

  1. 第 1 站 卡號:輸入框是 Stripe 的元件(Elements 或 Checkout),卡號直接進 Stripe,你的伺服器只拿到 token。
  2. 第 2 站 Radar:每筆付款先即時評分,高風險的預設直接擋下,連銀行都不會問(outcome 裡寫 not_sent_to_network)。
  3. 第 3 站 webhook:收到錢,Stripe 用簽過章的事件(Stripe-Signature 標頭)通知你的網站;你的伺服器掛了,正式環境會重試最多 3 天。
  4. 第 4 站 重送(最常漏):網路一斷、程式再送一次,只要帶同一把 Idempotency-Key,Stripe 回的是第一次的結果,不會扣兩次。

最後一段有一段貼給 Claude Code 的話,叫它補 3 樣:用 Stripe 的卡號元件、每筆扣款帶 idempotency key、驗 webhook 簽章並處理重複事件。Radar 不在清單裡,因為它預設就在跑,不用你寫。

Stripe 官方 Checkout 示範頁(checkout.stripe.dev):Card information 欄、MM/YY、CVC、Apple Pay、藍色 Pay 按鈕,下面寫 Powered by stripe
Stripe 官方的 Checkout 示範頁(2026-11-20 截圖,登出狀態)。這就是你想讓 Claude Code 做出來的東西;示範頁上什麼都沒輸入、沒送出。

02第 1 站:卡號直接進 Stripe,你的伺服器只拿到 token

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

Stripe 官方 Web Elements 文件:tokenizes sensitive payment details within an Element,資料不碰你的伺服器
Stripe 官方文件(2026-11-20 截圖):卡號在元件裡就被換成 token,不會碰到你的伺服器。
  1. 用 Stripe Checkout(Stripe 代管或嵌在你網站上的付款頁)或 Elements(自己排版的付款元件)收卡號。Elements 文件現在建議大多數整合用 Checkout Sessions API 搭 Payment Element。
  2. 問 Claude:「這個專案的卡號是哪個元件收的?有沒有任何一段程式讀得到完整卡號?」答案如果是自己的表單欄位,請它改成 Checkout 或 Elements。
  3. Stripe 回傳的卡別、末四碼、到期日可以存進你的資料庫;security guide 說這些不在 PCI 的範圍內。

03第 2 站:Radar 先評分,高風險不送銀行

卡號進了 Stripe,還沒去問銀行之前,先過 Radar。官方文件寫:Radar 的 AI 模型用風險分數即時評估每一筆付款,看的是這筆付款的幾百個風險因子,加上整個 Stripe 網路的資料。評出來分三級:normal、elevated、highest。

Stripe 官方 Radar 文件 High risk payments 段:outcome 寫 network_status not_sent_to_network、risk_level highest
Stripe 官方文件(2026-11-20 截圖):高風險付款預設被擋,outcome 裡的 network_status 是 not_sent_to_network,意思是根本沒送去卡組織。
  1. 高風險(highest):預設直接擋下。Charge 的 outcome 會是 type: blocked、network_status: not_sent_to_network,seller_message 寫 Stripe blocked this charge as too risky。
  2. 中風險(elevated):預設放行;方案支援的話可以進人工審核佇列。
  3. 正常(normal):照常送銀行授權。文件也提醒,正常風險的付款還是有可能事後被認定詐騙。
  4. 分數預設 65 以上算 elevated、75 以上算 high;分數本身只有 Plus、Pro 方案看得到,Standard 看得到等級。
  5. 擋錯了怎麼辦:在 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 金鑰驗證,確認事件不是第三方送來或改過的。

Stripe 官方 webhooks 文件:Stripe signs every webhook event,簽章在 Stripe-Signature 標頭,下面是取得 endpoint secret 的步驟
Stripe 官方文件(2026-11-20 截圖):每個事件都有簽章,用 endpoint 的 whsec_ 金鑰驗。
  1. 在 Dashboard 的 Workbench → Webhooks 建 endpoint,把 whsec_ 金鑰放進環境變數。本機測試跑 stripe listen --forward-to localhost:4242/webhook,它會印出一把測試用的金鑰。
  2. 驗簽章要用 request 的原始 body;框架如果先把 body 解析或改過,驗證會失敗。
  3. 先回 2xx,再做出貨、開通這些慢的事。回太慢會被當成逾時失敗。
  4. 同一個事件可能收到不只一次:把處理過的 event id 記下來,看過的就跳過。
  5. 事件順序也不保證,不要用 created 時間判斷有沒有處理過,用 event id。
Reels 畫面:房間燈暗下來,牆上螢幕是 webhooks 文件的 Automatic retries 段,紙條寫「你的伺服器掛了」和「重試 3 天」
Reels 畫面:你的伺服器掛了,Stripe 在正式環境會重試最多三天(文件原句:for up to three days with an exponential back off in live mode)。

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

Reels 畫面:上面是 idempotent_requests 文件的紙瀏覽器,下面兩張請求卡 POST /v1/payment_intents 帶同一把 Idempotency-Key,第二張標「重送」
Reels 畫面(示意圖):同一筆付款送了兩次,兩張請求卡帶同一把 key。key 值 7f3a-20usd 是畫的。

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

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

06貼給 Claude Code:補上這 3 個檢查

Reels 畫面:紙牌「貼給 Claude 的清單」下面三張卡:① 用 Stripe 的卡號元件 ② 每筆扣款帶 idempotency key ③ 驗 webhook 簽章
Reels 畫面:叫 Claude 補的三樣。

把下面這段整段貼進 Claude Code。它會先檢查專案現在的寫法,再補缺的,最後給你 diff。

貼給 Claude Code(把[]換成你的情況)
請檢查這個專案的 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 走一遍:

  1. 用測試卡 4242 4242 4242 4242,到期日任意未來日期(例如 12/34),CVC 任意 3 碼,付一次。
  2. 故意連按兩下付款、故意在送出後斷網再重送:Dashboard 裡應該只有一筆付款。
  3. 讓 webhook 先回 500 再回 200,看訂單有沒有被標兩次;sandbox 會重試三次。
  4. 想看 Radar 擋人的樣子:測試卡 4100 0000 0000 0019 的 risk level 是 highest,Radar 一定會擋,回來的 error code 是 fraud。

07要注意

  1. SDK 的重試和你自己的重送是兩回事。Stripe 官方 SDK 自動重試時會自己帶 key(次數看 SDK 和版本,例如 max_network_retries);但客人連按兩下、前端逾時後再送、排程跑兩次,是跨越不同次呼叫的重送,SDK 管不到,要你的程式產生、保存、每次都帶同一把 key。
  2. key 不是永久的。API v1 的 key 保留至少 24 小時,之後可能被清掉,清掉後同一把 key 會變成新的請求。超過 24 小時還不知道結果,不要用舊 key 也不要用新 key 再送,先查那筆付款。API v2 的規則不同(重播行為不一樣、保留 30 天),用 v2 看它自己的說明。
  3. webhook 事件會重複。同一個事件可能送兩次;Stripe 也可能為同一件事產生兩個不同的 Event 物件,這種要用 data.object 的 id 加 event.type 來認。處理訂單的函式要能跑很多次都不出錯。
  4. Radar 從 Standard 起每筆被檢查的交易都收費(Lite 沒有這條)。方案也決定你看得到什麼:Standard 有風險等級,分數和自訂規則要 Plus 以上。費率以 Radar 定價頁和你的 Dashboard 為準。
  5. 測試環境和正式環境的重試不一樣:正式環境最多重試三天、指數退避;sandbox 只重試三次、幾小時內。同一個 endpoint 的測試和正式 whsec_ 也是兩把。
  6. 驗簽章時官方函式庫預設容許簽章時間和現在差 5 分鐘,不要把容許值設成 0(那等於關掉時間檢查);伺服器時間要對準 NTP。Stripe 每次重送都會重新簽,時間戳也是新的。
  7. 我沒有為這支影片跑真的結帳,沒有扣到任何人的錢。影片裡的 $20 方塊、兩張請求卡是示意;有網址列的文件畫面和 Checkout 示範頁才是 Stripe 官方頁面的截圖。
  8. 不要把正式環境的 secret key 貼進對話或寫進程式碼,放環境變數;官方建議用只開必要權限的 restricted key。

資料來源

延伸閱讀