VibeFox Helcim for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块拒绝在较旧的 PHP 版本上安装。
HTTPS 和 PCI DSS：银行卡信息在您的结账页面输入，并由您的服务器通过 HTTPS 发送到 Helcim。这些信息从不被存储或记录，但会经过您的服务器，因此您的店铺需要 SSL 证书，且您的主机托管必须符合 PCI DSS（SAQ D）要求。
Helcim 账户：加拿大或美国的 Helcim 商户账户，以及具有交易处理权限的 API 令牌（参见「配置」）。Helcim 支持 CAD 和 USD。Helcim 测试（开发者）账户为可选项，仅用于测试。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者稍后在模块列表中找到 VibeFox Helcim Gateway，然后点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥输入 License key 字段，然后点击 Activate（参见「许可证密钥」）。
4. 在 Helcim 中打开 All Tools > Integrations > API Access Configuration，创建一个具有交易处理权限（购买、预授权、扣款、退款）的 API 访问，并复制其令牌。
5. 将令牌粘贴到 Live API token 中；如果您有 Helcim 测试账户，则将其令牌粘贴到 Test API token 中。
6. 选择 Transaction type 和 Account currencies，开启 Enable / Disable，然后点击 Save。若要先测试，请开启 Test mode 并使用您的测试账户付款；测试完成后再关闭。
安装时，模块会创建两个订单状态：Helcim payment authorized 和 Helcim payment on hold。PrestaShop 会为所有币种、国家和客户组启用一个新的支付模块。您可以在 Payment > Preferences 中对其进行限制。
配置
所有设置都位于模块页面：Modules > Module Manager > VibeFox Helcim Gateway > Configure。每个部分都有各自的 Save 按钮，该按钮会保存整个页面。在字段上方，如果您店铺的默认币种不在 Account currencies 之列，页面会发出警告；而在支付方式启用期间，如果当前模式的 API 令牌为空，页面也会发出警告。在这种情况下，该支付方式会在结账时被隐藏。
Helcim
Enable / Disable：Enable Helcim Gateway 用于开启或关闭该支付方式。默认：off。
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：使用 Test API token（Helcim 测试账户）。付款、扣款和退款会发送到您的 Helcim 测试账户，客户会看到测试模式提示。订单的扣款和退款始终使用支付该订单时所用模式的令牌。默认：off。
Test API token：您 Helcim 测试（开发者）账户的 API 令牌。在测试模式开启时使用。
已保存的令牌不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有需要更改时才输入新值。
Clear saved tokens：勾选某个令牌并点击 Save 即可将其删除。字段留空则保留已保存的值。
支付
Transaction type：银行卡的扣款方式。
Account currencies：您的 Helcim 账户可处理的币种。订单始终以购物车币种扣款。对于其他币种，该支付方式会在结账时被隐藏。
高级
Debug log：将 API 请求和响应写入模块文件夹中的 logs/wc_hlg_debug.log.php。该文件无法通过 Web 访问。卡号会被缩减为末 4 位。CVC、有效期、令牌、姓名、地址、电子邮件和 IP 地址从不被记录。错误（被拒绝或失败的付款、API 错误、失败的扣款和退款）即使在此选项关闭时也始终会被记录。默认：off。
Log：显示日志的大小及最新条目。点击 Clear log 可清空日志。
Delete data on uninstall：开启时，卸载模块会删除网关设置及其日志文件。Helcim 交易、退款和订单状态始终保留，因此之前已付款的订单在重新安装后仍可扣款和退款。默认：off。
结账
在付款步骤中，顾客选择支付方式（默认为带有银行卡图标的 Credit card (Helcim)），并在其下方的表单中输入 Card Number、Expiry (MM/YY)、CVC 和 Cardholder Name。在测试模式下，表单会显示 TEST MODE — payments go to a Helcim test account, no real charges are made. 顾客下单时，模块会检查卡号校验和、有效期是否有效且未过期、CVC 是否为 3 或 4 位数字以及姓名是否已填写。错误会显示在结账页面上，且不会向 Helcim 发送任何内容。
随后，您的服务器会以购物车币种，按购物车总额将银行卡作为购买或预授权发送到 Helcim。账单地址、电话和电子邮件会被发送用于地址验证。该付款在 Helcim 中会显示为一个发票号，由购物车编号、-PS 和一个简短代码组成。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 令牌缺失或被 Helcim 拒绝时显示 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.；付款已获批准但订单无法自动完成时显示 Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again.。购物车会被保留。技术细节会写入日志。
本模块不使用 HelcimPay.js 或 Helcim.js，因此银行卡信息会经过您的服务器。模块不支持保存银行卡、订阅、ACH 或银行付款、Apple Pay、Google Pay 或 3-D Secure，也不支持 Helcim Webhook。
订单与退款
订单状态
No order：银行卡被拒绝、Helcim 未响应，或顾客尚未付款。此时仅存在购物车。拒绝和错误会写入日志。
Payment accepted：购买已获批准，或预授权已扣款。付款会以 Helcim 交易 ID 记录，备注中会显示交易 ID、批准代码、银行卡类型、末 4 位数字和模式。
Helcim payment authorized：预授权已获批准。资金仅被冻结。可对其进行扣款或通过全额退款释放。
Helcim payment on hold：Helcim 批准了交易，但其响应中的金额、币种或交易 ID 与购物车不符，例如部分批准之后，或付款期间购物车发生了变化。备注会显示 Helcim response verification FAILED。对于购买，付款会以 Helcim 实际扣款的金额记录。在履行订单之前，请先在 Helcim 中核对该交易。
Refunded：付款已通过模块全额退款。
Canceled：未扣款的预授权已被释放。顾客未被扣款。
如果为已有订单的购物车批准了第二笔交易，订单不会改变。备注会提醒您在 Helcim 中核对并撤销或退款。
Helcim 付款区块
订单页面会显示一个 Helcim payment 区块，其中包括交易 ID（扣款后还包括预授权 ID）、交易类型和扣款状态、发票号、银行卡和批准代码、批准金额、订单总额和已退款金额、测试付款的 Test mode 标记、退款记录以及订单的 Helcim notes。扣款和退款需要具有编辑订单的权限。
扣款
对于状态为 Helcim payment authorized 的订单，请点击区块中的 Capture payment，并确认 Capture the pre-authorized amount through Helcim? 系统将扣除退款后的当前订单总额。该金额可能低于预授权金额，但不能高于。扣款使用支付该订单时所用模式的令牌。扣款成功后，订单变为付款已接受，付款会以扣款交易 ID 记录。如果扣款失败，区块会显示原因并将其添加到备注中。
退款
在区块中输入金额（会自动填入尚未退款的金额），可选填写原因，然后点击 Refund via Helcim。确认 Refund this amount through Helcim? This cannot be undone. 支持对购买或已扣款的预授权进行全额和部分退款，退款金额不超过 Helcim 实际扣款的金额；因此在部分批准之后，您退款的金额不能超过顾客已付的金额。对于未扣款的预授权，按钮为 Release pre-authorization：只能全额释放，冻结会被解除，订单变为已取消。
退款会在支付该订单时所用的模式下发送，因此该模式的令牌必须已设置。只有 Helcim 批准后退款才会生效。如果 Helcim 拒绝退款，区块会显示错误，且不会记录任何退款。成功的退款会以 Helcim 退款交易 ID 添加到退款记录和备注中。全额退款会将订单设为 Refunded。部分退款不会更改状态。超时后的重试不会重复退款。
本模块不会生成信用单。订单页面上 PrestaShop 的标准退款按钮不会通过 Helcim 退回款项。模块不接收 Helcim Webhook：在 Helcim 控制面板中执行的扣款、退款和撤销不会同步到 PrestaShop，因此请通过订单页面进行这些操作。
许可证密钥
本模块需要 vibefox.net 提供的 VibeFox 许可证密钥。模块 Configure 页面上方的许可证区块 License — VibeFox Helcim Gateway 是 Modules > Module Manager > VibeFox Helcim Gateway > Configure 页面中位于设置上方的第一个区块。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会显示被遮挡的密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now 用于重新检查状态，Change key 用于输入其他密钥，Remove key 用于从本店铺移除密钥。它们下方是 Product: presta-payment-helcim 一行和 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 账户中释放该名额。
没有有效的密钥时，结账页面不会向顾客显示 Helcim。如果仍然发起付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法得知您已登录后台，因此该支付方式对您也会隐藏：您可以在购买密钥前设置模块，但无法在结账时测试它。Modules > Module Manager 中的 Alerts 选项卡会显示提醒。现有订单不受影响：已完成的付款会保留，扣款和退款仍然可用。
许可证到期后，模块仍会继续运行，但更新和支持需要续费。在后台工作时会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时不显示 Helcim：请检查许可证是否有效、Enable / Disable 是否已开启、当前模式是否已设置 API 令牌（Live API token，或测试模式下的 Test API token），以及购物车币种是否属于 Account currencies。当令牌缺失或店铺币种不被允许时，设置页面会显示警告。在 Payment > Preferences 中，请检查该模块是否允许用于购物车币种、顾客所在国家以及顾客所属的客户组。
顾客看到了「We could not confirm your payment」：Helcim 没有响应，因此银行卡可能已被扣款。请查看 Log 字段：该错误会注明购物车和 Helcim 发票。在再次向顾客扣款之前，请先在 Helcim 中核对该发票。5 分钟内的重试会返回原始结果，且不会重复扣款。
顾客看到了「This payment method is temporarily unavailable」：当前模式的 API 令牌为空，或已被 Helcim 拒绝。日志会提示您检查令牌及其权限。请确保 API 访问具有交易处理权限。
付款因 Helcim 原因失败：Helcim 拒绝了请求，例如因银行卡或账单信息有问题。详细信息见日志。
顾客看到了「Your payment was received, but the order could not be completed」：Helcim 已批准付款，但 PrestaShop 无法创建订单（例如模块已被禁用）。日志会给出原因。当顾客再次提交同一购物车时，将根据已批准的付款创建订单，而不会二次扣款。
订单处于 Helcim payment on hold：请阅读 Helcim 区块中的备注。Helcim 的响应与购物车不符（响应验证失败）。请在 Helcim 中核对该交易，然后履行订单或退还付款。
无法扣款：扣款金额必须大于 0 且不得超过预授权金额，并且必须设置支付该订单时所用模式的令牌。
退款失败：请阅读消息内容。未扣款的预授权只能全额释放。与模式相关的消息表示支付该订单时所用模式的令牌为空。被拒绝的退款不会被记录。
测试付款：测试模式会将付款、扣款和退款发送到您的 Helcim 测试账户。订单会保留其付款时所用的模式，因此之后切换模式不会将其扣款和退款转移到另一个账户。
卸载
进入 Modules > Module Manager，打开 VibeFox Helcim Gateway 旁边的菜单，然后选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。如果 Delete data on uninstall 已开启，网关设置和日志会被删除。如果已关闭，所有设置都会保留，以便日后重新安装。Helcim 交易和退款以及订单状态 Helcim payment authorized 和 Helcim payment on hold 始终会保留，因此之前已付款的订单在重新安装后仍可扣款和退款。现有订单会保留其付款备注和交易 ID。
Helcim 是其各自所有者的商标。本模块与 Helcim 无关联，也未获得 Helcim 认可。