VibeFox Cardcom for WooCommerce — 帮助
系统要求
WordPress：6.0 或更高版本。
WooCommerce：8.0 或更高版本，已安装并启用。未安装时插件无法激活。
PHP：8.0 或更高版本。
HTTPS：您的站点必须可通过 HTTPS 从互联网访问，以便 Cardcom 发送付款通知。
币种：订单币种必须为 ILS、USD、EUR 或 GBP。对于其他币种，该付款方式在结账时隐藏。
Cardcom 账户：正式付款需要 Cardcom 商户账户，包括终端号、API 用户名和 API 密码。付款只需要终端号和 API 用户名；API 密码仅用于在 WooCommerce 中退款。测试模式无需 Cardcom 账户。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥仅适用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 wcp_cardcom_payment_gateway 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Payments > Cardcom > Manage，或在插件列表页点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 开启 Enable/Disable，保持 Test Mode 开启，然后使用卡号 4580 0000 0000 0000、任意未来有效期、CVV 123 下一笔测试订单。
6. 如需进行真实付款，请取消勾选 Test Mode，并填入从 Cardcom 获得的 Terminal Number、API Username 和 API Password。
配置
所有设置位于同一页面：WooCommerce > Settings > Payments > Cardcom。测试模式开启时，字段上方会显示 Test mode is on.。在正式模式下，若缺少终端号或 API 用户名，页面会发出警告（此时 Cardcom 在结账时隐藏），并提醒：若没有 API 密码，则无法从 WooCommerce 退款。若店铺币种不受支持，页面也会发出警告。保存正式模式设置时若未填写终端号或 API 用户名，将显示错误信息，提示该网关在填写之前于结账时保持隐藏。
常规
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: Enable test mode (terminal 1000, no real money)。默认：开启。取消勾选即可使用下方的正式凭据接收真实付款。退款始终使用订单付款时所在模式的凭据发送。
正式凭据
终端号、API 用户名和 API 密码由 Cardcom 随您的商户账户一同提供：可在 Cardcom 后台的 API 设置中找到，或向 Cardcom 支持索取。这些字段仅在正式模式下使用。
Terminal Number: 您的 Cardcom 终端号，只能包含数字。若输入其他内容，将显示错误，并保留原值。
API Username: 该终端的 Cardcom API 用户名（ApiName）。保存时会去除空格。
API Password: 您的 Cardcom API 密码。仅在通过 WooCommerce 退款时需要，并按输入的原样保存。
付款页面
Cardcom 会将付款通知（IndicatorUrl）发送到本节显示的地址。该地址形如 https://your-site/wc-api/cardcom_p_callback/。它会随每笔付款及订单 ID 自动传递给 Cardcom，因此无需在 Cardcom 中进行任何设置。该地址必须可从互联网访问。
Operation: Cardcom 在付款页面上执行的操作。
Max Installments: 顾客可在 Cardcom 页面选择的最大分期数（付款期数），范围为 1 至 36。1 表示不分期。默认：1。
Success Order Status: 付款确认后的订单状态。状态会立即设置，无需第二次状态变更。
高级
Debug log: Log API requests and notifications 写入 WooCommerce > Status > Logs，来源为 wcp_cardcom_payment_gateway。错误始终会被记录。凭据、卡令牌和持卡人信息绝不会写入日志。默认：关闭。
Delete on Uninstall: Delete all plugin data when uninstalling。开启时，删除插件会永久移除设置、订单上存储的 Cardcom 数据以及日志。订单本身会保留。默认：关闭。
结账
顾客选择付款方式（默认为 Credit Card (Cardcom)）并下单。插件会按订单币种为订单总额创建 Cardcom 付款页面，并将顾客转到该页面。店铺语言为希伯来语时，页面以希伯来语显示，否则以英语显示。订单商品会以商品名称的形式传递给 Cardcom。顾客在页面中输入银行卡信息，若允许分期，还可选择付款期数。
付款后，顾客会返回您店铺的订单已接收页面。只有在 Cardcom 确认后，订单才会被标记为已付款。Cardcom 会调用通知地址，插件仅从该调用中获取付款页面代码，并核对该代码是否由您的店铺为该订单签发，然后以服务器对服务器的方式向 Cardcom 查询真实结果。若通知延迟到达，顾客落到订单已接收页面时会再次执行同样的核对。
若付款未完成，Cardcom 会将顾客送回结账页面（或 Pay for order 页面），并显示 The card payment was not completed. Please try again or choose a different payment method.。经 Cardcom 确认被拒绝的付款会将订单标记为失败。顾客可以为未付款订单重新付款，例如通过 Pay for order 页面。同一订单较早的付款页面上完成的付款仍会被识别。若顾客切换到其他付款方式，但在 Cardcom 页面完成了付款，则该付款会被记录，并将付款方式改回 Cardcom。
若 Cardcom 无法打开付款页面，顾客会看到简短提示，例如 Could not connect to Cardcom. Please try again in a moment.，或提示 Cardcom 无法打开付款页面（附 Cardcom 代码），顾客可选择其他付款方式。
该付款方式支持经典结账、结账区块以及 Pay for order 页面。兼容 WooCommerce 高性能订单存储（HPOS）。
插件仅在 Cardcom 页面上接受银行卡付款。不支持保存银行卡或一键付款、订阅，不对已保存的令牌进行扣款，没有 Cardcom 发票或收据设置，不支持通过 Cardcom 使用 Bit、Apple Pay、Google Pay 或 PayPal，不支持 iframe 模式，也不支持延迟扣款交易。未完成的付款页面不会被自动检查。
订单与退款
订单状态
Pending payment: 顾客已被转到 Cardcom 但尚未付款，或 Cardcom 尚未确认付款。
Processing, Completed or On Hold: 付款已确认。状态遵循 Success Order Status 的设置。订单备注会显示 Cardcom 交易信息，以及 Cardcom 返回的银行卡末四位、发票号和分期数（如有）。测试付款会标注 Test mode — no real money was charged. 订单的交易 ID 即为 Cardcom 交易编号。
On hold after payment: Cardcom 确认的付款与订单不符，例如打开付款页面后订单总额被修改，或扣款金额或币种不同。订单备注会说明原因。请在 Cardcom 后台核对该笔付款与订单，然后处理订单或对该付款退款。
Failed: Cardcom 拒绝了该付款。订单备注会显示 Cardcom 返回的响应代码。较早的付款页面上的拒绝不会使较新的付款尝试失败，迟到的拒绝也绝不会改变已付款订单。
若同一订单已付款后又收到第二笔付款成功的结果（例如顾客在两个浏览器标签页中付款），订单不会再次被更改。备注会提示顾客可能被重复扣款，并请您在 Cardcom 后台办理退款。
退款
打开订单，点击 Refund，输入金额，然后点击 Refund via Credit Card (Cardcom)（按钮显示付款方式名称）。支持全额和部分退款，同一订单可进行多次部分退款。退款使用订单付款时所在模式的凭据发送：即使您已切换到正式模式，测试订单仍会通过 Cardcom 测试终端退款，正式订单则始终使用您的正式凭据。正式退款需要 API Username 和 API Password。若 Cardcom 未接受退款，WooCommerce 会显示错误，且不会记录退款。退款成功后，订单备注会添加 Cardcom 退款交易及退款原因。
在 Cardcom 后台进行的退款不会回传到店铺。如有需要，可在 WooCommerce 中手动创建退款，而不使用该网关的 Refund via 功能。
许可证密钥
本插件需要来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > Cardcom 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期截止日期以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将其从本站点移除。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。
一个密钥仅适用于一个域名。从站点移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效密钥时，结账时不会向顾客显示 Cardcom。若仍发起付款，顾客会看到 This payment method is not available. Please choose another one.。已登录的店铺管理员仍可看到该付款方式，并标注 (unlicensed — visible to admins only)，以便您在购买密钥前设置和测试插件。插件页面和 WooCommerce 页面上会显示提醒。现有订单不受影响：已发起的付款仍会被确认，退款也可正常使用。
许可证到期后，插件仍可继续使用，但更新和支持需要续费。系统会在后台自动重新检查状态。
故障排除
结账时未显示 Cardcom：请检查许可证是否有效、Enable/Disable 是否开启，以及订单币种是否为 ILS、USD、EUR 或 GBP。正式模式下，请检查 Terminal Number 和 API Username 是否已填写。设置页面在缺少项目时会显示警告。
付款已完成，但订单仍为待付款：Cardcom 无法访问您的站点，例如因为维护模式、防火墙、密码保护或本地开发站点。通知地址必须可通过 HTTPS 从互联网访问。顾客返回订单已接收页面时，订单也会得到确认。请开启 Debug log，并在 WooCommerce > Status > Logs 中查看来源为 wcp_cardcom_payment_gateway 的日志。
通知返回 Missing or invalid lowprofilecode 或 Unknown lowprofilecode for this order：该调用未携带您的店铺为该订单签发的付款页面代码。订单不会被更改。
通知返回 Gateway not configured 或 Indicator check failed：创建付款页面时所用模式的凭据缺失，或 Cardcom 在核对时无法连接。订单不会被更改，并会在顾客返回店铺时再次核对。
通知返回 ReturnValue mismatch 或 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 用户名。
顾客在下单时看到错误：请查看订单备注，或开启 Debug log 并查看日志。连接问题和 Cardcom 错误代码会记录在那里。
付款后订单为保留状态：请阅读订单备注。已付金额或币种与订单不符。请处理订单或对该付款退款。
退款失败，提示 API username and API password are required for refunds：请在设置中填写 API Password（以及 API Username），然后重试。
退款失败，提示 Could not connect to Cardcom：重试前请先在 Cardcom 后台核对，因为退款可能已完成，也可能未完成。
许可证区块显示错误：请按照区块中的提示操作。例如，若该密钥已在其他域名上使用，请在您的 vibefox.net 账户中释放一个名额，然后点击 Check now。若站点地址已更改，请点击 Check now，为新域名激活密钥。若无法连接许可证服务器，插件将继续使用最后已知的状态。
对于开发人员，自述文件列出了过滤器 cardcom_p_supported_currencies，可用于扩展支持的币种列表（请仅添加您 Cardcom 终端已启用的币种）。
卸载
停用插件会保留所有数据。要移除插件，请先停用，然后在 Plugins 页面将其删除。本插件的许可证密钥和许可证状态始终会被移除。仅当开启了 Delete on Uninstall 时，网关设置、订单上存储的 Cardcom 数据以及日志才会被移除。否则它们将保留，以便日后重新安装时使用。现有订单保留其付款备注和交易 ID。
Cardcom 是其各自所有者的商标。本插件与 Cardcom 无关联，也未获得 Cardcom 认可。