VibeFox Yoco for PrestaShop — 帮助

系统要求

PrestaShop：8.0 至 9.x。

PHP：8.0 或更高版本。模块不会安装在更早的 PHP 版本上。

店铺货币：南非兰特（ZAR）。Yoco 仅接受 ZAR。使用其他货币时，结账时不会显示该付款方式。订单总额必须至少为 R2.00。

Yoco 账户：开通了在线付款功能的 Yoco 账户。您需要其密钥，可在 Yoco Business Portal 的 Selling Online > Payment Gateway 下找到。只需填写密钥。Webhook 由模块注册，其签名密钥会自动填入。

公网站点：Yoco 会向您的店铺发送 Webhook，因此店铺必须可从互联网访问。Webhook URL 必须接受 POST 请求且不得重定向。

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

安装

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

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

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

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

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

安装时模块会创建订单状态 Yoco payment on hold。PrestaShop 会为所有货币、国家和客户组启用新的付款模块。您可以在 Payment > Preferences 中加以限制。

配置

所有设置都在模块页面中：Modules > Module Manager > VibeFox Yoco Pay Gateway > Configure。每个部分都有自己的 Save 按钮，保存的是整个页面。页面在字段上方会提示：当店铺货币不是 ZAR 时（此时结账不提供 Yoco），以及当前模式没有密钥时，例如 Enter the test secret key to offer Yoco at checkout (test mode). 保存时，模块会检查密钥和 Webhook 签名密钥，并注册 Webhook。相关消息会显示在页面顶部。

Yoco

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

Title：顾客在结账时看到的付款方式名称。订单中保存的付款方式名称也是它。默认：Card or Instant EFT (Yoco)。

Description：结账时显示在付款方式下方的文字。默认：You will be redirected to the secure Yoco page to pay by card or Instant EFT.

API 密钥

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

Test mode：使用测试密钥。不会扣除真实款项；请使用 Yoco 测试卡付款。默认：开启。关闭后即可接收真实付款。开启期间，顾客会在付款方式下方看到 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. 如果在注册 Webhook 时 Yoco 报告某个密钥属于另一种模式，页面会告知您。

已保存的密钥和签名密钥不会再次显示。字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。

Webhooks

Yoco 会将付款和退款确认发送到本部分 Webhook URL 中显示的 URL。使用友好 URL 时，它类似 https://your-shop/module/wcp_yoco_pay/webhook，可能带有语言代码，例如 /en/。您无需在 Yoco 后台创建 Webhook。保存设置时，模块会为每个有密钥但没有 Webhook 签名密钥的模式向 Yoco 注册该 URL，并将签名密钥保存到该模式的字段中。当该模式的密钥或 Webhook URL 发生变化时，会再次注册。URL 变化时，旧的注册会被删除。

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

模块会处理以下事件（本部分也列出了这些事件）：

没有有效签名的 Webhook 会被拒绝。事件必须使用付款所用模式的密钥签名，因此测试密钥永远无法确认正式付款。请完全按照设置中显示的内容复制 URL，因为 Webhook 必须无重定向地到达您的店铺。

Test webhook secret：注册 Webhook 时自动填入。只有在您自行注册了 Webhook URL 时，才粘贴签名密钥（whsec_...）。

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

Webhook 签名密钥的格式应为 whsec_ 加 base64 文本。其他任何值都不会被保存，之前的值会保留。

Clear saved secrets：勾选某个密钥或签名密钥，然后点击 Save 即可删除。字段为空时保留已保存的值。清空 Webhook 签名密钥并保存，会重新注册 Webhook。

高级

Debug log：将 Yoco 请求和 Webhook 写入模块文件夹中的 logs/yoco_p_debug.log.php。该文件无法通过网页打开。错误和警告（例如向 Yoco 发送失败的请求和被拒绝的 Webhook）始终会记录。密钥、Webhook 签名密钥和电子邮件地址都会被遮蔽。默认：关闭。

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

Delete data：开启时，卸载模块会删除设置、日志以及模块在 Yoco 注册的 Webhook。订单数据（Yoco checkout 和付款 ID、退款）以及 Yoco payment on hold 订单状态始终保留，因为退款需要它们。默认：关闭。

结账

在付款步骤，顾客选择付款方式（默认为 Card or Instant EFT (Yoco)）并确认。模块会按购物车总额（以分为单位）创建 Yoco checkout，并将顾客带到 Yoco 付款页面，顾客在那里使用银行卡或 Instant EFT 付款。此时尚未创建订单。

付款后，顾客返回您的店铺。只有在 Yoco 确认后，订单才会标记为已付款：顾客返回时，模块会向 Yoco 查询 checkout；签名的 Webhook 到达时，模块会再次查询。随后创建订单，顾客会看到标准的订单确认页面，并显示 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 按钮；Webhook 一到达就会创建订单。

如果顾客在 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. 购物车会被保留。

