VibeFox Tap for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本。

订单货币：AED、BHD、EGP、EUR、GBP、JOD、KWD、OMR、QAR、SAR 或 USD。对于其他货币的订单，结账时不会显示该付款方式。

店铺的互联网访问：Tap 会将付款结果发送到您店铺上的 Webhook，因此站点必须可从互联网访问。每次付款都会发送 Webhook URL；无需在 Tap 控制台中进行任何配置。

Tap 账户：您需要 Tap 控制台中的 API 密钥（goSell、API 凭据）。测试密钥以 pk_test_ / sk_test_ 开头，正式密钥以 pk_live_ / sk_live_ 开头。始终需要私钥；可公开密钥仅用于结账弹窗。提供哪些付款方式（mada、KNET、Benefit 等）以及 Apple Pay 域名验证，均在您的 Tap 账户中设置。

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

安装

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

OpenCart 3

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

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

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

4. 输入您的 Tap 测试和正式密钥，选择付款操作、结账类型和 Tap 页面语言（参见配置）。

5. 开启 Enable / Disable 并点击 Save。使用 Tap 测试卡进行测试，然后关闭 Test mode。

OpenCart 4

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

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

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

4. 按照 OpenCart 3 步骤 3 至 5 的方式输入许可证密钥、Tap 密钥和付款选项。两个版本的设置页面及其字段相同。

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

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox Tap Payments > Edit。各部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，页面会显示 Test mode is on: payments use your Tap test keys and no real money is charged. 或 Live mode: real payments are accepted. 当当前模式的密钥缺失（此时结账时不显示该付款方式）以及店铺默认货币不被 Tap 支持时，页面也会发出警告。如果没有修改扩展的权限，页面可以显示设置，但无法保存。

保存时，Title 不能为空，且不能超过 128 个字符；Sort Order 必须是整数（允许负值）；Total 必须是大于或等于 0 的数字；订单状态必须存在；否则不会保存任何内容。字段前缀错误的密钥不会被保存：保留原值，其他设置正常保存，并显示类似 Test secret key was not saved: a Tap key for this field starts with "sk_test_". 的消息。例如，在测试字段中输入正式密钥会被拒绝。

Tap Payments

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

Title：顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认：Tap Payments。必填，最多 128 个字符。

Description：顾客在 Confirm Order 步骤中、确认按钮上方看到的文字。默认：Pay with Visa, Mastercard, mada, KNET, Benefit, Apple Pay or Google Pay.

Sort Order：Tap 在结账付款方式中的位置。留空或输入整数（允许负值）。

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

Total：订单必须达到的结账总额（以店铺默认货币计）才会提供 Tap。留空则对任何金额都提供 Tap。

Tap API 密钥

您可以在 Tap 控制台（goSell、API 凭据）中找到密钥。本节链接到 Tap 开发者文档。

Test mode：使用测试密钥，不会扣除真实款项。付款、状态查询、扣款和退款始终使用付款时所在模式的密钥，因此即使切换到正式模式后，测试付款仍会使用测试密钥进行查询和退款。默认：开启。开启时，顾客在 Confirm Order 步骤和弹窗付款页面上会看到 Test mode: no real payment will be made.

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 要求您将付款路由到特定商户账户时才需要。

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

付款

Payment action：顾客付款时资金如何处理。

Checkout type：顾客在哪里付款。

Tap page language：Tap 付款页面和弹窗的语言：English（默认）或 Arabic。

付款通知（Webhook）

Tap 会将付款结果发送到本节 Webhook URL 中显示的地址。在 OpenCart 3 中，该地址形如 https://your-store/index.php?route=extension/payment/wcp_tap_payment_gateway/webhook，在 OpenCart 4 中形如 https://your-store/index.php?route=extension/wcp_tap_payment_gateway/payment/wcp_tap_payment_gateway.webhook，由您的 OpenCart 安装的店铺前台地址生成。每次付款都会发送该 URL，因此无需在 Tap 控制台中进行任何配置。请确保它可从互联网访问（未被防火墙或 HTTP 身份验证阻止）；维护模式不会阻止它（在 OpenCart 4 中，扩展的一个启动操作会让 Webhook 和顾客返回都能通过）。每个通知都使用 hashstring 签名进行校验（使用付款模式的私钥进行 HMAC-SHA256 计算）。没有有效签名的 Webhook 会被拒绝。即使是已签名的通知，也不会被直接信任：扩展在修改订单之前，会通过 Tap API 重新读取付款信息。如果没有可用的 Webhook，订单只有在顾客付款后返回店铺时才会获得状态。

