VibeFox Cardcom for PrestaShop — 帮助

系统要求

PrestaShop：8.0 至 9.x。

PHP：8.0 或更高版本。模块拒绝在较旧的 PHP 版本上安装。

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

币种：购物车币种必须为 ILS、USD、EUR 或 GBP。对于其他任何币种，结账时会隐藏该付款方式。

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

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

安装

1. 在后台依次进入 Modules > Module Manager，然后点击 Upload a module。选择模块的 ZIP 文件。

2. 上传完成后，点击 Configure；或者稍后在模块列表中找到 VibeFox Cardcom Payment Gateway，然后点击 Configure。

3. 在 Configure 页面顶部的许可证区块中，将您的 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 payment on hold。PrestaShop 会为所有币种、国家和客户群组提供一个新的付款模块。您可以在 Payment > Preferences 中加以限制。

配置

所有设置都位于模块页面：Modules > Module Manager > VibeFox Cardcom Payment Gateway > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。测试模式开启时，页面会在字段上方显示警告。在正式模式下，如果缺少终端号或 API 用户名，页面会发出警告（此时 Cardcom 在结账时会被隐藏）；如果正式模式字段中填写的是公共测试终端 1000 / CardTest1994，页面也会发出警告（同样，结账时 Cardcom 会被隐藏，因为不会扣除真实款项）；页面还会提醒，没有 API 密码就无法从 PrestaShop 退款。如果您商店的默认币种不受支持，页面也会发出警告。当您在正式模式下保存时，如果凭据缺失或为测试凭据，会显示错误消息，告知您在输入自己的终端号和 API 用户名之前，网关将在结账时保持隐藏。

Cardcom

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

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

Description：结账时显示在付款方式下方的文字。默认：Pay securely with your credit card via Cardcom.

测试模式

测试模式使用 Cardcom 公共测试终端 1000（API 用户 CardTest1994）。不会扣除真实款项，也不需要 Cardcom 账户。测试卡：4580 0000 0000 0000，任意未来的有效期，CVV 123。在测试模式下，结账页面还会显示一行提示此测试卡的信息。

Test Mode：启用测试模式（终端 1000，不扣真实款项）。默认：开启。如需使用下方的正式凭据接收真实付款，请将其关闭。退款始终使用订单付款时所在模式的凭据发送。

正式凭据

终端号、API 用户名和 API 密码由 Cardcom 随您的商户账户一同提供：可在 Cardcom 控制面板的 API 设置中查看，或向 Cardcom 客服索取。这些字段仅在正式模式下使用。

Terminal Number：您的 Cardcom 终端号。只能包含数字。如果输入其他内容，将显示错误，并保留之前的值。

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

API Password：您的 Cardcom API 密码。仅用于从 PrestaShop 发起退款。已保存的密码不会再次显示：该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。

Clear the saved API password：勾选此项并点击 Save 即可删除密码。字段留空则保留已保存的值。

付款页面

Notification URL：Cardcom 会将付款通知（IndicatorUrl）发送到此地址。启用友好 URL 时，其形式如 https://your-shop/module/wcp_cardcom_payment_gateway/webhook，可能还带有语言代码，例如 /en/。该地址会在每次付款时与购物车 ID 一起自动传递给 Cardcom，因此无需在 Cardcom 中进行任何设置。它必须可通过 HTTPS 从互联网访问。

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

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

Success Order Status：付款确认后的订单状态。订单会直接以此状态创建。

与订单不匹配的付款一律进入 Cardcom payment on hold 状态。

高级

Debug log：将 API 请求和通知记录到模块文件夹中的 logs/cardcom_p_debug.log.php。该文件无法通过网页打开。错误始终会被记录。凭据、银行卡令牌和持卡人信息绝不会被写入。默认：关闭。

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

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

结账

在付款步骤中，顾客选择付款方式（默认为 Credit Card (Cardcom)），并会看到提示 You will be redirected to the secure Cardcom payment page. 确认后，模块会按购物车币种为购物车总额创建一个 Cardcom 付款页面，并将顾客转到该页面。此时尚不存在订单。如果顾客的语言为希伯来语，页面将以希伯来语打开，否则以英语打开。购物车中的商品会以商品名称的形式传递给 Cardcom。顾客输入银行卡信息，如果允许分期，则选择付款期数。

