VibeFox Paymob for OpenCart — 帮助

要求

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

PHP：8.0 或更高版本。

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

货币：结账货币必须是您所在 Paymob 国家的货币：埃及为 EGP，阿联酋为 AED，沙特阿拉伯为 SAR，阿曼为 OMR，巴基斯坦为 PKR。如果您的店铺尚未添加，请在 System > Localisation > Currencies 中添加。使用其他货币时，结账时会隐藏该付款方式。不支持多货币的 Paymob 账户。

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

安装

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

OpenCart 3

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

2. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox Paymob Pay，点击 Install（绿色 + 按钮）。

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

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

5. 在 Paymob 后台，将您集成的回调 URL 设置为 Callbacks 部分中显示的 URL（参见 Callbacks）。

6. 开启 Enable/Disable 并点击 Save。使用 Paymob 测试集成的 ID 进行一次付款测试，然后输入您正式集成的 ID。

OpenCart 4

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

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

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

4. 按照 OpenCart 3 的第 3 至 6 步输入许可证密钥、Paymob 密钥和 ID 以及回调 URL。两个版本的设置页面及其字段相同，只有回调 URL 不同（参见 Callbacks）。

新安装默认关闭付款方式。

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox Paymob Pay > Edit。各部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，当四个 Paymob 值中有任何一个缺失时（在此之前结账时会隐藏 Paymob），以及当店铺默认货币不被所选 Paymob 国家接受时，页面会发出提醒。

保存时，Title 不能超过 128 个字符，Sort Order 必须是整数（允许负数），Total 必须是大于或等于 0 的数字，所选的地理区域和订单状态必须存在；否则不会保存任何内容，页面会指出相应字段。

Paymob

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

Title：顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称，最多 128 个字符。如果为空，顾客将看到 Paymob。默认：Paymob。

Description：在 Confirm Order 步骤中、确认按钮上方显示给顾客的文字。默认：Pay securely by card or mobile wallet on the Paymob payment page。留空则不显示任何文字。

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

Geo Zone：仅对所选地理区域内的付款地址提供 Paymob。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。在 OpenCart 4 中，当店铺不要求付款地址时，使用配送地址。

Total：订单必须达到的结账总额（以店铺默认货币计）才会提供 Paymob。留空则对任何金额都提供 Paymob。

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。其余字段仍会保存。

已保存的 API 密钥和 HMAC 密钥不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。若要删除已保存的值，请勾选字段下方的 Clear the saved API key on save 或 Clear the saved HMAC secret on save，然后点击 Save。

Callbacks

Paymob 会将每笔交易报告给您的店铺。在 Paymob 后台打开 Developers > Payment Integrations，选择您的集成，点击 Edit，并将 Transaction processed callback 和 Transaction response callback 都设置为本部分中显示的 Callback URL。在 OpenCart 3 中，它的格式类似 https://your-store/index.php?route=extension/payment/wcp_paymob_pay/callback；在 OpenCart 4 中为 https://your-store/index.php?route=extension/wcp_paymob_pay/payment/wcp_paymob_pay.callback。它由您 OpenCart 安装的店铺地址生成。使用 Copy 按钮复制它。本部分还提供了所选国家 Paymob 后台的链接。请在您使用的每个集成中设置这些 URL，包括测试集成。

Transaction processed callback 由 Paymob 服务器发送。Transaction response callback 会把顾客带回您的店铺。两者都使用您的 HMAC 密钥签名，并由扩展进行检查。没有有效签名的回调会被拒绝，且不会更改任何内容。如果服务器回调延迟或丢失，经签名的顾客返回同样会确认付款。即使店铺处于维护模式，回调 URL 仍可正常工作：OpenCart 3 会放行付款扩展的请求，而在 OpenCart 4 中，扩展会添加一个启动动作（startup），放行回调和顾客返回。

订单

