VibeFox Transbank for WooCommerce — 帮助
系统要求
WordPress：6.0 或更高版本。
WooCommerce：8.0 或更高版本，已安装并启用。未安装时插件无法启用。
PHP：8.0 或更高版本。
店铺货币：智利比索（CLP）。Webpay Plus 只收取整数比索，因此请在 WooCommerce > Settings > General 中将 Number of decimals 设为 0。在使用其他货币的店铺中，不会显示该付款方式。
Transbank 账户：正式付款需要一个标准的 Webpay Plus 商户账户（即时扣款），并配有其正式 Commerce Code 和 API Key Secret。Transbank 会在您的签约获批后提供 Commerce Code，并在集成验证流程完成后提供 API Key Secret（请参阅 Transbank 开发者文档）。测试时无需凭据。不支持 Webpay Plus Mall、Oneclick 和延迟扣款商户代码。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 wcp_transbank_gateway 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 在 WooCommerce > Settings > General 中，将店铺货币设为智利比索，并将 Number of decimals 设为 0。
4. 打开设置：WooCommerce > Settings > Payments > Transbank Webpay Plus > Manage，或在插件页面点击插件名称下方的 Settings。
5. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
6. 开启 Enable / Disable，并在 Integration (test) mode 开启的情况下，使用 Transbank 开发者文档中的测试卡进行一次付款测试。
7. 如需正式上线，请输入 Production Commerce Code 和 Production API Key Secret，取消勾选 Integration (test) mode，然后保存。
无需在 Transbank 设置返回 URL 或 Webhook。插件会在每笔交易中发送其返回 URL。
配置
所有设置都在同一个页面：WooCommerce > Settings > Payments > Transbank Webpay Plus。在字段上方，页面会在以下情况提醒您：选择了正式模式，但正式 Commerce Code 或 API Key 缺失或无效（此时 Webpay 将在结账时隐藏）；店铺货币不是 CLP（付款方式将被隐藏）；CLP 价格含小数（总额将四舍五入为整数比索）。开启集成模式时，页面会显示 Integration (test) environment：不会收取真实费用。保存后，提醒会按新设置更新。在付款方式列表中，若选择了正式模式但没有有效凭据，该网关会被标记为需要设置。
常规
Enable / Disable：Enable Transbank Webpay Plus payments，用于开启或关闭该付款方式。默认：关闭。
Title：顾客在结账时看到的付款方式名称。默认：Webpay Plus。
Description：结账时显示在付款方式下方的文字。默认：Pay with credit, debit or prepaid card via Webpay.
环境和凭据
此部分文字链接到 Transbank 开发者文档，并说明 Transbank 何时提供正式凭据。
Integration (test) mode：Use the Transbank integration environment。付款将发送到 Transbank 集成环境，并自动填入其公开的测试商户代码（597055555532）。下方的正式凭据不会被使用，也不会收取真实费用。默认：开启。如需正式上线，请取消勾选。
Production Commerce Code：您的正式商户代码（Tbk-Api-Key-Id）：12 位数字，以 5970 开头。如果您的代码是 8 位，请按原样输入；保存时插件会添加 5970 前缀。空格和其他字符会被删除。Transbank 的公开测试商户代码不能用于正式环境。
Production API Key Secret：您正式商户的 Tbk-Api-Key-Secret。请妥善保密。保存时会删除空格。
高级
Debug log：Log API requests and returns (errors are always logged)。详细信息将写入 WooCommerce > Status > Logs，来源为 wcp_transbank_gateway；该字段带有 view logs 链接。即使此选项关闭，错误和警告仍会被记录。日志中不会记录银行卡数据、API 密钥或完整令牌。默认：关闭。
Delete data on uninstall：Remove the gateway settings and logs when the plugin is deleted (order data is kept)。默认：关闭。
测试和正式
Integration (test) mode 决定新付款的去向。每笔付款都会记住其环境：付款的确认和退款始终发送到创建该付款时所用的环境（集成或正式）并使用其凭据，即使您之后切换了模式。
结账
顾客选择付款方式（默认为 Webpay Plus）并提交订单。在集成模式下，结账页面会显示 TEST MODE: Integration environment。不会产生真实扣款。插件会为订单总额创建一笔 Transbank 交易，以整数比索计（含小数的总额会四舍五入到最接近的比索），并将顾客带到一个简短的页面 Redirecting to Webpay. Please wait...，随后跳转到 Webpay 表单。若未启用 JavaScript，顾客需点击 Proceed to Webpay。在 Webpay 上，顾客使用信用卡、借记卡或预付卡付款。
顾客返回时，插件会通过服务器对服务器的方式与 Transbank 确认（commit）交易。只有在 Transbank 确认之后，订单才会被标记为已付款：响应必须为批准，且金额、buy order 和会话必须与店铺为本次尝试所发送的内容一致。之后，顾客会看到订单已接收页面。如果确认请求失败（例如超时），插件会向 Transbank 查询交易状态。若仍无法确定状态，订单不会被更改，顾客会看到 We could not confirm your Webpay payment with Transbank. Please try again in a moment; if your card was charged, contact us before paying again.
若顾客在 Webpay 上取消，Webpay 表单过期或报错，则不会产生任何扣款。订单保持待付款状态，顾客会返回 Pay for order 页面并看到提示，例如 You cancelled the Webpay payment. Nothing was charged — you can try again or choose another payment method. 银行卡被拒时会显示 Your Webpay payment was rejected and nothing was charged. Please try again or choose another payment method. 顾客可以在同一页面重新付款。每次新的尝试都是一笔新的 Webpay 交易。
每次 Webpay 尝试最多确认一次。重新加载返回页面、点击浏览器后退按钮，或同时发生第二次返回，都绝不会重复确认，也绝不会更改订单。如果订单已不需要付款（已通过其他尝试付款、已取消或已退款），迟到的返回将不会被确认，因此 Transbank 也不会扣款。顾客会看到 This order can no longer be paid (it was cancelled or already paid). Your Webpay payment was not confirmed, so it was not charged.
如果 Webpay 无法启动付款，顾客会看到简短提示，例如 Could not connect to Webpay. Please try again in a moment. 或 Webpay payments are not available at the moment. Please choose another payment method. 技术原因将记录在日志中。
该付款方式适用于经典结账、结账区块以及 Pay for order 页面。它兼容 WooCommerce 高性能订单存储（HPOS）。
Transbank 没有付款 Webhook：结果在顾客从 Webpay 返回时处理。如果顾客在 Webpay 上关闭浏览器且从未返回，交易将不会被确认，订单保持待处理；据 Transbank 称，未确认的交易不会结算。插件不支持 Webpay Plus Mall、Oneclick 保存卡、订阅、延迟扣款或货币转换。
订单和退款
订单状态
Pending payment：顾客已被送往 Webpay，但尚未付款、已取消、让表单过期，或付款尚无法确认。每次结束的尝试都会在备注中记录其 buy order。
Processing or Completed：Transbank 已批准付款。状态由 WooCommerce 设置：仅含虚拟可下载商品的订单为已完成（Completed），其他为处理中（Processing）。订单备注会显示授权码、银行卡后四位、buy order、金额、付款类型和分期期数。交易 ID 即为 Webpay 令牌。
On hold：Transbank 授权了一笔与订单不匹配的付款（金额、buy order 或会话 ID），例如因为付款开始后订单被修改。备注会列出差异。请检查 Transbank 门户，然后退款或完成订单。
Failed：付款被拒绝，未产生任何扣款。备注会显示响应代码和状态。
如果 Webpay 为一个已付款、已取消或已退款的订单返回付款，该付款将不会被确认，并且备注会提示您在顾客报告扣款时检查 Transbank 门户。现有订单不受后续尝试影响。
退款
仅对通过 Webpay 付款的订单提供退款按钮。打开订单，点击 Refund，输入金额，然后点击 Refund via Webpay Plus（该按钮使用付款方式的标题）。支持以整数比索进行全额和部分退款。含小数的部分金额会被拒绝，并显示 Webpay refunds are in whole Chilean pesos. Please enter an amount without decimals. 含小数的订单总额的最后余数会与扣款一样进行四舍五入。退款将发送到付款时所用的环境，因此在正式环境中必须已设置正式凭据。
Transbank 会以冲正（REVERSED）或作废（NULLIFIED）作为回应。退款成功后，会将金额、类型、授权码以及 Transbank 上剩余的余额添加到订单备注中。如果 Transbank 不接受退款，WooCommerce 会显示错误，且不记录任何退款。在 Transbank 门户中完成的退款不会导入 WooCommerce。
许可证密钥
插件需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > Transbank Webpay Plus 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期截止日期和您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将其从本站点移除。Manage licenses and domains in your account 链接会打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。从站点移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。
没有有效的许可证密钥时，Webpay Plus 不会在结账时向顾客显示。如果仍然启动了付款，顾客会看到 This payment method is not available. Please choose another one. 已登录的店铺管理员仍会看到该付款方式，并标有 (unlicensed — visible to admins only)，以便您在购买密钥前进行设置和测试。插件页面和 WooCommerce 页面会显示提醒。现有订单不受影响：已开始的付款仍会被确认，退款也照常可用。
许可证到期后，插件仍可继续工作，但更新和支持需要续费。状态会在后台自动重新检查。
故障排除
Webpay Plus 未出现在结账页面：请检查许可证是否有效，Enable / Disable 是否开启，店铺货币是否为 CLP（在 Pay for order 页面，则看订单货币），并且在集成模式关闭时，是否已保存有效的 Production Commerce Code（12 位数字，以 5970 开头）和 Production API Key Secret。设置页面会针对每个缺失的条件显示警告。
付款已完成，但订单仍为 Pending payment：Transbank 没有 Webhook，因此只有在顾客从 Webpay 返回时才会确认订单。如果顾客在 Webpay 上关闭了浏览器，交易未被确认，并且据 Transbank 称不会结算。请检查订单备注和日志，以及 Transbank 门户中的交易。
顾客看到 We could not confirm your Webpay payment with Transbank：确认请求失败，且无法检查状态。订单未被更改，并已添加备注。顾客可稍后重试。如果 Transbank 门户将该交易显示为已授权，请在发货前在门户中予以确认。
顾客下单时看到错误：开启 Debug log，并查看 WooCommerce > Status > Logs，来源为 wcp_transbank_gateway。Webpay payments are not available at the moment 通常表示正式凭据有误。Could not connect to Webpay 表示无法连接 Transbank。使用非 CLP 货币的订单无法通过 Webpay 付款。
总额和退款相差几个比索：CLP 价格含小数。Webpay 只收取整数比索，因此总额会被四舍五入。请将 Number of decimals 设为 0。
退款失败，提示 The production Commerce Code / API Key are missing：付款是在正式环境中完成的，但未保存正式凭据。请输入凭据后重试。
退款失败，提示 Transbank refused the refund 或 Transbank did not approve the refund：Transbank 未接受退款；消息会显示原因，或其返回的类型和响应代码。未退款任何金额。请在 Transbank 门户中检查该交易。
许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在其他域名上使用，请在您的 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now，以便为新域名激活该密钥。如果无法连接许可证服务器，插件将沿用最后一次已知的状态继续工作。
卸载
停用插件会保留所有数据。要移除插件，请在 Plugins 页面中停用并删除它。本插件的许可证密钥和许可证状态始终会被删除。网关设置、其他选项、插件的临时数据及其日志（日志文件，包括轮转的日志，以及数据库中的日志记录）仅在 Delete data on uninstall 开启时才会被删除。否则，它们将保留，以便日后重新安装时使用。订单中存储的 Transbank 数据始终保留，因为会计和退款需要这些数据。现有订单会保留其付款备注和交易 ID。
Transbank 和 Webpay 是其各自所有者的商标。本插件与 Transbank 无关联，也未获得 Transbank 的认可。