VibeFox Peach Payments for OpenCart — 帮助
系统要求
OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
PHP：8.0 或更高版本，并启用 OpenSSL 扩展（用于解密 Webhook）。
货币：顾客的结账货币必须为 ZAR、KES 或 MUR，因此您的店铺需要在 System > Localisation > Currencies 中至少添加其中一种货币。对于使用其他货币付款的顾客，付款方式会被隐藏。如果店铺的默认货币不是其中之一，设置页面会向您发出警告。
Peach Payments 账户：您需要 Peach Payments 账户的 Card API 凭据：Entity ID 和 Access Token。测试凭据来自 Peach Payments 沙盒控制台，正式凭据来自 Peach Payments 控制台，两者不同。对于 Webhook，您还需要一个 Webhook 解密密钥，当 Peach Payments 为您的店铺启用 Card Webhook 时会将其发送给您（参见配置）。您的店铺必须可从互联网访问，才能接收 Webhook。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
下载文件是一个 zip 压缩包，内含两个 OpenCart 版本的安装包。请先在电脑上解压。其中包括 README.txt、OpenCart 3 安装包 wcp_peach_pay-oc3-(version).ocmod.zip，以及 OpenCart 4 安装包 wcp_peach_pay.ocmod.zip。只安装与您 OpenCart 版本对应的安装包。两个版本使用相同的许可证密钥。
OpenCart 3
1. 在后台进入 Extensions > Installer，点击 Upload，选择文件 wcp_peach_pay-oc3-(version).ocmod.zip。本扩展没有 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装器，而是将本安装包中 upload 文件夹的内容复制到店铺的根目录。
2. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox Peach Payments Pay Gateway，点击 Install（绿色 + 按钮）。您的管理员用户需要具有修改付款扩展列表的权限。
3. 点击 Edit（铅笔按钮）打开设置页面。将您的 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 沙盒测试卡以 ZAR、KES 或 MUR 完成一次付款。然后关闭 Test mode，输入正式凭据和正式 Webhook 密钥，并点击 Save。
OpenCart 4
1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_peach_pay.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名中读取扩展代码，重命名后的安装包无法使用。
2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。
3. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox Peach Payments Pay Gateway，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。
4. 按照 OpenCart 3 的第 3–5 步输入许可证密钥、Peach Payments 凭据和 Webhook。设置页面及其字段在两个版本中相同。仅 Webhook URL 不同（参见「Webhook」）。
新安装时，付款方式默认关闭，测试模式默认开启。
配置
所有设置都在扩展页面中：Extensions > Extensions > Payments > VibeFox Peach Payments Pay Gateway > Edit。各部分列在左侧；列表下方的 Save 按钮保存整个页面。在设置上方，页面会显示以下提示：Test mode is on: payments go to the Peach Payments sandbox and no real money is charged.；当前模式的 Entity ID 或 Access Token 缺失时显示错误（在此之前，结账页面不会显示该付款方式）；当前模式的 Webhook 解密密钥缺失时显示警告（此时只有在顾客返回店铺后才会确认付款）；店铺默认货币不受支持时显示通知（此时该付款方式仅向使用受支持货币付款的顾客显示）。若没有修改扩展的权限，页面会显示设置，但无法保存。
保存时，Title 不能为空，且不能超过 128 个字符（页面会显示 Enter a title for the payment method (up to 128 characters).）；Sort Order 必须是整数（允许负值）；Total 必须是大于或等于 0 的数字；地理区域和订单状态必须存在。否则不会保存任何内容。凭据中的空格会被删除。如果 Webhook 密钥不是 64 位十六进制值，或卡品牌列表为空，则会保存并给出警告。
Peach Payments
Enable/Disable：Enable Peach Payments 用于开启或关闭该付款方式。默认：关闭。
Title：顾客在结账时看到的付款方式名称。订单中保存的付款方式名称也是它。默认：Credit / Debit Card (Peach Payments)。必填，最多 128 个字符。
Description：在 Confirm Order 步骤中、确认按钮上方、卡片图标旁显示给顾客的文字。默认：Pay securely with your card. You will enter the card details in the Peach Payments form on the next page.
Sort Order：Peach Payments 在结账付款方式中的位置。可留空或输入整数。
Geo Zone：仅向所选地理区域内的付款地址提供 Peach Payments。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。
Total：订单必须达到的结账总额（以店铺默认货币计）才会提供 Peach Payments。留空则对任何金额都提供。
API 凭据
Card API 的 Access Token 和 Entity ID 显示在 Peach Payments 控制台中（测试凭据位于沙盒控制台）。本节提供指向两个控制台以及 Peach Payments 开发者文档的链接。
Test mode：使用测试凭据将新付款发送到 Peach Payments 沙盒，不会收取真实款项。若要使用正式凭据接受真实付款，请关闭此项。在一种模式下发起的付款，即使之后切换模式，也始终会在该模式下进行核对。默认：开启。开启期间，顾客在 Confirm Order 步骤会看到 Test mode: no real payment will be made.
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 the saved value on save，然后点击 Save。
Webhook
即使顾客在返回店铺之前关闭了浏览器，Webhook 也会确认付款。Webhook URL 字段显示您店铺的 Webhook URL。在 OpenCart 3 中其格式类似 https://your-store/index.php?route=extension/payment/wcp_peach_pay/webhook，在 OpenCart 4 中为 https://your-store/index.php?route=extension/wcp_peach_pay/payment/wcp_peach_pay.webhook，由您 OpenCart 安装的前台地址生成。请完全按照设置中显示的内容复制该 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 密钥时，订单只有在顾客付款后返回店铺时才会获得状态。
付款表单
Card brands：Peach Payments 表单中显示的卡品牌：Visa、Mastercard、American Express、Diners Club。请仅选择为您的 Entity ID 启用的品牌。默认：Visa 和 Mastercard。如果未选择任何品牌，保存时会显示警告，且表单会显示 Visa 和 Mastercard。
订单
订单在 Confirm Order 步骤中创建时不带状态（即缺失订单），只有在 Peach Payments 确认付款后才会获得状态。被拒绝或中途放弃的付款会使订单保持无状态，购物车会被保留。下面的每个字段都列出了您的 OpenCart 订单状态。
Order Status After Payment：当 Peach Payments 确认付款且金额和货币一致时设置。默认：Processing。
Awaiting Payment Status：Peach Payments 报告了一笔等待确认的异步付款；之后由 Webhook 进行确认。默认：Pending，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择它。
On Hold (Review) Status：人工审核：已付金额或货币与订单不符，或付款在订单被取消后才到达。备注会说明原因。默认：Pending。
Payment Failed Status：订单所等待的异步付款被拒绝时设置。之后的成功付款仍会完成订单。默认：Failed。
Canceled Status：扩展不会设置此状态。对处于此状态的订单的付款会将其转为审核，而不是重新打开。默认：Canceled。
Refunded Status：扩展不会设置此状态。对处于此状态的订单收到的付款只会被备注，订单本身不会改变。默认：Refunded。
高级
Logging：将 API 请求和付款结果记录到 OpenCart 日志文件夹（storage/logs）中的 peach_p_debug.log.php。该文件无法通过网页读取，当其达到 5 MB 时会被移动到 peach_p_debug.old.log.php。错误和警告始终会被记录。日志不包含银行卡数据、密钥或顾客数据。默认：关闭。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Delete data on uninstall：开启时，卸载扩展会删除网关设置和日志。订单的 Peach Payments 数据（结账尝试和付款 ID）会被保留，因为它们属于订单。默认：关闭。
导入 / 导出
Export：Download JSON 会将设置保存为 JSON 文件。访问令牌和 Webhook 密钥不会被导出。
Import：粘贴之前导出的 JSON，然后点击 Import 以恢复设置。已保存的访问令牌和 Webhook 密钥会被保留。
结账
在 Payment Method 步骤中，顾客选择付款方式（默认为 Credit / Debit Card (Peach Payments)）。在 Confirm Order 步骤中，顾客会看到一个卡片图标和您的说明；OpenCart 在此步骤创建订单，但仍无状态。当顾客点击 Confirm Order 时，扩展会为订单货币下的订单总额准备一个 Peach Payments 结账，并打开您店铺的 Peach Payments payment 页面，其中包含 Please enter your card details to complete the 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 分钟。在 OpenCart 4 中，顾客通过付款方式区块的 Choose 按钮（位于 Payment method options 窗口中）选择付款方式，并点击结账页面底部的 Confirm Order。
付款完成后，顾客返回您的店铺。只有在 Peach Payments 确认付款后，订单才会被标记为已付款：店铺会从 Peach Payments API 读取该订单结账的结果（使用创建该结账时所处的模式），并核对该付款确实属于此订单。Webhook 也会独立地执行相同操作；哪个先到达，哪个就设置订单状态，另一个不会造成任何更改。随后，订单会以 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存，顾客会看到 OpenCart 订单成功页面。在 OpenCart 4 中，当顾客从银行的 3-D Secure 页面返回时，一个简短的中间页面会再次打开您店铺的返回地址，从而保留购物车和顾客登录状态。
如果付款未完成，顾客会返回结账页面并看到消息，然后可以重试：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 密钥时，顾客会被要求联系您。在 OpenCart 4 中，这些消息显示在结账页面上方。
OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单，OpenCart 4 则更新结账中的订单，但同一购物车只会付款一次：如果同一购物车的另一订单已付款，顾客会直接进入成功页面。购物车的任何变动（包括新的数量）都视为需要单独付款的新购物车。
OpenCart 4 会在显示成功页面之前，将订单保留在结账流程中。在一次被拒绝的尝试之后，顾客会通过新的 Peach Payments 结账为同一订单再次付款。如果该订单在此期间被关闭（例如其等待中的付款失败，或您取消了它），顾客会被送回结账页面，并显示消息 您之前的订单已关闭或已付款。请重新确认订单，以新订单付款。 下一次 Confirm Order 将为新订单付款。如果订单已付款，之后被您取消或退款，消息为 此订单已被商店取消或退款。请就其付款与商店联系，或重新确认订单：购物车将以新订单付款。
如果无法准备付款表单，顾客会停留在 Confirm Order 步骤并看到一条简短消息：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 同样有效，因为 OpenCart 会放行付款扩展的请求（在 OpenCart 4 中，扩展会为此添加一个启动动作，该动作同时允许顾客返回）。
本扩展在结账步骤本身没有银行卡表单，不支持保存银行卡、订阅、预授权后再捕获，也不支持 EFT、BNPL、QR 或其他非银行卡付款方式。
订单
订单状态
无状态（缺失订单）：顾客未付款、付款被拒绝或未完成，或 Peach Payments 尚未确认。顾客可以再次付款。在 Sales > Orders 中，这类订单仅在 Order Status 筛选器设为 Missing Orders 时才会显示。在 OpenCart 4.1 中，此类订单还可能带有 Voided 状态（OpenCart 在再次显示确认步骤时设置），扩展会将其视为无状态订单。
Order Status After Payment（默认 Processing）：付款已确认，且金额和货币与订单一致。备注会显示 Peach Payments 的结果代码、说明和付款 ID。如果 Peach Payments 将该付款标记为需要人工审核，备注会要求您在发货前在 Peach Payments 控制台中核对。
Awaiting Payment Status（默认 Pending）：Peach Payments 报告了一笔等待确认的付款。之后，Webhook 会将订单转为 Order Status After Payment 或 Payment Failed Status。
On Hold (Review) Status（默认 Pending）：已付金额或货币与订单不符（备注 amount/currency mismatch — manual review required），或付款在订单被取消后才到达。请在 Peach Payments 控制台中核对付款，然后处理订单或退还付款。
Payment Failed Status（默认 Failed）：Peach Payments 拒绝了待付款订单所等待的付款。被拒绝的尝试绝不会改变已付款或处于审核中的订单。
如果已付款订单的第二笔付款成功，或已付款购物车中另一订单的付款成功，已付款订单不会被改变。备注会说明这是重复付款，并要求您在 Peach Payments 控制台中退款。对已退款订单收到的付款只会在订单上做备注。
备注是订单 History 中顾客看不到的条目。
VibeFox Peach Payments Pay Gateway 标签页
在 Sales > Orders 中打开一个通过 Peach Payments 付款的订单。在订单页面底部，紧挨着 History 和 Additional，扩展标签页会显示 Payment ID（测试付款会带有 Test mode 标签）、Checkout ID、Merchant transaction ID、Amount sent to Peach Payments、Result 及结果代码，以及该订单的 Peach Payments notes。该标签页会显示给有权访问本扩展的用户。
退款
无法从 OpenCart 退款。请在 Peach Payments 控制台中退还该付款，并在需要时在 OpenCart 中记录。配置了 Webhook 后，在 Peach Payments 中进行的退款、冲正和拒付会连同金额和 ID 一起添加到订单备注中；订单状态不会改变。Sales > Returns 中的商品退货不会通过 Peach Payments 退还款项。
许可证密钥
本扩展需要配合 vibefox.net 提供的 VibeFox 许可证密钥使用。许可证区块 License — VibeFox Peach Payments Pay Gateway 是 Extensions > Extensions > Payments > VibeFox Peach Payments Pay Gateway > Edit 中设置上方的第一个区块。将密钥粘贴到 License key 中并点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺移除密钥）。其下方是 Product: opencart-payment-peach 一行和 Manage licenses and domains in your account 链接，该链接会打开您的 vibefox.net 账户。只有具有本扩展 Modify 权限的管理员用户可以更改密钥。该区块的文字跟随后台语言显示（包含英语和俄语）。
如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或 License expired on 加上日期。更改店铺地址后，或在您的账户中释放域名名额后，请点击 Check now。如果无法连接许可证服务器，扩展会继续使用最后一次已知的状态运行。
一个密钥只能用于一个域名：即 OpenCart 配置中的店铺地址。从店铺中移除密钥不会释放其域名名额，请在您的 vibefox.net 账户中释放该名额。
没有有效密钥时，Peach Payments 不会在结账时向顾客显示。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 在同一浏览器中登录后台的管理员用户仍会在店铺中看到该付款方式，并标记为 (unlicensed — visible to admins only)，以便您在购买密钥之前设置和测试扩展。在 OpenCart 4 中此预览不可用：店铺看不到管理员登录状态，因此没有有效密钥时，所有人都看不到该付款方式。打开一次 Edit 页面后，后台 Dashboard 上会出现提醒。点击 × 可将其关闭，并隐藏 7 天。现有订单不受影响：已发起的付款仍会通过顾客返回和 Webhook 来完成确认。
许可证到期后，扩展仍会继续工作，但更新和支持需要续费。当您打开后台的 Dashboard 或 Edit 页面时会自动重新检查状态：输入密钥后的前 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 付款。同时检查付款地址是否在所选的 Geo Zone 中，以及订单是否达到设置中的 Total。设置顶部的提示会指出问题所在。
付款已完成，但订单仍无状态：顾客没有返回店铺，且 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 代码。
顾客看到 The payment session was not found. Please confirm the order again.：付款页面是为一个已不再是顾客当前订单的订单打开的，或者付款方式在此期间被关闭。顾客需要重新确认订单。
付款后订单处于审核状态：请阅读扩展标签页中的备注。已付金额或货币与订单不符，或付款在订单被取消后才到达。请在 Peach Payments 控制台中核对付款，然后处理订单或退还付款。
保存时提示 Webhook 密钥必须为 64 位十六进制密钥：该值不是 Peach Payments 提供的密钥。在更正之前，Webhook 无法被解密。
卸载
进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Peach Payments Pay Gateway 旁边的 Uninstall（红色 − 按钮）。本扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Orders 部分的订单状态，这些设置在重新安装时会恢复为默认值。如果 Delete data on uninstall 已开启，其余网关设置（标题、说明、测试模式、凭据、Webhook 密钥、卡品牌、日志记录）和日志也会被删除；如果关闭，则会保留，以便日后重新安装时使用。结账尝试和付款 ID 始终会保留。在 OpenCart 4 中，扩展的事件以及在维护模式下允许 Webhook 和顾客返回的启动动作，始终会被删除。已有订单会保留其付款备注。
在 OpenCart 4 中，如需同时删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox Peach Payments Pay Gateway 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）删除已上传的安装包。
Peach Payments 是其各自所有者的商标。本扩展与 Peach Payments 无关联，也未获得 Peach Payments 的认可或背书。