订单

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

Paid Order Status：扣款成功后的状态。默认：处理中。

Authorized Status：Authorize only：资金已预留，尚未扣款。默认：待处理。

On Hold (Review) Status：付款需要您审核（参见订单状态）。默认：待处理，因为 OpenCart 没有“暂停”状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

Voided Status：在 Void Tap authorization 释放预留资金后设置。默认：已取消。

Refunded Status：在订单页面将付款全额退款后设置。默认：已退款。

高级

Debug log：将付款事件写入 OpenCart 日志文件夹（storage/logs；OpenCart 4 中为 system/storage/logs）中的 tap_p_debug.log.php。该文件无法通过网页读取，达到 5 MB 时会移动到 tap_p_debug.old.log.php。错误和警告始终记录；开启此选项可同时记录每个付款事件。日志绝不包含密钥、银行卡或顾客数据。默认：关闭。

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

Delete data on uninstall：开启后，卸载扩展会删除网关设置和日志。订单的付款记录始终保留。默认：关闭。

导入 / 导出

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

Import：粘贴之前导出的 JSON，然后点击 Import 恢复设置。已保存的私钥会保留。

结账

在 Payment Method 步骤中，顾客选择付款方式（默认为 Tap Payments）。在 Confirm Order 步骤中，顾客会看到您的描述。OpenCart 在此步骤创建订单，仍然没有状态。然后顾客点击 Confirm Order。在 OpenCart 4 中，顾客通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式，并点击结账页面底部的 Confirm Order。

Tap payment page：扩展会以订单货币为订单总额创建一笔 Tap 扣款（或在 Authorize only 模式下创建授权），描述为 Order # 加订单号，并将顾客转到 Tap 付款页面。顾客的姓名、电子邮件和电话号码会传递给 Tap。在那里，顾客可以选择银行卡、mada、KNET、Benefit、Apple Pay 或 Google Pay（以您 Tap 账户中已启用的为准）并完成付款。如果 Tap 无法发起付款，顾客会停留在 Confirm Order 步骤，并看到 The Tap payment could not be started. Please try again or choose another payment method.，原因会记录在日志中。

Tap checkout popup：顾客进入扩展的 Tap payment 页面，在其中打开 Tap 付款表单。该页面还显示 Pay on the Tap payment page instead 链接。如果窗口被关闭，Pay now 按钮会重新打开它。如果无法加载表单，系统会请顾客改用 Tap 付款页面。刷新页面会复用同一次付款尝试。

付款后，顾客返回您的店铺。只有在 Tap 确认后，订单才会被标记为已付款：扩展会使用付款模式对应的密钥，通过 Tap API 重新读取付款信息，检查其是否与该订单相关且由其结账流程发起，并将金额和币种与订单进行比较。仅凭返回地址中的 Tap ID 永远不会更改订单。Webhook 会在后台执行相同的检查。随后，订单会以 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存，顾客会看到 OpenCart 的订单成功页面。在 OpenCart 4 中，顾客从 Tap 付款页面返回时，一个简短的中间页面会重新打开来自您店铺的返回地址，因此购物车和顾客登录状态得以保留。对于已授权的付款，页面还会显示 Your payment has been authorized. We will process the order as soon as the payment is captured. 对于待审核的付款，页面会显示 Your payment is being reviewed. We will contact you if anything else is needed.

如果顾客返回时 Tap 尚未确认付款，Payment confirmation 页面会显示 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.，并带有 Check again 和 Back to checkout 按钮。Webhook 一到达就会设置订单状态。

如果付款被拒绝、中途放弃或取消，订单将保持无状态。顾客会返回结账页面，并看到 Your payment was not completed. Please try again or choose another payment method.（如果 Tap 提供了原因，还会显示该原因）。未完成的付款会显示 The payment was not completed. You can try again or choose another payment method. 购物车会被保留，可以再次付款。在 OpenCart 4 中，这些消息显示在结账页面上方。

