VibeFox GMO for PrestaShop — 帮助

系统要求

PrestaShop：8.0 至 9.x。

PHP：8.0 或更高版本。低于此版本时，模块拒绝安装。

币种：日元（JPY）。GMO-PG 仅收取日元，因此只有购物车币种为 JPY 时才会显示该付款方式。如果您的店铺尚未添加 JPY，请在 International > Localization > Currencies 中添加。

GMO Payment Gateway 账户：包含 Link Type Plus 的 GMO-PG 商户合同。您需要测试和/或正式环境的 Shop ID、Shop password 以及 Link Type Plus 的 Config ID（設定ID），并且需要在 GMO-PG 店铺控制台中开启结果通知（結果通知）（参见配置）。Site ID 和 Site password 不会使用。

VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。

安装

1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。

2. 上传完成后，点击 Configure；或者稍后在模块列表中找到 VibeFox GMO Payment Gateway，然后点击 Configure。

3. 在 Configure 页面顶部的许可证区块中的 License key 字段输入您的 VibeFox 许可证密钥，然后点击 Activate（参见许可证密钥）。

4. 输入测试和/或正式环境的 Shop ID、Shop password 和 Config ID，并选择 Environment。

5. 在 GMO-PG 店铺控制台中开启結果通知（结果通知），并设置设置页面中显示的通知 URL（参见配置）。

6. 开启 Enable/Disable，然后点击 Save。在测试环境中完成一笔测试付款，然后将 Environment 切换为正式环境。

安装时，模块会创建订单状态 GMO-PG payment on hold。PrestaShop 会为所有币种、国家和客户群组提供新的付款模块。您可以在 Payment > Preferences 中进行限制，但必须保留 JPY 的允许状态。

配置

所有设置都位于模块页面：Modules > Module Manager > VibeFox GMO Payment Gateway > Configure。每个 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. 保存时会删除凭据前后的空格。

GMO Payment Gateway — Credit Card

Enable/Disable：Enable GMO Payment Gateway — Credit Card 用于开启或关闭该付款方式。默认：关闭。

Title：结账时显示的付款方式名称。订单中保存的付款方式名称也是它。默认：Credit card。必填。

Description：结账时付款方式下方显示的文字。默认：You will be redirected to the secure GMO Payment Gateway page to pay by credit card.

GMO-PG 账户

Shop ID 和 Shop password 位于 GMO-PG 控制台的 Shop management > Shop information 下，Config ID 位于 Link Type Plus > Settings 下（設定ID）。测试和正式环境的凭据不同。

Environment：哪个 GMO-PG 环境接收新付款。

Test (sandbox)：使用测试凭据连接 pt01.mul-pay.jp（默认）。

Production (live)：使用正式凭据连接 p01.mul-pay.jp。

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 saved passwords：勾选某个密码，然后点击 Save 将其删除。字段留空则保留已保存的值。

Payment

Capture：何时从卡中扣款。

Capture immediately (即時売上)：立即从卡中扣款（默认）。

Authorize only (仮売上)：仅授权金额，订单进入 GMO-PG payment on hold，直到您在订单页面或 GMO-PG 控制台中通过 Capture payment (GMO-PG) 扣款，且须在授权过期之前完成。

Order status after payment：已付款订单的状态。

Processing：订单变为 Payment accepted（默认）。

Completed：订单变为 Delivered。适用于虚拟商品和可下载商品。

付款通知（結果通知）

结果通知告知您的店铺已完成付款。该通知是必需的。请在 GMO-PG 控制台中开启結果通知（结果通知），并设置本节 Notification URL 中显示的 URL。使用友好 URL 时，它的格式类似 https://your-shop/module/wcp_gmo_payment/notify，可能还带有 /ja/ 之类的语言代码。请完全按照设置中显示的内容复制该 URL。它必须可以从互联网访问；维护模式不会阻止它。

GMO-PG 通知没有签名，因此模块从不信任其内容。通知必须来自您已配置的某个 Shop ID，并且引用的是本店在付款所属环境中创建的付款。随后，模块会使用您的 Shop password 向 GMO-PG 查询该交易（SearchTrade），并且仅根据该响应修改购物车或订单。与真实交易不匹配的通知不会产生任何变化。非本店创建的交易（例如在 GMO-PG 控制台中完成的交易）会被确认并忽略。当模块无法核验某个通知时，会以让 GMO-PG 重新发送的方式作出响应（GMO-PG 最多重试 5 次）。

如果没有该通知，只有当顾客付款后返回店铺时才会创建订单。

Advanced

Debug log：将 API 请求和通知写入模块文件夹中的 logs/gmo_pg_debug.log.php。该文件无法通过网页打开。即使开关关闭，错误也始终会被记录。密码和顾客数据会被遮蔽。默认：关闭。

Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。

