VibeFox Paymob for WooCommerce — 帮助

系统要求

WordPress：6.2 或更高版本。

WooCommerce：8.0 或更高版本，已安装并启用。没有 WooCommerce 时插件无法启用。

PHP：8.0 或更高版本。

Paymob 账户：在受支持国家之一的商户账户：埃及、阿拉伯联合酋长国、沙特阿拉伯、阿曼或巴基斯坦。您需要从 Paymob 控制面板获取四个值：API 密钥、在线支付集成的集成 ID、支付页面的 iFrame ID，以及 HMAC 密钥。

货币：商店货币必须是您所在 Paymob 国家的货币：埃及为 EGP，阿拉伯联合酋长国为 AED，沙特阿拉伯为 SAR，阿曼为 OMR，巴基斯坦为 PKR。使用其他货币时，结账页面不会显示该付款方式。

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

安装

1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 wcp_paymob_pay 文件夹上传到 /wp-content/plugins/。

2. 点击 Activate。

3. 打开设置：WooCommerce > Settings > Payments > Paymob > Manage，或在插件页面中点击插件名称下方的 Settings。

4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。

5. 选择 Paymob country，并输入 API 密钥、集成 ID、iFrame ID 和 HMAC 密钥（参见配置）。

6. 在 Paymob 控制面板中，将您集成的回调 URL 设置为设置页面上显示的 URL（参见 Callbacks）。

7. 开启 Enable/Disable。使用 Paymob 测试集成的 ID 测试一次付款，然后再输入您正式集成的 ID。

配置

所有设置都在同一个页面：WooCommerce > Settings > Payments > Paymob。页面在字段上方提醒您：如果四个 Paymob 值中缺少任何一个（在此之前 Paymob 不会在结账时显示），或者所选 Paymob 国家不接受商店货币，页面都会发出警告。方框中会显示回调 URL，并附带一个 Copy 按钮，以及所选国家 Paymob 控制面板的链接。

常规

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

Title：顾客在结账时看到的付款方式名称。默认：Paymob。

Description：结账时显示在付款方式下方的文字。默认：Pay securely by card or mobile wallet on the Paymob payment page.

Paymob 账户

所有值都在您的 Paymob 商户控制面板中。没有单独的测试模式：进行测试付款时，请输入处于测试模式的集成的集成 ID。其他设置不会改变。

Paymob country：您 Paymob 账户所在的国家。它决定使用哪个 API 和支付页面服务器，商店货币必须是该国家的货币。默认：Egypt。

API key：在 Paymob 控制面板的 Settings > Account info > API Key 中获取。

Integration ID：在 Paymob 控制面板的 Developers > Payment Integrations 中获取：即在线银行卡或钱包集成的数字 ID。Paymob 页面提供的付款方式以该集成为准。

iFrame ID：在 Paymob 控制面板的 Developers > iframes 中获取：付款 iFrame 的数字 ID。

HMAC secret：在 Paymob 控制面板的 Settings > Account info > HMAC 中获取。必填：只有经此密钥签名的回调才会将订单标记为已付款。

Integration ID 和 iFrame ID 只能包含数字。空格会被删除。其他任何值在保存时都会被拒绝，并提示该字段 must contain digits only — the previous value was kept。

Callbacks

Paymob 会将每笔交易通知到您的商店。在 Paymob 控制面板中打开 Developers > Payment Integrations，选择您的集成，点击 Edit，然后将 Transaction processed callback 和 Transaction response callback 都设置为设置页面上显示的 URL。它的样子类似 https://your-site/wc-api/paymob_pay/。使用 Copy 按钮复制。您使用的每个集成（包括测试集成）都要设置这些 URL。

交易处理完成回调由 Paymob 服务器发送。交易响应回调会把顾客带回您的商店。两者都使用您的 HMAC 密钥签名，并由插件进行验证。签名无效的回调会被拒绝，不会产生任何变化。如果服务器回调延迟或丢失，经签名的顾客返回也会确认付款。

高级

Debug log：Log payment steps and callbacks 会将付款步骤和回调写入 WooCommerce > Status > Logs，来源为 wcp_paymob_pay。错误和被拒绝的回调始终会被记录。密钥、令牌和顾客数据从不写入。默认：关闭。

Clean uninstall：Delete the plugin settings and logs when the plugin is deleted。停用插件从不会删除任何内容。订单上保存的 Paymob ID 会保留。默认：关闭。

结账

顾客选择付款方式（默认为 Paymob）并提交订单。插件会以订单货币为订单总额创建一个新的 Paymob 订单，将顾客的姓名、电子邮件、电话和账单地址传给 Paymob，并将顾客带到您所在国家的 Paymob 支付页面。顾客在那里使用您集成中的某种方式付款，例如银行卡或移动钱包。

付款后，顾客返回您的商店。只有 Paymob 通过经签名的交易确认后，订单才会被标记为已付款。已付款、待处理或已授权的付款会将顾客引导至订单接收页面。

如果付款被拒绝，顾客会返回结账页面（如果付款是在 Pay for order 页面发起的，则返回该页面），并看到消息 Your Paymob payment was not completed. Please try again or choose another payment method. 每次新的尝试都会创建一个新的 Paymob 订单，因此顾客可以为同一订单重试。如果无法验证来自 Paymob 的返回，顾客会看到 We could not verify the response from Paymob. If you were charged, your order will be updated as soon as Paymob confirms the payment.

