VibeFox Yoco for OpenCart — 帮助

要求

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

PHP：8.0 或更高版本。

店铺币种：必须在 System > Localisation > Currencies 中启用南非兰特（ZAR）。Yoco 仅接受 ZAR。当顾客以其他币种付款时，结账页面会隐藏该付款方式。订单总额必须至少为 R2.00。

Yoco 账户：一个拥有在线付款功能的 Yoco 账户。您需要其密钥，可在 Yoco Business Portal 的 Selling Online > Payment Gateway 下找到。只需输入密钥。webhook 由扩展注册，其签名密钥会为您自动填写。

公开站点：Yoco 会向您的店铺发送 webhook，因此店铺必须可以从互联网访问。

VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥对应一个域名。

安装

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

OpenCart 3

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

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

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

4. 粘贴测试模式的密钥（sk_test_...），准备就绪后再粘贴正式模式的密钥（sk_live_...）。点击 Save。每个有密钥的模式都会注册 webhook。

5. 打开 Enable/Disable，点击 Save。在 Test mode 开启时，使用 Yoco 测试卡完成一次测试付款，然后关闭 Test mode 以接收真实付款。

OpenCart 4

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

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

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

4. 按照 OpenCart 3 的第 3 至 5 步输入许可证密钥和 Yoco 密钥。两个版本的设置页面及其字段相同。只有 webhook URL 不同（参见 Webhook）；保存时会以同样的方式在 Yoco 注册。

新安装时，付款方式默认关闭，测试模式默认开启。

配置

所有设置都在扩展页面中：Extensions > Extensions > Payments > VibeFox Yoco Pay Gateway > Edit。各个部分列在左侧；列表下方的 Save 按钮会保存整个页面。如果没有修改扩展的权限，页面会显示设置但无法保存。

设置上方，页面会显示当前模式（Test mode: the test secret key is used, no real money is charged. 或 Live mode: real payments are accepted.）。如果店铺的默认币种不是 ZAR，页面会发出警告（此时只有顾客以 ZAR 付款时才会提供 Yoco；如果没有启用任何 ZAR 币种，则完全不提供），如果当前模式没有密钥，页面也会警告，例如 Enter the test secret key to offer Yoco at checkout (test mode).

保存时，Title 最多 128 个字符，Sort Order 必须是整数（允许负数），Total 必须是大于或等于 0 的数字，并且地理区域和订单状态必须存在。否则不会保存任何内容，页面会指出相应字段。之后，扩展会检查密钥和 webhook 密钥，并注册 webhook。相关消息会显示在设置上方。

Yoco

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

Title：顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认：Card or Instant EFT (Yoco)。最多 128 个字符；为空时，顾客看到的是 Card or Instant EFT (Yoco)。

Description：在 Confirm Order 步骤中、确认按钮上方显示给顾客的文字。默认：You will be redirected to the secure Yoco page to pay by card or Instant EFT.

Sort Order：Yoco 在结账付款方式中的位置。留空或输入整数。

Geo Zone：仅为所选地理区域内的付款地址提供 Yoco。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。

Total：在提供 Yoco 之前，订单需要达到的结账总额（按店铺默认币种计算）。留空则对任何金额都提供 Yoco。Yoco 本身始终要求至少 R2.00。

API 密钥

从 Yoco Business Portal 中 Selling Online > Payment Gateway 下复制密钥（该部分有链接）。Yoco 两种模式使用同一个 API：由密钥决定付款是测试还是真实的。测试模式只使用测试密钥，正式模式只使用正式密钥。

Test mode：使用测试密钥。不会收取真实费用；请使用 Yoco 测试卡付款。默认：on。关闭后接收真实付款。开启期间，顾客在 Confirm Order 步骤会看到 Test mode — use a Yoco test card; no real money is charged.

Test secret key：测试模式的密钥。以 sk_test_ 开头。

Live secret key：正式模式的密钥。以 sk_live_ 开头。

不以预期前缀开头的密钥不会被保存：页面会显示错误，例如 Yoco: the test secret key must start with sk_test_ — the previous value was kept. 其他设置仍会保存。如果 Yoco 在注册 webhook 时指出某个密钥属于另一模式，页面会告知您。

已保存的密钥和密钥值不会再次显示。字段保持为空，并显示 Saved — leave empty to keep it. 只有需要更改时才输入新值。要删除已保存的值，请勾选字段下方的 Clear the saved value 并点击 Save。

Webhook

