VibeFox Viva Wallet for PrestaShop — 帮助

系统要求

PrestaShop：8.0 至 9.x。

PHP：8.0 或更高版本。模块拒绝在更旧的 PHP 版本上安装。

Viva 账户：一个 Viva 商户账户。您可以使用演示账户（demo.vivapayments.com）进行测试，使用正式账户（www.vivapayments.com）处理真实付款。每个账户都有各自的凭据。付款需要 Smart Checkout 凭据（Client ID 和 Client Secret）以及付款来源的 Source Code。Merchant ID 和 API Key 为可选项：它们仅用于响应 Viva 对 Webhook URL 的验证。

币种：EUR、GBP、PLN、RON、BGN、CZK、HUF、DKK、SEK、NOK 或 CHF。使用其他币种时，结账时会隐藏该付款方式。

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

安装

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

2. 上传完成后，点击 Configure；或者以后在模块列表中找到 VibeFox Viva Wallet Gateway 并点击 Configure。

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

4. 输入 Viva 演示和/或正式账户的凭据，并在您的 Viva 账户中设置付款来源和 Webhook（参见配置）。

5. 开启 Enable/Disable 并点击 Save。在 Test Mode 开启时，使用 Viva 演示卡完成一笔演示付款，然后关闭 Test Mode 以正式上线。

安装时，模块会创建订单状态 Viva Wallet payment on hold。模块会在安装时处于启用状态的国家/地区提供。您可以在 Payment > Preferences 中更改币种、国家/地区和客户组；之后可在那里添加新的国家/地区。

配置

所有设置都位于模块页面：Modules > Module Manager > VibeFox Viva Wallet Gateway > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。在字段上方，如果当前模式没有 Client ID、Client Secret 或 Source Code（Viva Wallet is hidden at checkout until the Demo Client ID, Client Secret and Source Code are entered.，或正式模式下的 Live 对应内容），或者店铺默认币种不受支持，页面会向您发出警告。测试模式开启时，页面会显示 Test mode is on: payments go to the Viva demo environment. 保存设置会清除缓存的 Viva 访问令牌，因此新凭据会立即生效。

Viva Wallet

Enable/Disable：Enable Viva Wallet payment gateway 用于开启或关闭该付款方式。默认：关闭。

Title：顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认：Viva Wallet。必填：空标题不会保存，页面会显示 Enter a title for the payment method.

Description：结账时显示在付款方式下方的文字。默认：Pay securely with Viva Wallet — cards, Apple Pay, Google Pay and more.

Test Mode：使用 Viva 演示环境（demo.vivapayments.com）。新付款和 API 调用使用演示账户的凭据。不会扣除真实款项，结账时顾客会看到 (Test mode: use Viva demo cards, no real money is charged.) 默认：开启。关闭后，将使用正式账户接受真实付款。已经完成的付款仍会在其发生时所在的环境中继续验证和退款。

演示账户（测试模式）和正式账户

两个部分的字段相同：一组用于演示账户，一组用于正式账户。在您的 Viva 账户中打开 Settings > API Access，复制 Smart Checkout 凭据（Client ID、Client Secret）、Merchant ID 和 API Key。Source Code 位于 Sales > Online payments > Websites / apps。

Client ID (Demo) / Client ID (Live)：账户的 Smart Checkout OAuth 2.0 Client ID。付款时必填。

Client Secret (Demo) / Client Secret (Live)：账户的 Smart Checkout OAuth 2.0 Client Secret。付款时必填。

Source Code (Demo) / Source Code (Live)：账户付款来源的 4 位代码。其 Success URL 和 Failure URL 必须指向本店铺（见下文）。付款时必填。

Merchant ID (Demo) / Merchant ID (Live)：可选。仅用于响应 Viva 对 Webhook URL 的验证。

API Key (Demo) / API Key (Live)：可选。仅用于响应 Viva 对 Webhook URL 的验证。

已保存的 Client Secret 和 API Key 不会再次显示。该字段将保持为空，并显示 Saved — leave empty to keep it. 仅当您想更改时才输入新值。

Clear saved secrets：勾选某个密钥并点击 Save 即可将其删除。空字段会保留已保存的值。

返回 URL 与 Webhook

Addresses for the Viva account：此字段显示需要在 Viva 账户中填写的店铺三个地址。使用友好 URL 时，它们类似 https://your-shop/module/wcp_viva_gateway/success、https://your-shop/module/wcp_viva_gateway/fail 和 https://your-shop/module/wcp_viva_gateway/webhook，可能带有语言代码，如 /en/。请完全按照设置中显示的内容复制。

Payment source：在每个您使用的账户中，进入 Sales > Online payments > Websites / apps，为您店铺的域名创建付款来源。在 Success URL 和 Failure URL 中填写成功和失败地址中域名之后的路径部分。

Webhook：在 Settings > API Access > Webhooks 中，为以下事件添加 Webhook 地址：