OpenCart 在 Confirm Order 步骤创建订单时没有状态（即缺失订单）。只有在 Paymob 报告了经过正确签名的交易之后，订单才会获得状态。被拒绝的付款会使订单保持无状态；顾客会带着保留的购物车返回结账页面。下方每个字段都列出了您的 OpenCart 订单状态。

Order Status After Payment：Paymob 交易已按预期的金额和货币付款。默认：处理中。

Awaiting Paymob Payment Status：交易处于待处理状态，例如现金或自助终端付款。当 Paymob 确认付款后，订单会获得付款后状态。默认：待处理。

Paymob Payment On Hold Status：Paymob 只是授权了金额（请在 Paymob 后台进行捕获）；已付金额或货币与订单不符；或者付款是针对已取消订单到达的。备注会说明原因。默认：待处理，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

接下来的三个字段告诉扩展您的店铺使用哪些状态。扩展从不设置它们。

Payment Error Status：您的店铺用于付款出错订单的状态。待处理的交易可能会将此类订单转为等待状态。默认：失败。

Cancelled Order Status：您的店铺用于已取消订单的状态。针对此类订单收到的付款会将其置于暂存状态，或者如果订单之前已付款，则仅添加备注。默认：已取消。

Refunded Order Status：您的店铺用于已退款订单的状态。针对此类订单收到的付款只会添加备注。默认：已退款。

高级

Debug log：将付款步骤和回调写入 OpenCart 日志文件夹（storage/logs）中的 paymob_p_debug.log.php。该文件无法通过网页打开。即使关闭，错误和被拒绝的回调也始终会被记录。密钥、令牌和顾客数据绝不会被写入。默认：关闭。

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

Clean uninstall：开启时，卸载扩展会删除网关设置和日志。为订单保存的 Paymob ID（付款尝试）始终会被保留。默认：关闭。

导入 / 导出

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

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

结账

在 Payment Method 步骤中，顾客选择付款方式（默认为 Paymob）。在 Confirm Order 步骤中，顾客会看到您的说明以及备注 You will be redirected to the secure Paymob payment page to pay by card or mobile wallet. OpenCart 在此步骤创建订单，此时仍没有状态。在 OpenCart 4 中，顾客使用付款方式区块中的 Choose 按钮（位于 Payment method options 窗口中）选择付款方式，并点击结账页面底部的 Confirm Order。当顾客点击 Confirm Order 时，扩展会为订单货币下的订单金额注册一个新的 Paymob 订单，将顾客的姓名、电子邮件、电话和付款地址传递给 Paymob（在 OpenCart 4 中，当店铺不要求付款地址时，传递配送地址），并把顾客带到您所在国家的 Paymob 付款页面。顾客在那里使用您集成中的某种方式付款，例如银行卡或移动钱包。

付款后，顾客返回您的店铺。只有当 Paymob 用经过签名的交易确认付款后，订单才会被标记为已付款。之后，订单会以 OpenCart 的标准方式获得状态，并发送常规订单电子邮件、更新库存，顾客会看到 OpenCart 的订单成功页面。待处理的付款（例如现金或自助终端）或已授权的付款也会为订单设置状态，即等待或暂存状态，并同样进入成功页面。

如果顾客返回时订单仍在确认中，Payment confirmation 页面会显示 Paymob accepted your payment and we are confirming it. You will receive an e-mail as soon as your order is confirmed — there is no need to pay again. 对于待处理的付款，文字为 Your Paymob payment is pending (for example a cash or kiosk payment). Complete it as Paymob instructed you: your order is confirmed as soon as Paymob reports the payment. 该页面有 Check again 和 Back to checkout 两个按钮。

