VibeFox Satispay for OpenCart — 帮助

要求

OpenCart： 3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。

PHP： 8.0 或更高版本，并启用 OpenSSL 扩展。本扩展使用 OpenSSL 生成其 RSA 密钥。

货币： EUR。Satispay 仅收取欧元。必须在 System > Localisation > Currencies 中启用 EUR 货币，且只有当顾客选择了 EUR 时才会显示该支付方式。

Satispay 账户： Satispay Business 账户。您无需复制任何 API 密钥：本扩展通过您在 Satispay Business Dashboard 中生成的一次性激活码进行连接（参见 Configuration）。测试时，您需要一个 Satispay 沙盒账户，可向 Satispay 开发者支持申请。

公开店铺： 您的店铺必须能够从互联网访问，以便 Satispay 在付款状态变化时回调它。为此无需在 Satispay 中进行任何设置。

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

安装

下载文件是一个 zip 压缩包，内含两个 OpenCart 版本的安装包。请先将其解压到您的电脑上。压缩包中包括 README.txt、OpenCart 3 安装包 wcp_satispay_gateway-oc3-(version).ocmod.zip，以及 OpenCart 4 安装包 wcp_satispay_gateway.ocmod.zip。请只安装与您的 OpenCart 版本对应的安装包。两个版本使用相同的许可证密钥。

OpenCart 3

1. 在管理后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_satispay_gateway-oc3-(version).ocmod.zip。本扩展没有 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装器，而是将本安装包中 upload 文件夹的内容复制到店铺的根目录。

2. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox Satispay Gateway，点击 Install（绿色 + 按钮）。您的管理员用户需要有修改支付扩展列表的权限。

3. 点击 Edit（铅笔按钮）打开设置页面。将您的 VibeFox 许可证密钥粘贴到页面顶部许可证区块的 License key 中，然后点击 Activate（参见 License key）。

4. 选择环境：测试时开启 Sandbox Mode，进行真实付款时保持关闭。

5. 将该环境的激活码粘贴到 Activation Code 中，然后点击 Save。之后 Status 字段会显示 Connected 和 Key ID。

6. 开启 Enable/Disable，然后点击 Save。在沙盒中测试一笔付款，然后关闭 Sandbox Mode，并使用正式激活码连接正式环境。

OpenCart 4

1. 在管理后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_satispay_gateway.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名获取扩展代码，重命名后的安装包无法使用。

2. 安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。

3. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox Satispay Gateway，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。

4. 输入许可证密钥，选择环境，并按照 OpenCart 3 步骤 3 至 6 的方法，使用激活码进行连接。两个版本的设置页面及其字段相同。只有回调 URL 不同（参见 Payment notifications）。

新安装时，支付方式默认关闭，并选中正式环境。

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox Satispay Gateway > Edit。各设置区块列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，当支付方式已启用但所用环境未连接时（此时结账时会隐藏该支付方式），以及当店铺的默认货币不是 EUR 时（此时只有顾客选择 EUR 才会显示该支付方式），页面会向您发出警告。如果没有修改扩展的权限，页面会显示设置但无法保存。

保存时，Title 的长度必须为 1 到 128 个字符，Sort Order 必须为整数（允许负数），Total 必须为大于或等于 0 的数字，并且地理区域和订单状态必须存在。如果某个值有误，则不会保存任何内容，激活码也不会发送。

结账

Enable/Disable: Enable Satispay payment 用于开启或关闭该支付方式。Default: off.

Title: 顾客在结账时看到的支付方式名称。它也是订单中保存的支付方式名称。Default: Satispay. 必填，最多 128 个字符。

Description: 在 Confirm Order 步骤中、确认按钮上方显示给顾客的文字。Default: Pay with the Satispay app: scan the QR code or confirm the payment on your phone.

Sort Order: Satispay 在结账页面支付方式中的位置。可留空，或输入整数。

Geo Zone: 仅对所选地理区域内的付款地址提供 Satispay。Default: All zones。地理区域在 System > Localisation > Geo Zones 中设置。

Total: 订单在结账时必须达到的、以店铺默认货币计算的金额，达到后才会提供 Satispay：一个大于或等于 0 的数字。留空则对任何金额都提供 Satispay。

