VibeFox Tap for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块拒绝安装在较旧的 PHP 版本上。
商店货币：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 仅用于弹窗。提供哪些付款方式（mada、KNET、Benefit 等）以及 Apple Pay 域名验证，需在您的 Tap 账户中设置。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或之后在模块列表中找到 VibeFox Tap Payments，再点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，于 License key 处输入您的 VibeFox 许可证密钥，然后点击 Activate（见“许可证密钥”）。
4. 输入 Tap 的测试和正式密钥，选择付款操作、结账方式和 Tap 页面语言（见“配置”）。
5. 开启 Enable / Disable 并点击 Save。使用 Tap 测试卡进行测试，然后关闭 Test mode。
安装时，模块会创建两个订单状态：Tap payment authorized 和 Tap payment on hold。PrestaShop 会为所有货币、国家和客户组启用新的付款模块。您可以在 Payment > Preferences 中进行限制。
配置
所有设置位于模块页面：Modules > Module Manager > VibeFox Tap Payments > Configure。每个部分都有各自的 Save 按钮，点击后会保存整个页面。字段上方页面会显示 Test mode is on: payments use your Tap test keys and no real money is charged. 或 Live mode: real payments are accepted. 当当前模式的密钥缺失时（此时结账中不显示该付款方式），以及商店默认货币不被 Tap 支持时，页面也会发出警告。
保存时，若密钥前缀与其字段不符，该密钥不会被保存：保留原值，其他设置正常保存，并显示类似 Test secret key was not saved: a Tap key for this field starts with "sk_test_". 的消息。例如，在测试字段中输入正式密钥会被拒绝。Title 不能为空：页面显示 Enter a title for the payment method.，且不会保存任何内容。
Tap Payments
部分标题还会显示当前模式的 TEST 或 LIVE。
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：使用测试密钥，不会扣除真实款项。付款、状态查询、扣款和退款始终使用付款时所用模式的密钥，因此切换到正式模式后，测试付款仍会使用测试密钥进行查询和退款。默认：开启。开启时，顾客会在付款方式下方看到 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. 只有需要更改时才输入新值。公开密钥（publishable key）是公开的，会保持可见。
Clear saved secrets：勾选某个密钥并点击 Save 即可删除。空字段会保留已保存的值。
付款
Payment action：顾客付款时资金如何处理。
Checkout type：顾客在哪里付款。
Tap page language：English（默认）或 Arabic。
付款通知（Webhook）
Tap 会将付款结果发送到本节 Webhook URL 中显示的网址。使用友好网址时，形式类似 https://your-shop/module/wcp_tap_payment_gateway/webhook，可能带有语言代码，例如 /en/。该网址会随每笔付款发送，因此无需在 Tap 后台进行配置。只需确保其可从互联网访问（未被防火墙或 HTTP 身份验证拦截）。每条通知都会使用 hashstring 签名进行校验（HMAC-SHA256，使用付款所用模式的 secret key）。签名无效的 Webhook 会被拒绝。即便是已签名的通知，也不会被直接信任：模块会在创建或修改订单之前，再次通过 Tap API 读取付款信息。如果 Webhook 无法正常工作，只有在顾客付款后返回商店时才会创建订单。
高级
Debug log：将付款事件记录到模块文件夹中的 logs/tap_p_debug.log.php。该文件无法通过网页读取。错误和警告始终会被记录；开启此选项可同时记录每个付款事件。日志绝不包含密钥、银行卡或顾客数据。默认：关闭。
Log：显示日志的大小和最新条目。点击 Clear log 可清空。
Delete data on uninstall：开启时，卸载模块会删除网关设置和日志。订单的付款记录会保留。默认：关闭。
结账
在付款步骤，顾客选择付款方式（默认为 Tap Payments）并确认订单。此时尚未创建订单。
Tap payment page：模块会按购物车金额，以购物车货币在 Tap 创建一笔扣款（在 Authorize only 模式下则为授权），描述为 Cart # 和购物车编号，然后将顾客带到 Tap 付款页面。顾客的姓名、电子邮件和电话会传给 Tap。顾客在 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 payment 页面，Tap 付款表单在此打开。页面还会显示 Pay on the Tap payment page instead 链接。若窗口被关闭，Pay now 按钮会重新打开它。若表单无法加载，会提示顾客使用 Tap 付款页面。刷新页面会复用同一笔付款尝试。
付款后，顾客返回您的商店。只有在 Tap 确认后，订单才会被标记为已付款：模块使用付款所属模式的密钥通过 Tap API 读取付款信息，检查其是否属于此购物车并由其结账流程发起，并将金额和币种与购物车比对。返回地址中的 Tap ID 本身绝不会创建订单。Webhook 会在后台执行相同的检查。随后订单被创建，顾客会看到标准的订单确认页面。对于已授权的付款，页面显示 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. 购物车会被保留，可以再次付款。
结账时的其他消息：当购物车货币不受支持时，显示 Tap does not accept payments in 及货币代码；以及 The order total must be greater than zero to pay with Tap.
即使商店处于维护模式，Webhook 仍然有效，并且不受商店国家限制的影响。
模块不支持保存银行卡或令牌化、订阅，也不在结账页面嵌入银行卡输入框。Capture Tap payment 始终扣除订单总额；不支持部分扣款。
订单与退款
订单状态
尚无订单：顾客已被带到 Tap 但尚未付款，或 Tap 尚未确认付款。此时仅存在购物车。
Payment accepted：Tap 已确认一笔已扣款的付款。付款以 Tap 扣款 ID（chg_...）作为交易 ID 记录，备注中显示金额、扣款 ID、付款方式，以及（测试模式下）该笔为测试付款。
Tap payment authorized：付款仅获得授权，等待扣款或撤销。
Tap payment on hold：已付金额或币种与购物车不符（Tap: amount/currency mismatch — manual review required.），或付款在订单被取消后才到达。备注会说明原因。请检查订单并处理，或退还该笔付款。
Canceled：授权已通过 Void Tap authorization 撤销，预留资金已释放。
Refunded：该笔付款已通过模块全额退款。
失败的尝试绝不会改变已付款、已授权或已取消的订单。若已付款的订单又收到第二笔成功付款，订单不会被修改。备注会说明这是重复付款，并要求您在 Tap 后台退款。与购物车相关但未由其结账流程发起的付款，仅会被记录备注。
Tap 付款区块
订单页面显示 Tap payment 区块，包含 Tap ID、授权与扣款、模式（测试付款显示 Test mode 标签）、付款状态与方式、Charged / refunded、退款记录、购物车的付款尝试以及订单的 Payment notes。该区块的按钮直接在订单页面上生效；您需要具有编辑订单的权限，而不是模块设置的访问权限。
扣款与撤销
在 Authorize only 模式下，打开状态为 Tap payment authorized 的订单。Capture Tap payment（按钮上显示订单总额）会在确认 Capture the reserved funds of this order through Tap? 后扣除订单总额；订单随后变为 Payment accepted。Void Tap authorization 会询问 Release the reserved funds? The order will be canceled.，释放资金并将订单设为 Canceled。如果 Tap 拒绝该操作，区块中会显示错误，并添加到备注中。如果授权是直接在 Tap 后台扣款的，Webhook 会将订单标记为已付款；此类付款的退款必须在 Tap 后台完成。
退款
在 Tap payment 区块中输入金额（会自动填入尚未退款的金额），可选填写原因，然后点击 Refund via Tap。确认询问 Refund this amount through Tap? This cannot be undone. 支持对已扣款的 Tap 付款进行全额和部分退款。即使订单之后被编辑，您也最多可退还 Tap 实际扣款的金额和币种。退款使用付款所属模式的 secret key 发送，因此该模式的密钥必须已设置。被 Tap 接受的退款会连同 Tap 退款 ID 和状态一起添加到退款记录和备注中。若 Tap 拒绝，区块会显示错误，且不会记录退款。全额退款会将订单设为 Refunded；部分退款不会更改状态。对于已授权的订单，只有在授权被扣款后才能退款。因金额或币种不符而挂起的订单，需在 Tap 后台退款。
模块不会开具退款单。订单页面上 PrestaShop 的标准退款按钮不会通过 Tap 退回款项。在 Tap 后台进行的退款不会显示在 PrestaShop 中。
许可证密钥
本模块需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Tap Payments 位于 Modules > Module Manager > VibeFox Tap Payments > Configure 页面的最上方，位于设置之上。将密钥粘贴到 License key 中并点击 Activate。之后，该区块会以隐藏形式显示密钥，并显示状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now 用于重新检查状态，Change key 用于输入其他密钥，Remove key 用于从本商店移除密钥。其下方有一行 Product: presta-payment-tap 和链接 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 账户中释放该名额。
没有有效密钥时，结账时不会向顾客显示 Tap Payments。如果仍然开始了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法得知您已登录后台，因此付款方式对您也是隐藏的：您可以在购买密钥之前设置模块，但无法在结账时进行测试。Modules > Module Manager 的 Alerts 选项卡中会出现提醒。现有订单不受影响：已开始的付款仍会被确认，退款、扣款和撤销仍可正常使用。
许可证到期后，模块仍会继续运行，但更新和支持需要续费。在后台工作时会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
Tap Payments 未在结账时显示：请检查许可证是否有效、Enable / Disable 是否开启，以及当前模式是否有 secret key（当 Checkout type 为弹窗时还需要 publishable key）。检查购物车货币是否为 AED、BHD、EGP、EUR、GBP、JOD、KWD、OMR、QAR、SAR、USD 之一。在 Payment > Preferences 中，检查模块是否允许用于该购物车货币、顾客所在国家和顾客组。设置页面会对缺失的密钥和不受支持的商店货币显示警告。
付款已完成，但未创建订单：Webhook 无法访问您的商店。请检查 Webhook URL 中显示的网址能否从互联网访问（无防火墙或 HTTP 身份验证），并开启 Debug log，以在 Log 字段中查看响应。顾客从 Tap 返回时也会创建订单。
Webhook answers invalid signature：通知未使用该付款模式的 secret key 签名。请检查设置中的 secret key。
Webhook answers gateway not configured：该付款模式（测试或正式）的 secret key 为空。请输入。
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 字段。错误的密钥或被拒绝的请求会记录在那里。
顾客看到 We could not match this payment to an order：该付款不属于此购物车，或并非由其结账流程发起。如果已扣款，请在 Tap 后台核对该付款。
订单为 Tap payment on hold：请阅读 Tap payment 区块中的备注。已付金额或币种与购物车不符，或付款在订单被取消后才到达。
退款因模式相关的消息而失败：该付款是在测试或正式模式下完成的，而该模式没有配置 secret key。请输入后重试。如果区块提示未找到已扣款的 Tap 扣款，请在 Tap 后台退款。
开发者钩子：钩子 actionWcpTapChargePayload、actionWcpTapSupportedCurrencies 和 actionWcpTapCurrencyDecimals 允许开发者修改付款请求、支持的货币以及货币的小数位数。
卸载
进入 Modules > Module Manager，打开 VibeFox Tap Payments 旁边的菜单，选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。若 Delete data on uninstall 已开启，则会删除网关设置和日志。若关闭，则保留所有设置，以便日后重新安装。Tap 付款尝试和退款记录，以及 Tap payment authorized 和 Tap payment on hold 订单状态始终会保留，因此重新安装后，之前已付款的订单仍可退款。现有订单会保留其付款备注和交易 ID。
Tap Payments 是其各自所有者的商标。本模块与 Tap Payments 无关联，也未获得其认可或背书。