如果 Paymob 无法启动付款，顾客会看到一条简短消息，并可以选择其他付款方式，例如 Paymob could not start the payment. Please check your billing details and try again, or choose another payment method. 或 Could not connect to Paymob. Please try again in a moment. 技术原因会写入日志。

该付款方式适用于经典结账、结账区块和 Pay for order 页面。在 Pay for order 页面上，检查的是订单货币而不是商店货币。它与 WooCommerce 高性能订单存储（HPOS）兼容。

插件仅在 Paymob 页面上接受一次性付款。它不支持保存银行卡、订阅、您网站上的嵌入式银行卡表单，也不支持通过 WooCommerce 退款。

订单

订单状态

Pending payment：顾客已被带到 Paymob 但尚未付款，或 Paymob 尚未确认付款。

Processing：Paymob 已确认付款。仅包含虚拟可下载商品的订单会变为已完成，即 WooCommerce 的默认状态。订单备注会显示 Paymob 交易、金额，以及卡类型和卡号后四位。交易 ID 即 Paymob 交易 ID。

On hold：付款在 Paymob 处于待处理状态，例如现金或自助终端付款；或者 Paymob 只授权了金额但未捕获（请在 Paymob 控制面板中进行捕获，收到捕获回调后订单才会完成）；或者付款金额或货币与订单不符；或者付款到达时订单已被取消。订单备注会说明原因。

Failed：Paymob 拒绝了待付款订单的付款。顾客可以再次付款。

如果已付款的订单又收到第二笔成功付款，订单不会改变。备注会提示您在 Paymob 控制面板中退还重复付款。对于之前已付款后被取消的订单，或已退款的订单，收到的付款只会添加备注：订单不会重新打开。

退款

不支持通过 WooCommerce 退款。请在 Paymob 控制面板中退款或作废付款。Paymob 报告退款或作废时，订单会添加一条备注，订单状态不会改变。请手动更新订单，例如在 WooCommerce 中进行手动退款。

许可证密钥

插件需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > Paymob 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证的有效截止日期和您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将其从本站点移除。Manage licenses and domains in your account 链接会打开您的 vibefox.net 账户。

一个密钥只能用于一个域名。从站点移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。

没有有效密钥时，结账时不会向顾客显示 Paymob。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 已登录的商店管理员仍可看到该付款方式，并标注为 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置和测试插件。插件页面和 WooCommerce 页面上会出现提醒。现有订单不受影响：已发起的付款仍会被确认。

许可证过期后，插件仍可继续工作，但更新和支持需要续费。状态会在后台自动重新检查。

故障排除

结账时没有显示 Paymob：请检查许可证是否有效，Enable/Disable 是否已开启，四个值（API key、Integration ID、iFrame ID、HMAC secret）是否都已填写，以及商店货币是否为所选 Paymob country 的货币。缺少内容时，设置页面会显示警告。拥有多货币 Paymob 账户的开发者可以使用 paymob_p_supported_currencies 过滤器扩展可接受的货币。

付款已完成，但订单仍为 Pending payment：回调没有到达您的商店。请检查所用集成的 Transaction processed callback 和 Transaction response callback 是否与设置页面上的 URL 完全一致，并且 HMAC secret 属于同一个 Paymob 账户。被拒绝的回调即使在调试日志关闭时，也会以警告形式记录在 WooCommerce > Status > Logs 中，来源为 wcp_paymob_pay。

回调返回 Invalid signature：设置中的 HMAC 密钥与 Paymob 账户不匹配，或者选择了其他国家的账户。请重新复制 HMAC 密钥。

回调返回 Not configured：HMAC 密钥为空。请输入密钥；Paymob 会重试回调。

回调返回 locked：订单在同一时刻正被另一个请求更新，例如顾客返回。Paymob 会重试回调。

顾客下单时出现错误：请开启 Debug log 并查看日志。Paymob payments are temporarily unavailable 表示 API 密钥错误或缺少某个值。Paymob could not start the payment 表示 Paymob 拒绝了请求，例如集成 ID 错误或账单信息不完整。This order cannot be paid with Paymob 表示订单总额为零。

订单在付款后处于 On hold：请阅读订单备注。付款处于待处理状态（现金或自助终端），交易仅被授权（请在 Paymob 控制面板中捕获），金额或货币不符，或付款是在订单取消后到达的。订单备注会说明原因。

测试付款：在 Integration ID 中输入 Paymob 测试集成的 ID，并在该集成中设置回调 URL。进行正式付款时，请重新输入您正式集成的 ID。

许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在另一个域名上使用，请在您的 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now 为新域名激活密钥。如果无法连接许可证服务器，插件将继续使用最后已知的状态工作。

卸载

停用插件会保留所有数据。要删除插件，请在 Plugins 页面中先停用再删除。本插件的许可证密钥和许可证状态始终会被删除。只有开启了 Clean uninstall 时，网关设置和日志才会被删除；否则它们会保留，以便之后重新安装。现有订单会保留其付款备注、交易 ID 和 Paymob ID。

Paymob 是其各自所有者的商标。本插件与 Paymob 无关联，也未获得 Paymob 的认可。