Delete data on uninstall：开启后，卸载模块时会删除网关设置和日志。订单数据（GMO OrderID、交易 ID）始终保留。默认：关闭。

结账

在付款步骤中，顾客选择付款方式（默认为 Credit card）并查看其说明。在测试环境中，其上方会显示徽章 TEST — GMO-PG test environment, no real charges.。确认后，模块会为购物车总额创建一笔 GMO-PG Link Type Plus 付款（金额四舍五入为整数日元），并将顾客转到 GMO-PG 付款页面。顾客在该页面使用信用卡付款。3-D Secure 2.0 由 GMO-PG 处理，顾客的电子邮件地址会为 3-D Secure 传给 GMO-PG。付款页面会根据顾客的语言以日语、中文或英语打开。付款在 GMO-PG 中以 PS- 加购物车编号显示。不会发送其他顾客数据。此时尚未创建订单。

付款后，顾客返回您的店铺。签名结果会使用该付款所在环境的 Shop password 进行核验，并且只有在 GMO-PG 确认后，订单才会被标记为已付款：顾客返回时由服务器端的 SearchTrade 请求确认，或通过结果通知确认。两者使用相同的逻辑，因此订单绝不会被重复创建。随后顾客会看到标准的订单确认页面。如果 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 按钮；通知一到达，订单即会创建。

如果卡被拒绝，或者 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.。购物车会被保留。每次新的尝试都会取消上一个未付款的付款链接。如果上一个链接在此期间已被付款，则直接根据该付款创建订单，不会生成新的链接。

购物车总额在 1 至 9,999,999 JPY 之间的订单可以付款。更高的总额会隐藏该付款方式。如果无法开始付款，顾客会停留在结账页面，并看到简短提示，例如 Card payment could not be started. Please try again or choose another payment method.，原因会写入日志。

即使店铺处于维护模式，通知和返回也能正常工作，且不受店铺国家限制的影响。

本模块仅以 JPY 接受信用卡付款，并且始终在 GMO-PG 页面中完成。不支持其他 GMO-PG 付款方式、多币种、保存银行卡或 GMO-PG 会员注册、订阅或定期扣款，也不提供站内银行卡表单。

订单和退款

订单状态

尚无订单：顾客已被转到 GMO-PG 但尚未付款，或 GMO-PG 尚未确认付款。此时只存在购物车。

Payment accepted 或 Delivered：付款已确认。状态遵循 Order status after payment。付款会以 GMO-PG TranID 作为交易 ID 记录，备注中会显示金额、GMO-PG 状态、交易以及确认方式（通知或返回）。

GMO-PG payment on hold（已授权）：使用 Authorize only (仮売上) 时，金额已被授权。请在授权过期前通过 Capture payment (GMO-PG) 或 GMO-PG 控制台进行扣款。扣款后，订单变为 Payment accepted 或 Delivered。如果授权在 GMO-PG 被取消，订单变为 Canceled。

付款后 GMO-PG payment on hold：GMO-PG 报告的金额与购物车总额不同，或购物车不是 JPY。备注会说明原因，并且付款会按 GMO-PG 实际扣取的金额记录。请检查订单并履行，或退还该笔付款。

Refunded：付款已通过模块全额退款。对从未扣款的授权进行全额退款，会将订单设为 Canceled。

如果某个购物车的订单已付款或已关闭，又收到第二笔付款，订单不会被修改。备注会提示您在 GMO-PG 控制台中退还重复的付款。

GMO Payment Gateway 区块

订单页面会显示 GMO Payment Gateway 区块，包括 GMO OrderID、Transaction ID、状态（含 GMO-PG 状态）、Paid / refunded、测试付款的 TEST 徽章、退款记录以及订单的 GMO-PG notes。扣款和退款需要编辑订单的权限；无需访问模块页面。

扣款

Capture payment (GMO-PG) 会出现在仅被授权的待处理订单的区块中。请确认 Capture the authorized GMO-PG payment?。模块会在 GMO-PG 中核验交易，并扣取已授权的金额。如果交易已不再处于授权状态（例如已在 GMO-PG 控制台中扣款），备注会显示当前状态，订单随之变化。

退款

在区块中输入金额（会自动填入尚未退款的金额），可选填写原因，然后点击 Refund via GMO-PG。确认 Refund this amount through GMO-PG?。支持以整数日元进行全额和部分退款。上限是 GMO-PG 实际扣取且仍持有的金额，而非订单总额。退还剩余全部金额会取消 GMO-PG 交易，是作废还是退款由 GMO-PG 决定。部分退款会减少交易金额。退款会发送到付款所在的环境，因此该环境的 Shop ID 和 Shop password 必须已设置。如果 GMO-PG 不接受退款，区块会显示错误，并且不会记录退款。成功的退款会添加到退款记录和备注中。全额退款会将订单设为 Refunded；部分退款不会更改状态。

