VibeFox GMO for OpenCart — 帮助
系统要求
OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
PHP：8.0 或更高版本。
货币：日元（JPY）。GMO-PG 仅以日元收款，因此只有当顾客结账时的货币为 JPY 时才会显示该付款方式。如果您的店铺还没有 JPY，请在 System > Localisation > Currencies 中添加。金额为订单总额按店铺的 JPY 汇率换算后，四舍五入到整数日元的结果。
GMO Payment Gateway 账户：一份带有 Link Type Plus 的 GMO-PG 商户合同。您需要测试环境和/或正式环境的 Shop ID、Shop password 和 Link Type Plus Config ID（設定ID），并且需要在 GMO-PG 店铺控制台中开启结果通知（結果通知）（参见 Configuration）。Site ID 和 Site password 不会使用。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
下载文件是一个 zip 压缩包，内含两个 OpenCart 版本的安装包。请将其解压到您的电脑上。压缩包中包含 README.txt、OpenCart 3 安装包 wcp_gmo_payment-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 wcp_gmo_payment.ocmod.zip。只需安装与您的 OpenCart 版本对应的安装包。两个版本使用相同的许可证密钥。
OpenCart 3
1. 在管理后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_gmo_payment-oc3-(version).ocmod.zip。该扩展没有 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装器，直接把本安装包中 upload 文件夹的内容复制到店铺的根目录。
2. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox GMO Payment Gateway，点击 Install（绿色的 + 按钮）。您的管理员用户需要有修改支付扩展列表的权限。
3. 点击 Edit（铅笔按钮）打开设置页面。将您的 VibeFox 许可证密钥粘贴到页面顶部许可证区块中的 License key 中，然后点击 Activate（参见 License key）。
4. 输入测试环境和/或正式环境的 Shop ID、Shop password 和 Config ID，并选择 Environment。
5. 在 GMO-PG 店铺控制台中开启結果通知（result notification），并设置设置页面中显示的通知 URL（参见 Configuration）。
6. 开启 Enable/Disable 并点击 Save。在测试环境中完成一笔测试付款，然后将 Environment 切换为正式环境。
OpenCart 4
1. 在管理后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_gmo_payment.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名读取扩展代码，重命名后的安装包无法使用。
2. 安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。
3. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox GMO Payment Gateway，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。
4. 按照 OpenCart 3 的第 3 至 6 步输入许可证密钥、GMO-PG 凭据和通知 URL。设置页面及其字段在两个版本中相同。仅通知 URL 不同（参见 Payment notifications (結果通知)）。
新安装时，付款方式默认关闭，并选择测试环境。
配置
所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox GMO Payment Gateway > Edit。各个部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，如果店铺默认货币不是 JPY，或当前环境缺少 Shop ID、Shop password 或 Config ID（此时结账时会隐藏该付款方式），页面会发出提示。页面还会显示当前启用的环境：TEST — payments go to pt01.mul-pay.jp with the test credentials, no real money is charged. 或 PRODUCTION — payments go to p01.mul-pay.jp. 如果没有修改扩展的权限，页面只会显示设置，无法保存。
保存时，Title 必须为 1 到 128 个字符，Sort Order 必须为空或整数，Total 必须为空或 0 及以上的数字，并且每个订单状态都必须存在。如果有任何问题，将不会保存任何内容，页面会列出错误。凭据前后的空格会被自动去除。
GMO Payment Gateway — 信用卡
Enable/Disable：Enable GMO Payment Gateway — Credit Card 用于开启或关闭该付款方式。默认：关闭。
Title：顾客在结账时看到的付款方式名称，同时也是订单中保存的付款方式名称。默认：Credit card。必填，最多 128 个字符。
Description：在 Confirm Order 步骤中、确认按钮上方显示的付款方式说明。默认：You will be redirected to the secure GMO Payment Gateway page to pay by credit card.
Sort Order：该付款方式在结账时的排列位置。可留空或输入整数。
Geo Zone：仅向所选地理区域内的付款地址提供该付款方式。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。
Total：订单必须达到的金额（以店铺默认货币计）才会提供该付款方式。留空则对任何金额都提供。
GMO-PG 账户
Shop ID 和 Shop password 位于 GMO-PG 控制台的 Shop management > Shop information 下，Config ID 位于 Link Type Plus > Settings 下（設定ID）。测试环境与正式环境的凭据不同。
Environment：哪个 GMO-PG 环境接收新的付款。
Production Shop ID：正式环境的 Shop ID。
Production Shop password：正式环境的 Shop password。
Production Config ID：在 GMO-PG 控制台中注册的 Link Type Plus config ID（設定ID）。
Test Shop ID：测试环境的 Shop ID。
Test Shop password：测试环境的 Shop password。
Test Config ID：测试环境的 Link Type Plus config ID（設定ID）。
已保存的密码不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。若要删除已保存的密码，请勾选字段下方的 Clear the saved password on save，然后点击 Save。
付款
Capture：何时扣除银行卡款项。
Order status after payment：已付款订单获得的状态。
付款通知（結果通知）
结果通知会告知您的店铺已完成付款。它是必需的。在 GMO-PG 店铺控制台中开启結果通知（result notification），并设置本节 Notification URL 中显示的 URL。该 URL 在 OpenCart 3 中形如 https://your-store/index.php?route=extension/payment/wcp_gmo_payment/notify，在 OpenCart 4 中形如 https://your-store/index.php?route=extension/wcp_gmo_payment/payment/wcp_gmo_payment.notify，由您的 OpenCart 安装的店铺前台地址生成。请完全按照设置中显示的内容复制 URL。该 URL 必须能从互联网访问；维护模式不会阻止它。
GMO-PG 通知不带签名，因此扩展从不信任通知的内容。通知必须来自您配置的某个 Shop ID，并且针对的是本店铺在付款所在环境中创建的付款。随后，扩展会使用您的 Shop password 向 GMO-PG 查询该交易（SearchTrade），并且仅根据该查询结果修改订单。与真实交易不匹配的通知不会产生任何变化。非本店铺创建的交易（例如在 GMO-PG 控制台中完成的交易）会被确认并忽略。当扩展无法核实某个通知时，它会做出响应，使 GMO-PG 重新发送该通知。
如果没有通知，订单只有在顾客付款后返回店铺时才会获得状态。
订单状态
OpenCart 在 Confirm Order 步骤创建订单时不带状态（缺失订单，missing order）。只有在 GMO-PG 确认付款之后，订单才会获得状态。每个字段都列出了您的 OpenCart 订单状态。OpenCart 没有 On hold 状态，因此授权或金额不符的付款会获得下方所述的等待状态，并在订单中添加备注。
Processing：当 Order status after payment 为处理中时，已付款的订单。默认：处理中。
Completed：当 Order status after payment 为已完成时，已付款的订单。默认：已完成。
GMO-PG payment on hold：仅授权（等待扣款）或金额与订单不符。默认：待处理。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。
Cancelled：在 GMO-PG 中被取消的授权或处于等待状态的付款，或已全额退款的授权。默认：已取消。
Refunded：在订单页面全额退款后。默认：已退款。
高级
Debug log：将 API 请求和通知写入 OpenCart 日志文件夹（storage/logs）中的 gmo_pg_debug.log.php。该文件无法通过网页打开；达到 5 MB 时会进行轮转。错误和警告始终会被记录，即使开关处于关闭状态。密码和顾客数据会被掩码处理。默认：关闭。
Log：显示日志的大小和最新记录。点击 Clear log 可清空日志。
Delete data on uninstall：开启后，卸载扩展时会删除网关设置和日志。订单数据（GMO OrderID、交易 ID）始终保留。默认：关闭。
导入 / 导出
Export：Download JSON 将设置保存为 JSON 文件。店铺密码不会被导出。
Import：粘贴先前导出的 JSON，然后点击 Import 以恢复设置。已保存的店铺密码会保留。
结账
在 Payment Method 步骤中，顾客选择付款方式（默认为 Credit card）。在 Confirm Order 步骤中，顾客会看到您的说明；在测试环境中，其上方会显示标识 TEST — GMO-PG test environment, no real charges. OpenCart 在此步骤创建订单，仍然不带状态。在 OpenCart 4 中，顾客通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式，并点击结账页面底部的 Confirm Order。顾客点击 Confirm Order 后，扩展会为订单总额（以整数日元计）创建一笔 GMO-PG Link Type Plus 付款，并将顾客引导至 GMO-PG 付款页面。顾客在该页面使用信用卡付款。3-D Secure 2.0 由 GMO-PG 处理，顾客的电子邮件地址会传递给 GMO-PG 用于 3-D Secure。付款页面会根据订单语言以日语、中文或英语显示。付款在 GMO-PG 中显示为 OC- 加订单号。不会发送其他任何顾客数据。
付款后，顾客返回您的店铺。签名的结果会使用该付款所在环境的 Shop password 进行校验；只有在 GMO-PG 确认付款之后，订单才会被标记为已付款：要么是顾客返回时服务器端发起的 SearchTrade 请求，要么是结果通知。两种方式使用相同的逻辑，因此付款绝不会被重复处理。随后，订单会以 OpenCart 的标准方式获得状态，发送常规订单邮件并更新库存，顾客会看到 OpenCart 的订单成功页面。如果 GMO-PG 尚未确认付款，将显示 Payment confirmation 页面，内容为 Your card payment is being confirmed by GMO Payment Gateway. You will receive an e-mail as soon as it is confirmed.，并带有 Check again 和 Back to checkout 按钮；通知一到达，就会设置订单状态。
如果银行卡被拒绝，或在 GMO-PG 页面上付款失败，顾客会返回结账页面，并显示 The card payment was declined or could not be completed. Please try again or use another card. 如果顾客未付款就离开了 GMO-PG 页面，提示信息为 The payment was not completed. You can try again or choose another payment method. 购物车会被保留。在 OpenCart 4 中，这些消息显示在结账页面上方。每次新的尝试（OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单，OpenCart 4 则更新结账中的订单）都会取消购物车之前未付款的付款链接。如果之前的某个链接在此期间已经付款，则确认该笔付款，不再创建新链接。
在 OpenCart 4 中，订单在显示成功页面之前会一直保留在结账流程中。如果该订单在此期间未付款即被关闭（例如在 GMO-PG 中或由您取消），顾客会被带回结账页面，并显示 Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order.，下一次点击 Confirm Order 时会为购物车支付一个新订单。如果该订单已付款，但之后购物车发生了变化（包括数量变化），则显示 Your previous order has already been placed. Your cart has changed since — please confirm the order again to pay for the current cart with a new order. 已付款的订单绝不会在另一个购物车中显示为已付款。
订单总额在 1 到 9,999,999 JPY 之间可以付款；超过该金额时会隐藏付款方式。如果无法开始付款，顾客会停留在 Confirm Order 步骤，并在按钮上方看到简短提示，例如 Card payment could not be started. Please try again or choose another payment method.，原因会写入日志。
即使店铺处于维护模式，通知和返回也能正常工作，因为 OpenCart 3 会放行付款扩展的请求，而扩展在 OpenCart 4 上会为这些请求添加一个启动操作。
该扩展仅接受 JPY 信用卡付款，并且始终在 GMO-PG 页面上完成。它不提供其他 GMO-PG 付款方式，不支持多币种、保存银行卡、GMO-PG 会员注册、订阅或定期扣款，也没有站内银行卡表单。
订单与退款
订单状态
No status (missing order)：顾客已被引导至 GMO-PG 但尚未付款，或 GMO-PG 尚未确认付款。在 Sales > Orders 中，此类订单只有在筛选器 Order Status 设为 Missing Orders 时才会显示。
Processing or Completed status：付款已确认；状态按照 Order status after payment 设置。备注中会显示金额、GMO-PG 状态、交易，以及确认方式（通知或返回）。
GMO-PG payment on hold (authorized)：使用 Authorize only (仮売上) 时，金额已获授权。请在授权过期前使用 Capture payment (GMO-PG) 或在 GMO-PG 控制台中扣款。扣款后，订单获得已付款状态。如果授权在 GMO-PG 中被取消，订单将获得 Cancelled 状态。
GMO-PG payment on hold after payment：GMO-PG 报告的金额与订单总额不同。备注会说明原因。请检查订单并处理，或退还该笔付款。
Refunded：付款已通过扩展全额退款。对从未扣款的授权进行全额退款，会设置 Cancelled 状态。
如果某个已付款订单又收到第二笔付款，或同一购物车下的另一订单收到付款，已付款订单不会被更改。备注会提醒您在 GMO-PG 控制台中退还重复付款。如果某个订单已有状态但没有 GMO-PG 付款，收到付款时只会添加一条备注。
备注是订单 History 中的条目，顾客看不到。
VibeFox GMO Payment Gateway 选项卡
在 Sales > Orders 中打开一笔通过 GMO-PG 付款的订单。在订单页面底部，与 History 和 Additional 并列的 VibeFox GMO Payment Gateway 选项卡会显示 GMO OrderID（测试付款带有 TEST 标签）、Transaction ID、带有 GMO-PG 状态的 Status、Paid / refunded、扣款按钮和退款表单、退款历史，以及该订单的 GMO-PG notes。该选项卡对有权访问该扩展的用户显示；扣款和退款需要修改该扩展的权限（在 System > Users > User Groups 中设置）。
扣款
只有仅经过授权的等待订单，其选项卡中才会出现 Capture payment (GMO-PG)。请确认 Capture the authorized GMO-PG payment? 扩展会在 GMO-PG 检查交易并扣除授权金额；之后订单获得已付款状态。如果交易已不再处于授权状态（例如已在 GMO-PG 控制台中扣款），消息会显示当前状态。在 GMO-PG 控制台中完成的扣款会通过结果通知到达。
退款
在选项卡中输入 Amount（会自动填入尚未退款的金额），可选填写 Reason (optional)，然后点击 Refund via GMO-PG。请确认 Refund this amount through GMO-PG? 支持全额和部分退款，金额以整数日元计。上限是 GMO-PG 实际收取且仍持有的金额，而不是订单总额。退还全部剩余金额会取消 GMO-PG 交易，是作为撤销还是退货由 GMO-PG 决定。部分退款会减少交易金额。退款会发送到付款所在的环境，因此该环境的 Shop ID 和 Shop password 必须已设置。如果 GMO-PG 不接受退款，选项卡会显示错误，且不会记录任何退款。退款成功后会添加到退款历史和备注中。全额退款会将订单设为 Refunded 状态，但不会通知顾客，也不会把商品退回库存，与手动更改状态相同。部分退款不会更改状态。
Sales > Returns 中的商品退货不会通过 GMO-PG 退还款项。
在 GMO-PG 控制台中完成的退款和取消会通过结果通知到达，并添加到备注中。除非是在 GMO-PG 中被取消的授权或等待付款，否则订单状态不会自动更改。如有需要，请手动更新。
许可证密钥
该扩展需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox GMO Payment Gateway 是 Extensions > Extensions > Payments > VibeFox GMO Payment Gateway > Edit 页面中位于设置上方的第一个区块。将密钥粘贴到 License key 中并点击 Activate。之后，该区块会以掩码形式显示密钥，并显示状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入另一个密钥）和 Remove key（从本店铺移除该密钥）。其下方是 Product: opencart-payment-gmo 一行，以及打开您 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 账户中释放该名额。
没有有效密钥时，GMO-PG 信用卡付款不会在结账时显示给顾客。如果仍然启动了付款，顾客会看到 This payment method is not available. Please choose another one. 在同一浏览器中登录管理后台的管理员用户，仍会在店铺中看到该付款方式，并标注为 (unlicensed — visible to admins only)，因此您可以在购买密钥前设置和测试扩展。在 OpenCart 4 中此预览不可用：店铺无法看到管理员登录状态，因此没有有效密钥时，该付款方式对所有人都隐藏。打开一次 Edit 页面后，管理后台的 Dashboard 上会出现提醒。点击 × 可将其隐藏 7 天。现有订单不受影响：已发起的付款仍会被确认，扣款和退款也照常工作。
许可证到期后，扩展仍会继续工作，但更新和支持需要续费。当您打开管理后台的 Dashboard 或 Edit 页面时，状态会自动重新检查：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载扩展时，始终会删除许可证密钥和许可证状态。
故障排除
Credit card does not appear at checkout：请检查许可证是否有效、Enable/Disable 是否已开启、结账货币是否为 JPY，以及当前环境是否已设置 Shop ID、Shop password 和 Config ID。超过 9,999,999 JPY 的总额无法用银行卡支付。如果货币或凭据有误，设置页面会显示警告。另外请检查付款地址是否位于所选的 Geo Zone 中，以及订单是否达到了设置中的 Total。
The payment went through, but the order stays without a status：结果通知未生效。请在您所使用环境的 GMO-PG 店铺控制台中，检查結果通知是否已开启，并且 URL 与 Notification URL 中显示的完全一致。请检查该环境的 Shop ID 和 Shop password 是否已填写，因为扩展会用它们验证每一条通知。开启 Debug log，并查看扩展页面上的 Log 字段。顾客付款后返回店铺时，订单也会获得状态。
Log shows Notification rejected: unknown ShopID.：该通知来自一个 Shop ID 不在设置中的店铺。请输入该环境的 Shop ID。
Log shows Notification ignored: OrderID is not a payment of this store.：该交易并非由本店铺创建，例如是在 GMO-PG 控制台中完成的。无需任何操作。
Log shows that the order was paid in another environment：测试付款和正式付款是分开保存的。测试通知绝不会确认正式付款，反之亦然。
The customer sees an error after Confirm Order：开启 Debug log，并查看 Log 字段。日志会显示 GMO-PG 错误代码（ErrCode、ErrInfo）。Shop ID、Shop password 或 Config ID 错误是最常见的原因。This payment method is not available at the moment. Please choose another payment method. 表示结账会话已与订单不匹配，或付款方式在此期间已被关闭：顾客需要重新加载结账页面。
Order is in the GMO-PG payment on hold status：请阅读 VibeFox GMO Payment Gateway 选项卡中的备注。该订单仅经过授权，正在等待扣款，或付款金额与订单不符。
Refund or capture fails：请阅读选项卡中的消息。订单可能是在另一个环境中付款的，而该环境的 Shop ID 和密码未设置；交易可能已在 GMO-PG 中被取消；或金额可能超过了交易剩余的金额。The order is being updated by GMO-PG right now. Try again in a moment. 表示同时有一条通知正在处理中。
The tab shows You do not have permission to refund orders.：您所在的用户组没有修改该扩展的权限。请让管理员在 System > Users > User Groups 中授予该权限。
卸载
进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox GMO Payment Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除该扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Order statuses 部分的字段，这些字段在重新安装时会恢复默认值。在 OpenCart 4 中，扩展的事件（结账消息）及其启动操作（允许维护模式下的通知和返回通过）也会被删除。如果 Delete data on uninstall 已开启，其余网关设置（标题、说明、环境、凭据、扣款方式、付款后的订单状态、调试日志开关）和日志都会被删除；如果未开启，则会保留，以便日后重新安装时使用。GMO-PG 交易和退款始终会保留，因此重新安装后仍可对先前已付款的订单进行扣款和退款。现有订单会保留其付款备注。
在 OpenCart 4 中，如果还要删除扩展的文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox GMO Payment Gateway 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。
GMO Payment Gateway 是其各自所有者的商标。本扩展与 GMO Payment Gateway 无关联，也未获得其认可。