VibeFox Tap for WooCommerce — 帮助
系统要求
WordPress：6.0 或更高版本。
WooCommerce：8.0 或更高版本，已安装并启用。未安装 WooCommerce 时，插件无法启用。
PHP：8.0 或更高版本。
店铺货币：AED、BHD、EGP、EUR、GBP、JOD、KWD、OMR、QAR、SAR 或 USD。使用其他货币时，结账页面会隐藏该付款方式。
网站的互联网访问：Tap 会将付款结果发送至店铺中的 Webhook，因此网站必须能从互联网访问。每笔付款都会发送 Webhook 网址；无需在 Tap 控制面板中进行任何配置。
Tap 账户：您需要 Tap 控制面板（goSell，API 凭据）中的 API 密钥。测试密钥以 pk_test_ / sk_test_ 开头，正式密钥以 pk_live_ / sk_live_ 开头。secret key 始终需要；publishable key 仅用于 Tap Checkout 弹窗。提供哪些付款方式（mada、KNET、Benefit 等）以及 Apple Pay 域名验证，均在您的 Tap 账户中设置。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 wcp_tap_payment_gateway 文件夹上传至 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Payments > Tap Payments > Manage，或在插件列表页点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 输入您的 Tap 测试和正式密钥，选择付款操作、结账方式以及 Tap 页面语言（参见配置）。
6. 开启 Enable / Disable 并保存。使用 Tap 测试卡进行测试，然后取消勾选 Test mode。
配置
所有设置都在同一页面中：WooCommerce > Settings > Payments > Tap Payments。在字段上方，页面会在测试模式开启时显示 Test mode is on: payments use your Tap test keys and no real money is charged.。当前模式缺少密钥时（此时结账页面不会显示该网关），以及店铺货币不受 Tap 支持时，页面也会提示。在付款方式列表中，Tap Payments 会标记为需要设置，直到当前模式具有 secret key（弹窗还需要 publishable key）。
保存时，若密钥的前缀与其字段不符，则不会保存：会显示错误，并保留之前的值。例如，在测试字段中输入正式密钥会被拒绝。
常规
Enable / Disable：Enable Tap Payments 用于开启或关闭该付款方式。默认：关闭。
Title：结账页面上显示的付款方式名称。默认：Tap Payments。
Description：结账页面中付款方式下方显示的文字。默认：Pay with Visa, Mastercard, mada, KNET, Benefit, Apple Pay or Google Pay。
Tap API 密钥
请在 Tap 控制面板（goSell，API 凭据）中查找您的密钥。测试密钥以 pk_test_ / sk_test_ 开头，正式密钥以 pk_live_ / sk_live_ 开头。
Test mode：Use the test keys (no real money is charged)。付款、状态查询和退款始终使用付款时所用模式的密钥，因此即使您切换到正式模式，测试付款仍会使用测试密钥进行查询和退款。默认：开启。
Test publishable key：以 pk_test_ 开头。弹窗需要此密钥。
Test secret key：以 sk_test_ 开头。
Live publishable key：以 pk_live_ 开头。弹窗需要此密钥。
Live secret key：以 sk_live_ 开头。
Merchant ID：可选。您的 Tap 商户 ID；仅当 Tap 要求您将付款路由至特定商户账户时才需要。
付款
Payment action：顾客付款时资金如何处理。
Checkout type：顾客在哪里付款。
Tap page language：English（默认）或 Arabic。
付款通知（Webhook）
Tap 会将付款结果发送至本节显示的网址。其格式为 https://your-site/wc-api/tap_p_webhook/。该网址随每笔付款发送，因此无需在 Tap 控制面板中进行任何配置。请确保该网址可从互联网访问（未被防火墙、维护模式或 HTTP 身份验证阻止）。每条通知都会使用 hashstring 签名进行验证（HMAC-SHA256，使用付款所属模式的 secret key）。签名无效的 Webhook 会被拒绝。即使是已签名的通知，也不会被直接信任：插件会在修改订单之前，通过 Tap API 重新读取付款信息。若 Webhook 无法正常工作，只有在顾客付款后返回店铺时，订单才会更新。
高级
Debug log：Log payment events (WooCommerce → Status → Logs, source "wcp_tap_payment_gateway")。错误始终会被记录。日志绝不包含密钥、银行卡或顾客数据。默认：关闭。
Delete data on uninstall：Delete the gateway settings and logs when the plugin is deleted (order payment records are kept)。默认：关闭。
结账
顾客选择付款方式（默认为 Tap Payments）并提交订单。测试模式下，结账页面会显示 Test mode: no real payment will be made.
Tap payment page：插件会以订单货币为订单总额创建 Tap 扣款（若为 Authorize only 模式，则创建授权），描述为 Order # 加订单号，然后将顾客引导至 Tap 付款页面。顾客在该页面选择银行卡、mada、KNET、Benefit、Apple Pay 或 Google Pay（取决于您 Tap 账户中已启用的方式）并完成付款。如果 Tap 无法发起付款，顾客会看到 The Tap payment could not be started. Please try again or choose another payment method.，原因会记录在订单备注中。
Tap checkout popup：顾客进入订单付款页面，Tap 付款表单会在此打开。页面还会显示链接 Pay on the Tap payment page instead。若窗口被关闭，点击 Pay now 按钮可重新打开。若表单无法加载，则会提示顾客改用 Tap 付款页面。
付款完成后，顾客会返回订单接收页面。只有在 Tap 确认后，订单才会标记为已付款：插件会使用付款所属模式的密钥通过 Tap API 读取付款信息，核实其与本订单相关并由该订单的结账流程发起，同时将金额和币种与订单进行比对。仅凭返回地址中的 Tap ID 永远不会将订单标记为已付款。Webhook 会在后台执行相同的检查。重复的 Webhook 和返回操作绝不会对同一订单重复修改（每个订单同一时间只进行一次修改）。
若付款尚未确认，订单接收页面会显示 We have not received the payment confirmation from Tap yet. If you completed the payment, the order will be updated automatically in a few minutes — there is no need to pay again.。对于已授权的付款，则显示 Your payment has been authorized. We will process the order as soon as the payment is captured.
若付款被拒绝或被放弃，订单会标记为失败，顾客会返回 Pay for order 页面，并显示 Your payment was not completed. Please try again or choose another payment method.（若 Tap 提供了原因，则一并显示）。未完成的付款会显示 The payment was not completed. You can try again below. 顾客可以在该页面重新支付订单。
该付款方式适用于经典结账、结账区块和 Pay for order 页面。它兼容 WooCommerce 高性能订单存储（HPOS）。
插件不支持保存银行卡或令牌化、订阅，也不会在结账页面中嵌入银行卡输入框。Capture Tap payment 始终扣除订单总额；不支持部分扣款。
订单与退款
订单状态
Pending payment：顾客已被引导至 Tap，但尚未付款，或 Tap 尚未确认付款。
Processing：Tap 已确认一笔已扣款的付款。这是付款后 WooCommerce 的标准状态（仅包含虚拟可下载商品的订单会直接变为已完成）。订单备注会显示金额、Tap 扣款 ID（chg_...）、付款方式，以及（测试模式下）测试付款的标识。交易 ID 即为 Tap 扣款 ID。
On hold：付款仅被授权，等待扣款；或付款的金额或币种与订单不一致（Tap: amount/currency mismatch — manual review required.）；或订单取消后才收到付款。订单备注会说明原因。
Failed：付款被拒绝、放弃、取消或超时。只有仍在等待付款的订单会被标记为失败；失败的尝试绝不会更改已付款、已授权或已取消的订单。顾客可以再次付款。
Cancelled：授权已通过 Void Tap authorization 撤销，因此预留的资金已被释放。
若对已付款的订单又收到一笔成功付款，订单不会再次被修改。备注会说明这是重复付款，并提示您在 Tap 控制面板中退款。若付款与订单相关，但并非由该订单的结账流程发起，则仅作记录。
扣款与撤销
在 Authorize only 模式下，打开处于挂起状态的订单，并在 Order actions 中选择：Capture Tap payment 会扣除订单总额，订单随即变为已付款；Void Tap authorization 会释放资金并取消订单。若 Tap 拒绝该操作，将显示错误，并添加到订单备注中。若授权是直接在 Tap 控制面板中扣款的，Webhook 会将订单标记为已付款；此类付款的退款必须在 Tap 控制面板中进行。
退款
打开订单，点击 Refund，输入金额，然后点击 Refund via Tap Payments（按钮上会显示您的 Title）。已扣款的 Tap 交易支持全额和部分退款。退款使用付款所属模式的 secret key 发送，因此必须已设置该模式的密钥。Tap 接受的退款会连同 Tap 退款 ID 和状态添加到订单备注中。若 Tap 拒绝，WooCommerce 会显示错误，且不会记录退款。在 Tap 控制面板中进行的退款不会显示在 WooCommerce 中。
许可证密钥
本插件需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > Tap Payments 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期截止日期以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将密钥从本站点移除。Manage licenses and domains in your account 链接可打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。从站点移除密钥并不会释放域名名额。请在您的 vibefox.net 账户中释放名额。
若没有有效的密钥，Tap Payments 不会在结账时显示给顾客。若仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 已登录的店铺管理员仍能看到该付款方式，并标注为 (unlicensed — visible to admins only)，以便您在购买密钥前完成设置和测试。插件列表页和 WooCommerce 页面会显示提醒。现有订单不受影响：已发起的付款仍会被确认，退款、扣款和撤销仍可正常进行。
许可证到期后，插件仍可继续工作，但更新和技术支持需要续费。状态会在后台自动重新检查。
故障排除
Tap Payments 未出现在结账页面：请检查许可证是否有效、Enable / Disable 是否已开启、当前模式是否有 secret key（当 Checkout type 为弹窗时还需要 publishable key）。请检查店铺货币（或 Pay for order 页面上的订单货币）是否为 AED、BHD、EGP、EUR、GBP、JOD、KWD、OMR、QAR、SAR、USD 之一。设置页面会针对上述每个问题显示提示。
付款已成功，但订单仍为 Pending payment：Webhook 无法访问您的站点。请检查设置中显示的网址（/wc-api/tap_p_webhook/）是否可从互联网访问（无防火墙、维护模式或 HTTP 身份验证），并查看 WooCommerce > Status > Logs，来源为 wcp_tap_payment_gateway。顾客从 Tap 返回时，订单也会更新。
Webhook answers invalid signature：通知未使用付款所属模式的 secret key 签名。请检查设置中的 secret key。
Webhook answers gateway not configured：付款所属模式（测试或正式）的 secret key 为空。请填写该密钥。
Webhook answers verification failed：无法连接 Tap API 以验证付款。Tap 稍后会重试该 Webhook。
密钥未保存：密钥必须以其字段的前缀开头：pk_test_、sk_test_、pk_live_ 或 sk_live_。
订单为 On hold：请阅读订单备注。付款仅被授权（请通过订单操作进行扣款）、付款金额或币种与订单不符，或付款是在订单取消后才到达的。
退款因模式相关信息而失败：付款是在测试或正式模式下完成的，但该模式未配置 secret key。请填写后重试。若备注提示未找到已扣款的 Tap 交易，请在 Tap 控制面板中退款。
开发者钩子：可用的过滤器包括 tap_p_supported_currencies、tap_p_currency_decimals、tap_p_charge_payload、tap_p_icon、tap_p_checkout_sdk_url 和 tap_p_payment_page_hosts。
许可证区块显示错误：请按照区块中的提示操作。例如，若该密钥已在其他域名上使用，请在您的 vibefox.net 账户中释放名额，然后点击 Check now。若站点地址已更改，请点击 Check now，以便为新域名激活密钥。若无法连接许可证服务器，插件将继续使用最近一次已知的状态运行。
卸载
停用插件会保留所有数据。若要彻底删除，请先停用，然后在 Plugins 页面将其删除。本插件的许可证密钥和许可证状态始终会被删除。网关设置、插件的其他选项和日志仅在 Delete data on uninstall 已开启时才会被删除；否则会保留，以便日后重新安装。现有订单会保留其付款备注、Tap ID 和交易 ID。
Tap Payments 是其各自所有者的商标。本插件与 Tap Payments 无关联，也未获得其认可。