Satispay 连接

Status: 两个环境的状态，例如带有 Key ID 的 Live: Connected 或 Sandbox: Not connected，以及哪个环境正在使用中（in use）。在使用中的环境未连接期间，该字段会显示 Satispay is hidden at checkout until the environment in use is connected.

Sandbox Mode: 使用 Satispay 沙盒（测试）环境。沙盒付款不会被扣款。Default: off. 沙盒和正式环境的密钥是分开的：请使用对应环境的激活码连接各自的环境。使用沙盒期间，顾客在 Confirm Order 步骤会看到 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 的消息，并请您检查该激活码是否属于此环境且尚未使用；当前连接保持不变。不是 4 到 64 个字母和数字的激活码，会在发送任何内容之前被拒绝。为某个环境保存新激活码会替换其之前的连接。

付款通知

无需在 Satispay 中进行任何设置。每笔付款都带有自己的回调 URL，付款状态变化时 Satispay 会调用该 URL，并且扩展会在修改订单前从 Satispay API 重新读取该付款。Callback URL 字段会显示此 URL 的一个示例。在 OpenCart 3 中格式类似 https://your-store/index.php?route=extension/payment/wcp_satispay_gateway/callback&satispay_p_order={order}&payment_id={uuid}，在 OpenCart 4 中则类似 https://your-store/index.php?route=extension/wcp_satispay_gateway/payment/wcp_satispay_gateway.callback&satispay_p_order={order}&payment_id={uuid}，由您 OpenCart 安装的前台地址生成。该 URL 必须能够从互联网访问：其前面不能有防火墙或基本身份验证。OpenCart 的维护模式不会阻止它。如果回调无法访问您的店铺，则订单会在顾客返回时确认。

订单

OpenCart 会在 Confirm Order 步骤创建没有状态的订单（缺失订单，missing order）。只有在 Satispay 接受付款后，订单才会获得状态。下面的每个字段都列出了您的 OpenCart 订单状态。

Order Status After Payment: 付款被接受后设置的状态。Default: Processing.

Satispay Payment On Hold Status: 款项已收到，但订单需要审核（参见 Order statuses）。Default: Pending，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择它。

Refunded Status: 在订单页面将付款全额退款后设置。Default: Refunded.

高级

Debug log: 将 API 调用和付款事件写入 OpenCart 日志文件夹（storage/logs）中的 satispay_p_debug.log.php。该文件无法通过网页打开，达到 5 MB 时会被移动到 satispay_p_debug.old.log.php。密钥、激活码和顾客数据不会被记录。即使关闭此选项，错误也始终会被记录。Default: off.

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

Delete data on uninstall: 开启后，卸载扩展会删除网关设置、两个环境的 Satispay 密钥以及日志。为订单保存的 Satispay 付款和退款始终会保留。Default: off.

导入 / 导出

Export: Download JSON 将设置保存为 JSON 文件。Satispay 密钥不会被导出。

Import: 粘贴之前导出的 JSON，然后点击 Import 恢复设置。Satispay 连接会保持不变。

结账

在 Payment Method 步骤，顾客选择支付方式（默认为 Satispay）。在 Confirm Order 步骤，顾客会看到您的描述以及提示 You will be redirected to the Satispay page: scan the QR code with the Satispay app or confirm the payment on your phone. OpenCart 在此步骤创建订单，此时仍没有状态。当顾客点击 Confirm Order 时，扩展会以订单号作为参考，为订单总额（欧元）创建一笔 Satispay 付款，并将顾客带到 Satispay 付款页面。在电脑上，顾客用 Satispay 应用扫描二维码。在手机上，顾客在应用中确认付款。在 OpenCart 4 中，顾客通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式，然后点击结账页面底部的 Confirm Order。

付款后，顾客返回您的店铺。只有在 Satispay 确认之后，订单才会被标记为已付款：扩展会通过 Satispay API 读取付款，检查它是否为该订单而创建，并将其状态、金额（以分为单位）和货币与订单进行比对。无论 Satispay 先调用回调 URL，还是顾客先返回，都会执行此检查，以先发生者为准。然后，订单会以 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存，顾客会看到 OpenCart 的订单成功页面。如果顾客返回时 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. 当顾客在应用中拒绝付款时，也会显示同样的消息。购物车会被保留。

OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单。OpenCart 4 为结账保留一个订单并更新它，因此取消付款后，同一订单会以新的 Satispay 付款完成支付。在创建新的 Satispay 付款之前，会检查购物车之前的付款：待处理的付款会在 Satispay 处被取消；如果其中某笔已经付款，它会确认自己的订单，不会再进行第二次付款，顾客会直接进入成功页面。

在 OpenCart 4 中，取消付款的消息显示在结账页面上方。如果结账时的订单已被店铺关闭（例如已取消或已退款），或已付款但此后购物车发生了变化（包括新的数量），顾客会被带回结账页面，并在结账页面上方看到 Your previous order is already closed. Please confirm the order again: the cart will be paid with a new order.，而下一次点击 Confirm Order 将支付一个新订单。

如果无法发起付款，顾客会停留在 Confirm Order 步骤，按钮上方显示简短消息：Satispay 拒绝密钥时显示 Satispay is not available at the moment. Please choose another payment method.；订单使用其他货币时显示 Satispay supports EUR currency only.；其他错误时显示 Unable to create the Satispay payment. Please try again or choose another payment method. 原因会写入日志。

回调和顾客的返回在店铺处于维护模式时仍然有效：OpenCart 3 允许支付扩展的请求通过，而在 OpenCart 4 中，扩展为这些请求添加了一个启动操作。

本扩展仅接受以欧元计价的一次性付款。它不支持订阅、已保存的支付方式、预授权或餐饮券。没有对待处理付款的定时检查：如果 Satispay 回调和顾客返回都未能到达您的店铺，订单将保持无状态，而该付款可在 Satispay Dashboard 中查看。

订单与退款

订单状态

No status (missing order): 顾客已被转到 Satispay 但尚未付款，或 Satispay 尚未确认付款。在 Sales > Orders 中，这类订单只有在筛选器 Order Status 设为 Missing Orders 时才会显示。已取消的 Satispay 付款会使订单保持无状态，顾客可以再次付款。

Order Status After Payment (default Processing): 付款已被接受。备注会显示 Satispay 付款、金额以及验证方式（回调、重定向或结账）。

Satispay Payment On Hold Status (default Pending): Satispay 报告的金额或货币与订单总额不同，或者订单在获得其他状态（例如已取消）之后才接受付款。备注会说明这一点。请在 Satispay Dashboard 中检查该付款，然后履行订单或为付款退款。如果之后该购物车的另一笔金额正确的付款被接受，订单会转为 Order Status After Payment。

Refunded Status (default Refunded): 付款已通过扩展全额退款。

如果对已付款的订单，或对同一购物车的另一个订单，接受了第二笔付款，已付款的订单不会被更改。备注会要求您在 Satispay Dashboard 中为重复付款退款。

备注是订单 History 中的条目，顾客看不到。

VibeFox Satispay Gateway tab

在 Sales > Orders 中打开一笔通过 Satispay 付款的订单。在订单页面底部，紧挨着 History 和 Additional，VibeFox Satispay Gateway 选项卡会显示 Satispay payment ID（沙盒付款会带有 Sandbox 标签）、付款的 Status、Paid / refunded 金额、退款表单、Refunds 历史记录、Satispay payments of this cart 列表（包含每次付款尝试、其订单和环境），以及订单的 Satispay notes。该选项卡对有权访问扩展的用户显示。

退款

在 VibeFox Satispay Gateway 选项卡中输入 Amount（尚未退款的金额会自动填入），可选填 Reason (optional)，然后点击 Refund via Satispay。确认提问 Refund this amount through Satispay? This cannot be undone. 支持全额和部分退款。您需要有修改扩展的权限（在 System > Users > User Groups 中设置）。退款金额被限制为 Satispay 对该付款实际扣款的金额，因此在金额不一致的情况下，您最多只能退还顾客实际支付的金额，而不是订单总额。退款会发送到付款时所用的环境（正式或沙盒），因此该环境必须仍处于连接状态。只有当 Satispay 接受退款时，退款才算完成：成功的退款会连同 Satispay 退款 ID 和原因一起添加到历史记录和备注中。如果 Satispay 不接受退款，选项卡会显示错误，并且不会记录任何退款。全额退款会将订单设为 Refunded Status，且不通知顾客，也不会将商品退回库存，与手动更改状态一样。部分退款不会更改状态。只有在 Satispay 接受付款之后，才能进行退款。