在 OpenCart 3 中，每次显示 Confirm Order 步骤时，OpenCart 都会创建一个新订单；在 OpenCart 4 中，则会更新结账的订单。如果同一购物车的另一个订单已经付款，顾客会直接进入成功页面，而不会再次付款。在开始新付款之前，会向 Tap 检查该订单和该购物车在最近 24 小时内打开的 Tap 付款页面，因此在其他标签页中完成的付款会被确认，而不会被重复扣款。购物车发生变化（包括数量变化）即视为新的购物车，需要单独付款。

OpenCart 4 会在显示成功页面之前将订单保留在结账流程中。付款被拒绝或取消后，下一次点击 Confirm Order 会为同一订单发起新的 Tap 付款。如果该订单在此期间未付款即被关闭（例如您取消了它或其授权已被撤销），顾客会被带回结账页面，并看到 Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order. 消息，下一次点击 Confirm Order 将支付一个新订单。

结账时的其他消息：当订单货币不受支持时，显示 Tap does not accept payments in 加上货币代码；以及 The order total must be greater than zero to pay with Tap.

该扩展不支持保存银行卡或令牌化，不支持订阅，也不会在您的结账页面中嵌入银行卡输入框。Capture Tap payment 始终扣除订单总额；不支持部分扣款。

订单与退款

订单状态

无状态（缺失订单）：顾客已被转到 Tap 但尚未付款，或 Tap 尚未确认付款。在 Sales > Orders 中，只有将 Order Status 筛选器设置为 Missing Orders 时才会显示此类订单。在 OpenCart 4.1 中，此类订单在重新显示确认步骤时，还可能带有 OpenCart 设置的 Voided 状态；扩展会将其视为无状态订单。

Paid Order Status (default Processing)：Tap 已确认扣款成功。备注会显示金额、Tap 扣款 ID（chg_...）、付款方式，以及（测试模式下）测试付款的标识。

Authorized Status (default Pending)：付款仅获得授权，正在等待扣款或撤销。

On Hold (Review) Status (default Pending)：已付金额或币种与订单不一致（Tap: amount/currency mismatch — manual review required.），或订单取消后才收到付款。备注会说明原因。请检查订单并完成处理，或退还该付款。

Voided Status (default Canceled)：授权已通过 Void Tap authorization 撤销，预留资金已被释放。

Refunded Status (default Refunded)：付款已通过扩展全额退款。

失败的尝试绝不会更改已有状态的订单。如果已付款的订单又收到第二笔成功付款，订单不会被更改。备注会说明这是重复付款，并请您在 Tap 控制台中退款。属于同一购物车中另一个已付款订单的付款，会使该订单保持无状态，并记录在已付款订单上。与订单相关但并非由其结账流程发起的付款，仅会被记录。

备注是订单 History 中的条目，顾客看不到。它们以“Tap”开头。

VibeFox Tap Payments 标签页

在 Sales > Orders 中打开一个通过 Tap 付款的订单。在订单页面底部，与 History 和 Additional 并列的 VibeFox Tap Payments 标签页会显示 Tap ID、Authorization 和 Charge、Mode（测试付款显示 Test 标签）、付款的 Status 和付款方式、Charged / refunded、退款表单、退款记录、订单的 Payment attempts 以及 Tap notes。该标签页显示给有权访问该扩展的用户；扣款、撤销和退款需要修改扩展的权限（在 System > Users > User Groups 中设置）。

扣款与撤销

在 Authorize only 模式下，打开已授权的订单。Capture Tap payment（按钮上显示订单总额）会在确认问题 Capture the reserved funds of this order through Tap? 后扣除订单总额；订单随后获得 Paid Order Status。Void Tap authorization 会提示 Release the reserved funds? The order will be canceled.，释放资金并设置 Voided Status。2 分钟内的第二次扣款点击会被阻止。如果 Tap 拒绝该操作，标签页会显示错误并将其添加到备注中。这些状态变更不会通知顾客，也不会改变库存，与手动更改状态相同。如果授权是在 Tap 控制台中直接扣款的，Webhook 会将订单标记为已付款；此类付款的退款必须在 Tap 控制台中进行。

退款

