Stripe

**管理后台位置：**Finance › Payment channels › Stripe（/payments/stripe）。开关与手续费：Finance › Payment channels › Fees & limits（/payments/fees）。

功能说明

Stripe支持通过银行卡进行钱包充值。使用同一个账户，你还可以提供Apple Pay、Google Pay、Link和Alipay，并允许客户保存卡片以进行automatic top-up。建议将其作为国际客户的主要支付渠道。

前提条件

项目	要求
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会自动为你处理。
依赖项	无。

共享Stripe账户

NexCMP仅处理由自身创建的付款的webhook事件，因此你可以使用同时服务于其他应用程序的Stripe账户。

准备基础设施

在Stripe端：

1. 登录Stripe Dashboard。开启或关闭Test mode以决定是进行测试演练还是正式上线。两种模式的密钥绝不能混用。
2. 打开Developers › API keys。复制Publishable key，并显示并复制Secret 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 可用，然后开启Alipay (Stripe, JPY display)（位于Fees & limits）。设置Alipay fee %、Alipay fixed fee、¥/USD rate（50–500）以及 FX spread %（0–20）。请定期更新 ¥/USD rate；当该汇率超过 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 结算；Alipay 以 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）下进行批准。支付宝退款是异步的；失败的退款（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。

故障排查

症状	原因	解决办法
"密钥必须以 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 中将其开启并保存密钥。