在 Sales > Returns 中的商品退货不会通过 Satispay 退回资金。在 Satispay Dashboard 中进行的退款不会记录到 OpenCart 中。如有需要，请手动更新订单。

许可证密钥

本扩展需要使用在 vibefox.net 获取的 VibeFox 许可证密钥。许可证区块 License — VibeFox Satispay Gateway 是 Extensions > Extensions > Payments > VibeFox Satispay Gateway > Edit 中的第一个区块，位于设置上方。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期的截止日期以及您的域名），并提供以下按钮：Check now（再次检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺中移除该密钥）。它们下方有一行 Product: opencart-payment-satispay，以及打开您 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 账户中释放该名额。

没有有效密钥时，Satispay 不会在结账时向顾客显示。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 以同一浏览器登录管理后台的管理员用户，仍会在店铺中看到该支付方式，并标有 (unlicensed — visible to admins only)，这样您就可以在购买密钥之前设置和测试扩展。在 OpenCart 4 中，此预览不可用：店铺看不到管理员的后台登录状态，因此在没有有效密钥时，所有人都看不到该付款方式。打开一次 Edit 页面之后，管理后台的 Dashboard 上会出现一条提醒。点击 × 可将其隐藏 7 天。现有订单不受影响：已经发起的付款仍会被确认，退款也可以正常进行。

许可证到期时，扩展仍会继续运行，但更新和支持需要续订。当您打开管理后台的 Dashboard 或 Edit 页面时，系统会自动再次检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需定时任务。卸载扩展时，始终会删除许可证密钥和许可证状态。

故障排除

Satispay 未出现在结账页面： 请检查许可证是否有效、Enable/Disable 是否开启、所用环境是否已连接（Status 字段会为其显示 Connected），以及顾客是否选择了 EUR。另外请检查付款地址是否位于所选的 Geo Zone 内，以及订单是否达到了设置中的 Total。

付款已完成，但订单仍无状态： 订单会在 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.： 结账页面已与订单不再匹配，或支付方式在此期间被关闭。顾客重新加载结账页面。

订单在付款后处于审核状态： 请阅读 VibeFox Satispay Gateway 选项卡中的备注（参见 Order statuses），在 Satispay Dashboard 中检查该付款，然后履行订单或为付款退款。

选项卡中没有退款表单： 选项卡会说明原因：订单没有已接受的 Satispay 付款、已全额退款、您的用户组没有修改扩展的权限，或付款的环境已不再连接。

因环境已不再连接而退款失败： 付款是在正式或沙盒环境中进行的，而该环境现在已没有密钥。请使用激活码重新连接，或在 Satispay Dashboard 中为付款退款。

退款失败，提示 Satispay did not accept the refund： Satispay 返回了 accepted 以外的状态。OpenCart 没有记录该退款，备注中会说明。请在 Satispay Dashboard 中检查。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Satispay Gateway 旁边的 Uninstall（红色 − 按钮）。本扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Orders 部分中的订单状态，这些设置在重新安装时会恢复为默认值。在 OpenCart 4 中，扩展的事件以及在维护模式下放行回调和顾客返回的启动操作也会被移除。如果 Delete data on uninstall 已开启，其他网关设置（标题、描述、沙盒模式、日志）、两个环境的 Satispay 密钥以及日志都会被删除。如果未开启，这些内容会被保留，以便日后重新安装时使用，包括 Satispay 连接。为订单保存的 Satispay 付款和退款始终会保留，因此，之前已付款的订单在重新安装并重新连接环境后，仍可退款。现有订单会保留其付款备注。

在 OpenCart 4 中，如需同时删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox Satispay Gateway 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）删除已上传的安装包。

Satispay 是其各自所有者的商标。本扩展与 Satispay 无关联，也未获得 Satispay 的认可。