在标签页中输入 Amount（会自动填入尚未退款的金额），可选填写 Reason (optional)，然后点击 Refund via Tap。确认提示 Refund this amount through Tap? This cannot be undone.。对于已扣款的 Tap 交易，支持全额和部分退款。即使订单之后被修改，您最多也可以退还 Tap 实际扣除的金额和币种。退款使用付款模式对应的私钥发送，因此必须已设置该私钥。被 Tap 接受的退款会连同 Tap 退款 ID 和状态一起添加到退款记录和备注中。如果 Tap 拒绝，标签页会显示错误，不会记录任何退款。全额退款会设置 Refunded Status，且不会通知顾客，也不会将商品退回库存；部分退款不会改变状态。对于已授权的订单，只有授权被扣款后才能退款。因金额或币种不一致而处于审核中的订单，需在 Tap 控制台中退款。

Sales > Returns 中的商品退货不会通过 Tap 退回款项。在 Tap 控制台中进行的退款不会出现在 OpenCart 中。

许可证密钥

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

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

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

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

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

故障排除

Tap Payments 未在结账时显示：请检查许可证是否有效、Enable / Disable 是否开启，以及当前模式是否有私钥（当 Checkout type 为弹窗时，还需要可公开密钥）。检查订单货币是否为 AED、BHD、EGP、EUR、GBP、JOD、KWD、OMR、QAR、SAR、USD 之一，付款地址是否位于所选的 Geo Zone 内，以及订单是否达到设置中的 Total。设置页面会对缺失的密钥和不受支持的店铺货币显示警告。

付款已成功，但订单仍无状态：Webhook 无法访问您的店铺。请检查 Webhook URL 中显示的地址能否从互联网访问（没有防火墙或 HTTP 身份验证），并开启 Debug log，以便在 Log 字段中查看响应。顾客从 Tap 返回后，订单也会获得状态。

Webhook answers invalid signature：通知未使用付款模式的私钥签名。请检查设置中的私钥。

Webhook answers gateway not configured：付款模式（测试或正式）的私钥为空。请输入该密钥。

Webhook answers verification failed：无法连接 Tap API 以核实付款。Tap 稍后会重试 Webhook。

Webhook answers order not found：通知所指的订单在本店没有任何 Tap 付款尝试。

Webhook answers busy, retry later or order could not be updated, retry later：订单在同一时刻正被另一个请求确认，或无法设置订单状态。Tap 会重试 Webhook。请在 Log 字段中查看原因。

密钥未能保存：密钥必须以其字段的前缀开头：pk_test_、sk_test_、pk_live_ 或 sk_live_。

顾客看到 The Tap payment could not be started：请查看扩展页面上的 Log 字段。错误的密钥或被拒绝的请求会记录在那里。

顾客看到 This payment method is not available：结账会话已与订单不匹配，或付款方式在此期间被关闭或失去了密钥。顾客需要重新加载结账页面。

顾客看到 We could not match this payment to an order：该付款不属于此订单，或不是由其结账流程发起的。如果已扣款，请在 Tap 控制台中检查该付款。

订单处于审核状态：请阅读 VibeFox Tap Payments 标签页中的备注。已付金额或币种与订单不符，或订单取消后才收到付款。

退款失败并提示与模式相关的消息：付款是在测试或正式模式下完成的，而该模式未配置私钥。请输入私钥后重试。如果标签页提示未找到已扣款的 Tap 交易，请在 Tap 控制台中退款。

面向开发者：OpenCart 事件 tap_p_charge_payload、tap_p_supported_currencies 和 tap_p_currency_decimals 允许开发者修改付款请求、支持的货币以及货币的小数位数。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Tap Payments 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被移除。OpenCart 始终会移除扩展自身的设置：Enable / Disable、Sort Order、Geo Zone、Total 以及 Orders 部分的订单状态，这些设置在重新安装后会恢复为默认值。扩展的 OpenCart 事件也会被移除（在 OpenCart 4 中，还会移除其事件及启动操作，该操作可让 Webhook 和顾客在维护模式下返回时通过）。如果 Delete data on uninstall 已开启，其他网关设置（标题、说明、密钥、付款选项、调试日志开关）和日志也会被删除。如果关闭，这些设置会保留，供以后重新安装时使用。Tap 付款尝试和退款始终会保留，因此即使重新安装后，之前已付款的订单仍可退款。现有订单会保留其付款备注。

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

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