Yoco 会将付款和退款通知发送到本部分 Webhook URL 中显示的 URL。该 URL 在 OpenCart 3 中形如 https://your-store/index.php?route=extension/payment/wcp_yoco_pay/webhook，在 OpenCart 4 中则形如 https://your-store/index.php?route=extension/wcp_yoco_pay/payment/wcp_yoco_pay.webhook，由您 OpenCart 安装的店铺前台地址构成。您无需在 Yoco 门户中创建 webhook。保存设置时，扩展会为每个有密钥但没有 webhook 密钥的模式，在 Yoco 注册该 URL，并将签名密钥保存到该模式的字段中。当该模式的密钥或 webhook URL 更改时，它会重新注册该 URL。URL 更改时，旧的注册会被移除。

对于每个模式（Test 和 Live），本部分会显示 webhook 的状态：

扩展会处理以下事件（它们也列在本部分中）：

没有有效签名的 webhook 会被拒绝。事件必须使用付款时所在模式的密钥签名，因此测试密钥绝不会确认正式付款。

Test webhook secret：注册 webhook 时自动填写。仅当您自行注册了 webhook URL 时，才粘贴密钥（whsec_...）。

Live webhook secret：注册 webhook 时自动填写。清空后保存即可重新注册 webhook。

webhook 密钥的格式必须是 whsec_ 加上 base64 文本。其他任何值都不会被保存，并保留之前的值。清空 webhook 密钥并保存，会重新注册 webhook。

订单

OpenCart 在 Confirm Order 步骤创建订单时没有状态（即缺失订单）。只有在 Yoco 通过 API 确认付款后，订单才会获得状态。下面的每个字段都列出了您的 OpenCart 订单状态。

Paid Order Status：确认付款后的状态。默认：Processing。

On Hold Status：金额或币种与订单总额不符的付款会使订单进入此状态并附带备注。之后金额正确的付款会将其结清。默认：Pending，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态并在此处选择。

Refunded Status：退款金额达到已付金额时设置。默认：Refunded。

高级

Debug log：将 Yoco 请求和 webhook 写入 OpenCart 日志文件夹（storage/logs，在 OpenCart 4 中为 system/storage/logs）中的 yoco_p_debug.log.php。该文件无法通过网页打开，达到 5 MB 时会被移动到 yoco_p_debug.old.log.php。失败的 Yoco 请求和被拒绝的 webhook 等错误和警告始终会被记录。密钥、webhook 密钥和电子邮件地址都会被隐藏。默认：off。

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

Delete data：开启后，卸载扩展会删除网关设置、日志以及扩展在 Yoco 注册的 webhook。订单数据（Yoco 结账和付款 ID、退款）始终保留，因为退款需要这些数据。默认：off。

导入 / 导出

Export：Download JSON 将设置保存为 JSON 文件。密钥和 webhook 密钥不会被导出。

Import：粘贴之前导出的 JSON，然后点击 Import 以恢复设置。已保存的密钥会保留，导入不会注册任何 webhook。

结账

当顾客以 ZAR 付款且订单总额至少为 R2.00 时，会显示付款方式。顾客在 Payment Method 步骤中选择它（默认为 Card or Instant EFT (Yoco)）。在 Confirm Order 步骤，顾客会看到您的描述。OpenCart 在此步骤创建订单，此时仍没有状态。在 OpenCart 4 中，顾客通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式，并在结账页面底部点击 Confirm Order。当顾客点击 Confirm Order 时，扩展会以分为单位、按订单总额创建一个 Yoco 结账页面，并将顾客转到 Yoco 付款页面，顾客在那里使用银行卡或 Instant EFT 付款。

付款后，顾客返回您的店铺。只有在 Yoco 确认后，订单才会被标记为已付款：顾客返回时，扩展会向 Yoco 查询结账信息；签名的 webhook 到达时，会再次查询。之后，订单会以 OpenCart 的标准方式获得状态，发送常规订单邮件并更新库存，顾客会看到 OpenCart 订单成功页面，显示 Your payment with Yoco has been received. 如果顾客返回时 Yoco 尚未确认付款，Payment confirmation 页面会显示 We are waiting for Yoco to confirm your payment. The order will be updated automatically — please do not pay again.，并带有 Check again 和 Back to checkout 按钮；webhook 一到达就会设置订单状态。在 OpenCart 4 中，顾客从 Yoco 页面返回时，一个简短的中间页面会重新打开您店铺的返回地址，因此购物车和顾客登录状态都会保留。

如果顾客在 Yoco 页面取消，他会返回结账页面，显示 The Yoco payment was cancelled. Your cart is saved — you can pay again or choose another payment method. 如果付款失败，消息为 The Yoco payment was not successful. Please try again or choose another payment method.，并且订单中会添加一条备注。购物车会被保留。在 OpenCart 4 中，这些消息会显示在结账页面上方。

OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单；OpenCart 4 则会更新结账中的订单。在新的付款之前，扩展会检查购物车：如果同一购物车的另一个订单已付款，顾客会直接进入成功页面。该订单以及最近 24 小时内购物车中未付款的 Yoco 结账页面，会先向 Yoco 核查；如果其中一个在此期间已付款，则确认该付款，而不是创建新的付款。如果同一订单的未完成结账页面金额和模式相同，且创建于 30 分钟以内，顾客会再次看到同一个 Yoco 页面。否则会创建新的 Yoco 结账页面。购物车发生变化（包括数量变化）时，视为需要单独付款的新购物车。

OpenCart 4 会将订单保留在结账流程中，直到显示成功页面为止，因此付款被取消或失败后，顾客会再次支付同一订单。如果该订单在此期间未付款即已关闭（例如您已将其取消），顾客会被送回结账页面，并看到 Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order.；下一次 Confirm Order 会为新订单付款。

如果 Yoco 无法开始付款，顾客会停留在 Confirm Order 步骤，按钮上方显示 Yoco could not start the payment. Please try again in a moment or choose another payment method.，原因会写入日志和订单备注。金额低于 R2.00 的订单会显示 Yoco requires an order total of at least R2.00.

店铺处于维护模式时，webhook 仍然有效，因为 OpenCart 允许付款扩展的请求通过。在 OpenCart 4 中，扩展的启动动作会放行 webhook 和顾客的返回。

付款会在 Yoco 页面上立即扣款。扩展不支持保存银行卡、订阅或定期付款，店铺中没有银行卡表单，也不支持分别授权和扣款；并且不支持 ZAR 以外的币种。

订单和退款

订单状态

无状态（缺失订单）：顾客已被转到 Yoco 但尚未付款、在 Yoco 页面上取消，或 Yoco 尚未确认付款。在 Sales > Orders 中，此类订单只有在 Order Status 筛选器设为 Missing Orders 时才会显示。在 OpenCart 4.1 中，此类订单也可能带有 Voided 状态，OpenCart 在再次显示确认步骤时会设置该状态；扩展会将其视为无状态订单。

Paid Order Status（默认 Processing）：付款已确认。备注会显示金额、Yoco 付款和结账 ID、模式，以及付款是如何被确认的（顾客返回、webhook，或在新的付款尝试之前进行的检查）。

On Hold Status（默认 Pending）：Yoco 报告的金额或币种与订单总额不同，例如付款开始后，购物车在另一个标签页中被修改。备注会对此进行说明，顾客会看到 We received your payment and are reviewing it. We will contact you if anything else is needed. 发货前请核实付款。如果顾客之后通过另一次尝试支付了正确的金额，订单会转为 Paid Order Status。

Refunded Status（默认 Refunded）：退款已达到已付金额。

如果为一个状态不同的订单（例如已取消或已退款）收到了付款，订单不会被更改。备注会要求您在 Yoco 门户中退还付款，或手动恢复订单。顾客会看到 Your payment was received after the order had been cancelled. Please contact us — do not pay again.

如果为已付款的订单，或已付款购物车中的另一个订单收到了第二笔付款，订单不会被更改。已付款订单上的备注会要求您在 Yoco 门户中退还该笔付款。

备注是订单 History 中的条目，顾客看不到。它们以 Yoco 一词开头。

VibeFox Yoco Pay Gateway 选项卡

在 Sales > Orders 中打开一个通过 Yoco 付款的订单。在订单页面底部，紧挨着 History 和 Additional 的位置，VibeFox Yoco Pay Gateway 选项卡会显示 Checkout ID、Payment ID、Mode（测试付款会带有 Test 标签）、Status、Paid / refunded 金额、退款表单、Yoco checkouts of this order 表格、Refunds 历史以及订单的 Yoco notes。该选项卡仅对有权访问该扩展的用户显示。

退款

在 VibeFox Yoco Pay Gateway 选项卡中输入 Amount（自动填入尚未退款的金额），可选填写 Reason (optional)，然后点击 Refund via Yoco。确认提示 Refund this amount through Yoco? This cannot be undone. 支持全额和部分退款。您需要有修改扩展的权限（在 System > Users > User Groups 中设置）。退款金额以 Yoco 扣款金额为准，因此即使之后修改了订单，您最多也只能退还顾客实际支付的金额。退款会以付款时所在的模式（测试或正式）发送，因此该模式的密钥必须已设置。在响应丢失后重复的退款不会被重复支付。

退款成功后，会将其添加到退款历史和备注中，并附上 Yoco 退款 ID。退款金额达到已付金额时，订单会获得 Refunded Status，且不会通知顾客，也不会将商品退回库存；部分退款不会更改状态。如果 Yoco 拒绝退款，选项卡会显示 Yoco refused the refund: 及原因，且不会记录任何退款。如果 Yoco 报告退款为待处理，选项卡会显示待处理状态。请不要重复操作：当 Yoco 通过 webhook 确认后，退款会被记录。只有通过 Yoco 结账付款的订单才能退款。处于 On Hold Status 的订单没有已确认的付款可退，请在 Yoco 门户中退款。

