VibeFox Peach Payments for WooCommerce — 帮助
系统要求
WordPress: 6.2 或更高版本。
WooCommerce: 8.0 或更高版本，已安装并启用。没有它，插件将拒绝启用。
PHP: 8.0 或更高版本。
Currency: 店铺币种必须为 ZAR、KES 或 MUR。使用其他币种时，付款方式会隐藏，设置页面会说明原因。
Peach Payments account: 您需要 Peach Payments 账户的 Card API 凭据：Entity ID 和 Access Token。测试凭据来自 Peach Payments 沙盒控制面板，正式凭据来自 Peach Payments 控制面板，两者不同。使用 Webhook 还需要解密密钥，Peach Payments 会在为店铺启用 Card Webhook 时发送给您（参见“配置”）。您的网站必须可从互联网访问才能接收 Webhook。
VibeFox license key: 在 vibefox.net 购买。一个密钥适用于一个域名。
安装
1. 在 WordPress 中前往 Plugins > Add New > Upload Plugin，选择插件 ZIP 文件并点击 Install Now。您也可以通过 FTP 将 wcp_peach_pay 文件夹上传至 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Payments > Peach Payments > Manage，或在插件页面的插件名称下点击 Settings。
4. 在页面顶部的许可证区域输入 VibeFox 许可证密钥，然后点击 Activate。
5. 输入 Peach Payments 沙盒控制面板中的测试 Entity ID 和 Access Token，并请 Peach Payments 为设置页面显示的 Webhook URL 启用 Card Webhook（参见“配置”）。
6. 开启 Enable/Disable 并保存。保持 Test mode 开启，使用 Peach Payments 沙盒测试卡付款。然后取消勾选 Test mode，输入正式凭据和正式 Webhook 密钥，再保存。
更新后，1.0 版本的设置会自动迁移到新字段。
配置
所有设置都在同一页面：WooCommerce > Settings > Payments > Peach Payments。字段上方会显示通知：Test mode is on: payments go to the Peach Payments sandbox and no real money is charged.；当前模式缺少 Entity ID 或 Access Token 时的通知（在填写前，结账时不会显示此付款方式）；当前模式缺少 Webhook 解密密钥时的通知（此时只有顾客返回店铺才会确认付款）；以及店铺币种不受支持时的通知。在付款方式列表中，当前模式具有 Entity ID 和 Access Token 之前，Peach Payments 会被标记为需要设置。保存时会移除凭据中的空格；Webhook 密钥若不是 64 字符的十六进制值，会报错。
Enable/Disable: Enable Peach Payments 用于开启或关闭付款方式。默认：关闭。
Title: 结账时向顾客显示的付款方式名称。默认：Credit / Debit Card (Peach Payments)。
Description: 结账时显示在付款方式下方的文字。默认：Pay securely with your card. You will enter the card details in the Peach Payments form on the next page.
API 凭据
Card API 的 Access Token 和 Entity ID 显示在 Peach Payments 控制面板中（测试凭据在沙盒控制面板）。此部分包含两个控制面板及 Peach Payments 开发者文档的链接。
Test mode: Enable test mode 使用测试凭据将新付款发送到 Peach Payments 沙盒，不会扣取真实资金。取消勾选后，使用正式凭据接受真实付款。付款始终在发起时所用的模式下核验，即使之后切换模式也是如此。默认：开启。
Test Entity ID: 您沙盒账户的 Entity ID（3-D Secure 通道）。
Test Access Token: 您沙盒账户的 bearer 访问令牌。
Test Webhook Decryption Key: 用于解密沙盒 Card Webhook 的 64 字符十六进制密钥。
Live Entity ID: 您正式账户的 Entity ID（3-D Secure 通道）。
Live Access Token: 您正式账户的 bearer 访问令牌。
Live Webhook Decryption Key: 用于解密正式账户 Card Webhook 的 64 字符十六进制密钥。
Webhook
即使顾客在返回店铺前关闭浏览器，Webhook 也能确认付款。此部分显示店铺的 Webhook URL，格式如 https://your-site/wp-json/peach-pay/v1/webhook。请完全按照设置中显示的内容复制。请 Peach Payments（support@peachpayments.com）使用该 URL 为您的账户启用 Card Webhook，然后在同一模式的 Webhook Decryption Key 字段中输入收到的解密密钥。
Peach Payments 对每个 Webhook 进行加密（AES-256-GCM）。无法用测试或正式密钥解密的 Webhook 会被拒绝，因此只有 Peach Payments 能更改您的订单。用某一模式密钥解密的 Webhook，仅适用于该模式下发起的付款。插件使用以下付款通知：
其他通知，例如启用 Webhook 时发送的测试通知，会收到 OK 响应并被忽略。没有 Webhook 密钥时，只有顾客付款后返回店铺，订单才会得到确认。
付款表单
Card brands: Peach Payments 表单显示的品牌：Visa、Mastercard、American Express、Diners Club。仅选择已为您的 Entity ID 启用的品牌。默认：Visa 和 Mastercard。
高级
Logging: Log API requests and payment results 将调试信息写入 WooCommerce > Status > Logs，来源为 wcp_peach_pay。错误和警告始终会被记录。日志不含银行卡数据、密钥或顾客数据。默认：关闭。
Delete data on uninstall: Delete the plugin settings and logs when the plugin is deleted。停用插件绝不会删除任何内容。订单中存储的 Peach Payments 数据会保留。默认：关闭。
结账
顾客选择付款方式（默认为 Credit / Debit Card (Peach Payments)）并点击 Continue to payment，然后进入您店铺的 Pay for order 页面。插件在那里按订单总额和币种创建 Peach Payments 结账会话，显示含所选品牌的 Peach Payments 银行卡表单，并在 Peach Payments 支持时使用网站语言。测试模式下，页面显示 Test mode: use a Peach Payments test card, no real payment will be made.。银行卡信息在 Peach Payments 表单中输入，表单脚本使用 Subresource Integrity 哈希加载。
付款后，顾客返回店铺。只有 Peach Payments 确认后，订单才会标记为已付款：店铺通过 Peach Payments API，在创建结账会话的模式下读取此订单的结账结果，并核对付款属于此订单。Webhook 也会独立执行相同操作，先到达的一方应用结果，另一方不做更改。已付款顾客会看到 Order received 页面。
如果付款未完成，顾客会返回 Pay for order 页面，看到消息后可重试：Payment failed: 后接 Peach Payments 提供的原因和 Please try again or use another card.，或 The payment was not completed. Please try again.。如果结果暂时无法确认（例如 Peach Payments 未响应，或 Webhook 正在处理同一订单），消息为 We could not confirm your payment yet. If you were charged, the order will be updated automatically; otherwise please try again.。如果该模式未设置 Webhook 密钥，则会请顾客提供订单号与您联系。
如果无法准备付款表单，顾客会看到简短消息和 Try again 按钮：The payment form is not available right now (payment configuration error). Please contact us or choose another payment method.（凭据错误）、部分账单信息未获付款服务商接受的消息，或 The payment form could not be loaded. Please try again in a moment.。订单会添加包含 Peach Payments 代码和说明的备注。
此付款方式适用于经典结账、结账区块和 Pay for order 页面。兼容 WooCommerce High-Performance Order Storage（HPOS）。
插件不在结账页面本身显示银行卡表单，不支持保存银行卡、订阅、预授权和扣款，也不支持 EFT、BNPL、QR 或其他非银行卡方式。
订单
订单状态
Pending payment: 顾客尚未付款，或付款尚未完成。顾客可以再次支付同一订单。
Processing: 付款已确认，金额和币种与订单一致。订单备注显示 Peach Payments 结果代码、说明和付款 ID；付款 ID 即订单的交易 ID。如果 Peach Payments 标记付款需要人工审核，备注会请您在发货前到 Peach Payments 控制面板检查。
On hold: 付款正在等待 Peach Payments 确认（Webhook 之后会完成付款或标记为失败）；已付金额或币种与订单不同（备注 amount/currency mismatch — manual review required）；或付款在订单取消后到达。订单备注会说明要检查的内容。
Failed: Peach Payments 拒绝了待付款订单的付款，或拒绝了保留订单正在等待的付款。被拒绝的尝试绝不会更改已付款、因其他原因保留或已取消的订单。顾客可以再次付款。
如果已付款订单的第二笔付款成功，订单保持不变。备注会说明这是重复付款，并请您在 Peach Payments 控制面板退款。已退款订单收到付款时，只会添加备注。
退款
不支持从 WooCommerce 订单页面退款。请在 Peach Payments 控制面板退款，并在 WooCommerce 中记录手动退款。设置 Webhook 后，Peach Payments 中的退款、撤销和拒付会添加为含金额和 ID 的订单备注，不更改订单状态。
许可证密钥
插件使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区域位于 WooCommerce > Settings > Payments > Peach Payments 顶部。将密钥粘贴到 License key 并点击 Activate。此区域显示状态，例如许可证有效期和您的域名。用 Check now 再次检查状态，用 Change key 输入其他密钥，用 Remove key 从本站移除密钥。Manage licenses and domains in your account 链接会打开您的 vibefox.net 账户。
一个密钥适用于一个域名。从网站移除密钥不会释放其域名名额。请在 vibefox.net 账户中释放名额。
没有有效密钥时，顾客结账时看不到 Peach Payments。如果仍然发起付款，顾客会看到 This payment method is not available. Please choose another one.。已登录的店铺管理员仍能看到此方式，并带有 (unlicensed — visible to admins only) 标记，以便您在购买密钥前配置和测试插件。插件页面和 WooCommerce 页面会显示提醒。现有订单不受影响：已发起的付款仍通过顾客返回和 Webhook 得到确认。
许可证到期后，插件仍可运行，但更新和支持需要续订。状态会在后台自动重新检查。
故障排除
结账时未显示 Peach Payments：检查许可证是否有效、Enable/Disable 是否开启、当前模式的 Entity ID 和 Access Token 是否填写（测试模式为 Test Entity ID 和 Test Access Token，正式模式为 Live Entity ID 和 Live Access Token），以及币种是否为 ZAR、KES 或 MUR。设置顶部的通知会指出问题。开发者可通过 peach_p_supported_currencies 筛选器修改币种列表，只添加您的 Peach Payments 账户可处理的币种。
付款成功，但订单仍为 Pending payment：顾客没有返回店铺，Webhook 也未到达。检查 Peach Payments 是否为设置中完全一致的 URL 启用了 Card Webhook、是否填写付款模式的 Webhook Decryption Key，以及维护模式、防火墙或密码保护是否阻挡 URL。在 WooCommerce > Status > Logs 的 wcp_peach_pay 来源中查找被拒绝的 Webhook。
Webhook 返回 Decryption failed：无法用测试或正式密钥解密。密钥错误，或属于其他账户或模式。请输入 Peach Payments 为此 Webhook URL 发送的密钥。
Webhook 返回 Webhook key not configured：两个 Webhook 密钥均未设置或无效。请输入 64 字符密钥。Peach Payments 稍后会重新发送 Webhook。
Webhook 返回 Order busy, retry later：顾客返回触发的更新正在同时处理订单。没有发生更改，Peach Payments 会重新发送 Webhook。
Webhook 返回 Missing or malformed data：请求缺少加密正文或 X-Initialization-Vector / X-Authentication-Tag 标头，例如被代理修改。没有发生更改。
Webhook 返回 ignored：通知是真实的，但不属于本店结账会话（相同 Entity ID 下的其他店铺、已删除订单），或来自与付款不同的模式。没有发生更改。
顾客看到 The payment form is not available right now：当前模式的 Access Token 或 Entity ID 错误。检查凭据和模式，并阅读订单备注中的 Peach Payments 代码。
付款后订单为 On hold：阅读订单备注。已付金额或币种不同、付款在订单取消后到达，或 Peach Payments 仍在等待确认。请在 Peach Payments 控制面板核对付款，然后处理订单或退款。
保存时要求 Webhook 密钥为 64 字符十六进制值：当前值并非 Peach Payments 提供的密钥。修正前无法解密 Webhook。
许可证区域显示错误：按消息操作。例如密钥已用于其他域名，请在 vibefox.net 账户释放名额后点击 Check now。网站地址改变时，点击 Check now 在新域名激活密钥。如果无法访问许可证服务器，插件会按最后已知状态继续运行。
卸载
停用插件会保留所有数据。要移除插件，请在 Plugins 页面停用并删除。插件的许可证密钥和许可证状态始终会被移除。仅当 Delete data on uninstall 已开启时，才会移除插件设置和日志（wcp_peach_pay 来源的日志文件和数据库日志条目）。否则会保留以便日后重新安装。现有订单保留付款备注、交易 ID 和 Peach Payments 结账数据。
Peach Payments 是其各自所有者的商标。本插件与 Peach Payments 无关联，也未获其认可。