VibeFox Cardcom for OpenCart — 帮助

要求

OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。

PHP：8.0 或更高版本。

HTTPS：您的商店必须可通过 HTTPS 从互联网访问，以便 Cardcom 发送付款通知。

货币：订单货币（顾客购物所用的货币）必须是 ILS、USD、EUR 或 GBP。对于其他任何货币，结账时将隐藏该付款方式。

Cardcom 账户：进行实时付款需要一个 Cardcom 商户账户，其中包含终端号、API 用户名和 API 密码。付款只需要终端号和 API 用户名。API 密码仅用于从 OpenCart 发起的退款。测试模式无需 Cardcom 账户即可使用。

VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。

安装

下载文件是一个 zip 压缩包，内含两个 OpenCart 版本的安装包。请先将其解压到您的电脑上。压缩包中包括 README.txt、OpenCart 3 安装包 wcp_cardcom_payment_gateway-oc3-(version).ocmod.zip，以及 OpenCart 4 安装包 wcp_cardcom_payment_gateway.ocmod.zip。请只安装与您的 OpenCart 版本对应的安装包。两个版本使用相同的许可证密钥。

OpenCart 3

1. 在管理后台中进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_cardcom_payment_gateway-oc3-(version).ocmod.zip。该扩展没有 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装器，而是将本安装包中 upload 文件夹的内容复制到商店的根目录中。

2. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox Cardcom Payment Gateway，然后点击 Install（绿色的 + 按钮）。您的管理员用户需要有修改付款扩展列表的权限。

3. 点击 Edit（铅笔按钮）打开设置页面。将您的 VibeFox 许可证密钥粘贴到页面顶部许可证区块中的 License key 里，然后点击 Activate（参见许可证密钥）。

4. 开启 Enable/Disable，保持 Test Mode 开启，然后点击 Save。使用卡号 4580 0000 0000 0000、任意未来的有效期和 CVV 123 下一个测试订单。

5. 进行实际付款时，请关闭 Test Mode，填写您从 Cardcom 获得的 Terminal Number、API Username 和 API Password，然后点击 Save。无需在 Cardcom 后台进行任何设置：每次付款时都会发送通知地址和返回地址。

OpenCart 4

1. 在管理后台中进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_cardcom_payment_gateway.ocmod.zip。请勿重命名该文件：OpenCart 4 会从文件名获取扩展代码，重命名后的安装包将无法使用。

2. 安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。

3. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox Cardcom Payment Gateway，点击 Install（绿色的 + 按钮），然后点击 Edit（铅笔按钮）。

4. 按照 OpenCart 3 的第 3 至 5 步输入许可证密钥、测试付款并输入实时凭据。设置页面及其字段在两个版本中相同。只有通知 URL 不同（参见 Notification URL）。

新安装的扩展默认关闭付款方式，并开启测试模式。

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox Cardcom Payment Gateway > Edit。各个部分列在左侧；列表下方的 Save 按钮会保存整个页面。在测试模式开启时，设置上方的页面会显示警告。在实时模式下，如果缺少终端号或 API 用户名，页面会发出警告（此时 Cardcom 在结账时被隐藏）；如果实时字段中填写的是公共测试终端 1000 / CardTest1994，页面也会发出警告（此时同样会隐藏 Cardcom，因为不会收取真实款项），并提醒没有 API 密码则无法从 OpenCart 退款。如果商店的默认货币不受支持，页面也会发出警告。如果没有修改扩展的权限，页面可以显示设置，但无法保存。

保存时，Title 不能为空（最多 128 个字符），Sort Order 必须是整数，Total 必须是 0 或更大的数字，并且地区区域和订单状态必须存在；否则不会保存任何内容。如果在实时模式下保存时凭据缺失或为测试凭据，设置会以警告的形式保存，提示在您输入自己的终端号和 API 用户名之前，该网关在结账时将保持隐藏。

Cardcom

Enable/Disable：Enable Cardcom Payment Gateway 用于开启或关闭该付款方式。默认：关闭。

Title：顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认：Credit Card (Cardcom)。必填。

Description：顾客在 Confirm Order 步骤中、确认按钮上方看到的文字。默认：Pay securely with your credit card via Cardcom.