如果付款被拒绝，顾客会带着同一购物车返回结账页面，并看到 Your Paymob payment was not completed. Please try again or choose another payment method. 每次新的尝试都会注册自己的 Paymob 订单，因此顾客可以再次支付该购物车。OpenCart 3 每次显示 Confirm Order 步骤时都会创建新订单；OpenCart 4 为结账保留一个订单并更新它，因此顾客会以新的尝试支付同一订单。如果无法验证 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. 如果同一购物车的另一笔订单已付款或正在等待付款（例如在第二个浏览器标签页中），顾客会被带到成功页面，而不是再次付款。在 OpenCart 4 中，从 Paymob 返回后显示的消息会出现在结账页面上方。

OpenCart 4 会在显示成功页面之前将订单保留在结账中。如果该订单期间被关闭且未付款（例如您取消了它），顾客会带着 Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order. 返回结账页面，下一次 Confirm Order 将支付一个新订单。如果该订单已有状态，并且购物车现在有其他商品或数量，顾客同样会返回结账页面，新购物车将获得新订单。

如果 Paymob 无法启动付款，顾客会停留在 Confirm Order 步骤，并在按钮上方看到一条简短消息，例如 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. 技术原因会写入日志。

本扩展仅在 Paymob 页面上接受一次性付款。它不支持保存银行卡、订阅、在您网站上嵌入银行卡表单，也不支持从管理后台退款。

订单

订单状态

No status (missing order)：顾客已被转到 Paymob 但未付款，付款被拒绝，或 Paymob 尚未确认付款。在 Sales > Orders 中，此类订单只有在 Order Status 筛选条件设为 Missing Orders 时才会显示。

在 OpenCart 4 中，未付款的结账订单可能会获得 Voided 状态，该状态由 OpenCart 4 在顾客返回 Confirm Order 步骤时设置。扩展会将此类订单视为无状态订单，之后的付款仍会确认它。

Order Status After Payment (default Processing)：Paymob 已确认付款。备注会显示交易、金额以及银行卡类型和后四位数字。

Awaiting Paymob Payment Status (default Pending)：付款在 Paymob 处于待处理状态，例如现金或自助终端付款。当 Paymob 确认付款后，订单会变为付款后状态。

Paymob Payment On Hold Status (default Pending)：Paymob 只授权了金额但尚未捕获（请在 Paymob 后台进行捕获；捕获回调到达后，订单会变为付款后状态）；或者已付金额或货币与订单不符；或者付款是针对一个已被取消的订单到达的。备注会说明原因。请检查订单，然后履行订单，或在 Paymob 后台退还付款。

当已有状态的订单发生变化时，OpenCart 会通知顾客。如果已付款订单又收到了第二笔成功付款，或已付款购物车中的第二笔订单收到了付款，则已付款订单不会改变，并且备注会提醒您在 Paymob 后台退还重复款项。对于先前已付款的已取消订单或已退款订单的付款，只会添加备注：订单不会被重新打开。对于已有状态的订单，被拒绝的付款只会添加备注。

备注是订单 History 中的条目，顾客看不到。

VibeFox Paymob Pay 选项卡

在 Sales > Orders 中打开一个通过 Paymob 付款的订单。在订单页面底部，与 History 和 Additional 并列的 VibeFox Paymob Pay 选项卡会显示该订单的每一次 Paymob 尝试：包含商户订单 ID 和国家的 Paymob order、Paymob transaction ID、Status、Requested 金额、包含银行卡信息的 Amount reported by Paymob，以及 Paymob message。下方是本订单的扩展 Notes。该选项卡对有权访问本扩展的用户可见。

退款

不支持从管理后台退款。请在 Paymob 后台退款或撤销付款。当 Paymob 报告退款或撤销时，订单会添加一条备注，订单状态不会改变。请手动更新订单。

许可证密钥

本扩展需要使用来自 vibefox.net 的 VibeFox 许可证密钥。License — VibeFox Paymob Pay 许可证区块是 Extensions > Extensions > Payments > VibeFox Paymob Pay > Edit 中的第一个区块，位于设置上方。将密钥粘贴到 License key 中并点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及用于再次检查状态的 Check now 按钮、用于输入其他密钥的 Change key 按钮，以及用于从本店铺移除密钥的 Remove key 按钮。其下方是 Product: opencart-payment-paymob 一行和 Manage licenses and domains in your account 链接，该链接会打开您的 vibefox.net 账户。只有对本扩展拥有 Modify 权限的管理员用户才能更改密钥。区块中的文字遵循管理后台语言（包含英语和俄语）。

