VibeFox Viva Wallet for WooCommerce — 帮助

系统要求

WordPress：6.0 或更高版本。

WooCommerce：7.0 或更高版本，已安装并启用。未安装时插件无法启用。

PHP：8.0 或更高版本。

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。使用其他币种时，结账页面不会显示该付款方式。

公开的 HTTPS 站点：为了接收 Webhook，您的站点必须能够通过 HTTPS 从互联网访问。

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

安装

1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 wcp_viva_gateway 文件夹上传至 /wp-content/plugins/。

2. 点击 Activate。

3. 打开设置：WooCommerce > Settings > Payments > Viva Wallet > Manage，或在插件页面上点击插件名称下方的 Settings。

4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。

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

6. 开启 Enable/Disable。在 Test Mode 开启时，使用 Viva 演示银行卡完成一笔演示付款，然后取消勾选 Test Mode 以正式上线。

配置

所有设置都位于同一页面：WooCommerce > Settings > Payments > Viva Wallet。若当前模式缺少 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 Wallet 会被标记为需要设置，直到当前模式具备这三个值为止。

General

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

Title：顾客在结账时看到的付款方式名称。默认：Viva Wallet。

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

Test Mode：Use the Viva demo environment (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 验证。

返回 URL 与 Webhook

Payment source：在 Sales > Online payments > Websites / apps 中，为您使用的每个账户创建针对店铺域名的付款来源。在 Success URL 和 Failure URL 中填写设置中显示的两个地址域名之后的路径，地址形如 https://your-site/wc-api/viva_payment_success/ 和 https://your-site/wc-api/viva_payment_fail/。

Webhook：在 Settings > API Access > Webhooks 中添加设置里显示的 URL，形如 https://your-site/wp-json/wc-viva-gateway/v1/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。开头的 # 会被移除。留空则使用默认颜色。其他任何值在保存时都会被拒绝，并保留之前的值。

Debug Logging：Enable logging 会将 API 请求写入 WooCommerce > Status > Logs，来源为 wcp_viva_gateway。密钥和顾客数据不会被记录。即使此选项关闭，错误也始终会被记录。默认：关闭。

Delete Data on Uninstall：Remove all plugin data when the plugin is deleted。开启后，删除插件时会移除设置、付款尝试表和插件日志。订单备注和订单数据会保留。默认：关闭。

结账

顾客选择付款方式（默认为 Viva Wallet）并提交订单。插件会按订单金额和订单币种创建 Viva 付款订单，并将顾客引导至 Viva Smart Checkout 页面。顾客在该页面使用您 Viva 账户中启用的付款方式之一付款，例如银行卡、Apple Pay 或 Google Pay。顾客的电子邮件、姓名、电话和国家会传递给 Viva；如果 Viva 支持您站点的语言，页面将以该语言打开，否则以英语显示。在 Viva 中，付款显示为 WooCommerce # 加订单号。Viva 付款订单 30 分钟后过期。

付款后，顾客会返回您店铺的订单已收到页面。只有在 Viva 确认后，订单才会被标记为已付款：插件会在顾客返回时以及在 Webhook 中通过 Viva API 重新读取交易。如果付款尚未确认，页面会显示 We are waiting for Viva Wallet to confirm your payment. You will receive an e-mail as soon as it is confirmed.

如果付款失败或顾客在 Viva 页面取消，订单状态不会改变。顾客会被引导至 Pay for order 页面，并看到 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. 技术原因会写入日志。

该付款方式适用于经典结账、结账区块以及 Pay for order 页面（会检查该订单的币种）。它与 WooCommerce 高性能订单存储（HPOS）兼容。

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

订单与退款

Order statuses

Pending payment：顾客已被引导至 Viva 但尚未付款，付款尚未得到确认，或付款失败或被取消。备注会显示 Viva 付款订单以及环境（演示或正式）。失败和取消的尝试会添加到订单备注中，顾客可以再次付款。

Processing, Completed or On Hold：付款已确认。状态遵循 Order Status After Payment。订单备注会显示金额、Viva 交易 ID、环境以及确认方式（Webhook 或顾客返回）。

On hold for review：Viva 报告的金额或币种与订单总额不同，例如顾客开始付款后订单被修改。备注 Viva Wallet payment held for review 会说明原因。请在 Viva 后台核对该付款与订单，然后完成订单或手动退款。

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

退款

打开订单，点击 Refund，输入金额，然后点击 Refund via Viva Wallet。对于已确认 Viva 交易的订单，支持全额和部分退款。退款会发送至付款时所用的账户（演示或正式），并使用付款的币种，因此必须填写该账户的 Client ID 和 Client Secret。如果 Viva 拒绝退款，WooCommerce 会显示错误，且不会记录退款。成功的退款会连同 Viva 退款交易一起添加到订单备注中。

在 Viva 后台进行的退款不会被导入。如有需要，请在 WooCommerce 中创建手动退款，且不要使用 Refund via Viva Wallet。

许可证密钥

本插件需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > Viva Wallet 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期截至的日期以及您的域名。使用 Check now 可再次检查状态，Change key 用于输入其他密钥，Remove key 用于将其从本站点移除。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。

一个密钥只能用于一个域名。从站点中移除密钥不会释放域名名额。请在您的 vibefox.net 账户中释放该名额。

若没有有效的密钥，Viva Wallet 不会在结账时显示给顾客。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 已登录的店铺管理员仍会看到该付款方式，并标记为 (unlicensed — visible to admins only)，以便您在购买密钥之前设置和测试插件。插件页面和 WooCommerce 页面上会显示提醒。现有订单不受影响：已发起的付款仍会被确认，退款也仍可正常进行。

许可证到期后，插件仍可继续工作，但更新和支持需要续费。状态会在后台自动重新检查。

故障排除

Viva Wallet 未在结账时显示：请检查许可证是否有效，Enable/Disable 是否已开启，以及当前模式是否具有其 Client ID、Client Secret 和 Source Code（测试模式下为 Demo 字段，正式模式下为 Live 字段）。店铺币种（在 Pay for order 页面，即订单币种）必须是 EUR、GBP、PLN、RON、BGN、CZK、HUF、DKK、SEK、NOK 或 CHF 之一。若缺少任何设置，设置页面会显示警告。

付款已完成，但订单仍为 Pending payment：Webhook 无法正常工作。请在 Viva 中检查您所用账户（演示或正式）中是否存在该 Webhook，其 URL 是否与设置中显示的完全一致，以及是否已选择 Transaction Payment Created。同时确认该付款所属账户的 Client ID 和 Client Secret 仍已填写：插件需要它们来验证付款。详细信息位于 WooCommerce > Status > Logs，来源为 wcp_viva_gateway。

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 响应。

顾客在下单时看到错误：开启 Debug Logging，并查看 WooCommerce > Status > Logs，来源为 wcp_viva_gateway。Client ID 或 Client Secret 错误，或缺少 Source Code，都会提示 Viva Wallet 付款不可用。如果无法连接 Viva，或 Viva 拒绝了付款订单（例如 Source Code 属于另一个账户），顾客会收到店铺无法连接 Viva Wallet 的提示。

付款后订单显示为 On hold：请阅读订单备注。已付金额或币种与订单不符。请完成订单或退还付款。

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

许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在另一个域名上使用，请在您的 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now，为新域名激活密钥。如果无法连接许可证服务器，插件会沿用最后已知的状态继续工作。

面向开发者：过滤器 viva_wp_supported_currencies 可启用您 Viva 账户支持的其他币种；viva_wp_create_order_payload 可修改付款订单请求（金额、币种和 Source Code 必须保持不变）；viva_wp_icon 可修改结账图标。

卸载

停用插件会保留所有数据；仅会移除缓存的 Viva 访问令牌。要彻底删除插件，请先停用，然后在 Plugins 页面中删除。本插件的许可证密钥和许可证状态，以及缓存的令牌和 Webhook 密钥，始终会被移除。设置、付款尝试表以及插件日志（包括已轮转的日志文件和数据库日志条目）仅在 Delete Data on Uninstall 开启时才会被移除。否则它们会保留，以便日后重新安装。现有订单会保留其付款备注和交易 ID。

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