Sort Order：Cardcom 在结账时的付款方式中的位置。留空或输入整数。

Geo Zone：仅向所选地理区域内的付款地址提供 Cardcom。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。

Total：订单必须达到的、以商店默认货币计算的结账金额，达到后才会提供 Cardcom。留空则对任何金额都提供 Cardcom。

测试模式

测试模式使用公共的 Cardcom 测试终端 1000（API 用户 CardTest1994）。不会收取真实款项，也不需要 Cardcom 账户。测试卡：4580 0000 0000 0000，任意未来的有效期和 CVV 123。在测试模式下，Confirm Order 步骤还会显示一行包含该测试卡的提示。

Test Mode：启用测试模式（终端 1000，不产生真实款项）。默认：开启。关闭它即可使用下面的实时凭据接受真实付款。退款始终使用订单付款时所处模式的凭据发送。

实时凭据

终端号、API 用户名和 API 密码由 Cardcom 随您的商户账户一起提供：可在 Cardcom 后台的 API 设置中查看，也可向 Cardcom 支持团队索取。这些字段仅在实时模式下使用。

Terminal Number：您的 Cardcom 终端号。只能包含数字。如果输入其他内容，其他设置会附带警告保存，并保留之前的终端号。

API Username：该终端对应的 Cardcom API 用户名（ApiName）。保存时会删除空格。

API Password：您的 Cardcom API 密码。仅用于从 OpenCart 发起的退款。已保存的密码将不会再次显示：该字段保持为空，并显示 已保存 — 留空即可保留。 只有在需要更改时才输入新值。要删除已保存的密码，请勾选字段下方的 Clear the saved API password，然后点击 Save。

付款页面

Notification URL：Cardcom 会将付款通知（IndicatorUrl）发送到此地址。OpenCart 3 的格式类似 https://your-store/index.php?route=extension/payment/wcp_cardcom_payment_gateway/webhook，OpenCart 4 的格式类似 https://your-store/index.php?route=extension/wcp_cardcom_payment_gateway/payment/wcp_cardcom_payment_gateway.webhook，由您的 OpenCart 安装的前台商店地址生成。每次付款时，该地址都会与订单号一起自动传递给 Cardcom，因此无需在 Cardcom 中进行任何设置。它必须能够通过 HTTPS 从互联网访问。

Operation：Cardcom 在付款页面上执行的操作。

Max Installments：顾客在 Cardcom 页面上可以选择的最大分期数（付款次数），范围为 1 至 36。1 表示不分期。默认：1。

订单

OpenCart 在 Confirm Order 步骤中创建的订单没有状态（缺失订单）。只有在 Cardcom 确认付款之后，订单才会获得状态。下面的每个字段都列出了您的 OpenCart 订单状态。

Success Order Status：付款确认后设置的状态。默认：处理中。

On Hold (Review) Status：与订单不匹配的付款（金额、货币、没有交易号）会获得此状态，并附带说明原因的备注。默认：待处理，因为 OpenCart 没有搁置状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择它。

Refunded Status：在订单页面中全额退款付款后设置。默认：已退款。

高级

Debug log：将 API 请求和通知记录到 OpenCart 日志文件夹（storage/logs）中的 cardcom_p_debug.log.php。该文件无法通过网页打开，达到 5 MB 时会进行轮转。错误始终会被记录。凭据、卡令牌和持卡人信息绝不会写入。默认：关闭。

Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。

Delete on Uninstall：开启后，卸载扩展会永久删除设置和日志。订单以及 Cardcom 交易和退款始终保留，因此即使重新安装后，旧订单仍可退款。默认：关闭。

导入 / 导出

Export：Download JSON 会将设置保存为 JSON 文件。API 密码不会被导出。

Import：粘贴之前导出的 JSON，然后点击 Import 以恢复设置。已保存的 API 密码将被保留。

结账

