VibeFox Peach Payments for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本，并启用 OpenSSL 扩展（用于解密 Webhook）。缺少这些条件时，模块无法安装。
货币：购物车货币必须是 ZAR、KES 或 MUR。对于使用其他货币的购物车，付款方式会被隐藏。如果商店的默认货币不是其中之一，设置页面会发出警告。
Peach Payments 账户：您需要 Peach Payments 账户的 Card API 凭据：Entity ID 和 Access Token。测试凭据来自 Peach Payments 沙盒控制面板，正式凭据来自 Peach Payments 控制面板，两者不同。使用 Webhook 还需要 Webhook 解密密钥，它会在 Peach Payments 为您的商店启用 Card Webhook 时发送给您（请参阅配置）。您的商店必须能从互联网访问，才能接收 Webhook。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 进入后台，前往 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者之后在模块列表中找到 VibeFox Peach Payments Pay Gateway 并点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥输入 License key，然后点击 Activate（见许可证密钥）。
4. 从 Peach Payments 沙盒控制面板输入测试 Entity ID 和 Access Token，并请 Peach Payments 为设置页面所示的 Webhook URL 启用 Card Webhook（请参阅配置）。
5. 开启 Enable/Disable 并点击 Save。保持 Test mode 开启，并使用 Peach Payments 沙盒测试卡完成一笔付款。然后关闭 Test mode，输入正式凭据和正式 Webhook 密钥，再点击 Save。
安装时，模块会创建两个订单状态：Awaiting Peach Payments payment 和 Peach Payments payment on hold。PrestaShop 会为当时启用的货币、国家和客户组提供一个新的付款模块。之后添加的国家必须在 Payment > Preferences 中为该模块启用，您也可以在那里进行限制。
配置
所有设置都位于模块页面：Modules > Module Manager > VibeFox Peach Payments Pay Gateway > Configure。每个部分都有自己的 Save 按钮，会保存整个页面。在字段上方，页面会显示以下提示：Test mode is on: payments go to the Peach Payments sandbox and no real money is charged.；当前模式的 Entity ID 或 Access Token 缺失时显示错误（在此之前，结账时不会显示该付款方式）；当前模式的 Webhook 解密密钥缺失时显示警告（此时只有顾客返回商店后才会确认付款）；商店的默认货币不受支持时显示错误。保存时，凭据中的空格会被删除；如果 Webhook 密钥不是 64 位十六进制值，会显示警告。
Peach Payments
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 credentials
Card API 的 Access Token 和 Entity ID 显示在 Peach Payments 控制面板中（测试凭据在沙盒控制面板中）。该部分提供了两个控制面板和 Peach Payments 开发者文档的链接。
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 密钥不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有需要更改时才输入新值。
Clear saved secrets：勾选访问令牌或 Webhook 密钥，然后点击 Save 将其删除。字段为空时保留已保存的值。
Webhook
即使顾客在返回商店之前关闭浏览器，Webhook 也能确认付款。Webhook URL 字段显示您商店的 Webhook URL。使用友好 URL 时，它看起来像 https://your-shop/module/wcp_peach_pay/webhook，可能包含语言代码，例如 /en/。请完全按照设置中显示的样子复制该 URL。请联系 Peach Payments（support@peachpayments.com），用此 URL 为您的账户启用 Card Webhook，然后在相同模式的 Webhook Decryption Key 字段中输入您收到的解密密钥。
Peach Payments 会对每个 Webhook 进行加密（AES-256-GCM）。无法用测试或正式密钥解密的 Webhook 会被拒绝，因此只有 Peach Payments 才能更改您的订单。使用某一模式密钥解密的 Webhook，只会应用于在该模式下发起的付款。模块使用以下付款通知：
其他通知（例如启用 Webhook 时发送的测试通知）会收到 ignored 响应。没有 Webhook 密钥时，只有顾客付款后返回商店，才会创建订单。
Payment form
Card brands：Peach Payments 表单中显示的品牌：Visa、Mastercard、American Express、Diners Club。请只选择您 Entity ID 已启用的品牌。默认：Visa 和 Mastercard。如果未选择任何品牌，保存时会显示警告，表单则显示 Visa 和 Mastercard。
Advanced
Logging：将 API 请求和付款结果记录到模块文件夹中的 logs/peach_p_debug.log.php。该文件无法通过网页读取。错误和警告始终会被记录。日志不包含银行卡数据、密钥或顾客数据。默认：关闭。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Delete data on uninstall：开启后，卸载模块时会删除模块设置和日志。订单中的 Peach Payments 数据（结账尝试、付款 ID）和订单状态会保留，因为它们属于订单。默认：关闭。
结账
顾客选择付款方式（默认为 Credit / Debit Card (Peach Payments)）并确认订单。在测试模式下，付款方式会显示 Test mode: no real payment will be made. 模块会以购物车货币为购物车总额准备一个 Peach Payments 结账，并在您商店中显示 Peach Payments payment 页面，其中包含 Peach Payments 银行卡表单和所选银行卡品牌；如果 Peach Payments 支持顾客的语言，页面会使用该语言。在测试模式下，页面会显示 Test mode: use a Peach Payments test card, no real payment will be made. 银行卡信息在 Peach Payments 表单中输入，表单脚本使用 Subresource Integrity 哈希加载。Choose another payment method 链接会返回结账页面。此时尚未创建订单。刷新页面时，除非购物车已更改，否则最多 25 分钟内会重复使用同一个结账。
付款后，顾客返回您的商店。只有在 Peach Payments 确认后，订单才会被标记为已付款：商店会通过 Peach Payments API 读取此购物车的结账结果（使用创建结账时的模式），并检查该付款是否属于此购物车。Webhook 也会独立执行同样的操作，因此先到达的那个会创建订单，另一个不会做任何更改。之后，顾客会看到标准的订单确认页面。
如果付款未完成，顾客会带着提示返回结账页面，并可以重试：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 密钥，则会要求顾客联系您。
如果无法准备付款表单，顾客会停留在结账页面并看到简短提示：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. 技术原因会写入日志。
即使商店处于维护模式，Webhook 仍然可以工作，并且不受您商店国家限制的影响。
模块在结账步骤本身不提供银行卡表单，也不支持保存银行卡、订阅、预授权和扣款，以及 EFT、BNPL、QR 或其他非银行卡付款方式。
订单
订单状态
No order yet：顾客尚未付款，付款被拒绝或未完成，或 Peach Payments 尚未确认。此时只存在购物车，顾客可以再次付款。
Payment accepted：付款已确认，且金额和货币与购物车一致。付款会以 Peach Payments 付款 ID 作为交易 ID 记录，并且备注中会显示 Peach Payments 结果代码、描述和付款 ID。如果 Peach Payments 将付款标记为需要人工审核，备注会提醒您在发货前到 Peach Payments 控制面板中核实。
Awaiting Peach Payments payment：Peach Payments 报告了一笔等待确认的付款。之后，Webhook 会将订单更改为 Payment accepted，或将其标记为失败。
Peach Payments payment on hold：已付金额或货币与购物车不一致（备注：amount/currency mismatch — manual review required），或付款是在订单被取消之后到达的。备注会说明需要检查什么。请在 Peach Payments 控制面板中核实付款，然后处理订单或退款。
Payment error：Peach Payments 拒绝了等待中的订单所等待的付款。被拒绝的尝试绝不会更改已付款、保留或已取消的订单。
如果已付款订单的第二笔付款成功，订单不会改变。备注会说明这是重复付款，并要求您在 Peach Payments 控制面板中退款。为已退款订单到达的付款，只会记录在订单上。
Peach Payments 付款区块
订单页面会显示 Peach Payments payment 区块，其中包括付款 ID、结账 ID、商户交易 ID、发送至 Peach Payments 的金额、结果和结果代码、测试付款的 Test mode 标记，以及订单的 Peach Payments notes。
退款
无法从 PrestaShop 订单页面退款。请在 Peach Payments 控制面板中退款，并在需要时在 PrestaShop 中记录（部分退款或退款单）。设置 Webhook 后，在 Peach Payments 中进行的退款、撤销和拒付会连同金额和 ID 一起添加到订单备注中；订单状态不会更改。
许可证密钥
模块需要使用来自 vibefox.net 的 VibeFox 许可证密钥。License — VibeFox Peach Payments Pay Gateway 许可证区块位于模块 Modules > Module Manager > VibeFox Peach Payments Pay Gateway > Configure 页面最上方，位于设置上方。将密钥输入 License key，然后点击 Activate。此后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），并提供以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本商店中移除密钥）。其下方是 Product: presta-payment-peach 行以及 Manage licenses and domains in your account 链接，该链接会打开您的 vibefox.net 账户。只有拥有该模块 Configure 权限的员工才能更改密钥。该区块的文字跟随后台语言显示（包括英语和俄语）。
如果密钥未被接受，该区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached 或 License expired on 加日期。商店地址更改后，或在账户中释放域名名额后，请点击 Check now。如果无法连接许可证服务器，模块会继续使用上次已知的状态运行。
一个密钥只能用于一个域名：主商店的域名，多店铺设置中也是如此。从商店中移除密钥并不会释放其域名名额。请在 vibefox.net 账户中释放名额。
没有有效密钥时，结账时不会向顾客显示 Peach Payments。如果仍然启动了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法识别您已登录后台，因此付款方式对您也会隐藏：您可以在购买密钥之前设置模块，但无法在结账时测试。Modules > Module Manager 的 Alerts 选项卡中会显示提醒。现有订单不受影响：已发起的付款仍会通过顾客返回和 Webhook 得到确认。
许可证到期后，模块仍会继续工作，但更新和支持需要续订。您在后台工作时会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块始终会删除许可证密钥和许可证状态。
故障排除
结账时不显示 Peach Payments：请检查许可证是否有效，Enable/Disable 是否开启，当前模式的 Entity ID 和 Access Token 是否已输入（测试模式为 Test Entity ID 和 Test Access Token，正式模式为 Live Entity ID 和 Live Access Token），以及购物车货币是否为 ZAR、KES 或 MUR。设置顶部的提示会说明问题。在 Payment > Preferences 中，请检查模块是否允许购物车货币、顾客所在国家和顾客所属客户组。
付款已完成，但未创建订单：顾客没有返回商店，Webhook 也没有到达。请检查 Peach Payments 是否为设置中显示的确切 URL 启用了 Card Webhook，是否输入了付款所在模式的 Webhook Decryption Key，以及是否有防火墙或密码保护阻止了该 URL。开启 Logging，并查看 Log 字段中被拒绝的 Webhook。
Webhook 返回 Decryption failed：Webhook 无法用测试密钥或正式密钥解密。密钥错误，或属于其他账户或模式。请输入 Peach Payments 为此 Webhook URL 发送的密钥。
Webhook 返回 Webhook key not configured：测试和正式模式的 Webhook 密钥均未设置或无效。请输入 64 位密钥。Peach Payments 之后会再次发送 Webhook。
Webhook 返回 Busy, retry later：购物车在同一时刻正在由顾客返回处理，或无法创建订单（例如模块已停用）。没有任何更改，Peach Payments 会再次发送 Webhook。日志会显示原因。
Webhook 返回 Missing or malformed data：请求没有加密正文，或缺少 X-Initialization-Vector / X-Authentication-Tag 标头，例如因为代理修改了请求。没有任何更改。
Webhook 返回 ignored：通知是真实的，但不属于本商店的结账（同一 Entity ID 下的其他商店，已删除的购物车），或来自与付款不同的模式。没有任何更改。
Webhook URL 在浏览器中显示 Method not allowed：这是正常的。该 URL 只接受来自 Peach Payments 的请求。
顾客看到 The payment form is not available right now：当前模式的 Access Token 或 Entity ID 有误。请检查凭据和模式，并查看日志中的 Peach Payments 代码。
付款后订单显示为 Peach Payments payment on hold：请阅读 Peach Payments payment 区块中的备注。已付金额或货币与购物车不同，或付款是在订单被取消之后到达的。请在 Peach Payments 控制面板中核实付款，然后处理订单或退款。
保存时提示 Webhook 密钥必须是 64 位十六进制密钥：该值不是 Peach Payments 提供的密钥。在更正之前，Webhook 无法解密。
卸载
前往 Modules > Module Manager，打开 VibeFox Peach Payments Pay Gateway 旁边的菜单，然后选择 Uninstall。此模块的许可证密钥和许可证状态始终会被删除。如果 Delete data on uninstall 已开启，模块设置和日志会被删除。如果已关闭，所有设置都会保留，以便之后重新安装。结账尝试、付款 ID 以及 Awaiting Peach Payments payment 和 Peach Payments payment on hold 订单状态始终会保留。现有订单会保留其付款备注、交易 ID 和 Peach Payments 结账数据。
Peach Payments 是其各自所有者的商标。本模块与 Peach Payments 无关联，也未获得 Peach Payments 的认可。