VibeFox Satispay for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本，并启用 OpenSSL 扩展。若 PHP 版本过低或未启用 OpenSSL，模块将拒绝安装。
货币：EUR。Satispay 仅收取欧元，因此当购物车货币不是 EUR 时，该付款方式会被隐藏。
Satispay 账户：Satispay Business 账户。您无需复制任何 API 密钥：模块通过您在 Satispay Business Dashboard 中生成的一次性激活码进行连接（参见“配置”部分）。测试时，您需要一个 Satispay 沙盒账户，可向 Satispay 为开发者申请。
公开店铺：您的店铺必须可以从互联网访问，以便 Satispay 在付款状态变化时调用它。无需在 Satispay 中进行任何设置。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 进入后台，前往 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者之后在模块列表中找到 VibeFox Satispay Gateway，然后点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥输入到 License key 字段，然后点击 Activate（参见“许可证密钥”）。
4. 选择环境：测试时开启 Sandbox Mode，进行真实付款时保持关闭。
5. 将该环境的激活码粘贴到 Activation Code 中，然后点击 Save。随后 Status 字段会显示 Connected 以及 Key ID。
6. 开启 Enable/Disable，然后点击 Save。在沙盒中测试付款，然后关闭 Sandbox Mode，并使用正式环境的激活码连接正式环境。
安装时，模块会创建订单状态 Satispay payment on hold。PrestaShop 会为所有货币、国家和顾客组提供一个新的付款模块。您可以在 Payment > Preferences 中进行限制。在那里，该模块必须被允许用于欧元。
配置
所有设置都位于模块页面：Modules > Module Manager > VibeFox Satispay Gateway > Configure。每个部分都有各自的 Save 按钮，点击后会保存整个页面。
结账
顾客在付款方式列表中看到的内容。
Enable/Disable：Enable Satispay payment 用于开启或关闭该付款方式。默认值：off。
Title：结账时显示的付款方式名称。它也是订单中保存的付款方式名称。默认值：Satispay。必填。
Description：结账时付款方式下方显示的文字。默认值：Pay with the Satispay app: scan the QR code or confirm the payment on your phone.
Satispay 连接
Status：两个环境的状态，例如带 Key ID 的 Live: Connected，或 Sandbox: Not connected，以及当前正在使用哪个环境。在所用环境未连接期间，该字段会显示 Satispay is hidden at checkout until the environment in use is connected.
Sandbox Mode：使用 Satispay 沙盒（测试）环境。沙盒付款不会被收费。默认值：off。沙盒和正式环境的密钥是分开的：请用对应环境的激活码分别连接。使用沙盒期间，顾客会在付款方式下方看到 Sandbox mode: no real money is charged.
Activation Code：要连接上方所选环境，请粘贴一个新的 6 位激活码，然后点击 Save。正式环境的激活码在 Satispay Business Dashboard 的 Online shop 部分生成。沙盒激活码随 Satispay 沙盒账户提供。激活码只能使用一次，且不会被保存。如需保持当前连接，请将该字段留空。
使用激活码保存时，模块会生成 RSA 密钥对，将公钥和激活码发送给 Satispay，并将 Key ID 以及该环境的密钥保存在店铺配置中。私钥永远不会显示。成功时，页面会显示例如 Satispay Live connected. Key ID: 及其 ID。如果 Satispay 拒绝了激活码，页面会显示 Satispay activation failed: 以及 Satispay 的消息，并提示您检查激活码是否属于该环境、是否尚未使用。包含字母和数字以外字符的激活码会在发送前被拒绝。为某个环境保存新激活码会替换其之前的连接。
付款通知
无需在 Satispay 中进行任何配置。每笔付款都带有自己的回调 URL，付款状态变化时 Satispay 会调用该 URL；模块在创建或修改订单之前，会从 Satispay API 重新读取付款信息。Callback URL 字段会显示该 URL 的示例。启用友好 URL 时，它类似于 https://your-shop/module/wcp_satispay_gateway/callback?id_cart={cart}&payment_id={uuid}，前面可能带有语言代码，例如 /en/。该 URL 必须可以从互联网访问，前面不能有基础身份验证。即使店铺处于维护模式，回调仍然有效，且不受店铺国家限制的影响。
高级
Debug log：将 API 调用和付款事件写入模块文件夹中的 logs/satispay_p_debug.log.php。该文件无法通过网页打开。密钥和顾客数据不会被记录。即使此选项关闭，错误也始终会被记录。默认值：off。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Delete data on uninstall：开启时，卸载模块会删除设置、两个环境的 Satispay 密钥以及日志。为订单保存的 Satispay 付款和退款，以及订单状态 Satispay payment on hold，始终会被保留。默认值：off。
结账
在付款步骤，顾客选择付款方式（默认为 Satispay）并确认订单。模块会以欧元为购物车总额创建一笔 Satispay 付款，并以购物车编号作为参考，然后将顾客引导至 Satispay 付款页面。在电脑上，顾客用 Satispay 应用扫描二维码；在手机上，顾客在应用中确认付款。此时尚不存在订单。
付款后，顾客返回您的店铺。只有在 Satispay 确认付款后，订单才会被标记为已付款：模块从 Satispay API 读取付款信息，检查其是否为该购物车创建，并将其状态、金额（以分为单位）和币种与购物车进行比对。无论是 Satispay 先调用回调 URL，还是顾客先返回，都会执行此操作，以先到者为准。随后订单会被创建，顾客会看到标准的订单确认页面。如果顾客返回时 Satispay 尚未确认付款，Payment confirmation 页面会显示 Satispay has not confirmed your payment yet. The order will be updated automatically as soon as the confirmation arrives. 以及一个 Check again 按钮。回调一到达就会创建订单。
如果顾客离开 Satispay 页面而未付款，模块会在 Satispay 端取消该笔付款，使被放弃的页面无法再付款。顾客会回到结账页面，并看到提示：Your Satispay payment was cancelled and nothing was charged. You can try again or choose another payment method. 当顾客在应用中拒绝付款时，也会显示相同的提示。购物车会被保留。
在为同一购物车创建新的 Satispay 付款之前，会先检查之前的付款：待处理的付款会在 Satispay 端被取消；如果之前的付款已经完成，则使用该付款创建订单，而不会再进行第二次付款。
如果无法发起付款，顾客会停留在结账页面并看到简短提示：当店铺未连接或 Satispay 拒绝密钥时显示 Satispay is not available at the moment. Please choose another payment method.；其他错误时显示 Unable to create the Satispay payment. Please try again or choose another payment method.。原因会被写入日志。
模块仅接受以欧元计价的一次性付款。它不支持订阅、已保存的付款方式、预授权或餐券。模块不会定时检查待处理的付款：如果 Satispay 的回调和顾客的返回都没有到达您的店铺，则不会创建订单，但该付款可以在 Satispay Dashboard 中看到。
订单与退款
订单状态
No order yet：顾客已被引导至 Satispay 且尚未付款，或 Satispay 尚未确认付款。此时仅存在购物车以及模块的 Satispay 付款记录。
Payment accepted：付款已确认。该付款以 Satispay 付款 ID 作为交易 ID 记录，备注中会显示 Satispay 付款、金额以及验证方式（callback、redirect or checkout）。
Satispay payment on hold：Satispay 报告的金额或币种与购物车总额不符（例如，付款开始后在另一个标签页中修改了购物车），或者订单被取消后才收到付款。收到的款项会记录在订单上，备注会对此作出说明。请在 Satispay Dashboard 中核实该付款，然后处理订单或退款。如果之后同一购物车中金额正确的另一笔付款被接受，订单将变为 Payment accepted。
Refunded：该付款已通过模块全额退款。
如果已付款的订单又收到了第二笔付款，订单不会被更改。备注会提醒您在 Satispay Dashboard 中退还重复的付款。重复确认永远不会重新打开已取消或已退款的订单。
Satispay 付款区块
订单页面会显示 Satispay payment 区块，其中包括 Satispay 付款 ID、付款状态、已付金额和已退款金额、沙盒付款的 Sandbox 标识、退款记录、Satispay payments of this cart 列表（显示每次付款尝试及其环境），以及订单的 Satispay notes。
退款
在 Satispay payment 区块中输入金额（会自动填入尚未退款的金额），可选填写原因，然后点击 Refund via Satispay。请确认提示 Refund this amount through Satispay? This cannot be undone. 支持全额和部分退款。您需要拥有编辑订单的权限；无需访问 Modules 页面。退款金额不得超过 Satispay 为该付款实际收取的金额，因此在金额不一致的情况下，您最多只能退还顾客实际支付的金额，而不是订单总额。退款会发送至付款时所在的环境（正式或沙盒），因此该环境必须仍处于连接状态。只有当 Satispay 接受退款时，退款才算完成：成功的退款会以 Satispay 退款 ID 和原因的形式，添加到退款记录和备注中。如果 Satispay 未接受退款，区块会显示错误，且不会记录任何退款。全额退款会将订单设为 Refunded。部分退款不会更改订单状态。
模块不会创建退款单（credit slip）。订单页面上 PrestaShop 的标准退款按钮不会通过 Satispay 退回款项。在 Satispay Dashboard 中进行的退款不会记录到 PrestaShop 中。如有需要，请手动更新订单。
许可证密钥
本模块需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Satispay Gateway 位于 Modules > Module Manager > VibeFox Satispay Gateway > Configure 页面的最上方，位于设置之上。将密钥输入 License key 并点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期以及您的域名），并提供以下按钮：Check now（重新检查状态）、Change key（输入另一个密钥）和 Remove key（从本店铺中移除该密钥）。其下方是 Product: presta-payment-satispay 一行和 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 账户中释放该名额。
如果没有有效的密钥，Satispay 将不会在结账时向顾客显示。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法得知您已登录后台，因此该付款方式对您也是隐藏的：您可以在购买密钥之前设置模块，但无法在结账时测试。Modules > Module Manager 的 Alerts 选项卡中会出现提醒。现有订单不受影响：已开始的付款仍会被确认，退款也可以正常进行。
许可证到期后，模块仍会继续运行，但更新和支持需要续费。在您使用后台期间，状态会自动重新检查：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时不显示 Satispay：请检查许可证是否有效，Enable/Disable 是否已开启，正在使用的环境是否已连接（Status 字段会为其显示 Connected），以及购物车货币是否为 EUR。在 Payment > Preferences 中，请检查该模块是否允许用于欧元、顾客所在国家以及顾客所属的顾客组。
付款已完成，但未创建订单：订单会在 Satispay 调用您的店铺或顾客返回时创建。请检查您的店铺是否可以从互联网访问，回调 URL 前面是否没有基础身份验证，并开启 Debug log 以在 Log 字段中查看回调。该付款可在 Satispay Dashboard 中看到。
回调返回 Payment status unavailable, retry later. 或 Not configured.：模块无法从 Satispay 读取付款信息，或该付款所属的环境未连接。不会更改任何订单。Satispay 会再次调用。请检查连接状态和日志。
回调返回 Busy, retry later.：同一时刻该购物车正被另一个请求确认，或订单无法创建（例如模块已被禁用）。Satispay 会再次调用。日志会显示原因。
回调返回 Unknown payment. 或 Missing or invalid payment_id.：该付款并非由本店铺为此购物车创建，或该请求不是 Satispay 回调。不会更改任何内容。
激活失败：激活码只能使用一次。请检查激活码是否属于 Sandbox Mode 中所选的环境（正式环境使用正式激活码，沙盒使用沙盒激活码），生成新的激活码后再次保存。如果页面提示无法生成 RSA 密钥对，请让您的主机提供商启用 PHP OpenSSL 扩展。如果无法连接 Satispay，请检查您的服务器是否可以打开出站 HTTPS 连接。
从沙盒切换到正式环境后，Satispay 从结账页面消失：沙盒和正式环境使用不同的密钥。请在关闭 Sandbox Mode 的情况下粘贴正式环境的激活码并保存。
顾客看到 This payment method is not available.：该付款方式不允许用于此购物车（在 Payment > Preferences 中的国家、货币或顾客组），或已被禁用，或正在使用的环境未连接。
付款后订单状态为 Satispay payment on hold：请阅读 Satispay payment 区块中的备注（参见“订单状态”），在 Satispay Dashboard 中核实该付款，然后处理订单或退款。
由于环境已不再连接，退款失败：该付款是在正式环境或沙盒中完成的，而该环境目前已没有密钥。请使用激活码重新连接，或在 Satispay Dashboard 中退款。
退款失败，提示 Satispay did not accept the refund：Satispay 返回的状态不是 accepted。PrestaShop 未记录该退款，并会在备注中说明。请在 Satispay Dashboard 中核实。
卸载
进入 Modules > Module Manager，打开 VibeFox Satispay Gateway 旁边的菜单，然后选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。如果 Delete data on uninstall 已开启，设置、两个环境的 Satispay 密钥以及日志都会被删除。如果已关闭，所有设置和密钥都会保留，以便日后重新安装。为订单保存的 Satispay 付款和退款，以及订单状态 Satispay payment on hold，始终会被保留，因此在重新安装后，只要环境重新连接，之前已付款的订单仍可退款。现有订单会保留其付款备注和交易 ID。
Satispay 是其各自所有者的商标。本模块与 Satispay 无关联，也未获得 Satispay 的认可。