Sales > Returns 中的商品退货不会通过 Yoco 退回款项。

在 Yoco 门户中进行的退款会通过 refund.succeeded webhook 到达，并记录在退款历史和备注中。当它们达到已付金额时，订单会获得 Refunded Status。超过剩余可退金额的退款不会被记录，备注会提示您检查订单。失败的退款会添加一条备注，说明款项未退还给顾客。

许可证密钥

本扩展需要来自 vibefox.net 的 VibeFox 许可证密钥。扩展的 License — VibeFox Yoco Pay Gateway 许可证块是 Extensions > Extensions > Payments > VibeFox Yoco Pay Gateway > Edit 页面中位于设置上方的第一个块。将密钥粘贴到 License key，然后点击 Activate。之后，该块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），并提供以下按钮：Check now 用于重新检查状态，Change key 用于输入其他密钥，Remove key 用于从本店铺移除密钥。其下方是 Product: opencart-payment-yoco 一行，以及 Manage licenses and domains in your account 链接，该链接会打开您的 vibefox.net 账户。只有拥有该扩展 Modify 权限的管理员用户才能更改密钥。该块的文字跟随后台语言显示（包含英文和俄文）。

如果密钥未被接受，该块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached 或 License expired on 加上日期。在店铺地址更改后，或在您的账户中释放一个域名名额后，请点击 Check now。如果无法连接许可证服务器，扩展会继续使用最近一次已知的状态。

一个密钥只对应一个域名：即 OpenCart 配置中的店铺地址。从店铺中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。

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

许可证到期后，扩展仍会继续工作，但更新和支持需要续费。打开后台 Dashboard 或 Edit 页面时会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载扩展时始终会删除许可证密钥和许可证状态。

故障排除

结账时没有显示 Yoco：请检查许可证是否有效，Enable/Disable 是否开启，当前模式是否有密钥（测试模式为 Test secret key，正式模式为 Live secret key）。顾客必须以 ZAR 付款，且订单总额至少为 R2.00。缺少密钥或店铺币种不是 ZAR 时，设置页面会显示警告。另外请检查付款地址是否在所选的 Geo Zone 中，以及订单是否达到设置中的 Total。

付款已完成，但订单仍无状态：webhook 没有正常工作。打开设置中的 Webhooks 部分，检查您所用模式的状态。如果未注册，或注册到了其他 URL，请保存设置。如果注册失败，页面会显示原因。如果您是自行输入的密钥，请检查它是否属于此 URL 和此模式的 webhook。顾客付款后返回店铺时，以及顾客再次尝试付款时，订单也会获得状态。

无法注册 webhook：顾客返回店铺时，付款仍会被确认。请解决消息中显示的原因（例如店铺必须可以从互联网访问），然后重新保存。您也可以自行注册该 URL，并粘贴签名密钥。

Webhook 被拒绝：被拒绝的 webhook 会写入日志。webhook secret not configured 表示没有设置任何 webhook 密钥。invalid signature 表示该密钥属于另一个注册或模式。timestamp outside the tolerance 表示服务器时钟有误：签名只在服务器时间 5 分钟内被接受。checkout not completed yet — retry 和 could not confirm the checkout with Yoco — retry 是临时性的；Yoco 会重新发送 webhook。

Webhook URL 在浏览器中只显示 POST：这是正常现象。该 URL 只接受来自 Yoco 的请求。

保存时出现 The secret key must start with sk_test_ / sk_live_ 错误：密钥被粘贴到了错误的字段中。测试密钥以 sk_test_ 开头，正式密钥以 sk_live_ 开头。之前的值已被保留。

顾客在 Confirm Order 之后看到错误：请查看扩展页面上的 Log 字段。Yoco is not available at the moment. Please choose another payment method. 表示当前模式没有密钥。

顾客被告知付款需要审核：某次尝试的付款金额不同，或订单在取消之后付款。请阅读 VibeFox Yoco Pay Gateway 选项卡中的备注，并在 Yoco 门户中处理订单或退款。

退款因模式相关信息而失败：付款是在测试或正式模式下完成的，而该模式的密钥未设置。请输入密钥后重试。

退款显示 No answer from Yoco 而失败：OpenCart 中没有记录任何内容。如果 Yoco 确实处理了退款，请重复同一笔退款：不会被退两次。

对于开发者：在创建 Yoco 结账页面之前，扩展会触发 OpenCart 事件 yoco_p_checkout_payload，并附带请求数据和订单，以便其他扩展向请求中添加内容。

卸载

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

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

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