付款后，顾客会返回您的商店。只有在 Cardcom 确认付款后，订单才会被标记为已付款。Cardcom 会调用通知地址，模块只从该调用中获取付款页面代码。它会核实该代码是您的商店为此购物车签发的，然后以服务器对服务器的方式向 Cardcom 查询真实结果。如果通知延迟到达，顾客返回时也会执行同样的核实。随后订单被创建，顾客会看到标准订单确认页面，并显示 Your payment with Cardcom has been received. 如果顾客返回时 Cardcom 尚未确认付款，Payment confirmation 页面会显示 Your payment is being confirmed by Cardcom. You will receive an e-mail as soon as it is confirmed. 以及 Check again 按钮；通知一到达，订单即会创建。

如果付款未完成或 Cardcom 拒绝付款，顾客会回到结账页面，并看到 The card payment was not completed. Please try again or choose a different payment method. 不会创建订单，购物车会被保留。顾客可以重试：每次尝试都会获得一个新的 Cardcom 付款页面。对同一购物车较早付款页面所做的付款仍会被识别，较早页面上的拒付也不会影响新的尝试。

如果 Cardcom 无法打开付款页面，顾客会停留在结账页面，并看到一条简短消息，例如 Could not connect to Cardcom. Please try again in a moment.，或者提示 Cardcom 无法打开付款页面并附上 Cardcom 代码的消息，顾客可以选择其他付款方式。

商店处于维护模式时，通知仍然有效，且不受商店国家限制的影响。

本模块仅在 Cardcom 页面接受银行卡付款。不支持保存银行卡或一键付款，不支持订阅，不会对已保存的令牌进行扣款，没有 Cardcom 发票或收据设置，不支持通过 Cardcom 使用 Bit、Apple Pay、Google Pay 或 PayPal，不支持 iframe 模式，也不支持延迟扣款交易。

订单与退款

订单状态

No order yet：顾客已被转到 Cardcom 但尚未付款，付款被拒绝，或 Cardcom 尚未确认付款。此时只存在购物车。

Payment accepted, Delivered or Cardcom payment on hold：付款已确认。状态跟随 Success Order Status。付款以 Cardcom 交易（deal）编号作为交易 ID 记录。订单中的私有消息会显示 Cardcom 交易，以及在 Cardcom 提供时显示的银行卡后四位、发票号和分期期数。测试付款会标记为 Test mode — no real money was charged.

Cardcom payment on hold after payment：Cardcom 确认了一笔与订单不匹配的付款，例如打开付款页面后购物车被修改，或者扣除的金额或币种不同。消息会对此作出说明，Cardcom 区块会将其显示在 Needs review 下。当币种与订单一致时，付款将按 Cardcom 扣除的金额记录。请在 Cardcom 控制面板中将该付款与订单进行核对，然后完成订单或退款。

Refunded：付款已通过模块全额退款。

如果针对已有订单的购物车又收到第二笔成功付款（例如顾客在两个浏览器标签页中付款），订单不会改变。消息会提醒顾客可能被重复扣款，并请您在 Cardcom 控制面板中办理退款。

Cardcom 付款区块

订单页面会显示一个 Cardcom payment 区块，其中包括交易、付款页面代码、状态、银行卡、分期、发票、银行卡令牌（使用 Charge + Save token 时）、扣除金额、订单总额和已退款金额，测试付款会显示 Test mode 标记，并附有退款记录。

退款

在 Cardcom payment 区块中输入金额（未退款的金额会自动填入），可选填写原因，然后点击 Refund via Cardcom。确认提示 Refund this amount through Cardcom? This cannot be undone. 支持全额和部分退款，同一订单可以进行多次部分退款。您需要拥有编辑订单的权限；访问模块页面的权限则不需要。退款以 Cardcom 扣除的金额和币种进行，因此在金额或币种不一致后，您最多可以退还顾客实际支付的金额，而不是订单总额。退款使用订单付款时所在模式的凭据发送：即使您已切换到正式模式，测试订单仍会通过 Cardcom 测试终端退款，正式订单则始终使用您的正式凭据。正式退款需要 API Username 和 API Password。如果 Cardcom 不接受退款，该区块会显示错误，且不会记录任何退款。成功的退款会添加到退款记录和订单消息中，包括 Cardcom 退款交易和原因。全额退款会将订单设为 Refunded。部分退款不会改变状态。