模块不会创建退款单。订单页面上 PrestaShop 的标准退款按钮不会通过 GMO-PG 退还款项。

在 GMO-PG 控制台中进行的退款和取消会通过结果通知到达，并添加到备注中。订单状态和退款单不会自动更改，但在 GMO-PG 取消授权的情况除外。如有需要，请手动更新。

许可证密钥

本模块需要来自 vibefox.net 的 VibeFox 许可证密钥。License — VibeFox GMO Payment Gateway 许可证区块是模块 Modules > Module Manager > VibeFox GMO Payment Gateway > Configure 页面中位于设置上方的第一个区块。请将密钥输入 License key 并点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），并提供 Check now 按钮以重新检查状态、Change key 按钮以输入其他密钥，以及 Remove key 按钮以从本店移除密钥。其下方是 Product: presta-payment-gmo 一行，以及 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 账户中释放名额。

没有有效密钥时，结账时不会向顾客显示银行卡付款。如果仍然启动了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法得知您已登录后台，因此该付款方式对您也会被隐藏：您可以在购买密钥之前设置模块，但无法在结账时测试。Modules > Module Manager 中的 Alerts 标签页会显示提醒。现有订单不受影响：已开始的付款仍会被确认，扣款和退款也照常进行。

许可证到期后，模块仍会继续运行，但更新和支持需要续费。在您使用后台期间，状态会自动重新检查：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块总会删除许可证密钥和许可证状态。

故障排除

结账时未显示信用卡付款：请检查许可证是否有效，Enable/Disable 是否已开启，购物车币种是否为 JPY，以及当前环境是否已设置 Shop ID、Shop password 和 Config ID。超过 9,999,999 JPY 的购物车总额无法用银行卡付款。如果币种或凭据有误，设置页面会显示警告。在 Payment > Preferences 中，请检查模块是否已允许 JPY、顾客所在国家以及顾客所属群组。

付款已完成，但未创建订单：结果通知未正常工作。请在您所用环境的 GMO-PG 店铺控制台中，检查結果通知是否已开启，以及 URL 是否与 Notification URL 中显示的完全一致。请检查该环境的 Shop ID 和 Shop password 是否已填写，因为模块会用它们核验每个通知。请开启 Debug log，并查看模块页面上的 Log 字段。顾客付款后返回店铺时，也会创建订单。

日志显示 Notification rejected: unknown ShopID：通知来自某个 Shop ID 不在设置中的店铺。请输入该环境的 Shop ID。

日志显示 Notification ignored: OrderID is not a payment of this store：该交易并非由本店创建，例如是在 GMO-PG 控制台中完成的。无需任何操作。

日志显示购物车已在其他环境中付款：测试和正式付款是分开保存的。测试通知绝不会确认正式付款，反之亦然。

日志显示 Cannot create the order: the module is disabled：在确认付款时模块被禁用了。请重新启用；GMO-PG 会再次发送通知。

顾客在选择银行卡付款时看到错误：请开启 Debug log，并查看 Log 字段。日志会显示 GMO-PG 错误代码（ErrCode、ErrInfo）。常见原因是 Shop ID、Shop password 或 Config ID 填写错误。GMO Payment Gateway accepts payments in Japanese Yen (JPY) only. 表示购物车不是 JPY。

订单处于 GMO-PG payment on hold 状态：请阅读 GMO Payment Gateway 区块中的备注。订单仅被授权并等待扣款，或已付金额与购物车不符。

退款或扣款失败：请阅读区块中的提示。订单可能是在另一个未设置 Shop ID 和密码的环境中付款的，交易可能已在 GMO-PG 中取消，或者金额可能超过交易中剩余的金额。The order is being updated by GMO-PG right now. Try again in a moment. 表示有一个通知正在同时处理。

区块显示 You do not have permission to refund orders.：您的员工档案没有编辑订单的权限。请让管理员为您授予该权限。

卸载

进入 Modules > Module Manager，打开 VibeFox GMO Payment Gateway 旁边的菜单，然后选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。如果 Delete data on uninstall 已开启，网关设置和日志会被删除。如果已关闭，所有设置都会保留，以便日后重新安装。GMO-PG 交易和退款以及订单状态 GMO-PG payment on hold 始终保留，因此之前已付款的订单在重新安装后仍可扣款和退款。现有订单会保留其付款备注和交易 ID。

GMO Payment Gateway 是其各自所有者的商标。本模块与 GMO Payment Gateway 没有关联，也未获其认可。