VibeFox Stripe for WooCommerce — 帮助
系统要求
WordPress：6.0 或更高版本。
WooCommerce：7.0 或更高版本，已安装并启用。未安装 WooCommerce 时，插件无法启用。
PHP：8.0 或更高版本。
HTTPS：使用正式付款时，您的网站应启用 HTTPS。
Stripe 账户：您需要 Stripe 账户的私密 API 密钥，以及 Stripe Dashboard 中的 Webhook 端点（参见"配置"）。仅使用私密密钥和 Webhook 签名密钥。无需可发布密钥（pk_...），因为 Stripe Checkout 是由 Stripe 托管的页面。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能在一个域名上使用。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 wcp_stripe_gateway 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Payments > Stripe > Manage，或在插件页面中点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 粘贴您的 Stripe 私密密钥，在 Stripe Dashboard 中设置 Webhook，并粘贴其签名密钥（参见"配置"）。
6. 开启 Enable/Disable。使用测试卡 4242 4242 4242 4242 在测试模式下测试付款，然后取消勾选 Test Mode。
配置
所有设置都在同一页面：WooCommerce > Settings > Payments > Stripe。在字段上方，当当前模式没有私密密钥（此时付款方式会在结账时隐藏）或没有 Webhook 签名密钥时，页面会向您发出警告；当测试模式开启时，页面会显示 Test mode is on: no real payments are taken.。在付款方式列表中，Stripe 会被标记为需要设置，直到当前模式具有私密密钥为止。
常规
Enable/Disable：Enable Stripe Gateway 用于开启或关闭该付款方式。默认：关闭。
Title：顾客在结账时看到的付款方式名称。默认：Stripe。
Description：结账时显示在付款方式下方的文字。默认：Pay securely with your credit or debit card via Stripe.
API 密钥
从 Stripe Dashboard > Developers > API keys 复制私密密钥。测试密钥和正式密钥是分开的。测试模式只使用测试密钥，正式模式只使用正式密钥。保存时，如果某个值不是以预期前缀开头（例如误将可发布密钥粘贴为私密密钥），插件会发出警告。
Test Mode：Enable test mode 使用 Stripe 测试密钥。不会扣取真实款项；请使用 Stripe 测试卡（例如 4242 4242 4242 4242）付款。默认：开启。取消勾选即可接受真实付款。
Test Secret Key：测试模式的私密密钥。以 sk_test_ 开头（受限密钥以 rk_test_ 开头）。
Test Webhook Secret：在测试模式下创建的 Webhook 端点的签名密钥（whsec_...）。
Live Secret Key：正式模式的私密密钥。以 sk_live_ 开头（受限密钥以 rk_live_ 开头）。
Live Webhook Secret：在正式模式下创建的 Webhook 端点的签名密钥（whsec_...）。
Webhook
Webhook 会告知您的店铺某笔付款已完成。在 Stripe Dashboard > Developers > Webhooks 中，为测试模式添加一个端点，再为正式模式添加另一个端点。请使用本节设置中显示的 URL，其格式类似于 https://your-site/wc-api/strg_stripe_webhook/。如果您的网站在 URL 中使用了语言前缀，请完全按照设置中显示的内容复制 URL，因为 Stripe 不会跟随重定向。
为每个端点选择以下事件：
创建每个端点后，从 Stripe 复制其签名密钥（whsec_...），并粘贴到 Test Webhook Secret 或 Live Webhook Secret 中。没有有效签名的 Webhook 会被拒绝。没有 Webhook 时，只有顾客付款后返回店铺，订单才会被确认。
订单
Order Status After Payment：付款成功后设置的订单状态。状态会立即设置，不会再进行第二次状态变更。
高级
Logging：Enable logging 会将 Stripe 请求和 Webhook 记录到 WooCommerce > Status > Logs，来源为 wcp_stripe_gateway。密钥和顾客数据不会被记录。默认：关闭。
Delete Data on Uninstall：开启后，删除插件时会移除网关设置、订单上保存的 Stripe 数据以及日志。默认：关闭。
结账
顾客选择付款方式（默认为 Stripe）并提交订单。插件会按订单币种为订单总额创建 Stripe Checkout 会话，并将顾客带到 Stripe 付款页面。顾客在该页面使用信用卡或借记卡付款。顾客的账单邮箱会传递给 Stripe，付款在 Stripe 页面上显示为 Order # 及订单号。
付款后，顾客会返回店铺的订单接收页面。只有在 Stripe 确认后，订单才会被标记为已付款：通过已签名的 Webhook，或在顾客到达该页面时由服务器向 Stripe 发起请求来确认。如果付款尚未确认，页面会显示 Your payment is being confirmed by Stripe. You will receive an e-mail as soon as it is confirmed.
如果顾客在 Stripe 页面上取消付款，订单会按 WooCommerce 的标准方式取消。顾客可以重新支付未付款的订单，例如通过 Pay for order 页面。每次新的尝试都会关闭之前的 Stripe 会话，因此同一订单不能被支付两次。
如果 Stripe 无法启动付款，顾客会看到一条简短消息，例如订单总额低于 Stripe 在该币种下可收取的最低金额，并可以选择其他付款方式。技术原因会添加到订单备注和日志中。已登录的店铺管理人员也会在该消息中看到原因。
该付款方式适用于经典结账、结账区块以及 Pay for order 页面。它兼容 WooCommerce 高性能订单存储（HPOS）。
本插件仅接受银行卡付款，并在 Stripe 页面上即时扣款。不支持保存银行卡、订阅或定期付款，不支持网站内的银行卡表单，不支持您网站上的 Apple Pay 或 Google Pay 按钮，也不支持分开的授权与扣款。
订单与退款
订单状态
Pending payment：顾客已被带到 Stripe 但尚未付款，或 Stripe 尚未确认付款。
Processing, Completed or On Hold：付款已确认。订单状态遵循 Order Status After Payment。订单备注会显示 Stripe 付款以及确认方式（Webhook 或返回）。交易 ID 为 Stripe 付款 ID（pi_...），在订单页面中会链接到 Stripe Dashboard 中的该笔付款。
On hold after payment：Stripe 报告的金额或币种与订单总额不一致（例如，付款开始后订单被修改），或付款在订单被取消后才到达。订单备注会对此进行说明。请检查订单，然后处理订单或退还付款。
Failed：延迟付款失败。
Cancelled：顾客在 Stripe 页面上取消，或订单被您取消，或因 WooCommerce 库存保留超时而取消。订单开启的 Stripe 会话会被关闭，因此无法再付款。
如果已付款的订单又收到第二笔付款，订单不会再次被修改。备注会提醒您检查，并在 Stripe Dashboard 中退还重复付款。
退款
打开订单，点击 Refund，输入金额，然后点击 Refund via Stripe。支持全额和部分退款。退款会在付款时所处的模式（测试或正式）中发送，因此必须已设置该模式的私密密钥。如果 Stripe 不接受退款，WooCommerce 会显示错误，并且不会记录退款。成功的退款会连同 Stripe 退款 ID 一起添加到订单备注中。
在 Stripe Dashboard 中进行的退款会通过 charge.refunded Webhook 送达，并添加到订单备注中。它们不会自动记录为 WooCommerce 退款。如有需要，可在 WooCommerce 中创建手动退款，而不使用 Refund via Stripe。
许可证密钥
本插件需要使用从 vibefox.net 获取的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > Stripe 的顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期至何时以及您的域名。使用 Check now 再次检查状态，使用 Change key 输入其他密钥，使用 Remove key 将其从本站点移除。Manage licenses and domains in your account 链接会打开您的 vibefox.net 账户。
一个密钥只能在一个域名上使用。从站点移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。
没有有效密钥时，结账时不会向顾客显示 Stripe。如果仍然启动了付款，顾客会看到 This payment method is not available. Please choose another one. 已登录的店铺管理人员仍会看到该付款方式，并标注为 (unlicensed — visible to admins only)，以便您在购买密钥之前设置和测试插件。插件页面和 WooCommerce 页面上会显示提醒。现有订单不受影响：已开始的付款仍会被确认，退款也可正常进行。
许可证过期后，插件仍可继续工作，但更新和支持需要续费。状态会在后台自动重新检查。
故障排除
结账时不显示 Stripe：请检查许可证是否有效，Enable/Disable 是否已开启，以及当前模式是否有私密密钥：测试模式下为 Test Secret Key，正式模式下为 Live Secret Key。缺少密钥时，设置页面会显示警告。
付款已完成，但订单仍为 Pending payment：Webhook 无法工作。请在 Stripe Dashboard 中检查：您所用模式（测试或正式）下是否存在该端点，其 URL 是否与设置中显示的完全一致，以及是否选中了这四个事件。检查该端点的签名密钥是否位于对应字段中（Test Webhook Secret 或 Live Webhook Secret）。Stripe Dashboard 会显示您的店铺对每个 Webhook 的响应。顾客付款后返回店铺时，订单也会被确认。
Webhook 响应 Webhook secret not configured：两个 Webhook 密钥都未设置。请将签名密钥粘贴到设置中。
Webhook 响应 Invalid signature：签名密钥属于另一个端点或另一种模式，或者服务器时间不正确。Stripe 签名仅在服务器时间的 5 分钟内被接受。
Webhook 响应 Busy, retry：订单在同一时刻正被另一个请求确认。Stripe 会自动重试该 Webhook。
保存时的警告：值看起来不对：密钥被粘贴到了错误的字段中。私密密钥以 sk_test_ / rk_test_ 或 sk_live_ / rk_live_ 开头，Webhook 签名密钥以 whsec_ 开头。
顾客下单时出现错误：打开订单备注，或开启 Logging，并在 WooCommerce > Status > Logs 中查看来源 wcp_stripe_gateway 的日志。密钥错误或缺失会显示付款方式配置不正确的消息。低于 Stripe 在该币种下最低金额的订单总额（例如 0.50 EUR）无法使用 Stripe 付款。
测试付款无法确认正式订单：测试付款和正式付款是分开处理的。测试付款绝不会确认正式订单，反之亦然。请将 Test Mode 切换到您需要的模式，并使用该模式的密钥和 Webhook。
订单在付款后处于 On hold：请阅读订单备注。付款金额或币种与订单不符，或付款是在订单取消后才到达的。请处理订单或退还付款。
退款因模式相关的消息而失败：付款是在测试或正式模式下完成的，而该模式的私密密钥未设置。请输入密钥后重试。
许可证区块显示错误：请按照区块中的消息操作。例如，如果该密钥已在另一个域名上使用，请在您的 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now，为新域名激活该密钥。如果无法连接许可证服务器，插件会继续使用上次已知的状态运行。
卸载
停用插件会保留所有数据。要移除插件，请在 Plugins 页面中停用并删除。本插件的许可证密钥和许可证状态始终会被删除。网关设置、订单上保存的 Stripe 数据以及日志，仅在 Delete Data on Uninstall 已开启时才会被删除；否则会保留，以便日后重新安装。现有订单会保留其付款备注和交易 ID。
Stripe 是其各自所有者的商标。本插件与 Stripe 无关联，也未获得 Stripe 的认可。