如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached 或带日期的 License expired on。在更改店铺地址之后，或在您的账户中释放一个域名名额之后，请点击 Check now。如果无法连接许可证服务器，扩展会继续使用最后已知的状态运行。

一个密钥只能用于一个域名：即 OpenCart 配置中的店铺地址。从店铺中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。

没有有效密钥时，结账时顾客将看不到 Paymob。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 在同一浏览器中登录后台的管理员用户仍会在店铺中看到该付款方式，并标记为 (unlicensed — visible to admins only)，以便您在购买密钥之前设置和测试扩展。在 OpenCart 4 中此预览不可用：店铺看不到后台登录，因此没有有效密钥时，该付款方式对所有人都隐藏。打开一次 Edit 页面后，管理后台的 Dashboard 上会出现提醒。点击 × 关闭它，即可隐藏 7 天。现有订单不受影响：已发起的付款仍会被确认。

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

故障排除

结账时没有显示 Paymob：请检查许可证是否有效，Enable/Disable 是否开启，四个值（API 密钥、集成 ID、iFrame ID、HMAC 密钥）是否都已填写，以及结账货币是否为所选 Paymob country 的货币。设置页面会在缺少某项内容时显示警告。另请检查付款地址是否位于所选的 Geo Zone 中，以及订单是否达到设置中的 Total。

付款已完成，但订单仍无状态：回调未能到达您的店铺。请检查您所用集成的 Transaction processed callback 和 Transaction response callback 是否与 Callbacks 部分显示的 URL 完全一致，并且 HMAC secret 与同一 Paymob 账户一致。被拒绝的回调会以警告形式写入日志，即使 Debug log 已关闭也是如此。请查看扩展页面上的 Log 字段。

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

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

回调返回 locked 或 retry：订单在同一时刻正被另一个请求（例如顾客返回）更新，或者无法设置订单状态。Paymob 会重试回调。原因会写入日志。

在浏览器中打开回调 URL 会进入结账页面，并显示无法验证的消息：这是正常现象。该 URL 只接受来自 Paymob 的已签名请求。

顾客在 Confirm Order 之后看到错误：请开启 Debug log 并查看日志。Paymob payments are temporarily unavailable 表示 API 密钥错误或缺少某个值。Paymob could not start the payment 表示 Paymob 拒绝了请求，例如集成 ID 错误或账单信息不完整。This order cannot be paid with Paymob 表示订单总额为零。Paymob does not accept payments in 后接货币，表示订单货币不是所选 Paymob 国家的货币。This payment method is not available. 表示结账会话已与订单不再匹配，或付款方式在此期间已被关闭：顾客需要重新加载结账页面。

付款后订单处于暂存或等待状态：请阅读 VibeFox Paymob Pay 选项卡中的备注。付款处于待处理状态（现金或自助终端），交易只是被授权（请在 Paymob 后台进行捕获），金额或货币不匹配，或者付款是在订单被取消之后到达的。

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

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Paymob Pay 旁边的 Uninstall（红色 −）按钮。许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Orders 部分中的订单状态；重新安装时这些设置会恢复为默认值。在 OpenCart 4 中，还会删除扩展的 OpenCart 事件及其启动动作（在维护模式下放行回调和顾客返回）。如果 Clean uninstall 已开启，则其余网关设置（标题、描述、国家、密钥和 ID、日志记录）和日志都会被删除。如果已关闭，它们会保留，以便之后重新安装时使用。订单的 Paymob 付款尝试始终会被保留。现有订单会保留其付款备注和 Paymob ID。

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

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