VibeFox Transbank for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块会拒绝安装在较旧的 PHP 版本上。
货币：智利比索（CLP）。Webpay Plus 只收取整数比索，因此请在 International > Localization > Currencies 中将 CLP 货币的精度设为 0。对于使用其他货币的购物车，不会显示该付款方式。
Transbank 账户：正式付款需要标准的 Webpay Plus 商户（即时扣款），并具备正式的 Commerce Code 和 API Key Secret。Transbank 会在您的签约获批后提供 Commerce Code，并在集成验证流程完成后提供 API Key Secret（请参阅 Transbank 开发者文档）。测试无需任何凭据。不支持 Webpay Plus Mall、Oneclick 和延迟扣款的商户代码。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者稍后在模块列表中找到 VibeFox Transbank Gateway，然后点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥输入 License key，然后点击 Activate（参见许可证密钥）。
4. 开启 Enable / Disable，然后点击 Save。开启 Integration (test) mode 后，使用 Transbank 开发者文档中的测试卡进行付款测试。
5. 要正式上线，请输入 Production Commerce Code 和 Production API Key Secret，关闭 Integration (test) mode，然后点击 Save。
无需在 Transbank 设置返回 URL 或 Webhook。模块会在每笔交易中发送其返回 URL。
安装时，模块会创建订单状态 Transbank payment on hold。PrestaShop 会为所有货币、国家和客户组启用新的付款模块。您可以在 Payment > Preferences 中限制这些范围；CLP 货币必须对该模块保持允许状态。
配置
所有设置都在模块页面中：Modules > Module Manager > VibeFox Transbank Gateway > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。在字段上方，当选择了正式模式但正式 Commerce Code 或 API Key 缺失或无效时（此时 Webpay 会在结账时隐藏）、当店铺默认货币不是 CLP 时（其他货币下会隐藏该付款方式），以及当 CLP 带有小数时（金额会四舍五入为整数比索），页面会发出警告。集成模式开启时，页面会显示付款将发送至 Transbank 集成环境并使用公开的测试商户代码，且不会扣除真实资金。
Transbank Webpay Plus
Enable / Disable：Enable Transbank Webpay Plus payments 用于开启或关闭该付款方式。默认：关闭。
Title：顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认：Webpay Plus。必填：如果标题为空时保存，会显示 Enter a title for the payment method.
Description：结账时显示在付款方式下方的文字。默认：Pay with credit, debit or prepaid card via Webpay.
环境和凭据
本节文字链接到 Transbank 开发者文档，并说明 Transbank 何时提供正式凭据。
Integration (test) mode：付款发送至 Transbank 集成环境，使用其公开的测试商户代码（597055555532），该代码会自动填入。下方的正式凭据不会被使用，也不会扣除真实资金。默认：开启。关闭即可正式上线。开启时，顾客会在付款方式描述上方看到 TEST MODE：集成环境，不产生真实扣款。
Production Commerce Code：您的正式商户代码（Tbk-Api-Key-Id）：12 位数字，以 5970 开头。如果您的代码为 8 位，请按原样输入；保存时模块会添加 5970 前缀。空格和其他字符会被删除。Transbank 的公开测试商户代码不能用于正式环境。
Production API Key Secret：您正式商户的 Tbk-Api-Key-Secret。请妥善保密。保存时会删除空格。已保存的密钥不会再次显示：字段保持为空，并显示 Saved — leave empty to keep it. 仅在需要更改时才输入新值。
Clear saved API key：勾选 Production API Key Secret 并点击 Save，即可删除已保存的密钥。字段为空时保留已保存的值。
返回 URL
Return from Webpay：Transbank 将顾客送回的地址，仅供参考。无需在 Transbank 中进行任何设置：模块会在每笔交易中发送此 URL。顾客必须能够访问该地址；维护模式不会阻止它。
高级
Debug log：将 API 请求和返回记录到模块文件夹中的 logs/wc_tbk_debug.log.php。该文件无法通过网页打开。即使此选项关闭，错误和警告也始终会被记录。不会记录银行卡数据、API 密钥或完整令牌。默认：关闭。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Delete data on uninstall：开启时，卸载模块会删除网关设置和日志。订单数据会保留。默认：关闭。
测试与正式
Integration (test) mode 决定新付款的去向。每笔付款都会记住其所用环境：付款的确认和退款始终发送至该付款所用的环境（集成或正式），并使用创建该付款时的凭据，即使您之后更改了模式也是如此。
结账
在付款步骤，顾客选择付款方式（默认为带有 Webpay 标志的 Webpay Plus）并确认。模块会为购物车总额以整数比索创建 Transbank 交易（带小数的总额会四舍五入到最接近的比索），并将顾客带到一个简短页面 Redirecting to Webpay. Please wait...，随后转至 Webpay 表单。如果未启用 JavaScript，顾客需要点击 Proceed to Webpay。在 Webpay 上，顾客使用信用卡、借记卡或预付卡付款。此时尚不存在订单。
顾客返回时，模块会通过服务器对服务器的方式与 Transbank 确认（commit）交易。只有在 Transbank 确认后，订单才会标记为已付款：响应必须获得批准，并且金额、buy order 和会话必须与店铺为本次尝试发送的内容一致。随后订单会被创建，顾客会看到标准订单确认页面，并显示 Your Webpay payment has been received. 对于处于保留状态的订单，页面会显示 Your Webpay payment was received and is being reviewed by the shop.
如果确认请求失败（例如超时），模块会向 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. 如果此时另一个请求正在确认同一购物车，或 Transbank 已批准付款但订单尚无法创建，顾客会看到 Payment confirmation 页面，显示 Your Webpay payment is being confirmed. Please do not pay again — check again in a moment. 以及 Check again 按钮。随后将根据已保存的响应创建订单，无需再次确认。
如果顾客在 Webpay 上取消，或 Webpay 表单过期或报错，则不会扣除任何费用。顾客会返回结账页面，并看到提示信息，例如 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 交易。
如果付款开始后购物车发生了变化（例如在另一个标签页中修改，或购物车中的优惠券已失效且被 PrestaShop 移除），交易不会被确认，因此 Transbank 不会扣款。顾客会看到 Your cart changed after the Webpay payment was started. The payment was not confirmed, so it was not charged — please pay again. 如果购物车已经有订单（已通过其他尝试或其他付款方式支付），迟到的返回同样不会被确认，并且如果该订单未付款，顾客会看到 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. 技术原因会写入日志。
在店铺处于维护模式时，仍可从 Webpay 返回，且不受店铺的国家限制影响。
Transbank 没有付款 Webhook：结果会在顾客从 Webpay 返回时处理。如果顾客在 Webpay 上关闭浏览器且从未返回，交易不会被确认，也不会创建订单；根据 Transbank 的说明，未确认的交易不会进行结算。模块不支持 Webpay Plus Mall、Oneclick 保存卡、订阅、延迟扣款或货币转换。
订单与退款
订单状态
No order yet：顾客已被引导至 Webpay，但尚未付款、已取消、让表单过期、银行卡被拒，或付款仍无法确认。目前只存在购物车。
Payment accepted：Transbank 已批准付款。付款会以 Webpay 令牌作为交易 ID 记录，备注中会显示授权码、银行卡末四位、buy order、金额、付款类型和分期数。
Transbank payment on hold：Transbank 授权了一笔与订单不匹配的付款（金额、buy order 或会话），或者在 Transbank 批准付款后，购物车中的优惠券失效且被 PrestaShop 移除。付款会以 Transbank 实际扣除的金额记录，备注中会列出差异。请检查 Transbank 门户，然后履行订单或退还付款。
Refunded：该付款已通过模块全额退款。
如果 Webpay 为一个已经有订单的购物车返回了付款，则该付款不会被确认，并且该订单上会有一条备注，提醒您在顾客报告扣款时检查 Transbank 门户。之后的尝试不会影响现有订单。
Transbank Webpay Plus 区块
订单页面会显示 Transbank Webpay Plus 区块，其中包括 buy order 及其环境、付款状态、授权码、银行卡和付款类型（含分期数）、已扣除和已退款金额、测试付款的 Integration 标记、退款记录、Webpay attempts of the cart，以及订单的 Transbank notes。
退款
在 Transbank Webpay Plus 区块中输入 CLP 金额（会自动填入尚未退款的金额），可选填写原因，然后点击 Refund via Transbank。确认提示 Refund this amount via Transbank? 后即可退款。支持以整数比索进行全额和部分退款。您需要具有编辑订单的权限；无需访问模块页面。带小数的部分金额会被拒绝，并显示 Webpay refunds are in whole Chilean pesos. Please enter an amount without decimals. 带小数的订单总额中的尾差会与扣款一样四舍五入。退款金额最多可达 Transbank 实际扣除的金额，因此在出现差异后，您可以退还顾客实际支付的金额。退款会发送至付款时所用的环境，因此对于正式付款，必须已设置正式凭据。
Transbank 会返回撤销（REVERSED）或作废（NULLIFIED）结果。成功的退款会以金额、类型、授权码以及 Transbank 上的剩余余额添加到退款记录和备注中。全额退款会将订单设为 Refunded。部分退款不会改变状态。如果 Transbank 不接受退款，区块会显示错误，且不会记录退款。
模块不会创建信用单。订单页面上的 PrestaShop 标准退款按钮不会通过 Transbank 退款。在 Transbank 门户中完成的退款不会导入 PrestaShop。
许可证密钥
模块需要使用来自 vibefox.net 的 VibeFox 许可证密钥。位于 Modules > Module Manager > VibeFox Transbank Gateway > Configure 设置上方的第一个区块是许可证区块 License — VibeFox Transbank Gateway。将密钥输入 License key 并点击 Activate。之后，该区块会显示已隐藏部分字符的密钥、状态（例如许可证有效期截止日期和您的域名），以及按钮：Check now 用于重新检查状态，Change key 用于输入其他密钥，Remove key 用于从本店铺移除该密钥。它们下方是一行 Product: presta-payment-transbank 和链接 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 账户中释放该名额。
没有有效密钥时，结账时不会向顾客显示 Webpay Plus。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法得知您已登录后台，因此该付款方式对您也会隐藏：您可以在购买密钥之前设置模块，但无法在结账时进行测试。Modules > Module Manager 中的 Alerts 选项卡会显示提醒。现有订单不受影响：已发起的付款仍会在顾客从 Webpay 返回时确认，订单页面的退款也可以正常进行。
许可证到期后，模块仍会继续运行，但更新和支持需要续费。在后台工作时会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时不显示 Webpay Plus：请检查许可证是否有效、Enable / Disable 是否开启、购物车货币是否为 CLP；如果集成模式已关闭，还要检查是否已保存有效的 Production Commerce Code（12 位数字，以 5970 开头）和 Production API Key Secret。设置页面会针对每个缺失的条件显示警告。在 Payment > Preferences 中，请检查该模块是否允许用于 CLP、顾客所在国家以及顾客所属的客户组。
付款已完成，但未创建订单：Transbank 没有 Webhook，因此只有在顾客从 Webpay 返回时才会创建订单。如果顾客在 Webpay 上关闭了浏览器，交易未被确认，并且根据 Transbank 的说明，不会结算。请开启 Debug log，查看 Log 字段，并在 Transbank 门户中检查该交易。
顾客看到 We could not confirm your Webpay payment with Transbank：确认请求失败，且无法查询状态。未创建订单，原因已记录在日志中。顾客可以稍后重试。如果 Transbank 门户显示该交易已授权，请在顾客再次付款前与其联系。
顾客看到 Your cart changed after the Webpay payment was started：购物车总额与交易不一致，例如由于另一个标签页中的更改或优惠券过期。未扣除任何费用；顾客需支付新的总额。
顾客在选择 Webpay Plus 时看到错误：请开启 Debug log，并查看模块页面上的 Log 字段。Webpay payments are not available at the moment 通常表示正式凭据有误。Could not connect to Webpay 表示无法连接到 Transbank。Transbank Webpay only supports payments in CLP (Chilean Peso) 表示购物车使用的是其他货币。
总额和退款相差几个比索：CLP 货币带有小数。Webpay 只收取整数比索，因此总额会被四舍五入。请在 International > Localization > Currencies 中将 CLP 精度设为 0。
付款后订单显示为 Transbank payment on hold：请阅读 Transbank Webpay Plus 区块中的备注（参见订单状态），然后履行订单或退还付款。
退款失败，提示 The production Commerce Code / API Key are missing：该付款是在正式环境中完成的，但未保存正式凭据。请输入凭据后重试。
退款失败，提示 Transbank refused the refund 或 Transbank did not approve the refund：Transbank 未接受退款；消息会显示原因，或其返回的类型和响应代码。未退还任何金额。请在 Transbank 门户中检查该交易。
退款失败，提示 Another request is processing this order：该订单正在同时退款或确认。请稍后重试。
卸载
进入 Modules > Module Manager，打开 VibeFox Transbank Gateway 旁边的菜单，然后选择 Uninstall。该模块的许可证密钥和许可证状态始终会被删除。如果 Delete data on uninstall 已开启，网关设置和日志将被删除。如果已关闭，所有设置都会保留，以便日后重新安装。订单的 Webpay 尝试记录和退款，以及订单状态 Transbank payment on hold，始终会保留，因此之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款备注和交易 ID。
Transbank 和 Webpay 是其各自所有者的商标。本模块与 Transbank 无关联，也未获得其认可。