VibeFox Helcim for OpenCart — 帮助
系统要求
OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
PHP：8.0 或更高版本。
HTTPS 与 PCI DSS：银行卡信息在您的结账页面输入，并从您的服务器发送至 Helcim。这些信息绝不会被存储或记录，但会经过您的服务器，因此您的店铺需要为结账页面配置 SSL 证书，且您的主机必须符合 PCI DSS（SAQ D）要求。
货币：Helcim 处理 CAD 和 USD。只有当结账货币是扩展中设置的某个 Account currencies 时，才会显示该付款方式。
Helcim 账户：位于加拿大或美国的 Helcim 商户账户，以及具有交易处理权限的 API 令牌（参见 Configuration）。Helcim 测试（developer）账户可选，用于测试。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
下载文件为一个 zip 压缩包，内含两个 OpenCart 版本的安装包。请在您的计算机上解压。压缩包中包括 README.txt、OpenCart 3 安装包 wcp_helcim_gateway-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 wcp_helcim_gateway.ocmod.zip。只安装与您的 OpenCart 版本对应的安装包。许可证密钥在两个版本中相同。
OpenCart 3
1. 在后台依次进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_helcim_gateway-oc3-(version).ocmod.zip。该扩展没有 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装器，而是将本安装包中 upload 文件夹的内容复制到商店的根目录。
2. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox Helcim Gateway，点击 Install（绿色的 + 按钮）。您的后台用户需要具有修改支付扩展列表的权限。
3. 点击 Edit（铅笔按钮）打开设置页面。将您的 VibeFox 许可证密钥粘贴到页面顶部许可证区块中的 License key 中，然后点击 Activate（参见 License key）。
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，并使用您的测试账户付款；测试完成后再关闭。
OpenCart 4
1. 在后台依次进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_helcim_gateway.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名中获取扩展代码，重命名后的安装包将无法使用。
2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色的 + 按钮）。
3. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox Helcim Gateway，点击 Install（绿色的 + 按钮），然后点击 Edit（铅笔按钮）。
4. 按照 OpenCart 3 步骤 3 至 6 的方式填写许可证密钥、API 令牌和付款设置。两个版本的设置页面及其字段相同。
全新安装时，付款方式默认关闭，测试模式也默认关闭。
配置
所有设置都在扩展页面中：Extensions > Extensions > Payments > VibeFox Helcim Gateway > Edit。各部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，如果商店的默认货币不在 Account currencies 中，页面会发出提示（此时 Helcim 仅会对允许货币的订单提供）；在付款方式启用期间，如果当前模式的 API 令牌为空，页面也会提示（此时付款方式会在结账时隐藏）。如果您没有修改扩展的权限，页面可以显示设置，但无法保存。
保存时，Title 不能为空（最多 128 个字符），Sort Order 必须是整数，Total 必须是大于或等于 0 的数字，并且每个订单状态都必须存在。如果有任何设置有误，则不会保存任何内容，页面会列出错误。
Helcim
Enable / Disable：Enable Helcim Gateway 用于开启或关闭付款方式。默认：关闭。
Title：结账时显示的付款方式标题。它也是订单中保存的付款方式名称。默认：Credit card (Helcim)。必填。
Description：客户在 Confirm Order 步骤中、银行卡表单上方看到的文字。默认：Pay securely with your credit card.
Sort Order：付款方式在结账时的排列位置。留空或输入一个整数。
Geo Zone：仅对所选地理区域内的付款地址显示银行卡表单。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。
Total：订单需要达到的结账金额（以商店默认货币计）才会提供该付款方式。留空则对任何金额都提供。
API 凭据
在 Helcim 中进入 All Tools > Integrations > API Access Configuration，创建 API 访问并复制其令牌。为其授予购买、预授权、扣款和退款的交易处理权限。Helcim 测试账户与正式账户使用相同的 API 地址，因此测试模式只需使用您 Helcim 测试账户的令牌。该部分包含指向 Helcim API 文档的链接。
Live API token：您正式 Helcim 账户的 API 令牌。在测试模式关闭时使用。
Test mode：使用 Test API token（Helcim 测试账户）。付款、扣款和退款都会发送至您的 Helcim 测试账户，客户会看到测试模式提示。订单的扣款和退款始终使用该订单付款时所用模式的令牌。默认：关闭。
Test API token：您 Helcim 测试（developer）账户的 API 令牌。在测试模式开启时使用。
已保存的令牌不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。要删除已保存的令牌，请勾选字段下方的 Clear the saved token on save，然后点击 Save。
付款
Transaction type：银行卡的扣款方式。
Account currencies：您的 Helcim 账户可以处理的货币。订单始终以订单货币扣款。对于其他货币，结账时会隐藏该付款方式。
订单
订单在 Confirm Order 步骤中创建时没有状态（缺失订单），只有在 Helcim 批准银行卡后才会获得状态。每个字段都列出您的 OpenCart 订单状态。
Order Status After Payment：银行卡已扣款（购买，或预授权的扣款）。默认：处理中。
Authorized Status：预授权：资金仅被冻结，尚未扣款。在订单标签页中通过 Capture payment 扣款。默认：待处理，因为 OpenCart 没有 On hold 状态。
On Hold (Review) Status：Helcim 的响应与订单不符（部分批准、货币不同、没有交易 ID，或订单总额与扣款金额不同）。在处理订单前，请先在 Helcim 中核实该交易；备注中会说明原因。默认：待处理。您可以在 System > Localisation > Order Statuses 中创建自己的状态，以区分已授权订单和待审核订单。
Canceled Status：未扣款的预授权已在订单标签页中释放（客户未被扣款）。默认：已取消。
Refunded Status：在订单标签页中将付款全额退款后设置。默认：已退款。
高级
Debug log：将 API 请求和响应写入 OpenCart 日志文件夹（storage/logs）中的 wc_hlg_debug.log.php。该文件无法通过网页打开。银行卡号仅保留后 4 位。CVC、有效期、令牌、姓名、地址、电子邮件和 IP 地址绝不会被记录。错误（被拒绝或失败的付款、API 错误、失败的扣款和退款）即使在此选项关闭时也始终会被记录。默认：关闭。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Delete data on uninstall：开启时，卸载扩展会删除网关设置及其日志文件。Helcim 的交易和退款记录始终保留，因此之前已付款的订单在重新安装后仍可扣款和退款。默认：关闭。
导入 / 导出
Export：Download JSON 将设置保存为 JSON 文件。API 令牌不会被导出。
Import：粘贴之前导出的 JSON，然后点击 Import 恢复设置。已保存的 API 令牌会被保留。
结账
在 Payment Method 步骤中，客户选择付款方式（默认为 Credit card (Helcim)）。在 Confirm Order 步骤中，客户会看到一个银行卡图标、您的描述，以及包含 Card Number、Expiry (MM/YY)、CVC 和 Cardholder Name 的表单。在测试模式下，表单会显示 TEST MODE — payments go to a Helcim test account, no real charges are made. OpenCart 在此步骤创建订单，此时仍没有状态。客户点击 Confirm Order 后，扩展会检查银行卡号的校验和、有效期是否有效且未过期、CVC 是否为 3 或 4 位数字，以及姓名是否已填写。错误会显示在表单上方，且不会向 Helcim 发送任何内容。
在 OpenCart 4 中，客户通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式。此时银行卡表单会出现在结账页面底部的订单确认区块中，位于 Confirm Order 按钮上方。OpenCart 4 默认不要求付款地址；此时扩展会将配送地址与持卡人姓名一起发送至 Helcim 进行地址验证。
随后，您的服务器会以订单货币的订单总额，将银行卡作为购买或预授权发送给 Helcim。持卡人姓名、付款地址、电话和电子邮件会被发送，用于地址验证。该付款在 Helcim 中显示为由订单号、-OC 和一个短代码组成的发票号。Helcim 在同一请求中返回响应。只有在 Helcim 批准交易后，订单才会获得状态，其方式与 OpenCart 的标准流程相同，并发送常规订单邮件、更新库存。购物车会立即清空，客户随后进入 OpenCart 的订单成功页面。
每个购物车同一时间只会运行一次付款尝试；已付款的购物车即使在此期间 OpenCart 为其创建了新订单（OpenCart 3 中每次显示 Confirm Order 步骤时都会创建新订单；OpenCart 4 中，更早的订单或第二个浏览器标签页仍可能持有同一购物车），也绝不会再次扣款。OpenCart 4 为结账保留一个订单并更新它，因此银行卡被拒后，客户支付的是同一订单。如果该订单在此期间已关闭（例如您取消了它），或已付款且购物车现在包含新的购买，Confirm Order 会将客户带回结账页面，并在上方显示 Your previous order is already closed (cancelled or refunded by the store) or paid for another cart. Please confirm the order again: the cart will be paid with a new order.；下一次 Confirm Order 会为该购物车支付新订单。包括数量变化在内的任何购物车变更，都视为需要单独付款的新购物车。每次尝试都会使用幂等密钥。如果 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.；付款已收到但无法自动完成订单时显示 Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again.。客户会停留在 Confirm Order 步骤，购物车保持不变。技术详情会写入日志。
该扩展不使用 HelcimPay.js 或 Helcim.js，因此银行卡信息会经过您的服务器。它不支持保存银行卡、订阅、ACH 或银行付款、Apple Pay、Google Pay 或 3-D Secure，也没有 Helcim Webhook。
订单与退款
订单状态
无状态（缺失订单）：银行卡被拒绝、Helcim 没有响应，或客户尚未付款。拒绝和错误会写入日志，并作为备注添加。在 Sales > Orders 中，此类订单只有在 Order Status 筛选器设为 Missing Orders 时才会显示。
Order Status After Payment（默认 Processing）：购买已获批准，或预授权已扣款。备注会显示交易 ID、授权码、卡类型、后 4 位数字和模式。
Authorized Status（默认 Pending）：预授权已获批准。资金仅被冻结。可以扣款，或通过全额退款释放。
On Hold (Review) Status（默认 Pending）：Helcim 已批准交易，但其响应中的金额、货币或交易 ID 与订单不符，例如部分批准之后，或付款期间订单总额发生了变化。备注内容为 Helcim response verification FAILED。在处理订单前，请先在 Helcim 中核实该交易。
Refunded Status（默认 Refunded）：付款已通过扩展全额退款。
Canceled Status（默认 Canceled）：未扣款的预授权已被释放。客户未被扣款。
备注是订单 History 中的记录，客户看不到。
VibeFox Helcim Gateway 标签页
在 Sales > Orders 中打开一个使用 Helcim 付款的订单。在订单页面底部，紧邻 History 和 Additional 的位置，VibeFox Helcim Gateway 标签页会显示 Transaction ID（扣款后还会显示预授权 ID），测试付款会带有 Test mode 标签；同时显示 Transaction type 和扣款状态、Invoice、Card 和授权码、Approved / order / refunded 金额、扣款按钮和退款表单、退款历史，以及订单的 Helcim notes。该标签页对有权访问扩展的用户显示；扣款和退款需要修改权限（在 System > Users > User Groups 中设置）。
扣款
对于未扣款的预授权，请在标签页中点击 Capture payment（按钮上会显示金额），并确认 Capture the pre-authorized amount through Helcim? 系统将扣除退款后的当前订单总额。该金额可能低于授权金额，但不能高于授权金额。扣款使用订单付款时所用模式的令牌。扣款成功后，订单会获得 Order Status After Payment。如果扣款失败，标签页会显示原因并将其添加到备注中。
退款
在标签页中输入 Amount（系统会自动填入尚未退款的金额），可选填写 Reason (optional)，然后点击 Refund via Helcim。确认 Refund this amount through Helcim? This cannot be undone. 支持对购买或已扣款的预授权进行全额和部分退款，但不能超过 Helcim 实际扣款的金额；因此，在部分批准后，您退款的金额不能超过客户的付款金额。对于未扣款的预授权，按钮为 Release pre-authorization：只能全额释放，冻结会被取消，订单将获得 Canceled Status。
退款会在订单付款时所用的模式下发送，因此该模式的令牌必须已设置。只有 Helcim 批准后退款才会生效。如果 Helcim 拒绝退款，标签页会显示错误，且不会记录任何退款。成功的退款会连同 Helcim 退款交易 ID 一起添加到退款历史和备注中。全额退款会将订单设为 Refunded Status，且不会通知客户，也不会将商品退回库存，与手动更改状态相同。部分退款不会更改状态。超时后的重试不会重复退款。
Sales > Returns 中的商品退货不会通过 Helcim 退还款项。该扩展不接收 Helcim Webhook：在 Helcim 后台进行的扣款、退款和作废操作不会同步到 OpenCart，因此请在订单页面进行这些操作。
许可证密钥
该扩展需要使用从 vibefox.net 获取的 VibeFox 许可证密钥。许可证区块 License — VibeFox Helcim Gateway 是 Extensions > Extensions > Payments > VibeFox Helcim Gateway > Edit 页面中的第一个区块，位于设置上方。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会显示已遮蔽的密钥、状态（例如许可证的有效截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本商店移除该密钥）。其下方是 Product: opencart-payment-helcim 一行，以及打开您 vibefox.net 账户的链接 Manage licenses and domains in your account。只有对该扩展拥有 Modify 权限的管理员用户才能更改密钥。该区块的文字会跟随后台语言显示（包括英文和俄文）。
如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或带日期的 License expired on。更改商店地址后，或在您的账户中释放一个域名名额后，请点击 Check now。如果无法连接许可证服务器，扩展会继续使用最后一次已知的状态运行。
一个密钥只能用于一个域名：即 OpenCart 配置中的商店地址。将密钥从商店中移除并不会释放域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效密钥时，结账时不会向客户显示 Helcim。如果仍然发起了付款，客户会看到 This payment method is not available. Please choose another one. 在同一浏览器中登录后台的管理员用户仍会在商店中看到该付款方式，并标有 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置和测试扩展。在 OpenCart 4 中，此预览不可用：商店看不到管理员登录状态，因此没有有效密钥时，付款方式对所有人都会隐藏。打开一次 Edit 页面后，后台的 Dashboard 会出现一条提醒。点击 × 可将其关闭，关闭后 7 天内不再显示。现有订单不受影响：已完成的付款会保留，扣款和退款仍可正常进行。
许可证过期后，扩展仍可继续工作，但更新和支持需要续期。当您打开后台的 Dashboard 或 Edit 页面时，系统会自动重新检查状态：输入密钥后的前 14 天每天检查一次，之后每周检查一次。无需设置 cron 任务。卸载扩展时，许可证密钥和许可证状态总会被删除。
故障排除
Helcim 没有出现在结账页面：请检查许可证是否有效，Enable / Disable 是否已开启，当前模式是否已设置 API 令牌（Live API token，或测试模式下的 Test API token），以及结账货币是否属于 Account currencies。如果缺少令牌或商店货币不被允许，设置页面会显示警告。另请检查付款地址是否位于所选的 Geo Zone 中，以及订单是否达到设置中的 Total。
客户看到了 We could not confirm your payment：Helcim 没有响应，因此银行卡可能已被扣款。订单备注和日志会注明 Helcim 发票。在再次向客户扣款之前，请先在 Helcim 中核实该发票。5 分钟内的重试会返回原始结果，且不会重复扣款。
客户看到 This payment method is temporarily unavailable：Helcim 拒绝了 API 令牌。订单备注会提示检查令牌及其权限。请确保该 API 访问具有交易处理权限。
客户看到 This payment method is not available. Please reload the checkout page.：结账会话已不再与订单匹配，付款方式可能在此期间被关闭，或者令牌或货币已不再适用。客户需要重新加载结账页面。
付款因 Helcim 原因失败：Helcim 拒绝了请求，例如因银行卡或账单信息有误。订单备注和日志中有详细信息。
客户看到 Your payment was received, but the order could not be completed：Helcim 已批准付款，但 OpenCart 无法设置订单状态。原因可在日志中查看。客户再次提交同一购物车时，将根据已批准的付款设置状态，而不会再次扣款。
订单处于审核状态：请阅读 VibeFox Helcim Gateway 标签页中的备注。Helcim 的响应与订单不符（响应验证失败）。请在 Helcim 中核实该交易，然后处理订单或退款。
无法扣款：扣款金额必须大于 0 且不得超过授权金额，并且必须已设置订单付款时所用模式的令牌。
退款失败：请阅读提示信息。未扣款的预授权只能全额释放。提到模式的提示表示订单付款时所用模式的令牌为空。被拒绝的退款不会被记录。You do not have permission to capture or refund (modify this extension). 表示您的用户组没有修改该扩展的权限。
测试付款：测试模式会将付款、扣款和退款发送至您的 Helcim 测试账户。订单会保留其付款时的模式，因此之后切换模式不会将其扣款和退款转移到另一个账户。
卸载
进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Helcim Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态总会被删除。OpenCart 总会删除扩展自身的设置：Enable / Disable、Sort Order、Geo Zone、Total，以及 Orders 部分中的订单状态，这些设置在重新安装后会恢复为默认值。在 OpenCart 4 中，在结账页面上方显示消息的扩展 OpenCart 事件也会被删除。如果开启了 Delete data on uninstall，其余网关设置（标题、描述、API 令牌、测试模式、交易类型、账户货币、调试日志开关）和日志都会被删除；如果关闭，则会保留，以便日后重新安装时使用。Helcim 的交易和退款记录始终保留，因此之前已付款的订单在重新安装后仍可扣款和退款。现有订单会保留其付款备注。
在 OpenCart 4 中，如需同时删除扩展文件，请在卸载后进入 Extensions > Installer，点击已安装扩展列表中 VibeFox Helcim Gateway 旁的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。
Helcim 是其各自所有者的商标。本扩展与 Helcim 无关联，也未获得 Helcim 的认可。