VibeFox Yoco for WooCommerce — 帮助
系统要求
WordPress：6.2 或更高版本。
WooCommerce：8.0 或更高版本，已安装并启用。未安装 WooCommerce 时插件无法启用。
PHP：8.0 或更高版本。
店铺货币：南非兰特（ZAR）。Yoco 仅接受 ZAR。使用其他货币时，结账页面不会显示该付款方式。订单总额必须至少为 R2.00。
Yoco 账户：开通了在线付款功能的 Yoco 账户。您需要其密钥，可在 Yoco Business Portal 的 Selling Online > Payment Gateway 中找到。只需输入密钥。Webhook 由插件注册，其签名密钥会自动填入。
公网站点：Yoco 会向您的网站发送 Webhook，因此网站必须可以从互联网访问。Webhook URL 必须接受 POST 请求而不发生重定向。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件 ZIP 文件并点击 Install Now。您也可以通过 FTP 将 wcp_yoco_pay 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Payments > Yoco > Manage。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 粘贴测试密钥（sk_test_...），准备好后再粘贴正式密钥（sk_live_...）。保存设置。每个有密钥的模式都会注册 Webhook。
6. 开启 Enable/Disable。在 Test mode 开启时，使用 Yoco 测试卡完成一笔测试付款，然后取消勾选 Test mode 以接受真实付款。
配置
所有设置都在一个页面中：WooCommerce > Settings > Payments > Yoco。当店铺货币不是 ZAR（此时结账时不提供 Yoco）或当前模式没有密钥时，页面会在字段上方发出警告。在付款方式列表中，在当前模式设置密钥之前，Yoco 会被标记为需要设置。保存时，插件会检查密钥和 Webhook 签名密钥，并注册 Webhook。相关消息会显示在页面顶部。
常规
Enable/Disable：Enable Yoco 用于开启或关闭该付款方式。默认：off。
Title：顾客在结账时看到的付款方式名称。默认：Card or Instant EFT (Yoco)。
Description：结账时付款方式下方显示的文字。默认：You will be redirected to the secure Yoco page to pay by card or Instant EFT.
API 密钥
从 Yoco Business Portal 的 Selling Online > Payment Gateway 复制密钥。Yoco 为两种模式提供同一个 API：由密钥决定付款是测试还是真实付款。测试模式只使用测试密钥，正式模式只使用正式密钥。
Test mode：Use the test secret key (no real payments)。不会扣除真实款项；请使用 Yoco 测试卡付款。默认：on。取消勾选即可接受真实付款。
Test secret key：测试模式的密钥，以 sk_test_ 开头。
Live secret key：正式模式的密钥，以 sk_live_ 开头。
不以预期前缀开头的密钥不会被保存：页面会显示错误，并保留之前的值。如果 Yoco 在注册 Webhook 时提示某密钥属于另一模式，页面会告知您。
Webhook
Yoco 会将付款和退款结果发送到本节显示的 Webhook URL。其格式如下：https://your-site/wc-api/yoco_pay_webhook/。您无需在 Yoco 后台创建 Webhook。保存设置时，插件会为每个有密钥但没有 Webhook 签名密钥的模式向 Yoco 注册该 URL，并将签名密钥填入该模式的字段。当该模式的密钥或 Webhook URL 变化时，插件会重新注册该 URL。URL 变化时，旧的注册会被删除。
本节会为每种模式显示 Webhook 的状态：
插件处理以下事件：
没有有效签名的 Webhook 会被拒绝。如果您的网站 URL 中使用了语言前缀，请保持 URL 与设置中显示的完全一致，因为 Webhook 必须无重定向地到达您的店铺。
Test webhook secret：注册 Webhook 时自动填入。只有当您自行注册了 Webhook URL 时，才粘贴签名密钥（whsec_...）。
Live webhook secret：注册 Webhook 时自动填入。清空该字段并保存即可重新注册 Webhook。
Webhook 签名密钥的格式应为 whsec_ 加 base64 文本。其他任何值都不会被保存，并保留之前的值。
高级
Debug log：Log Yoco requests and webhooks 会将请求和 Webhook 写入 WooCommerce > Status > Logs，来源为 wcp_yoco_pay。错误和警告（例如向 Yoco 发送失败的请求、被拒绝的 Webhook）始终会被记录。密钥、Webhook 签名密钥和电子邮件地址会被遮蔽。默认：off。
Delete data：Delete the settings and logs of this plugin when it is deleted。停用插件从不会删除任何内容。订单数据（Yoco checkout 与付款 ID）始终保留，因为退款需要用到它们。默认：off。
结账
顾客选择付款方式（默认为 Card or Instant EFT (Yoco)）并下单。在测试模式下，结账页面会显示 Test mode — use a Yoco test card; no real money is charged. 插件会按订单总额（以分为单位）创建一个 Yoco checkout，并将顾客带到 Yoco 付款页面，顾客可在该页面使用银行卡或 Instant EFT 付款。
付款后，顾客返回您的店铺。只有在 Yoco 确认付款后，订单才会标记为已付款：插件会在顾客返回时以及已签名的 Webhook 到达时向 Yoco 查询 checkout。如果 Yoco 尚未确认付款，订单接收页面会显示 We are waiting for Yoco to confirm your payment. The order will be updated automatically — please do not pay again.
如果顾客在 Yoco 页面取消，订单保持未付款状态，顾客会进入 Pay for order 页面，并看到消息 The Yoco payment was cancelled. Your order is saved — you can pay again below or choose another payment method. 如果付款失败，消息为 The Yoco payment was not successful. Please try again or choose another payment method.，并且订单中会添加备注。
顾客可以通过 Pay for order 页面重新支付未付款的订单。在发起新的尝试之前，插件会先向 Yoco 查询之前的付款。如果之前的付款已完成，订单会直接完成，而不会再显示新的付款页面。如果之前的付款金额相同、仍处于未完成状态，并且创建于 30 分钟以内，顾客会再次看到同一个 Yoco 页面。
如果 Yoco 无法发起付款，顾客会看到 Yoco could not start the payment. Please try again in a moment or choose another payment method.，原因会添加到订单备注中。订单金额低于 R2.00 时，顾客会看到 Yoco requires an order total of at least R2.00.
该付款方式可用于经典结账、结账区块以及 Pay for order 页面。它兼容 WooCommerce 高性能订单存储（HPOS）。
付款会在 Yoco 页面立即扣款。插件不支持保存银行卡、订阅或定期付款，不提供站内银行卡表单，也不支持单独的授权和扣款，且不支持 ZAR 以外的货币。
订单与退款
订单状态
Pending payment：顾客已被转到 Yoco 且尚未付款，在 Yoco 页面取消，或 Yoco 尚未确认付款。
Processing or Completed：付款已确认。WooCommerce 会设为「处理中」；对于仅包含可下载虚拟商品的订单，则设为「已完成」。订单备注会显示金额、Yoco 付款与 checkout ID、模式，以及付款的确认方式（顾客返回、Webhook，或在新付款尝试前的查询）。交易 ID 即为 Yoco 付款 ID。
On hold：Yoco 报告的金额或币种与订单总额不符，例如付款开始后订单被修改。备注会对此进行说明，从 Yoco 返回的顾客会看到 We received your payment and are reviewing it. We will contact you if anything else is needed. 发货前请核对付款。
Cancelled or Refunded：针对此类订单到达的付款不会改变订单。备注会提示您在 Yoco 后台退款或手动恢复订单。从 Yoco 返回的顾客会看到 Your payment was received after the order had been cancelled. Please contact us — do not pay again.
如果已付款的订单又收到第二笔付款，订单不会再次被修改。备注会提示您在 Yoco 后台将其退款。
退款
打开订单，点击 Refund，输入金额，然后点击带有您付款方式名称的 Refund via 按钮（默认为 Card or Instant EFT (Yoco)）。支持全额和部分退款。退款会以付款时所用的模式（测试或正式）发送，因此该模式的密钥必须已设置。因响应丢失而重复的退款不会被重复退款。
退款成功后，会在订单备注中添加 Yoco 退款 ID。如果 Yoco 拒绝退款，WooCommerce 会显示 Yoco refused the refund: 及原因，并且不会记录退款。如果 Yoco 报告退款待处理，WooCommerce 会显示仍在待处理，且不记录任何内容。请勿重复操作：当 Yoco 通过 Webhook 确认后，退款会添加到订单中。
在 Yoco 后台进行的退款会通过 refund.succeeded Webhook 到达，并自动记录为 WooCommerce 退款，且不会将商品退回库存。超过剩余可退款金额的退款不会被记录，备注会提示您检查订单。失败的退款会添加备注，说明款项未退还给顾客。
许可证密钥
插件需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > Yoco 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期的截止日期以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将其从本站点移除。Manage licenses and domains in your account 链接会打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。将密钥从站点移除并不会释放域名名额，请在您的 vibefox.net 账户中释放名额。
没有有效密钥时，Yoco 不会在结账时向顾客显示。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 已登录的店铺管理员仍会看到该付款方式，并标注 (unlicensed — visible to admins only)，以便您在购买密钥之前设置并测试插件。插件页面和 WooCommerce 页面会显示提醒。现有订单不受影响：已发起的付款仍会被确认，退款也可正常进行。
许可证到期后，插件仍可继续工作，但更新和支持需要续费。状态会在后台自动重新检查。
故障排除
Yoco 没有出现在结账页面：请检查许可证是否有效，Enable/Disable 是否已开启，以及当前模式是否有密钥：测试模式需要 Test secret key，正式模式需要 Live secret key。店铺或订单货币必须为 ZAR，订单总额至少为 R2.00。缺少密钥或货币不是 ZAR 时，设置页面会显示警告。
付款已完成，但订单仍为 Pending payment：Webhook 没有正常工作。打开设置中的 Webhooks 部分，检查您所用模式的状态。如果未注册，或注册到了其他 URL，请保存设置。如果注册失败，页面会显示原因。如果您是自行输入的签名密钥，请确认它属于该 URL 和该模式的 Webhook。顾客付款后返回店铺，或再次尝试付款时，订单也会被确认。
无法注册 Webhook：顾客返回店铺时，付款仍会被确认。请修正消息中显示的原因，例如网站必须能通过 HTTPS 从互联网访问，然后再次保存。您也可以自行注册该 URL，并粘贴签名密钥。
Webhook 被拒绝：被拒绝的 Webhook 会写入日志，来源为 wcp_yoco_pay。webhook secret not configured 表示两个 Webhook 签名密钥都未设置。invalid signature 表示该密钥属于其他注册或模式。timestamp outside the tolerance 表示服务器时钟有误：签名仅在服务器时间的 5 分钟内被接受。checkout not completed yet — retry 和 could not confirm the checkout with Yoco — retry 属于临时性错误；Yoco 会再次发送 Webhook。
The secret key must start with sk_test_ / sk_live_ error on save：密钥被粘贴到了错误的字段中。测试密钥以 sk_test_ 开头，正式密钥以 sk_live_ 开头。之前的值已被保留。
顾客下单时看到错误：请阅读订单备注，或查看 WooCommerce > Status > Logs，来源为 wcp_yoco_pay。Yoco is not available at the moment. Please choose another payment method. 表示当前模式没有密钥。
顾客被告知付款需要审核：之前的一次尝试以不同金额付款，或在订单取消之后付款。请阅读订单备注，然后完成订单或在 Yoco 后台退款。
退款失败并提示与模式有关的消息：付款是在测试或正式模式下完成的，而该模式的密钥未设置。请输入密钥后重试。
退款失败并显示 No answer from Yoco：WooCommerce 中没有记录任何内容。如果 Yoco 确实处理了退款，请重复同一笔退款：不会被重复退款。
许可证区块显示错误：请按照区块中的消息操作。例如，如果该密钥已在其他域名上使用，请在您的 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now，为新域名激活密钥。如果无法连接许可证服务器，插件将继续使用上一次已知的状态。
卸载
停用插件会保留所有数据。要删除插件，请先停用，然后在 Plugins 页面中删除。本插件的许可证密钥和许可证状态始终会被删除。网关设置、Yoco 中的 Webhook 注册以及日志（包括轮转的日志文件）仅在 Delete data 已开启时才会被删除；否则它们会保留，以便日后重新安装。现有订单会保留其付款备注和交易 ID。
Yoco 是其各自所有者的商标。本插件与 Yoco 无关联，也未获得 Yoco 的认可。