VibeFox Helcim for WooCommerce — 帮助
系统要求
WordPress：5.8 或更高版本。
WooCommerce：7.0 或更高版本，已安装并启用。未安装 WooCommerce 时，插件将拒绝激活。
PHP：8.0 或更高版本。
HTTPS 和 PCI DSS：银行卡信息在您的结账页面输入，并通过 HTTPS 从您的服务器发送到 Helcim。这些信息绝不会被存储或记录到日志中，但会经过您的服务器，因此您的店铺需要 SSL 证书，且主机托管必须符合 PCI DSS（SAQ D）规范。
Helcim 账户：位于加拿大或美国的 Helcim 商户账户，以及具备交易处理权限的 API 令牌（参见配置）。Helcim 处理 CAD 和 USD 交易。可选用 Helcim 测试（开发者）账户进行测试。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥仅适用于一个域名。
安装
1. 在 WordPress 中前往 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件并点击 Install Now。您也可以通过 FTP 将 wcp_helcim_gateway 文件夹上传至 /wp-content/plugins/ 目录。
2. 点击 Activate。
3. 在 Helcim 中打开 All Tools > Integrations > API Access Configuration，创建一个具备交易处理权限（购买、预授权、扣款、退款）的 API 访问并复制其令牌。
4. 打开设置页面：前往 WooCommerce > Settings > Payments > Helcim > Manage，或在「插件」页面上点击插件名称下方的 Settings。
5. 在页面顶部的许可证栏中输入您的 VibeFox 许可证密钥，然后点击 Activate。
6. 将令牌粘贴到 Live API token 中；如果您拥有 Helcim 测试账户，请将其令牌粘贴到 Test API token 中。
7. 选择 Transaction type 和 Account currencies，开启 Enable / Disable 并保存。如需先进行测试，请开启 Test mode 并使用测试账户付款，测试完成后将其关闭。
配置
所有设置均位于同一个页面：WooCommerce > Settings > Payments > Helcim。当店铺币种不在 Account currencies 中时，以及当网关处于启用状态但当前模式的 API 令牌为空时，页面上方都会显示警告。在这两种情况下，网关都会在结账时隐藏。在支付方式列表中，网关会被标记为需要设置，直到当前模式配置了令牌。
Enable / Disable:Enable Helcim Gateway 用于启用或关闭该支付方式。默认：关闭。
Title:结账时显示的支付方式标题。默认：Credit card (Helcim)。
Description:结账时显示的支付方式描述。默认：Pay securely with your credit card。
API 凭据
在 Helcim 中前往 All Tools > Integrations > API Access Configuration，创建一个 API 访问并复制其令牌。为其分配购买、预授权、扣款和退款的交易处理权限。Helcim 测试账户使用与正式账户相同的 API 地址，因此测试模式只需使用您 Helcim 测试账户的令牌。
Live API token:您的 Helcim 正式账户的 API 令牌。在测试模式关闭时使用。
Test mode:Use the Test API token (Helcim test account)。付款、扣款和退款将发送到您的 Helcim 测试账户，顾客会看到测试模式提示。订单的退款和扣款始终使用支付该订单时所用模式的令牌。默认：关闭。
Test API token:您的 Helcim 测试（开发者）账户的 API 令牌。在测试模式开启时使用。
付款
Transaction type:银行卡的扣款方式。
Account currencies:您的 Helcim 账户可以处理的币种。订单始终以订单自身的币种进行扣款。对于其他币种，网关在结账时自动隐藏。
高级
Debug log:Log API requests and responses 记录到 WooCommerce > Status > Logs，来源为 wcp_helcim_gateway。卡号将简化为仅保留后 4 位。CVC、有效期、令牌、姓名、地址、电子邮件和 IP 地址绝不记录。默认：关闭。
Delete data on uninstall:Remove the gateway settings, its own options (wc_hlg_*) and its log files when the plugin is deleted. 默认：关闭。
结账
顾客在结账时选择该支付方式（默认名称为 Credit card (Helcim)），并输入 Card Number、Expiry (MM/YY)、CVC 和 Cardholder Name。标题旁会显示 Visa、Mastercard、American Express 和 Discover 图标。在测试模式下，表单会显示 TEST MODE — payments go to a Helcim test account, no real charges are made. 在发送前，插件会验证卡号校验和、有效期是否有效且未过期、CVC 是否为 3 或 4 位数字，以及持卡人姓名是否已填写。
提交订单时，您的服务器会将银行卡信息以订单币种的订单总额形式作为购买或预授权发送到 Helcim。账单地址、电话和电子邮件会一同发送用于地址验证。该笔付款在 Helcim 中显示的账单发票号由订单号和简短代码组成。Helcim 在同一个请求中返回响应。仅在 Helcim 批准交易且批准的金额和币种与订单一致后，订单才会被标记为已付款。随后顾客将跳转到订单已收到页面。
每笔订单同一时间仅执行一次付款尝试，已付款的订单绝不会被再次扣款。每次尝试均使用幂等性密钥。如果 Helcim 未响应，订单将保持为待付款状态，在 5 分钟内重试将返回 Helcim 的原始结果，而不会对卡进行二次扣款。
顾客可能看到的提示信息：Helcim 拒绝交易时显示 Your card was declined. Please check the card details or use another card.；其他被拒请求显示 Payment failed: 及 Helcim 的具体原因；Helcim 未响应时显示 We could not confirm your payment with the card processor. Please try again in a minute; if the problem persists, contact us before using another card.；API 令牌缺失或被拒绝时显示 This payment method is temporarily unavailable. Please choose another payment method.；重复提交表单时显示 Your payment is already being processed. Please wait a moment and check your e-mail before trying again. 技术细节会记录在订单备注和日志中。
该支付方式适用于经典结账、结账区块（具有相同的银行卡字段）以及 Pay for order 页面。它兼容 WooCommerce 高性能订单存储（HPOS）。
本插件不使用 HelcimPay.js 或 Helcim.js，因此银行卡信息会经过您的服务器。它不支持保存银行卡、订阅、ACH 或银行付款、Apple Pay、Google Pay 或 3-D Secure，且不接收 Helcim Webhook。
订单与退款
订单状态
Pending payment:付款被拒绝或尚未确认。如果 Helcim 没有响应，订单备注会提示您在再次向顾客收取费用之前先核查 Helcim 中的账单发票。
Processing:购买已获批准，或预授权已被扣款。仅包含可下载虚拟商品的订单将变为已完成（WooCommerce 默认规则）。订单备注会显示交易 ID、批准代码、银行卡类型、后 4 位数字和模式。该交易 ID 即为 Helcim 交易 ID。
On hold (pre-authorization):资金仅处于冻结状态。可通过订单操作对其扣款，或通过全额退款解除冻结。
On hold after payment:Helcim 批准了交易，但其响应中的金额、币种或交易 ID 与订单不符。备注显示 Helcim response verification FAILED。在发货处理之前，请先在 Helcim 中核实该交易。
扣款
打开订单（状态为保留），选择订单操作 Capture Helcim pre-authorization 并点击 Update。扣款金额为当前订单总额扣除退款后的金额。该金额可以低于授权金额，但不能高于授权金额。扣款使用支付订单时所用模式的令牌。成功扣款后，订单状态变为处理中，交易 ID 也会更新为扣款交易的 ID。如果扣款失败，页面会显示原因并将其添加到订单备注中。
退款
打开订单，点击 Refund，输入金额并点击 Refund via Credit card (Helcim)（按钮上显示您设置的 Title）。支持对购买或已扣款的预授权进行全额和部分退款。未扣款的预授权只能全额退款：此时预授权冻结将被解除，不会向顾客收取任何费用。退款是在订单支付时的模式下发送的，因此必须配置该模式的令牌。退款仅在 Helcim 批准后才生效。如果 Helcim 拒绝退款，WooCommerce 会显示错误信息且不会记录任何退款。成功退款的信息会记录到订单备注中，并附带 Helcim 退款交易 ID。超时后的重试不会导致二次退款。
本插件不接收 Helcim Webhook。在 Helcim 控制面板中执行的扣款、退款和撤销操作不会同步到 WooCommerce，因此请直接在 WooCommerce 中进行这些操作。
许可证密钥
本插件需配合来自 vibefox.net 的 VibeFox 许可证密钥使用。许可证栏位于 WooCommerce > Settings > Payments > Helcim 页面顶部。将密钥粘贴到 License key 中并点击 Activate。该栏会显示状态信息，例如许可证有效截止日期和您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 从本站点移除密钥。点击链接 Manage licenses and domains in your account 可打开您的 vibefox.net 账户。
一个密钥仅适用于一个域名。从站点移除密钥并不会释放其域名槽位。请在您的 vibefox.net 账户中释放槽位。
若没有有效的密钥，结账时将不会向顾客显示 Helcim。如果仍然发起付款，顾客会看到 This payment method is not available. Please choose another one. 已登录的店铺管理员仍能看到该支付方式，并标注有 (unlicensed — visible to admins only)，以便您在购买密钥之前配置和测试插件。提示信息会出现在「插件」页面和 WooCommerce 各页面上。现有订单不受影响：扣款和退款功能仍可正常运作。
许可证过期后，插件仍可继续工作，但获取更新和技术支持需要续费。系统会在后台自动重新检查状态。
故障排除
Helcim 未在结账页面显示：请检查许可证是否有效、Enable / Disable 是否已开启、当前模式是否已配置 API 令牌（正式模式下的 Live API token 或测试模式下的 Test API token），以及购物车币种是否属于 Account currencies。在 Pay for order 页面上以订单币种为准。在这两种情况下，设置页面都会显示警告提示。
Helcim 未响应且订单保持为待付款状态：银行卡可能已被扣款。在再次向顾客收取费用之前，请先阅读订单备注并核对 Helcim 中的账单发票。5 分钟内的重试会返回原始结果，不会重复扣款。
顾客看到 This payment method is temporarily unavailable：当前模式的 API 令牌为空或已被 Helcim 拒绝。订单备注会提示检查令牌及其权限。请确保 API 访问具有交易处理权限。
付款失败并显示 Helcim 的原因：Helcim 拒绝了该请求，例如由于银行卡问题或账单信息有误。订单备注中包含详细信息。
付款后订单状态为保留：请阅读订单备注。订单可能是预授权状态并正在等待扣款，或者 Helcim 的响应与订单不匹配（响应验证失败）。
无法进行扣款：扣款金额必须大于 0 且不能超过授权金额，并且必须配置支付订单时所用模式的令牌。
退款失败：请阅读提示信息。未扣款的预授权只能全额退款。有关模式的提示信息意味着支付订单时所用模式的令牌为空。被拒绝的退款不会被记录。
测试付款：测试模式会将付款、扣款和退款发送到您的 Helcim 测试账户。订单会保留其付款时的模式，因此稍后切换模式不会将其扣款和退款转移到另一个账户。
许可证栏显示错误：请按照栏内的提示信息进行操作。例如，如果密钥已在其他域名上使用，请在 vibefox.net 账户中释放一个槽位，然后点击 Check now。如果站点网址发生变更，请点击 Check now 为新域名激活密钥。如果无法连接到许可证服务器，插件将按最后已知的状态继续运行。
针对开发者：过滤器 wc_hlg_supported_currencies 可用于修改支持的币种列表，wc_hlg_card_brands 可用于修改结账时的银行卡图标。
卸载
停用插件会保留所有数据。若要彻底移除，请在 Plugins 页面先停用然后再删除。本插件的许可证密钥和许可证状态始终会被移除。仅当开启了 Delete data on uninstall 时，网关设置、插件自带选项和日志文件才会被删除。否则它们将予以保留以便日后重新安装。订单数据属于订单历史记录的一部分，绝不会被删除。现有订单将保留其付款备注和交易 ID。
Helcim 是其各自所有者的商标。本插件与 Helcim 无关联，也未获得 Helcim 认可。