VibeFox SimplePay for PrestaShop — 帮助

系统要求

PrestaShop：8.0 至 9.x。

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

店铺币种：HUF、EUR 或 USD。SimplePay 不接受其他币种，购物车使用其他币种时不显示该付款方式。

SimplePay 商户账户：SimplePay 为每种币种提供单独的商户账户，正式与沙盒模式也各有独立账户。每个账户都需要在 SimplePay 商户后台（正式环境为 admin.simplepay.hu，沙盒环境为 sandbox.simplepay.hu）的 account > Technical data 中获取其 MERCHANT 和 SECRET KEY。如果您只以 HUF 销售，HUF 账户就足够了。不需要其他密钥。

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

安装

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

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

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

4. 为您销售的每种币种输入 SimplePay 账户的 MERCHANT 和 SECRET KEY：测试使用沙盒账户，真实付款使用正式账户（参见“配置”）。

5. 将 Configure 页面显示的 IPN URL 复制到 SimplePay 商户后台的每个商户账户（正式和沙盒）中。

6. 开启 Enable/Disable 并点击 Save。在开启 Sandbox mode 的情况下测试一笔付款，然后关闭 Sandbox mode 以接受真实付款。

安装时，模块会创建订单状态 SimplePay payment on hold。PrestaShop 会为所有币种、国家和顾客群组提供一个新的付款模块。您可以在 Payment > Preferences 中加以限制。

配置

所有设置都在模块页面中：Modules > Module Manager > VibeFox SimplePay Gateway > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。在各字段上方，如果店铺的默认币种不受 SimplePay 支持，或在当前模式下没有对应的商户账户，页面会发出警告。在这两种情况下，购物车使用该币种时都不会显示付款方式。沙盒模式开启时，页面会显示 Sandbox mode is on: payments go to the SimplePay sandbox, no real money is charged.

SimplePay (OTP)

Enable/Disable：Enable SimplePay Gateway 用于开启或关闭付款方式。默认：关闭。

Title：顾客在结账时看到的付款方式名称。订单中保存的付款方式名称也是它。默认：SimplePay (Card Payment)。必填。

Description：结账时付款方式下方显示的文字。默认：Pay securely with your credit or debit card via SimplePay。匈牙利商户可以在此填写 SimplePay 数据传输声明（并附上链接）。

Sandbox mode：使用 SimplePay 沙盒以及沙盒账户进行测试付款。它会同时切换 API 地址和商户账户。不会扣除真实款项。默认：开启。关闭后，将使用正式账户接受真实付款。开启时，顾客会在付款方式下方看到 Sandbox mode: no real payment is taken. 在沙盒中发起的订单始终在沙盒中退款。

正式商户账户

在 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. 只有在需要更改时才输入新值。

IPN URL

IPN 是付款状态变化时 SimplePay 发送到您店铺的消息。这是创建订单的常规方式。该部分显示您店铺的 IPN URL。使用友好 URL 时，它的形式类似 https://your-shop/module/wcp_simplepay_gateway/ipn，可能还带有 /en/ 之类的语言代码。请在 SimplePay 商户后台为每个商户账户（正式和沙盒）设置此 URL。请完全按照设置页面显示的内容复制该 URL，因为被重定向的 IPN 会丢失。

IPN 必须使用其指定的商户账户的 SECRET KEY 签名，并且签名所用的模式（沙盒或正式）必须与付款发起时的模式一致。签名无效的 IPN 会被拒绝。模块会以 SimplePay 要求的签名格式，向 SimplePay 确认每个有效的 IPN。系统使用以下 IPN 状态：

被拒绝、取消和超时的状态只会记录在尚无订单的购物车的最后一次付款尝试上。其他状态会写入日志，不会改变任何内容。没有 IPN 时，只有顾客在付款成功后返回店铺，才会创建订单。

Clear saved secret keys：勾选某个密钥并点击 Save 即可将其删除。空字段会保留已保存的值。

订单

Order Status After Payment：付款成功后设置的订单状态。

金额或币种与订单不同的付款，始终会进入 SimplePay payment on hold。

高级

Logging：将 API 调用、IPN 和返回记录到模块文件夹中的 logs/simplepay_op_debug.log.php。该文件无法通过网页打开。密钥和顾客数据不会被记录。即使此选项关闭，错误也始终会被记录。默认：关闭。

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

Delete Data on Uninstall：开启时，卸载模块会删除网关设置和日志。订单数据（SimplePay 交易和退款）始终保留。默认：关闭。

结账

在付款步骤中，顾客选择付款方式（默认为 SimplePay (Card Payment)），并看到提示 You will be redirected to the SimplePay payment page to pay by card. 确认后，模块会以购物车币种为购物车总额发起 SimplePay 银行卡付款，使用当前模式下该币种的商户账户，并将顾客转到 SimplePay 付款页面。顾客的电子邮件以及（填写完整时的）账单地址会传递给 SimplePay。如果 SimplePay 支持店铺的语言，付款页面将使用该语言，否则使用英语。已发起的付款可在 30 分钟内完成。此时还不存在订单。