在 Payment Method 步骤中，顾客选择付款方式（默认为 Credit Card (Cardcom)）。在 Confirm Order 步骤中，顾客会看到您的描述以及提示 您将被重定向到安全的 Cardcom 付款页面。 OpenCart 会在此步骤创建订单，但仍没有状态。当顾客点击 Confirm Order 时，扩展会以订单货币为订单总额创建一个 Cardcom 付款页面，并将顾客转到该页面。如果订单语言为希伯来语，页面将以希伯来语打开，否则以英语打开。订单中的商品会以商品名称的形式传递给 Cardcom。顾客输入银行卡信息，如果允许分期，则选择付款次数。在 OpenCart 4 中，顾客通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式，然后点击结账页面底部的 Confirm Order。

付款完成后，顾客会返回您的商店。只有在 Cardcom 确认付款之后，订单才会被标记为已付款。Cardcom 会调用通知地址，扩展只从该调用中获取付款页面代码。扩展会检查该代码是否由您的商店为该订单签发，然后以服务器对服务器的方式向 Cardcom 查询真实结果。如果通知延迟，顾客返回时会执行同样的检查。随后，订单会以 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存，顾客会看到 OpenCart 的订单成功页面，并显示 您通过 Cardcom 的付款已收到。 如果顾客返回时 Cardcom 尚未确认付款，Payment confirmation 页面会显示 您的付款正在由 Cardcom 确认。确认后，我们会向您发送电子邮件。，并带有 Check again 和 Back to checkout 按钮；通知一到达就会设置订单状态。在 OpenCart 4 中，顾客返回时 Cardcom 不会发送商店会话，因此扩展会先显示一个简短页面，从您的商店重新打开同一个返回地址：顾客会保留购物车和登录状态。

如果付款未完成或 Cardcom 拒绝付款，顾客会回到结账页面，并显示 银行卡付款未完成。请重试或选择其他付款方式。 在 OpenCart 4 中，此消息显示在结账页面上方。订单保持无状态，购物车会保留。顾客可以重试：OpenCart 3 每次显示 Confirm Order 步骤时都会创建新订单，OpenCart 4 则为结账保留一个订单并对其进行更新，每次尝试都会获得新的 Cardcom 付款页面。在创建新页面之前，系统会向 Cardcom 检查此订单以及同一购物车（相同的顾客会话和购物车内容）的其他订单在过去 24 小时内打开的 Cardcom 付款页面。如果其中某个页面已付款，该订单会被确认，顾客会进入成功页面，而不必再次付款。已由其他订单付款的购物车不会再次扣款：顾客会进入成功页面。旧页面上的拒绝不会影响较新的尝试。

如果结账订单在此期间未付款即被关闭（例如您取消了它），Confirm Order 或从 Cardcom 返回都会把顾客带回结账页面，并显示 This order can no longer be paid. Please confirm your order again.，然后下一次 Confirm Order 会为购物车支付一个新订单。OpenCart 4 会在显示成功页面之前将订单保留在结账中：如果该订单已经有状态，并且购物车此后发生了变化（其他商品或数量），顾客会收到同样的消息，变化后的购物车会获得新订单及其自己的付款，而相同的购物车则会直接进入成功页面，无需重新付款。

如果 Cardcom 无法打开付款页面，顾客会停留在 Confirm Order 步骤，并在按钮上方看到简短提示，例如 无法连接到 Cardcom。请稍后再试。，或者 Cardcom 无法打开付款页面（并附带 Cardcom 代码）的提示，顾客可以选择其他付款方式。

即使商店处于维护模式，通知仍然有效：OpenCart 3 允许付款扩展的请求通过，而在 OpenCart 4 中，扩展会添加一个启动操作，使通知和顾客的返回得以通过。

该扩展仅在 Cardcom 页面上接受银行卡的一次性付款。它不支持保存的银行卡或一键付款，不支持订阅，不会对已存储的令牌进行扣款，没有 Cardcom 发票或收据设置，不支持通过 Cardcom 使用 Bit、Apple Pay、Google Pay 或 PayPal，不支持 iframe 模式，也不支持稍后扣款（延迟捕获）的协议。

订单和退款

订单状态

无状态（缺失订单）：顾客已被转到 Cardcom，但尚未付款，付款被拒绝，或者 Cardcom 尚未确认付款。在 Sales > Orders 中，此类订单只有在 Order Status 筛选器设置为 Missing Orders 时才会显示。