模块不会生成退款单（credit slip）。订单页面上标准的 PrestaShop 退款按钮不会通过 Cardcom 退还款项。在 Cardcom 控制面板中进行的退款不会回传给商店。

许可证密钥

本模块需要一个来自 vibefox.net 的 VibeFox 许可证密钥。License — VibeFox Cardcom Payment Gateway 许可证区块位于 Modules > Module Manager > VibeFox Cardcom Payment Gateway > Configure 页面的第一个区块，位于设置上方。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效截止日期和您的域名），以及按钮：Check now（再次检查状态）、Change key（输入其他密钥）和 Remove key（从本商店移除密钥）。其下方是 Product: presta-payment-cardcom 一行和 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 账户中释放该名额。

如果没有有效的密钥，结账时顾客将看不到 Cardcom。如果仍然启动了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法得知您已登录后台，因此付款方式对您也会隐藏：您可以在购买密钥之前设置模块，但无法在结账时测试。Modules > Module Manager 中的 Alerts 选项卡会显示提醒。现有订单不受影响：已开始的付款仍会被确认，退款也仍可正常进行。

许可证到期后，模块会继续运行，但更新和支持需要续期。在您于后台工作时，状态会自动重新检查：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块将始终删除许可证密钥和许可证状态。

故障排除

结账时不显示 Cardcom：请检查许可证是否有效、Enable/Disable 是否已开启，以及购物车币种是否为 ILS、USD、EUR 或 GBP。在正式模式下，请检查 Terminal Number 和 API Username 是否已填写您自己的凭据，而不是测试终端 1000 / CardTest1994。缺少任何内容时，设置页面都会显示警告。在 Payment > Preferences 中，请检查该模块是否允许用于购物车币种、顾客所在国家和顾客所属群组。

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

通知返回 Missing or invalid lowprofilecode or Unknown lowprofilecode for this order：该调用未携带您的商店为此购物车签发的付款页面代码。不会更改任何内容。

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

通知返回 Busy, retry：该购物车正在被另一个请求确认，或者订单无法创建（例如模块已被禁用）。请开启 Debug log 查看原因。

通知返回 ReturnValue mismatch or Terminal mismatch：Cardcom 报告了另一个购物车或另一个终端的付款。不会更改任何内容。请检查 Terminal Number 是否为您账户的终端。

顾客看到 Payment error: this currency is not supported by Cardcom.：购物车币种不是 ILS、USD、EUR 或 GBP。

顾客看到 Card payment is temporarily unavailable. Please choose another payment method.：正式模式已开启，但终端号或 API 用户名缺失，或者正式模式字段中填写的是公共测试终端。

顾客在选择 Cardcom 时出现错误：请开启 Debug log 并查看 Log 字段。连接问题和 Cardcom 错误代码都会记录在那里。

订单在付款后处于 Cardcom payment on hold 状态：请阅读订单消息，或查看 Cardcom payment 区块中的 Needs review。付款金额或币种与订单不符。请完成订单或为付款退款。

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

退款失败，提示 Could not connect to Cardcom：请在重试前检查 Cardcom 控制面板，因为退款可能已经完成，也可能没有完成。

对于开发人员，README 列出了 actionCardcomSupportedCurrencies 钩子（用于扩展币种列表，只添加您的 Cardcom 终端已启用的币种）和 actionCardcomLowProfileParams 钩子（用于更改付款页面参数）。

卸载

进入 Modules > Module Manager，打开 VibeFox Cardcom Payment Gateway 旁边的菜单，然后选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。如果 Delete on Uninstall 已开启，设置和日志将被删除。如果已关闭，所有设置都会保留，以便日后重新安装。Cardcom 交易和退款以及 Cardcom payment on hold 订单状态始终会保留，因此之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款消息和交易 ID。

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