Viva 会在保存前检查该 URL。模块会使用您账户的验证密钥进行响应：它使用当前模式的 Merchant ID 和 API Key 获取该密钥，或使用下方输入的密钥。即使顾客关闭了浏览器，Webhook 仍会确认付款。Viva Webhook 未经签名，因此模块从不单独信任 Webhook：每笔付款在创建订单前都会通过 Viva API 验证。没有 Webhook 时，只有顾客付款后返回店铺，才会创建订单。

Webhook Verification Key：可选。留空则使用当前模式的 Merchant ID 和 API Key 自动获取密钥，或将 Viva 账户的验证密钥粘贴到此处。

高级设置

Order Status After Payment：付款成功后设置的订单状态。状态会立即设置，不会再进行第二次状态变更。

Brand Color：用于 Viva 付款页面的 6 位 HEX 颜色代码，例如 0000ff。开头的 # 会被去除。留空则使用默认颜色。其他任何值都不会保存：页面会显示 Brand Color must be a 6-digit HEX code (e.g. 0000ff). The previous value was kept.

Debug Logging：将 API 请求写入模块文件夹中的 logs/viva_wp_debug.log.php。该文件无法通过网页打开。密钥、令牌和顾客数据不会被记录。即使此选项关闭，错误也始终会被记录。默认：关闭。

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

Delete Data on Uninstall：开启后，卸载模块时会删除设置和模块日志。订单及其付款数据（Viva 付款尝试、退款、订单状态）永远不会被删除。默认：关闭。

结账

在付款步骤，顾客选择付款方式（默认为 Viva Wallet），并会看到提示 You will be redirected to the secure Viva Wallet payment page (cards, Apple Pay, Google Pay and more). 确认后，模块会按购物车金额和购物车币种创建 Viva 付款订单，并将顾客带到 Viva Smart Checkout 页面。顾客在该页面使用您 Viva 账户中启用的付款方式之一付款。顾客的电子邮件、姓名、电话和国家会传递给 Viva；如果 Viva 支持，页面将以购物车的语言打开。在 Viva 中，付款显示为 Cart #、购物车编号和您的店铺名称。Viva 付款订单 30 分钟后过期。此时尚不存在订单。

付款后，顾客返回您的店铺。只有在 Viva 确认后，订单才会被标记为已付款：模块会在返回时和 Webhook 中通过 Viva API 重新读取交易。随后订单被创建，顾客会看到标准的订单确认页面。如果付款尚未确认，Payment confirmation 页面会显示 We are waiting for Viva Wallet to confirm your payment. You will receive an e-mail as soon as it is confirmed. 并提供 Check again 和 Back to checkout 按钮；Viva 一确认付款，Webhook 就会创建订单。

如果付款失败或顾客在 Viva 页面取消，则不会创建订单，购物车会保留。顾客会回到结账页面，并看到 The Viva Wallet payment was not completed. Please try again or choose another payment method. 或 The Viva Wallet payment was cancelled. You can try again or choose another payment method.，之后可以再次付款。

如果 Viva 无法发起付款，顾客会停留在结账页面，并看到 Viva Wallet payments are not available at the moment. Please choose another payment method or contact us.（凭据缺失或错误），或 We could not connect to Viva Wallet. Please try again in a moment or choose another payment method. 技术原因会写入日志。

返回页面只向已付款的顾客显示订单确认。其他打开返回地址的人会被引导至订单历史或结账页面，且不显示订单详情。

即使店铺处于维护模式，Webhook 仍会工作，并且不受店铺国家限制的影响。

本模块仅支持一次性付款，并在 Viva 页面上立即扣款。不支持预授权和捕获、分期付款、保存的银行卡、订阅、Viva Native Checkout（在自有页面输入银行卡字段）或 POS 终端。顾客重新发起付款时，旧的未付款 Viva 付款订单不会被取消；Viva 会在 30 分钟后使其过期。

订单与退款

订单状态

尚无订单：顾客已被引导至 Viva 但尚未付款，付款失败或已取消，或 Viva 尚未完成付款。目前只存在购物车，顾客可以再次付款。

Payment accepted、Delivered 或 Viva Wallet payment on hold：付款已确认。状态遵循 Order Status After Payment。付款会记录 Viva 交易 ID，备注中会显示金额、交易、Viva 订单代码、环境（演示或正式）以及确认方式（Webhook 或顾客返回）。

金额或币种不一致后的 Viva Wallet payment on hold：Viva 报告的金额或币种与购物车总额不同，例如顾客开始付款后购物车被修改。订单会在未记录付款的情况下创建，备注 Viva Wallet payment held for review 会说明原因。顾客看到的是标准订单确认页面，不包含 Viva 确认的承诺。请在 Viva 后台核对付款与订单，然后手动发货或退款。如果之后收到同一购物车的匹配付款，订单会转为已付款状态。

针对已取消或已退款订单的付款，不会改变订单状态；备注会提示您恢复订单或在 Viva 后台退款。如果已付款订单又收到第二笔付款，订单不会被修改；备注会提示您在 Viva 后台退还重复付款。

Viva Wallet payment 模块

订单页面会显示 Viva Wallet payment 模块，其中包含 Viva 订单代码、交易 ID、环境和 Source Code、Viva 状态、已付金额和已退金额、演示付款的 Demo 标记、退款历史、购物车的付款尝试（如果不止一次）以及订单的 Viva Wallet notes。

