---
title: Stripe
description: 將 Stripe 連線至 NexCMP 以支援卡片付款、Apple Pay、Google Pay、Link 與 Alipay — 包含 API 金鑰、Webhook、網域註冊與測試付款。
url: https://nexcmp.com/zh-tw/docs/billing/stripe/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# Stripe

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

## 功能 {#what-it-does}

Stripe透過卡片付款來進行錢包加值。使用同一個帳號，您也可以提供**Apple Pay**、**Google Pay**、**Link**和**Alipay**，並讓客戶**儲存卡片**以便進行[自動加值](https://nexcmp.com/zh-tw/docs/billing/auto-top-up/)。將其作為國際客戶的主要管道。

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| 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會為您處理此事。 |
| 相依項目 | 無。 |

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

## 準備基礎設施 {#prepare-the-infrastructure}

在Stripe端：

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

## 在 NexCMP 中連線 {#connect-in-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](https://nexcmp.com/zh-tw/docs/billing/payment-channels/#switches-and-fees-fees-limits)。

![填入範例數值的Stripe頁面，包含模式、密鑰與發布金鑰](https://nexcmp.com/zh-tw/docs/images/billing/stripe-01-keys.webp)


### Webhook {#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 {#apple-pay-google-pay-and-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、Google Pay 和 Link 狀態的錢包卡片](https://nexcmp.com/zh-tw/docs/images/billing/stripe-03-wallets.webp)

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

### Alipay {#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天未更新時，頁面會顯示警告。

## 驗證 {#verify}

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是分開的）。

## 限制與注意事項 {#limits-notes}

- **金額與貨幣。** 電子錢包以USD計價。信用卡、錢包與Link付款以USD扣款；支付寶以JPY向客戶展示，並依您的匯率進行換算。
- **手續費。** Stripe的實際手續費不會自動回讀；您設定的手續費百分比決定了客戶看到的金額以及錢包入帳的金額。在*Fees & limits*中選擇**Customer pays top-up fee**以額外向客戶收取手續費。
- **已儲存的信用卡。** 當客戶勾選*Save card for auto top-up*時，信用卡會儲存在Stripe，而非您的伺服器上。請參閱[Saved payment methods](https://nexcmp.com/zh-tw/docs/billing/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](https://nexcmp.com/zh-tw/docs/customers/resellers/)。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| 「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** 中開啟並儲存金鑰。 |