---
title: Stripe
description: 将Stripe接入NexCMP以支持银行卡、Apple Pay、Google Pay、Link及Alipay——涵盖API密钥、Webhook、域名注册与测试支付。
url: https://nexcmp.com/zh-cn/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**，并允许客户**保存卡片**以进行[automatic top-up](https://nexcmp.com/zh-cn/docs/billing/auto-top-up/)。建议将其作为国际客户的主要支付渠道。

## 前提条件 {#requirements}

| 项目 | 要求 |
|---|---|
| Stripe账户 | 一个能够接收**USD**付款的Stripe账户。Alipay以JPY结算，且必须由Stripe为你的账户开通。 |
| 密钥 | 一个Secret key（`sk_live_...`或`sk_test_...`）和一个Publishable key（`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**。请务必保管好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-cn/docs/billing/payment-channels/#switches-and-fees-fees-limits)。

![填有示例模式、Secret key和Publishable key的Stripe页面](https://nexcmp.com/zh-cn/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-cn/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 可用，然后开启**Alipay (Stripe, JPY display)**（位于**Fees & limits**）。设置**Alipay fee %**、**Alipay fixed fee**、**¥/USD rate**（50–500）以及 **FX spread %**（0–20）。请定期更新 ¥/USD rate；当该汇率超过 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 结算；Alipay 以 JPY 向客户展示，并按您的汇率进行换算。
- **手续费。** Stripe 的实际手续费不会被自动读取；您设置的手续费百分比决定了客户看到的价格以及钱包实际入账的金额。在 *Fees & limits* 中选择 **Customer pays top-up fee** 可将手续费叠加收取。
- **保存的卡片。** 当客户勾选 *Save card for auto top-up* 时，卡片会存储在 Stripe，而不是您的服务器上。请参阅 [Saved payment methods](https://nexcmp.com/zh-cn/docs/billing/saved-payment-methods/)。
- **退款。**原路退款至银行卡是一个分步过程：管理员为已完成的付款创建退款申请（**Finance › Billing › Top-ups**，在付款项上执行退款操作），然后在**Finance › Payouts › Card refunds**（`/billing/payouts`）下进行批准。支付宝退款是异步的；失败的退款（`refund.failed`）会将冻结金额退回钱包。
- **争议。** 在 `charge.dispute.created` 发生争议时，NexCMP 会锁定客户账户，停止其预付费服务（不会删除任何内容）并向管理员发送警报。如果您胜诉（`charge.dispute.closed`），相应金额将退回到钱包中。
- **待处理支付。** 如果 webhook 一直未到达，NexCMP 会自行将保持 pending 状态超过 10 分钟的支付与 Stripe 进行核对并完成支付。超过 7 天的支付将被忽略。
- **Resellers** 可以连接他们自己的 Stripe 账户（webhook `https://<their-domain>/v1/billing/stripe/webhook/r/<id>`）；请参阅 [Resellers](https://nexcmp.com/zh-cn/docs/customers/resellers/)。

## 故障排查 {#troubleshooting}

| 症状 | 原因 | 解决办法 |
|---|---|---|
| "密钥必须以 sk_live_/sk_test_ 开头" | 粘贴了错误的密钥 | 从 **Developers › API keys** 复制并粘贴 Secret key。 |
| “秘密密钥与Live/Test模式不匹配” | 模式与密钥不符 | 使 **Mode** 与密钥的前缀相匹配。 |
| “可发布密钥必须以pk_开头” | 密钥错误 | 使用公钥。 |
| 检查提示连接失败 | 密钥错误、密钥已被撤销，或者服务器无法访问 `api.stripe.com` | 重新粘贴密钥；使用服务器上的 `curl -I https://api.stripe.com` 进行测试。 |
| 红色横幅显示 "Missing webhook_secret" | 未保存签名密钥 | 点击 **Create webhook** 或从 Stripe 管理后台粘贴 `whsec_...` 密钥并点击 **Save**。 |
| 已扣款但余额未变 | Webhook 未送达或签名验证失败 | 检查 URL 是否以 `/v1/billing/stripe/webhook` 结尾、密钥是否与端点匹配，并在 **Gateway events** 中重新发送事件。在 Stripe 中打开端点并查看投递尝试（HTTP 400 表示签名密钥错误）。 |
| "Create webhook" 失败 | URL 不是 HTTPS 或无法访问 | 使用您的公开 `https://` 域名。 |
| Apple Pay 状态未激活 | 域名未验证 | 在域名关联文件返回 200 后，再次点击 **Register / verify domain**。 |
| 检查对话框中不可用支付宝 | 未在 Stripe 中激活 | 在 Stripe 管理后台中激活它，然后点击 **Check**。 |
| 客户看不到卡片表单 | **Card (Stripe)** 已关闭或缺少密钥 | 在 **Fees & limits** 中将其开启并保存密钥。 |