Success Order Status（默认 处理中）：付款已确认。备注会显示 Cardcom 交易，并且在 Cardcom 提供这些信息时，还会显示银行卡末四位、发票号码和分期数，以及付款的确认方式（通知、返回或新的尝试）。测试付款会标记为 测试模式 — 未收取真实款项。

On Hold (Review) Status（默认 待处理）：Cardcom 确认了一笔与订单不匹配的付款，例如收取的金额或货币不同，或者 Cardcom 没有返回交易号。备注会说明原因，订单页签会在 Needs review: 下显示此信息。请在 Cardcom 后台将付款与订单进行核对，然后完成订单或退还付款。

Refunded Status（默认 已退款）：付款已通过该扩展全额退款。

如果一个已经有状态的订单又收到第二笔成功付款（例如顾客在两个浏览器标签页中付款了），订单不会被更改。备注会提醒顾客可能被重复扣款，并请您在 Cardcom 后台将其退款。如果同一购物车又用另一个订单付了一次款（例如在第二个标签页中），同样的备注也会添加到已付款的订单中；该另一个订单不会获得任何状态。

备注是订单 History 中的记录，顾客看不到。

VibeFox Cardcom Payment Gateway 选项卡

在 Sales > Orders 中打开一个通过 Cardcom 付款的订单。在订单页面底部，紧邻 History 和 Additional 的位置，VibeFox Cardcom Payment Gateway 选项卡会显示 Transaction（对于测试付款，会带有 Test mode 标签）、Payment page (LowProfileCode)、Status、Card、Installments、Invoice、Card token（配合 Charge + Save token）、已扣金额 Charged、Order total / refunded、退款表单、退款历史以及该订单的 Cardcom notes。该选项卡仅向有权访问此扩展的用户显示。

退款

在该选项卡中输入 Amount（会自动填入尚未退款的金额），可选填写 Reason (optional)，然后点击 Refund via Cardcom。确认提示 Refund this amount through Cardcom? This cannot be undone. 支持全额退款和部分退款，同一订单可以进行多次部分退款。您需要拥有修改该扩展的权限（在 System > Users > User Groups 中设置）。退款以 Cardcom 扣款的金额和货币进行，因此在金额或货币不一致的情况下，您可以退款至顾客实际支付的金额，而非订单总额。退款使用订单付款时所处模式的凭据发送：即使您已切换到实时模式，测试订单仍会通过 Cardcom 测试终端退款，而实时订单始终使用您的实时凭据。实时退款需要 API Username 和 API Password。如果 Cardcom 不接受退款，选项卡会显示错误，且不会记录任何退款。成功的退款会连同 Cardcom 退款交易和原因一起添加到退款历史和备注中。全额退款会将订单设置为 Refunded Status，但不会通知顾客，也不会将商品退回库存，与手动更改状态相同。部分退款不会更改状态。

Sales > Returns 中的商品退货不会通过 Cardcom 退回款项。在 Cardcom 后台进行的退款不会回传给商店。

许可证密钥

该扩展需要使用从 vibefox.net 获取的 VibeFox 许可证密钥。许可证区块 License — VibeFox Cardcom Payment Gateway 是 Extensions > Extensions > Payments > VibeFox Cardcom Payment Gateway > Edit 中的第一个区块，位于设置上方。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），并提供以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本商店移除该密钥）。其下方有 Product: opencart-payment-cardcom 一行，以及打开您 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 账户中释放名额。

没有有效密钥时，结账时不会向顾客显示 Cardcom。如果仍然启动了付款，顾客会看到 此付款方式不可用。请选择其他方式。 在同一浏览器中登录管理后台的管理员用户，仍然可以在商店中看到该付款方式，并标有 （未授权 — 仅管理员可见），因此您可以在购买密钥之前设置和测试该扩展。在 OpenCart 4 中没有此预览：商店看不到管理员登录，因此在没有有效密钥时，该付款方式对所有人都隐藏。打开过一次 Edit 页面后，管理后台的 Dashboard 上会出现提醒。点击 × 可将其隐藏 7 天。现有订单不受影响：已经开始的付款仍会被确认，退款也正常工作。

