Stripe

管理員後台位置： Finance › Payment channels › Stripe（/payments/stripe）。開關與手續費：Finance › Payment channels › Fees & limits（/payments/fees）。

功能

Stripe透過卡片付款來進行錢包加值。使用同一個帳號，您也可以提供Apple Pay、Google Pay、Link和Alipay，並讓客戶儲存卡片以便進行自動加值。將其作為國際客戶的主要管道。

需求

項目	需求
Stripe帳號	能夠以USD接受付款的Stripe帳號。Alipay以JPY計費，必須由Stripe為您的帳號啟用。
金鑰	密鑰（sk_live_...或sk_test_...）與發布金鑰（pk_live_...或pk_test_...）。表單僅接受帶有這些前綴的金鑰。
網路	您的控制台必須能夠從網際網路透過HTTPS存取（Stripe會呼叫Webhook），並且必須能夠透過連接埠443連線至api.stripe.com。
網域（僅限錢包）	客戶端網域必須提供/.well-known/apple-developer-merchantid-domain-association服務——NexCMP會為您處理此事。
相依項目	無。

共用Stripe帳號

NexCMP僅處理自身建立之付款的Webhook事件，因此您可以使用同時服務其他應用程式的Stripe帳號。

準備基礎設施

在Stripe端：

1. 登入Stripe Dashboard。切換Test mode的開關，以決定您是要進行測試執行還是正式上線。某一模式的金鑰在另一模式中永不適用。
2. 開啟Developers › API keys。複製Publishable key，並顯示並複製Secret key。請將密鑰保密。
3. （選用）開啟Settings › Payment methods並啟用Alipay（如果您想提供該選項）。
4. 您不需要手動建立Webhook——NexCMP可以為您建立（請參閱下方第5步）。如果您偏好手動建立，請在Developers › Webhooks中使用Webhook中列出的URL與事件建立端點。

在 NexCMP 中連線

1. 開啟Finance › Payment channels › Stripe（/payments/stripe）。
2. 在API keys卡片中選擇Mode（live或test），貼上Secret key與Publishable key。
3. 點擊Save。金鑰會寫入伺服器上的設定檔，只有NexCMP服務帳號可以讀取。它們永遠不會被傳回瀏覽器；之後頁面僅顯示最後4個字元。
4. 點擊Check。對話框會回報連線狀況、模式、可用與待處理餘額、帳號ID、是否啟用收費、是否存在Webhook以及Alipay是否可用。紅線代表該部分需要注意。
5. 在Webhook卡片中點擊Create webhook並確認。NexCMP會要求Stripe建立包含所有必要事件的端點，並自動填入Webhook signing secret（whsec_...）。欄位中預先填入的URL為https://<your-domain>/v1/billing/stripe/webhook，例如https://cloud.example.com/v1/billing/stripe/webhook。
6. 開啟Fees & limits（/payments/fees），保持Card (Stripe)開啟，將Stripe fee %與Stripe fixed fee (cents)設定為您的實際費率，然後點擊Save channels & fees。請參閱Payment channels。

Webhook

紅色橫幅「Missing webhook_secret」會一直顯示，直到儲存了簽章密鑰為止。沒有它，Stripe加值將不會被記錄，即使Stripe已經收了錢。

項目	值
URL	https://<your-domain>/v1/billing/stripe/webhook
事件	checkout.session.completed, payment_intent.succeeded, payment_intent.payment_failed, charge.refunded, charge.dispute.created, charge.dispute.closed, radar.early_fraud_warning.created, refund.updated, refund.failed
簽章	Stripe Stripe-Signature標頭、HMAC-SHA256、300秒容忍度。簽章錯誤的請求會獲得HTTP 400。
冪等性	每個事件ID只會儲存一次；重複傳遞絕不會重複計入點數。

如果您是從註冊較少事件的版本升級而來，請再次點擊Create webhook——舊的端點會被保留，因此之後請在Stripe Dashboard中手動刪除它。

Webhook卡片中的24h events與Latest event橫列會告訴您Stripe是否已連線至面板。個別事件列於Payment channels › Gateway events（/payments/events，Stripe分頁）中，每個事件皆可檢視（Payload）或重新播放（Replay）。

Apple Pay、Google Pay與Link

1. 在Wallets (Apple Pay · Google Pay · Link) & Alipay卡片中，Customer app Domain registered with Stripe欄位已預先填入您的網站主機名稱（例如cloud.example.com）。
2. 按一下Register / verify domain並確認。NexCMP會在Stripe的付款方式網域中註冊該網域，並要求Stripe進行驗證。
3. 結果會顯示Apple Pay、Google Pay與Link的狀態。Apple Pay僅會在狀態為active時顯示。
4. 在Fees & limits中保持Apple Pay · Google Pay · Link開啟。

