VibeFox SimplePay for OpenCart — 帮助
要求
OpenCart： 3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
PHP： 8.0 或更高版本。
店铺货币： HUF、EUR 或 USD。SimplePay 不接受其他货币，当顾客选择了其他货币时，不会提供该支付方式。
SimplePay 商户账户： SimplePay 为每种货币提供单独的商户账户，并为正式环境和沙盒分别提供账户。对于每个账户，您都需要从 SimplePay 商户管理后台获取其 MERCHANT 和 SECRET KEY（正式环境为 admin.simplepay.hu，沙盒为 sandbox.simplepay.hu），路径为 account > Technical data。如果您只在 HUF 下销售，则 HUF 账户即可。无需其他密钥。
VibeFox 许可证密钥： 在 vibefox.net 上购买。一个密钥只能用于一个域名。
安装
下载文件是一个 zip 压缩包，内含两个 OpenCart 版本的安装包。请先将其解压到您的电脑上。压缩包中包括 README.txt、OpenCart 3 安装包 wcp_simplepay_gateway-oc3-(version).ocmod.zip，以及 OpenCart 4 安装包 wcp_simplepay_gateway.ocmod.zip。请只安装与您的 OpenCart 版本对应的安装包。两个版本使用相同的许可证密钥。
OpenCart 3
1. 在管理后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_simplepay_gateway-oc3-(version).ocmod.zip。本扩展没有 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装器，而是将本安装包中 upload 文件夹的内容复制到店铺的根目录。
2. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox SimplePay Gateway，点击 Install（绿色 + 按钮）。您的管理员用户需要有修改支付扩展列表的权限。
3. 点击 Edit（铅笔按钮）打开设置页面。将您的 VibeFox 许可证密钥粘贴到页面顶部许可证区块的 License key 中，然后点击 Activate（参见 License key）。
4. 为您销售的每种货币输入 SimplePay 账户的 MERCHANT 和 SECRET KEY：测试用沙盒账户，真实付款用正式账户（参见 Configuration）。
5. 将设置页面显示的 IPN URL 复制到 SimplePay 商户管理后台中的每个商户账户（正式和沙盒）。
6. 开启 Enable/Disable，然后点击 Save。在开启 Sandbox mode 的情况下测试一笔付款，然后关闭 Sandbox mode 以接受真实付款。
OpenCart 4
1. 在管理后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_simplepay_gateway.ocmod.zip。请勿重命名该文件：OpenCart 4 会从文件名获取扩展代码，重命名后的安装包将无法使用。
2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。
3. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox SimplePay Gateway，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。
4. 请按照 OpenCart 3 的步骤 3 至 6 输入许可证密钥、商户账户和 IPN URL。两个版本的设置页面及其字段完全相同，只有 IPN URL 不同（参见 IPN URL）。
新安装时，支付方式默认关闭，并开启沙盒模式。
配置
所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox SimplePay Gateway > Edit。各设置区块列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，当店铺的默认货币不受 SimplePay 支持，或当前模式下没有该货币的商户账户时，页面会向您发出警告。在这两种情况下，都不会为该货币的订单提供该支付方式。开启沙盒模式时，页面会显示 Sandbox mode is on: payments go to the SimplePay sandbox, no real money is charged. 如果没有修改扩展的权限，页面会显示设置但无法保存。
保存时，Title 不能为空（最多 128 个字符），Sort Order 必须为整数（允许负值），Total 必须为大于或等于 0 的数字，并且地理区域和订单状态必须存在。如果某个值有误，则不会保存任何内容。
SimplePay (OTP)
Enable/Disable: Enable SimplePay Gateway 用于开启或关闭该支付方式。Default: off.
Title: 顾客在结账时看到的支付方式名称。它也是订单中保存的支付方式名称。Default: SimplePay (Card Payment). 必填。
Description: 在 Confirm Order 步骤中、确认按钮上方显示给顾客的文字。Default: Pay securely with your credit or debit card via SimplePay. 匈牙利商户可以在此处填写 SimplePay 数据传输声明。
Sandbox mode: 使用 SimplePay 沙盒和沙盒商户账户进行测试付款。它会同时切换 API 地址和商户账户。不会收取真实费用。Default: on. 关闭后，将使用正式商户账户接受真实付款。开启时，顾客在 Confirm Order 步骤会看到 Sandbox mode: no real payment is taken. 在沙盒中发起的订单始终在沙盒中退款。
Sort Order: SimplePay 在结账页面支付方式中的位置。可留空，或输入整数（允许负值）。
Geo Zone: 仅对所选地理区域内的付款地址提供 SimplePay。Default: All zones。地理区域在 System > Localisation > Geo Zones 中设置。
Total: 订单在结账时必须达到的、以店铺默认货币计算的金额，达到后才会提供 SimplePay。留空则对任何金额都提供 SimplePay。
正式商户账户
当 Sandbox mode 关闭时使用的账户。请填写您店铺销售的各货币对应的账户。MERCHANT 和 SECRET KEY 的值位于 SimplePay 商户管理后台（admin.simplepay.hu，那里有各部分的链接），路径为 account > Technical data。只有当两个字段都已填写时，账户才会被使用。
HUF account — Merchant ID: 您的 HUF 正式账户的 MERCHANT。
HUF account — Secret key: 您的 HUF 正式账户的 SECRET KEY。
EUR account — Merchant ID 和 EUR account — Secret key: 您的 EUR 正式账户的相同内容。
USD account — Merchant ID 和 USD account — Secret key: 您的 USD 正式账户的相同内容。
沙盒商户账户
当 Sandbox mode 开启时使用的账户。字段与正式账户相同：HUF account — Merchant ID、HUF account — Secret key，以及 EUR 和 USD 的相同字段对。请从 SimplePay 沙盒商户管理后台（sandbox.simplepay.hu）的 account > Technical data 中获取这些值。
已保存的密钥不会再次显示。该字段将保持为空，并显示 Saved — leave empty to keep it. 只有在您想更改时才输入新值。要删除已保存的密钥，请勾选字段下方的 Clear the saved secret key，然后点击 Save。
IPN URL
IPN 是付款状态变化时 SimplePay 发送给您店铺的消息。它是订单获得状态的常规途径。该部分会显示您店铺的 IPN URL。OpenCart 3 中它的格式类似 https://your-store/index.php?route=extension/payment/wcp_simplepay_gateway/ipn，OpenCart 4 中则类似 https://your-store/index.php?route=extension/wcp_simplepay_gateway/payment/wcp_simplepay_gateway.ipn，由您 OpenCart 安装的前台地址生成。请在 SimplePay 商户管理后台为每个商户账户（正式和沙盒）设置此 URL。请完全按照设置中显示的样子复制 URL，因为被重定向的 IPN 会丢失。
IPN 必须使用其所指定商户账户的 SECRET KEY 签名，并且签名所用的模式（沙盒或正式）必须与付款发起时的模式一致。没有有效签名的 IPN 会被拒绝。扩展会以 SimplePay 要求的签名格式，向 SimplePay 确认每个有效的 IPN。使用以下 IPN 状态：
被拒绝、已取消和超时的状态仅会针对尚未有任何付款成功的购物车的最新一次付款尝试进行记录。其他状态不会产生任何变化。没有 IPN 时，只有当顾客在付款成功后返回店铺时，订单才会获得状态。
订单
OpenCart 会在 Confirm Order 步骤创建没有状态的订单（缺失订单，missing order）。只有在 SimplePay 确认付款之后，订单才会获得状态。状态字段会列出您的 OpenCart 订单状态。
Order Status After Payment: 已付款订单获得的状态。
Paid Order Status: 当 Order Status After Payment 为 Processing 时，已付款订单的状态。Default: Processing.
Complete Order Status: 当 Order Status After Payment 为 Completed 时，已付款订单的状态。Default: Complete.
On Hold (Review) Status: 付款金额或货币与订单不同（参见 Order statuses）。Default: Pending，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择它。
Refunded Status: 在订单页面将付款全额退款后设置。Default: Refunded.
高级
Logging: 将 API 调用、IPN 和返回信息写入 OpenCart 日志文件夹（storage/logs）中的 simplepay_op_debug.log.php。该文件无法通过网页打开，达到 5 MB 时会被轮转。密钥和顾客数据不会被记录。即使关闭此选项，错误也始终会被记录。Default: off.
Log: 显示日志的大小和最新条目。点击 Clear log 可清空日志。
Delete Data on Uninstall: 开启后，卸载扩展会删除网关设置和日志。订单数据（SimplePay 交易和退款）始终会保留。Default: off.
导入 / 导出
Export: Download JSON 将设置保存为 JSON 文件。密钥不会被导出。
Import: 粘贴之前导出的 JSON，然后点击 Import 恢复设置。已保存的密钥会被保留。
结账
在 Payment Method 步骤，顾客选择支付方式（默认为 SimplePay (Card Payment)）。在 Confirm Order 步骤，顾客会看到您的描述以及提示 You will be redirected to the SimplePay payment page to pay by card. OpenCart 在此步骤创建订单，此时仍没有状态。当顾客点击 Confirm Order 时，扩展会以订单货币、按订单总额，使用当前模式下该货币的商户账户发起一笔 SimplePay 银行卡付款，并将顾客带到 SimplePay 付款页面。顾客的电子邮件以及（如果已完整填写）付款地址会传递给 SimplePay。若 SimplePay 支持订单的语言，付款页面会使用该语言，否则使用英文。已发起的付款可在 30 分钟内完成。在 OpenCart 4 中，顾客通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式，然后点击结账页面底部的 Confirm Order。
付款成功后，顾客返回您的店铺。仅仅返回本身绝不会支付订单：扩展会通过带签名的请求向 SimplePay 查询交易状态，因此即使 IPN 延迟，订单也会获得状态。只有当 SimplePay 确认付款后，订单才会被标记为已付款。然后，订单会以 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存，顾客会看到 OpenCart 的订单成功页面，其中包含 Successful transaction. SimplePay transaction ID: 及其 ID。如果 SimplePay 尚未确认付款，Payment confirmation 页面会显示 Your payment is being confirmed by SimplePay. SimplePay transaction ID: 及其 ID、Your order will be confirmed as soon as SimplePay confirms the payment — please do not pay again.，以及 Check again 和 Back to checkout 按钮；IPN 一到达就会设置订单状态。
如果付款失败、被取消或超时，顾客会带着 SimplePay 的消息和交易 ID 回到结账页面，例如 Cancelled payment. You cancelled the payment 或 Timeout. The time allowed to complete the payment has expired。付款失败时，会请顾客检查所输入的信息，并联系发卡银行。订单保持无状态，购物车会被保留，顾客可以重试。OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单。OpenCart 4 只为结账保留一个订单并更新它，因此下一次尝试支付的是同一个订单。每次尝试都会获得自己的 SimplePay 参考号：OC、订单号和尝试次数，例如 OC123-1，随后是 OC123-2。如果同一购物车的另一个订单已经付款或处于审核中，顾客会直接进入成功页面，而不会再次付款。
如果 SimplePay 无法发起付款，顾客会停留在 Confirm Order 步骤，并看到 The SimplePay payment could not be started. Please try again or choose another payment method. 如果订单货币没有商户账户，消息为 SimplePay is not available for the currency of this order. Please choose another payment method. 技术原因会写入日志。无法与任何付款尝试匹配的返回，会显示 We could not match this payment to an order. If you were charged, please contact us.
在 OpenCart 4 中，将顾客带回结账页面的提示会显示在结账页面上方。如果本次结账的订单在此期间已被关闭，顾客会被带回结账页面，并看到 Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order.；如果该订单已有 SimplePay 付款，则会看到 Your previous order was cancelled or refunded by the store. Please confirm the order again to pay with a new order.。下一次点击 Confirm Order 将为一个新订单付款。如果本次结账的订单已付款，但之后购物车发生了变化（包括新的数量），顾客会被带回结账页面，并为新购物车创建新订单付款。
即使店铺处于维护模式，IPN 和顾客的返回也同样有效：OpenCart 3 允许付款扩展的请求通过，而在 OpenCart 4 中，扩展会为此添加一个启动操作。
本扩展仅接受在 SimplePay 页面上完成的一次性银行卡付款。它不支持已保存的银行卡或一键付款、订阅或定期付款，也不支持分开的授权与扣款。
订单与退款
订单状态
No status (missing order): 顾客已被转到 SimplePay 但尚未付款，付款失败、被取消或超时，或 SimplePay 尚未确认付款。在 Sales > Orders 中，这类订单只有在筛选器 Order Status 设为 Missing Orders 时才会显示。
Paid Order Status or Complete Order Status: 付款已被确认。状态遵循 Order Status After Payment。备注会显示 SimplePay 交易 ID，以及确认付款的是 IPN 还是状态查询。
On Hold (Review) Status (default Pending): 付款发起之后，订单总额或货币被更改，因此已付金额与订单不一致。备注会显示两个金额。请检查订单，并在 SimplePay 商户管理后台履行订单或为付款退款。如果之后同一购物车的另一次尝试以正确金额付款，则该付款对应的订单会获得已付款状态。
Refunded Status (default Refunded): 付款已通过扩展全额退款。
已付款、已退款或已完成的订单，不会因为延迟的 IPN 而被重新打开。如果对已付款的订单，或对同一购物车的另一个订单，第二笔付款成功，已付款的订单不会被更改。备注会要求您在 SimplePay 后台检查，如果是重复付款，则将其退款。
备注是订单 History 中的条目，顾客看不到。
VibeFox SimplePay Gateway tab
在 Sales > Orders 中打开一笔通过 SimplePay 付款的订单。在订单页面底部，紧挨着 History 和 Additional，VibeFox SimplePay Gateway 选项卡会显示 Transaction ID（沙盒付款会带有 Sandbox 标签）、Order reference (orderRef)、Merchant account 及其模式、SimplePay 的 Status、Paid / refunded 金额、退款表单、退款历史记录、若有多次尝试则显示的 Payment attempts of the cart，以及订单的 SimplePay notes。该选项卡对有权访问扩展的用户显示。
退款
在 VibeFox SimplePay Gateway 选项卡中输入 Amount（尚未退款的金额会自动填入），可选填 Reason (optional, order note only)，然后点击 Refund via SimplePay (OTP)。确认提问 Refund this amount via SimplePay? This cannot be undone. 支持全额和部分退款。您需要有修改扩展的权限（在 System > Users > User Groups 中设置）。HUF 退款必须为整数福林。退款会发送到支付订单的那笔 SimplePay 交易，使用该付款的商户账户和模式（沙盒或正式），即使之后店铺已切换到另一模式也是如此；该账户必须仍在设置中。如果 SimplePay 不接受退款，选项卡会显示错误，并且不会记录任何退款。成功的退款会连同 SimplePay 退款交易以及（如果您填写了）原因一起添加到历史记录和备注中。全额退款会将订单设为 Refunded Status，且不通知顾客，也不会将商品退回库存，与手动更改状态一样。部分退款不会更改状态。因金额不一致而处于审核中的订单，无法通过该选项卡退款：请在 SimplePay 商户管理后台中为其退款。
在 Sales > Returns 中的商品退货不会通过 SimplePay 退回资金。在 SimplePay 商户管理后台进行的退款不会同步到 OpenCart。请手动记录。
许可证密钥
本扩展需要使用在 vibefox.net 获取的 VibeFox 许可证密钥。许可证区块 License — VibeFox SimplePay Gateway 是 Extensions > Extensions > Payments > VibeFox SimplePay Gateway > Edit 中的第一个区块，位于设置上方。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期的截止日期以及您的域名），并提供以下按钮：Check now（再次检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺中移除该密钥）。它们下方有一行 Product: opencart-payment-simplepay，以及打开您 vibefox.net 账户的链接 Manage licenses and domains in your account。只有对该扩展拥有 Modify 权限的管理员用户才能更改密钥。该区块的文字跟随管理后台语言显示（包括英文和俄文）。
如果密钥未被接受，该区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或 License expired on 加上日期。店铺地址变更后，或在您的账户中释放了域名名额后，请点击 Check now。如果无法连接许可证服务器，扩展会继续使用最后一次已知的状态运行。
一个密钥只能用于一个域名：即 OpenCart 配置中的店铺地址。从店铺中移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效密钥时，SimplePay 不会在结账时向顾客显示。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 以同一浏览器登录管理后台的管理员用户，仍会在店铺中看到该支付方式，并标有 (unlicensed — visible to admins only)，这样您就可以在购买密钥之前设置和测试扩展。在 OpenCart 4 中没有此预览功能：店铺无法看到后台登录状态，因此没有有效密钥时，所有人都看不到该付款方式。打开一次 Edit 页面之后，管理后台的 Dashboard 上会出现一条提醒。点击 × 可将其隐藏 7 天。现有订单不受影响：已经发起的付款仍会通过 IPN 得到确认，退款也可以正常进行。
许可证到期时，扩展仍会继续运行，但更新和支持需要续订。当您打开管理后台的 Dashboard 或 Edit 页面时，系统会自动再次检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需定时任务。卸载扩展时，始终会删除许可证密钥和许可证状态。
故障排除
SimplePay 未出现在结账页面： 请检查许可证是否有效、Enable/Disable 是否开启、顾客的货币是否为 HUF、EUR 或 USD，以及该货币在当前模式下是否同时具有 Merchant ID 和 Secret key：Sandbox mode 开启时使用沙盒账户，关闭时使用正式账户。另外请检查付款地址是否位于所选的 Geo Zone 内，以及订单是否达到了设置中的 Total。
付款已完成，但订单仍无状态： IPN 没有到达店铺。请在 SimplePay 商户管理后台中检查您所用商户账户（正式或沙盒，订单货币）的 IPN URL。它必须与设置中显示的 URL 完全一致，并且您的服务器必须能够从互联网访问。顾客付款后返回店铺时，订单也会获得状态。
IPN 返回 Invalid signature.： IPN 指定了设置中不存在的商户账户，其 Secret key 有误，或者它是用与付款模式不同的那个账户签名的。请完全按照 SimplePay 商户管理后台显示的内容输入 MERCHANT 和 SECRET KEY。SimplePay 会重新发送未确认的 IPN。
IPN 返回 Order not found. 或 Unknown transaction.： 该 IPN 对应的是本店铺并未发起的付款。不会更改任何内容。
IPN 返回 Busy, retry.： 购物车在同一时刻正被另一请求处理，或无法设置订单状态。SimplePay 会重试 IPN。原因会写入日志。
顾客看到 The SimplePay payment could not be started： 请查看扩展页面上的 Log 字段。商户密钥错误会导致 Invalid response signature from SimplePay. Check the secret key of the merchant account. SimplePay 的错误会连同错误代码一起写入日志。
顾客看到 This payment method is not available.： 结账页面已与订单不再匹配，或支付方式在此期间被关闭。顾客重新加载结账页面。
在沙盒与正式模式之间切换后： 新付款会使用新模式的账户。之前发起的付款会保留其发起时所用的商户账户和模式：它们的 IPN、状态查询和退款都会使用该账户。在仍有未完成或可能需要退款的付款时，请在设置中保留旧模式的账户。
订单在付款后处于审核状态： 请阅读 VibeFox SimplePay Gateway 选项卡中的备注。付款发起后，订单总额或货币被更改了。请在 SimplePay 商户管理后台履行订单或为付款退款。
选项卡中没有退款表单： 选项卡会说明原因：订单未通过 SimplePay 交易付款（例如金额不一致之后）、已全额退款、您的用户组没有修改扩展的权限，或付款的商户账户不在设置中。
退款失败： 请阅读选项卡中的消息。SimplePay refunds in HUF must be whole amounts. 表示 HUF 金额包含小数。如果消息提示该付款的商户账户未配置，请重新输入付款时所用的账户（货币和模式）。如果 SimplePay 退还的金额不同，消息会要求您在 SimplePay 后台检查该退款。
面向开发者：在付款发起之前，扩展会触发 OpenCart 事件 simplepay_op_payment_data，并附带付款数据和订单。商户、订单参考、货币、总额和返回 URL 不能在此处更改。
卸载
进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox SimplePay Gateway 旁边的 Uninstall（红色 − 按钮）。本扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Orders 部分中的订单状态，这些设置在重新安装时会恢复为默认值。扩展的 OpenCart 事件也会被删除（在 OpenCart 4 中，还包括其事件和启动操作，启动操作用于在维护模式下放行 IPN 和顾客的返回）。如果 Delete Data on Uninstall 已开启，其他网关设置（标题、描述、沙盒模式、商户账户、日志）和日志都会被删除。如果未开启，这些内容会被保留，以便日后重新安装时使用。SimplePay 交易和退款始终会保留，因此，之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款备注。
在 OpenCart 4 中，如需删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox SimplePay Gateway 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。
SimplePay 是其各自所有者的商标。本扩展与 SimplePay 无关联，也未获得 SimplePay 的认可。