许可证过期后，扩展仍会继续工作，但更新和支持需要续订。打开管理后台的 Dashboard 或 Edit 页面时，状态会自动重新检查：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载扩展时，始终会删除许可证密钥和许可证状态。

故障排除

Cardcom 未出现在结账页面：请检查许可证是否有效、Enable/Disable 是否已开启，以及顾客的货币是否为 ILS、USD、EUR 或 GBP。在实时模式下，请检查 Terminal Number 和 API Username 是否填写的是您自己的凭据，而不是测试终端 1000 / CardTest1994。缺少内容时，设置页面会显示警告。另外请检查付款地址是否位于所选 Geo Zone 内，以及订单是否达到设置中的 Total。

付款已完成，但订单仍无状态：Cardcom 无法访问您的商店，例如因为防火墙、密码保护或本地开发站点。通知地址必须能够通过 HTTPS 从互联网访问。顾客付款后返回商店时，订单也会获得状态。请开启 Debug log，并查看扩展页面上的 Log 字段。

通知返回 Missing or invalid lowprofilecode 或 Unknown lowprofilecode for this order：该调用未包含您的商店为此订单签发的付款页面代码。不会进行任何更改。

通知返回 Gateway not configured 或 Indicator check failed：创建付款页面所用模式的凭据缺失，或者无法连接 Cardcom 进行检查。不会进行任何更改；顾客返回商店时会重新检查付款。

通知返回 Busy, retry：订单正在被另一个请求确认，或者无法设置订单状态。请开启 Debug log 查看原因。

通知返回 ReturnValue mismatch 或 Terminal mismatch：Cardcom 报告了另一个订单或另一个终端的付款。不会进行任何更改。请检查 Terminal Number 是否为您账户的终端。

浏览器中的通知 URL 显示 Missing or invalid lowprofilecode：这是正常现象。该 URL 只接受来自 Cardcom 的调用。

顾客看到「付款错误：Cardcom 不支持此货币。」：订单货币不是 ILS、USD、EUR 或 GBP。

顾客看到「银行卡付款暂时不可用。请选择其他付款方式。」：实时模式已开启，但终端号或 API 用户名缺失，或者实时字段中填写的是公共测试终端。

顾客在 Confirm Order 之后看到「此付款方式不可用。」：结账会话已与订单不匹配，或者付款方式已被关闭。顾客需重新加载结账页面。

顾客在 Confirm Order 之后看到其他错误：请开启 Debug log 并查看 Log 字段。连接问题和 Cardcom 错误代码都会记录在那里。

付款后订单处于审核状态：请阅读备注或 VibeFox Cardcom Payment Gateway 选项卡中的 Needs review:。付款金额或货币与订单不符。请完成订单或退还付款。

选项卡中没有退款表单：选项卡会说明原因：交易尚未确认，付款已全额退款，您的用户组没有修改该扩展的权限，或者该付款模式的 API 用户名和 API 密码缺失。

退款失败并显示 API username and API password are required for refunds：请在设置中输入 API Password（以及 API Username），然后重试。

退款失败并显示 Could not connect to Cardcom：在重试之前请先检查 Cardcom 后台，因为退款可能已成功也可能未成功。

对于开发人员：扩展会触发 OpenCart 事件 cardcom_p_supported_currencies（用于扩展货币列表，请仅添加 Cardcom 终端上已启用的货币）和 cardcom_p_low_profile_params（用于在创建付款页面之前修改其参数）。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Cardcom Payment Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Orders 部分中的订单状态，这些设置在重新安装时会恢复为默认值。扩展的 OpenCart 事件也会被删除（在 OpenCart 4 中还会删除其事件以及在维护模式下让 Cardcom 通过的启动操作）。如果 Delete on Uninstall 已开启，则其他网关设置（标题、描述、测试模式、凭据、付款页面选项、日志记录）和日志都会被删除。如果已关闭，它们将被保留，以便之后重新安装时使用。Cardcom 交易和退款始终会保留，因此之前付款的订单在重新安装后仍可退款。现有订单会保留其付款备注。

在 OpenCart 4 中，如果还要删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox Cardcom Payment Gateway 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）删除已上传的安装包。

Cardcom 是其各自所有者的商标。本扩展与 Cardcom 无关联，也未获得 Cardcom 的认可。