Apple Pay保持未啟用狀態

Apple Pay需要網域關聯檔案在您的公開網域上回應HTTP 200。如果您在前方部署了Cloudflare或其他代理伺服器，請勿封鎖/.well-known/。

Alipay

支付寶（Alipay）為選填項目。請在Stripe Dashboard › Settings › Payment methods中啟用它，按一下Check並等待對話框顯示支付寶可用，然後在Alipay (Stripe, JPY display)中開啟Fees & limits。設定Alipay fee %、Alipay fixed fee、¥/USD rate（50–500）以及FX spread %（0–20）。請定期更新¥/USD匯率；當匯率超過7天未更新時，頁面會顯示警告。

驗證

1. 在測試模式下，以測試客戶身分登入入口網站，開啟Billing，按一下Deposit，選擇Card並使用Stripe測試卡4242 4242 4242 4242（任意未來日期、任意CVC）支付最低金額。
2. 餘額會在數秒內增加，且該筆付款會顯示於Finance › Billing › Top-ups中，狀態為Completed。
3. 前往Payment channels › Gateway events › Stripe：您應該會看到帶有處理時間的checkout.session.completed或payment_intent.succeeded。
4. 回到Stripe頁面，24h events大於0。

在正式上線之前，將Mode切換至live，貼上正式密鑰並再次按一下Create webhook（測試模式與正式模式的webhook是分開的）。

限制與注意事項

• 金額與貨幣。 電子錢包以USD計價。信用卡、錢包與Link付款以USD扣款；支付寶以JPY向客戶展示，並依您的匯率進行換算。
• 手續費。 Stripe的實際手續費不會自動回讀；您設定的手續費百分比決定了客戶看到的金額以及錢包入帳的金額。在Fees & limits中選擇Customer pays top-up fee以額外向客戶收取手續費。
• 已儲存的信用卡。 當客戶勾選Save card for auto top-up時，信用卡會儲存在Stripe，而非您的伺服器上。請參閱Saved payment methods。
• 退款。退款至信用卡為兩步驟流程：管理員先為已完成的付款建立退款申請（Finance › Billing › Top-ups，付款項目上的退款操作），接著在Finance › Payouts › Card refunds（/billing/payouts）底下核准。Alipay 退款為非同步處理；若退款失敗（refund.failed），暫扣金額將退回錢包。
• 爭議款。 當 charge.dispute.created NexCMP 會凍結客戶帳戶、暫停其預付服務（不刪除任何資料）並發送管理員警報。若您勝訴（charge.dispute.closed），金額將會退回至錢包。
• 等待付款。 若未收到 webhook，NexCMP 會自行針對在 Stripe 上保持待處理超過 10 分鐘的付款進行檢查並完成交易。超過 7 天的付款將被忽略。
• Resellers 可以連接他們自己的 Stripe 帳戶（webhook https://<their-domain>/v1/billing/stripe/webhook/r/<id>）；請參閱 Resellers。

故障排除

症狀	原因	修正方式
「Secret key必須以sk_live_/sk_test_開頭」	貼上了錯誤的金鑰	請從 Developers › API keys 貼上密鑰。
「密鑰與 live/test 模式不符」	模式與金鑰不符	使 Mode 與金鑰的前綴相符。
「Publishable key 必須以 pk_ 開頭」	金鑰錯誤	請使用可發布金鑰。
檢查顯示連線失敗	金鑰錯誤、金鑰遭撤銷，或伺服器無法連線至 api.stripe.com	重新貼上金鑰；使用伺服器上的 curl -I https://api.stripe.com 進行測試。
紅色橫幅「Missing webhook_secret」	未儲存簽章密鑰	點擊 Create webhook，或是從 Stripe Dashboard 貼上 whsec_... 密鑰並點擊 Save。
已扣款但餘額未變更	未送達 Webhook 或簽章驗證失敗	檢查網址是否以 /v1/billing/stripe/webhook 結尾、密鑰是否與端點相符，並在 Gateway events 中重新執行事件。在 Stripe 中，開啟端點並查看傳遞嘗試（HTTP 400 代表簽章密鑰錯誤）。
「Create webhook」失敗	網址不是 HTTPS 或無法連線	請使用您的公開 https:// 網域。
Apple Pay 狀態未啟用	網域未驗證	在網域關聯檔案回應 200 後，再次點擊 Register / verify domain。
檢查對話框中無法使用 Alipay	尚未在 Stripe 中啟用	請在 Stripe Dashboard 中啟用它，然後點擊 Check。
客戶未看到卡片表單	Card (Stripe) 已關閉或沒有密鑰	請在 Fees & limits 中開啟並儲存金鑰。