付款成功后，顾客返回您的店铺。仅仅返回不会让订单付款：模块会通过经签名的请求向 SimplePay 查询交易状态，因此即使 IPN 延迟，订单也会被创建。只有在 SimplePay 确认后，订单才会标记为已付款。随后，顾客会看到标准的订单确认页面，其中显示 Successful transaction. SimplePay transaction ID: 及 ID。如果 SimplePay 尚未确认付款，Payment confirmation 页面会显示 Your payment is being confirmed by SimplePay. SimplePay transaction ID:、ID 和 Check again 按钮；IPN 一到达就会创建订单。

如果付款失败、被取消或超时，顾客会带着 SimplePay 的提示信息和交易 ID 返回结账页面，例如 Cancelled payment. You cancelled the payment 或 Timeout. The time allowed to complete the payment has expired。付款失败时，系统会提示顾客检查所填信息并联系发卡银行。购物车会保留，顾客可以重试。每次新的尝试都会获得自己的 SimplePay 参考号：PS、购物车编号和尝试编号，例如 PS123-1、PS123-2。

如果 SimplePay 无法发起付款，顾客会看到 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. 技术原因会写入日志。

即使店铺处于维护模式，IPN 仍可正常工作，也不会被店铺的国家限制阻止。

模块仅接受在 SimplePay 页面上完成的一次性银行卡付款。不支持保存银行卡或一键付款、订阅或定期付款，也不支持单独的授权与扣款。

订单与退款

订单状态

尚无订单：顾客已被转到 SimplePay 但尚未付款，付款失败、被取消或超时，或 SimplePay 尚未确认付款。此时只存在购物车。

Payment accepted or Delivered：付款已确认。状态遵循 Order Status After Payment。付款会以 SimplePay 交易 ID 记录，备注中会显示交易 ID，以及是 IPN 还是状态查询确认了付款。

SimplePay payment on hold：付款发起后购物车总额或币种发生了变化，因此已付金额与订单不一致。不会记录付款。备注会显示两个金额。请检查订单并处理，或在 SimplePay 商户后台对付款进行退款。如果随后同一购物车的另一次尝试以正确金额付款，订单会转为已付款状态。

Refunded：付款已通过模块全额退款。

已付款、已退款或已送达的订单绝不会因延迟的 IPN 而重新打开。如果已付款的订单又有第二笔付款成功，订单不会被修改。备注会提醒您在 SimplePay 后台检查，如果是重复付款则应予以退款。

SimplePay 付款区块

订单页面会显示 SimplePay payment 区块，其中包括交易 ID、订单参考号（orderRef）、商户账户和模式、SimplePay 状态、已付和已退金额、沙盒付款的 Sandbox 标记、购物车的付款尝试（如果不止一次）、退款记录以及订单的 SimplePay notes。

退款

在 SimplePay payment 区块中输入金额（会自动填入尚未退款的金额），可选填写原因，然后点击 Refund via SimplePay (OTP)。确认提示 Refund this amount via SimplePay? This cannot be undone.。支持全额和部分退款。您需要具有编辑订单的权限；不需要访问 Modules 页面。HUF 退款必须为整数福林。退款会针对支付该订单的 SimplePay 交易发起，金额和币种与该交易一致，使用该付款的商户账户和模式（沙盒或正式），因此该账户必须仍保留在设置中。如果 SimplePay 不接受退款，区块会显示错误，并且不会记录任何退款。成功的退款会添加到退款记录和备注中，包含 SimplePay 退款交易 ID，以及您填写的原因（如有）。全额退款会将订单设为 Refunded。部分退款不会改变状态。因金额不符而被保留的订单无法通过该区块退款：请在 SimplePay 商户后台退款。

模块不会开具贷项凭证。订单页面上的标准 PrestaShop 退款按钮不会通过 SimplePay 退还款项。在 SimplePay 商户后台进行的退款不会同步到 PrestaShop。请手动记录。

许可证密钥

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

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

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

故障排除

结账时不显示 SimplePay：请检查许可证是否有效、Enable/Disable 是否开启、购物车币种是否为 HUF、EUR 或 USD，以及该币种在当前模式下是否同时具有 Merchant ID 和 Secret key：Sandbox mode 开启时使用沙盒账户，关闭时使用正式账户。在 Payment > Preferences 中，请检查模块是否允许用于该购物车币种、顾客所在国家和顾客群组。

付款已完成，但没有创建订单：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 字段。错误的 secret key 会导致 Invalid response signature from SimplePay. Check the secret key of the merchant account. SimplePay 的错误会连同其错误代码一起记录。

在沙盒和正式之间切换之后：新的付款使用新模式的账户。之前发起的付款仍保留其发起时的商户账户和模式：它们的 IPN、状态查询和退款都使用该账户。只要此类付款仍未结束或可能需要退款，就请在设置中保留旧模式的账户。

付款后订单进入 SimplePay payment on hold：请阅读 SimplePay payment 区块中的备注。付款发起后购物车总额或币种已被更改。请处理订单，或在 SimplePay 商户后台对付款进行退款。

退款失败：请阅读区块中的消息。SimplePay refunds in HUF must be whole amounts. 表示 HUF 金额包含小数。如果消息提示该付款的商户账户未配置，请重新输入付款时使用的账户（币种和模式）。如果 SimplePay 退还的金额不同，消息会要求您在 SimplePay 后台检查该退款。

卸载

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

SimplePay 是其各自所有者的商标。本模块与 SimplePay 无关联，也未获得 SimplePay 的认可。