退款

在 Viva Wallet payment 模块中输入金额（会自动填入尚未退款的金额），可选填写原因，然后点击 Refund via Viva Wallet。确认提示 Refund this amount via Viva Wallet? This cannot be undone. 对于已确认 Viva 交易的订单，支持全额和部分退款。您需要拥有编辑订单的权限；不需要模块访问权限。您最多可退还 Viva 为该付款收取的金额，即使订单之后被编辑过。退款会发送到付款时所在的账户（演示或正式），并使用付款的币种，因此必须填写该账户的 Client ID 和 Client Secret。如果 Viva 不接受退款，模块会显示错误，并且不会记录退款。成功的退款会添加到退款历史和备注中，并附上 Viva 退款交易。全额退款会将订单设为 Refunded。部分退款不会改变状态。未确认付款而被保留待审核的订单，无法通过该模块退款。

本模块不会创建退款单。订单页面上标准的 PrestaShop 退款按钮不会通过 Viva 退回款项。在 Viva 后台进行的退款不会被导入。如有需要，请手动更新订单。

许可证密钥

本模块使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Viva Wallet Gateway 位于 Modules > Module Manager > VibeFox Viva Wallet Gateway > Configure 页面中设置上方的第一个区块。将密钥输入 License key，然后点击 Activate。之后该区块会显示隐藏部分字符的密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now 用于重新检查状态，Change key 用于输入其他密钥，Remove key 用于从本店铺移除密钥。其下方有 Product: presta-payment-viva 一行，以及 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 账户中释放该名额。

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

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

故障排除

结账时未显示 Viva Wallet：检查许可证是否有效，Enable/Disable 是否开启，以及当前模式是否已填写 Client ID、Client Secret 和 Source Code（测试模式为 Demo 字段，正式模式为 Live 字段）。购物车币种必须是 EUR、GBP、PLN、RON、BGN、CZK、HUF、DKK、SEK、NOK 或 CHF 之一。在 Payment > Preferences 中检查模块是否允许该购物车币种、顾客所在国家和顾客所属客户组。缺少凭据时，设置页面会显示警告。

付款已完成，但未创建订单：Webhook 无法工作。在 Viva 中检查您所用账户（演示或正式）中是否存在该 Webhook，其 URL 是否与设置中显示的完全一致，以及是否已选中 Transaction Payment Created。检查该付款所属账户的 Client ID 和 Client Secret 是否仍已填写：模块需要它们来验证付款。开启 Debug Logging 并查看 Log 字段。顾客付款后返回店铺时，也会创建订单。

Viva 无法验证 Webhook URL：输入当前模式的 Merchant ID 和 API Key（或直接在 Webhook Verification Key 中输入验证密钥），保存，然后在 Viva 中重新验证。要验证另一个账户的 Webhook，请先切换 Test Mode，或输入该账户的密钥。

Webhook 返回错误：Viva 会显示您店铺的响应，并重试失败的 Webhook。verification_failed（HTTP 500）表示无法连接 Viva API 验证付款，或无法创建订单（例如模块已禁用）。busy（HTTP 503）表示该订单在同一时刻正被另一个请求处理。transaction_not_found（HTTP 404）表示该交易在该付款所属账户中不存在，例如凭据错误。同一 Viva 账户上其他店铺的付款事件会收到 ignored 响应。

顾客选择 Viva Wallet 时出现错误：查看模块页面上的 Log 字段。Client ID 或 Client Secret 错误会显示 Viva Wallet 付款不可用的消息。如果无法连接 Viva，或 Viva 拒绝付款订单（例如 Source Code 属于其他账户），顾客会收到店铺无法连接 Viva Wallet 的消息。

顾客返回后看到 We could not find your order. If you were charged, please contact us.：返回地址中的 Viva 订单代码不是本店铺的付款，例如其他店铺的付款来源指向了这里。请检查付款来源的 Success URL 和 Failure URL。

付款后订单处于 Viva Wallet payment on hold 状态：阅读 Viva Wallet payment 模块中的备注（参见订单状态），然后处理订单或退款。

退款失败，提示 This payment was made in the Viva demo (or live) environment：未填写付款所在账户的 Client ID 和 Client Secret。请填写后重试。其他退款错误会显示 HTTP 代码和 Viva 的消息。

模块显示 Transaction ID not found. Cannot process refund.：订单没有已确认的 Viva 付款，例如金额不一致之后。如有需要，请在 Viva 后台退款。

卸载

停用模块会保留所有数据，只删除缓存的 Viva 访问令牌。要删除模块，请进入 Modules > Module Manager，打开 VibeFox Viva Wallet Gateway 旁边的菜单，然后选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。缓存的访问令牌和 Webhook 密钥始终会被删除。如果 Delete Data on Uninstall 已开启，设置和日志会被删除。如果关闭，所有设置都会保留，以便之后重新安装。Viva 付款尝试和退款以及订单状态 Viva Wallet payment on hold 始终保留，因此重新安装后，之前已付款的订单仍可退款。现有订单会保留其付款备注和交易 ID。

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