VibeFox Satispay for WooCommerce — 帮助
系统要求
WordPress：6.0 或更高版本。
WooCommerce：7.0 或更高版本，已安装并启用。没有它，插件无法激活。
PHP：8.0 或更高版本，并启用 OpenSSL 扩展。没有 OpenSSL 时，插件会在管理后台显示错误，且该付款方式不会加载。
货币：EUR。Satispay 仅收取欧元，因此当店铺货币（或在订单支付页面上的订单货币）不是 EUR 时，该付款方式会被隐藏。
Satispay 账户：Satispay Business 账户。您无需复制任何 API 密钥：插件通过您在 Satispay Business Dashboard 中生成的一次性激活码进行连接（参见“配置”）。测试时，您需要一个 Satispay 沙盒账户，可向 Satispay for developers 申请。
公开网站：您的网站必须可以从互联网访问，以便 Satispay 在付款状态变化时调用它。为此无需在 Satispay 中进行任何配置。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 wcp_satispay_gateway 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Payments > Satispay > Manage，或在插件列表页面点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 选择环境：测试时勾选 Sandbox Mode，进行真实付款时保持不勾选。
6. 将该环境的激活码粘贴到 Activation Code 中并保存。此时连接状态会显示 Key ID。
7. 开启 Enable/Disable 并保存。在沙盒中测试一笔付款，然后取消勾选 Sandbox Mode，并使用正式环境的激活码连接正式环境。
配置
所有设置都在同一页面中：WooCommerce > Settings > Payments > Satispay。Satispay connection 区域显示两个环境的状态，例如 Live: Connected（附带 Key ID）或 Sandbox: Not connected，并标明当前使用的环境。在当前使用的环境未连接时，页面会显示：在当前使用的环境连接之前，Satispay 在结账时处于隐藏状态。 在 WooCommerce 付款方式列表中，在当前使用的环境连接之前，Satispay 会被标记为需要设置；而在 Sandbox Mode 开启期间，会显示测试模式标识。
Enable/Disable：Enable Satispay payment 用于开启或关闭该付款方式。默认：关闭。
Checkout
顾客在付款方式列表中看到的内容。
Title：结账时显示的付款方式名称。默认：Satispay。
Description：结账时付款方式下方显示的文字。默认：Pay with the Satispay app: scan the QR code or confirm the payment on your phone.
Satispay connection
Sandbox Mode：Use the Satispay sandbox (staging) environment。沙盒付款不会被扣款。默认：关闭。沙盒和正式环境使用不同的密钥：请使用对应环境的激活码分别连接。当使用沙盒时，顾客会在付款方式下方看到 沙盒模式：不会扣除真实款项。
Activation Code：要连接上方所选的环境，请粘贴一个新的 6 位激活码并保存。正式环境的激活码在 Satispay Business Dashboard 的 Online shop 部分生成。沙盒激活码随 Satispay 沙盒账户一同提供。激活码只能使用一次，且不会被保存。若要保留当前连接，请将此字段留空。
使用激活码保存时，插件会生成一对 RSA 密钥，将公钥和激活码发送给 Satispay，并在 WordPress 数据库中保存 Key ID 以及该环境的密钥。成功时，页面会显示例如 Satispay Live connected. Key ID: 及其后的 ID。如果 Satispay 拒绝了激活码，页面会显示 Satispay 的提示信息，并要求您检查该激活码是否属于此环境以及是否尚未使用。包含字母和数字以外字符的激活码会在发送前被拒绝。为某个环境保存新激活码会替换其之前的连接。
Payment notifications
Satispay 中无需任何配置。每笔付款都带有自己的回调 URL，Satispay 会在付款状态变化时调用该 URL，插件在更改订单之前还会从 Satispay API 重新读取付款信息。此区域会显示该 URL 的示例，格式类似：https://your-site/wc-api/satispay_payment_callback/?action=callback&order_id={order}&payment_id={uuid}。该 URL 必须可从互联网访问：/wc-api/ 不能处于维护模式或受密码保护。
Advanced
Debug log：Log API calls and payment events 会写入 WooCommerce > Status > Logs，来源为 wcp_satispay_gateway，不包含密钥或顾客数据。即使此选项关闭，错误也始终会被记录。默认：关闭。
Delete data on uninstall：Remove the settings and Satispay keys when the plugin is deleted。订单上保存的付款数据会被保留。默认：关闭。
结账
顾客选择付款方式（默认为 Satispay），然后点击 Pay with Satispay。插件会以欧元为单位，按订单总额创建一笔 Satispay 付款，并以订单号作为参考，然后将顾客引导至 Satispay 付款页面。在电脑上，顾客用 Satispay 应用扫描二维码；在手机上，顾客在应用中确认付款。
付款后，顾客返回您的店铺。只有在 Satispay 确认之后，订单才会被标记为已付款：插件会从 Satispay API 读取付款信息，检查它是否为此订单创建，并将其状态、金额（以分为单位）和币种与订单进行比对。无论 Satispay 先调用回调 URL，还是顾客先返回，都会进行此操作。如果付款尚未确认，订单接收页面会显示：Satispay 尚未确认您的付款。确认到达后，订单将自动更新。
如果顾客离开 Satispay 页面而未付款，插件会在 Satispay 端取消该付款，使被放弃的页面无法再被支付。顾客会被带回结账页面（或订单支付页面），并看到提示：Your Satispay payment was cancelled and nothing was charged. You can try again or choose another payment method. 当顾客在应用中拒绝付款时，也会显示同样的提示。
顾客可以再次支付未付款的订单，例如通过 Pay for order 页面。在创建新的 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. 原因会写入日志。
该付款方式适用于经典结账、结账区块和 Pay for order 页面。它兼容 WooCommerce 高性能订单存储（HPOS）。
插件仅接受以欧元计价的一次性付款。不支持订阅、已保存的付款方式、预授权或餐券。插件不会定时检查待处理的付款：如果 Satispay 的回调和顾客的返回都没有到达您的站点，订单将保持为待付款状态，而付款可以在 Satispay Dashboard 中查看。
订单与退款
Order statuses
Pending payment：顾客已被引导至 Satispay，但尚未付款，或 Satispay 尚未确认付款。订单备注会显示 Satispay 付款 ID、金额和环境（Live 或 Sandbox）。
Processing or Completed：付款已确认。订单遵循 WooCommerce 的标准规则：待处理（Processing），或者对于仅包含虚拟可下载商品的订单则为已完成（Completed）。订单备注会显示 Satispay 付款、金额以及验证方式（回调、重定向或结账）。交易 ID 即为 Satispay 付款 ID。
On hold：Satispay 报告的金额或币种与订单总额不符，或者付款是在订单被取消之后才被接受的。订单备注会说明此情况，付款会被保存为交易 ID，以便进行退款。请在 Satispay Dashboard 中检查该付款，然后完成订单或退还该付款。
Cancelled：订单的最新 Satispay 付款已被取消或过期，例如顾客离开了 Satispay 页面。较早的付款过期时，不会取消一个存在更新的进行中付款的订单。您在管理后台创建的订单（付款链接）不会被取消：它们会保持为待付款状态并附带备注，以便顾客仍可付款。
如果对已付款的订单又接受了第二笔付款，订单不会被更改。备注会提示您在 Satispay Dashboard 中退还重复的付款。重复的确认永远不会重新打开已取消或已退款的订单。
Refunds
打开订单，点击 Refund，输入金额，然后点击 Refund via Satispay。对于使用 Satispay 付款的订单，支持全额和部分退款。退款会发送到付款时所在的环境（正式或沙盒），因此该环境必须仍处于连接状态。只有 Satispay 接受退款时，退款才算完成：成功的退款会以 Satispay 退款 ID 和原因的形式添加到订单备注中。如果 Satispay 未接受退款，WooCommerce 会显示错误，并且不会记录任何退款。
在 Satispay Dashboard 中进行的退款不会转换为 WooCommerce 退款。如有需要，请在 WooCommerce 中创建手动退款，且不要使用 Refund via Satispay。
许可证密钥
本插件需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > Satispay 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期截止日期以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将其从此站点移除。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。将密钥从某个站点移除，并不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效的密钥时，Satispay 不会在结账时显示给顾客。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 已登录的店铺管理员仍会看到该付款方式，并标记为 (unlicensed — visible to admins only)，以便您在购买密钥之前设置和测试插件。插件列表页面和 WooCommerce 页面上会出现提醒。现有订单不受影响：已发起的付款仍会被确认，退款也照常可用。
许可证过期后，插件仍可继续运行，但更新和支持需要续费。状态会在后台自动重新检查。
故障排除
Satispay 没有出现在结账页面：请检查许可证是否有效、Enable/Disable 是否已开启、当前使用的环境是否已连接（Satispay connection 区域对其显示 Connected），以及货币是否为 EUR。
付款已完成，但订单仍为 Pending payment：订单会在 Satispay 调用您的站点或顾客返回时更新。请检查您的站点是否可以从互联网访问，/wc-api/ 是否没有维护模式或密码保护，并查看 WooCommerce > Status > Logs，来源为 wcp_satispay_gateway。付款可以在 Satispay Dashboard 中查看。
回调返回 Payment status unavailable, retry later 或 Not configured：插件无法从 Satispay 读取付款信息，或者订单所属的环境未连接。订单不会被更改。请检查连接状态和日志。
回调返回 Busy, retry later：订单在同一时刻正被另一个请求更新。此回调不会更改订单。订单将在下一次回调时或顾客返回时更新。
回调返回 Unknown payment 或 Missing or invalid payment_id：该付款不是为此订单创建的，或者该请求不是 Satispay 的回调。订单不会被更改。
激活失败：激活码只能使用一次。请检查激活码是否属于 Sandbox Mode 中所选的环境（正式环境使用正式激活码，沙盒使用沙盒激活码），重新生成一个新的激活码并再次保存。如果页面提示无法生成 RSA 密钥对，请让您的主机服务商启用 PHP 的 OpenSSL 扩展。
从沙盒切换到正式环境后，Satispay 从结账页面消失：沙盒和正式环境使用不同的密钥。请在取消勾选 Sandbox Mode 的情况下粘贴正式激活码并保存。
订单处于 On hold，且备注与订单不符：Satispay 报告的金额或币种与订单总额不符，例如付款开始后订单又被修改。请在 Satispay Dashboard 中检查该付款，然后完成订单或退还该付款。
由于环境已不再连接，退款失败：付款是在正式环境或沙盒中进行的，而该环境现在已没有密钥。请使用激活码重新连接，或在 Satispay Dashboard 中退还该付款。
退款失败，提示 Satispay did not accept the refund：Satispay 返回的状态不是 accepted。WooCommerce 没有记录该退款。请在 Satispay Dashboard 中核对。
许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在另一个域名上使用，请在您的 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now，为新域名激活该密钥。如果无法连接许可证服务器，插件会继续使用最后已知的状态运行。
卸载
停用插件会保留所有数据。要删除插件，请先停用，然后在 Plugins 页面将其删除。该插件的许可证密钥和许可证状态总会被删除。网关设置、两个环境的 Satispay 密钥以及插件日志只有在开启 Delete data on uninstall 时才会被删除；否则它们会保留，以便日后重新安装。现有订单会保留其付款备注和交易 ID。
Satispay 是其各自所有者的商标。本插件与 Satispay 没有关联，也未获得 Satispay 的认可。