对于同一购物车的新付款尝试，模块会先向 Yoco 检查之前的尝试。如果已付款，则直接创建订单，无需再次打开付款页面。如果仍处于开放状态、金额相同且创建于 30 分钟以内，顾客会再次看到同一个 Yoco 页面。否则会创建新的 Yoco checkout。

如果 Yoco 无法启动付款，顾客会停留在结账页面，并显示 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 仍然有效，并且不受店铺国家限制的影响。

付款会在 Yoco 页面上立即扣款。模块不支持保存银行卡、订阅或定期付款，不提供站内银行卡表单，也不支持单独的授权和扣款，且不适用于 ZAR 以外的货币。

订单与退款

订单状态

No order yet：顾客已被转到 Yoco 但尚未付款，在 Yoco 页面取消，或 Yoco 尚未确认付款。此时只存在购物车。

Payment accepted：付款已确认。付款会以 Yoco 付款 ID 作为交易 ID 记录，备注中会显示金额、Yoco 付款和 checkout ID、模式，以及付款的确认方式（顾客返回、Webhook，或新付款尝试前的检查）。

Yoco payment on hold：Yoco 报告的金额或币种与购物车总额不符，例如付款开始后购物车在另一个标签页中被修改。不会记录付款，备注会说明原因，顾客会看到 We received your payment and are reviewing it. We will contact you if anything else is needed. 发货前请核实付款。如果顾客随后通过另一次尝试支付了正确金额，订单会变为 Payment accepted。

Cancelled or Refunded：针对此类订单的付款不会改变订单。备注会提醒您在 Yoco 后台退款，或手动恢复订单。顾客会看到 Your payment was received after the order had been cancelled. Please contact us — do not pay again.

如果已付款的订单又收到第二笔付款，订单不会改变。备注会提示您在 Yoco 后台退还该笔付款。

Yoco 付款区块

订单页面会显示 Yoco payment 区块，其中包括 Yoco 付款和 checkout ID、状态、已付和已退金额、测试付款的 Test mode 标记、退款记录、购物车的付款尝试（如果有多次），以及订单的 Yoco notes。

退款

在 Yoco payment 区块中输入金额（会自动填入尚未退款的金额），可选填原因，然后点击 Refund via Yoco。确认提示 Refund this amount through Yoco? This cannot be undone. 支持全额和部分退款。您需要拥有编辑订单的权限。退款金额以 Yoco 实际扣款金额为准，因此即使订单之后被修改，您最多也只能退还顾客实际支付的金额。退款会以付款时所用的模式（测试或正式）发送，因此该模式的密钥必须已设置。因响应丢失而重复发起的退款不会被重复支付。

退款成功后，会将 Yoco 退款 ID 添加到退款记录和备注中。全额退款会将订单设置为 Refunded；部分退款不会改变状态。如果 Yoco 拒绝退款，该区块会显示 Yoco refused the refund: 及原因，并且不会记录退款。如果 Yoco 报告退款待处理，该区块会显示仍在待处理。请勿重复操作：Yoco 通过 Webhook 确认后会自动记录。退款仅适用于通过 Yoco checkout 付款的订单。处于 Yoco payment on hold 状态的订单没有可退款的已付 checkout；请在 Yoco 后台退款。

模块不会生成退款单（credit slip）。PrestaShop 订单页面的标准退款按钮不会通过 Yoco 退回款项。

在 Yoco 后台进行的退款会通过 refund.succeeded Webhook 到达，并记录在退款记录和备注中。当退款金额达到已付金额时，订单会被设置为 Refunded。超过剩余可退金额的退款不会被记录，备注会提示您检查订单。失败的退款会添加一条备注，说明款项未退还给顾客。

许可证密钥

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

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

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

故障排除

结账时不显示 Yoco：请检查许可证是否有效、Enable/Disable 是否开启，以及当前模式是否有密钥：测试模式需要 Test secret key，正式模式需要 Live secret key。购物车货币必须为 ZAR，订单总额至少为 R2.00。当密钥缺失或店铺货币不是 ZAR 时，设置页面会显示警告。在 Payment > Preferences 中，请检查模块是否允许用于 ZAR、顾客所在国家以及顾客所属的客户组。

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

无法注册 Webhook：顾客返回店铺时，付款仍会被确认。请修正消息中显示的原因，例如店铺必须可以通过 HTTPS 从互联网访问，然后再次保存。您也可以自行注册 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_ 开头。之前的值已保留。

顾客选择 Yoco 时出现错误：请查看模块页面上的 Log 字段。Yoco is not available at the moment. Please choose another payment method. 表示当前模式没有密钥。

顾客收到付款需要审核的通知：某次尝试是以不同金额付款，或在订单取消之后付款。请阅读 Yoco payment 区块中的备注，然后处理订单，或在 Yoco 后台退还该付款。

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

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

开发者：钩子 actionYocoPCheckoutPayload 允许其他模块修改创建 Yoco checkout 的请求。

卸载

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

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