VibeFox Paymob for PrestaShop — 帮助

系统要求

PrestaShop：8.0 至 9.x。

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

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

币种：购物车币种必须是您 Paymob 国家的币种：埃及为 EGP，阿拉伯联合酋长国为 AED，沙特阿拉伯为 SAR，阿曼为 OMR，巴基斯坦为 PKR。使用其他币种时，结账时会隐藏该付款方式。不支持多币种的 Paymob 账户。

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

安装

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

2. 上传完成后，点击 Configure；或者之后在模块列表中找到 VibeFox Paymob Pay，然后点击 Configure。

3. 在 Configure 页面顶部许可证区块的 License key 中输入您的 VibeFox 许可证密钥，然后点击 Activate（参见许可证密钥）。

4. 选择 Paymob country，并输入 API key、integration ID、iFrame ID 和 HMAC secret（参见配置）。

5. 在 Paymob 后台，将您集成的回调地址设置为 Configure 页面上显示的地址（参见 Callbacks）。

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

安装时，模块会创建两个订单状态：Awaiting Paymob payment 和 Paymob payment on hold。PrestaShop 默认会为所有币种、国家和客户组启用新的付款模块。您可以在 Payment > Preferences 中加以限制。之后在店铺中启用的国家，也必须在那里为本模块勾选。

配置

所有设置都位于模块页面：Modules > Module Manager > VibeFox Paymob Pay > Configure。每个部分都有自己的 Save 按钮，会保存整个页面。在各字段上方，当四个 Paymob 值之一缺失时（在此之前结账时会隐藏 Paymob），以及当所选 Paymob 国家不接受店铺默认币种时，页面都会给出警告。Callbacks 框会显示回调地址，附带 Copy 按钮，并提供所选国家 Paymob 后台的链接。

Paymob

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

Title：顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认：Paymob。

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

Paymob 账户

所有值都在您的 Paymob 商户后台中。没有单独的测试模式：进行测试付款时，请输入测试模式下集成的 integration 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 key 和 HMAC secret 不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。

Clear saved secrets：勾选 API key 或 HMAC secret 并点击 Save，即可删除它。字段留空则保留已保存的值。

Callbacks

Paymob 会把每笔交易通知给您的店铺。在 Paymob 后台打开 Developers > Payment Integrations，选择您的集成，点击 Edit，并将 Transaction processed callback 和 Transaction response callback 都设置为 Callbacks 框中显示的地址。使用友好 URL 时，地址形如 https://your-shop/module/wcp_paymob_pay/callback，可能带有语言代码，如 /en/。该地址使用店铺的默认语言生成。使用 Copy 按钮复制。请在您使用的每个集成中设置这些地址，包括测试集成。

Transaction processed callback 由 Paymob 服务器发送。Transaction response callback 会把顾客带回您的店铺。两者都使用您的 HMAC secret 签名，并由模块进行校验。签名无效的回调会被拒绝，且不会更改任何内容。如果服务器回调延迟或丢失，经签名的顾客返回也会确认付款。即使店铺处于维护模式，服务器回调仍然有效，并且不受店铺国家限制的阻止。

高级

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

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

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

结账

在付款步骤中，顾客选择付款方式（默认为 Paymob）并确认。模块会以购物车币种为购物车总额创建一个新的 Paymob 订单，将顾客的姓名、电子邮件、电话和账单地址传给 Paymob，并把顾客带到您所在国家的 Paymob 付款页面。在那里，顾客可使用您集成中的某种方式付款，例如银行卡或移动钱包。此时尚不存在订单。

付款后，顾客返回您的店铺。只有在 Paymob 用签名交易确认付款后，订单才会被标记为已付款。随后订单会被创建，顾客看到标准的订单确认页面。待付款（例如现金或自助终端）或已授权的付款也会创建订单，状态为等待，并引导至确认页面。

如果订单恰好同时被 Paymob 回调确认，顾客会看到一个页面，内容为 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 订单，因此顾客可以再次支付该购物车。如果无法验证 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. 技术原因会写入日志。

本模块在 Paymob 页面上处理一次性付款。不支持保存银行卡、订阅、您网站上嵌入的银行卡表单，也不支持在后台退款。

订单

订单状态

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

Payment accepted：Paymob 已确认付款。付款会以 Paymob 交易 ID 作为交易 ID 记录，备注中会显示交易、金额，以及卡类型和卡号后四位。

Awaiting Paymob payment：付款在 Paymob 处于待处理状态，例如现金或自助终端付款。当 Paymob 确认付款后，订单会转为 Payment accepted。

Paymob payment on hold：Paymob 只授权了金额，尚未扣款（请在 Paymob 后台进行扣款；收到扣款回调后，订单会转为 Payment accepted）；或已付金额或币种与购物车不一致（例如付款开始后修改了购物车）；或收到了已取消订单的付款。备注会说明原因。请检查订单并进行处理，或在 Paymob 后台退款。

如果对已付款的订单又收到第二笔成功付款，订单不会改变。备注会要求您在 Paymob 后台退还该重复付款。对于之前已付款的已取消订单或已退款订单，收到的付款只会添加备注：订单不会被重新打开。对于尚未付款的订单，被拒绝的付款只会添加备注。

Paymob 付款区块

订单页面会显示一个 Paymob payment 区块，列出该订单的每次 Paymob 尝试：Paymob 订单、商户订单 ID 和国家、Paymob 交易 ID、状态、请求金额、Paymob 为银行卡报告的金额，以及 Paymob 消息。下方是该订单的模块 Notes。

退款

不支持在后台退款。请在 Paymob 后台退款或撤销付款。当 Paymob 报告退款或撤销时，订单会添加一条备注，订单状态不会改变。请手动更新订单，例如更改其状态或开具折让单（credit slip）。

许可证密钥

本模块需要使用在 vibefox.net 获取的 VibeFox 许可证密钥。模块 Configure 页面顶部、设置上方的许可证区块 License — VibeFox Paymob Pay 是 Modules > Module Manager > VibeFox Paymob Pay > Configure 中的第一个区块。请将密钥输入 License key，然后点击 Activate。之后，该区块会以掩码形式显示密钥，以及状态（例如许可证有效期截止日期和您的域名），并提供以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺移除密钥）。其下方是 Product: presta-payment-paymob 一行，以及打开您 vibefox.net 账户的链接 Manage licenses and domains in your account。只有拥有本模块 Configure 权限的员工才能更改密钥。该区块的文字跟随后台语言显示（包括英语和俄语）。

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

一个密钥只能用于一个域名：主店铺的域名，多店铺配置下同样如此。从店铺中移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。

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

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

故障排除

结账时没有显示 Paymob：请检查许可证是否有效，Enable/Disable 是否已开启，四个值（API key、integration ID、iFrame ID、HMAC secret）是否都已填写，以及购物车币种是否为所选 Paymob country 的币种。缺少内容时，设置页面会显示警告。在 Payment > Preferences 中，请检查模块是否允许用于购物车币种、顾客所在国家和顾客所属客户组。

付款已成功，但未创建订单：回调没有到达您的店铺。请检查您所用集成的 Transaction processed callback 和 Transaction response callback 是否与 Callbacks 框中显示的地址完全一致，并且 HMAC secret 属于同一个 Paymob 账户。被拒绝的回调会以警告形式写入日志，即使 Debug log 已关闭也是如此。请查看模块页面上的 Log 字段。

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

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

回调返回 locked 或 retry：订单在同一时刻正被另一个请求更新（例如顾客返回），或订单无法创建（例如模块已停用）。Paymob 会重试回调。原因会写入日志。

在浏览器中打开回调地址会进入结账页面并显示 could not verify 消息：这是正常现象。该地址只接受来自 Paymob 的签名请求。

顾客在选择 Paymob 时看到错误：请开启 Debug log 并查看日志。Paymob payments are temporarily unavailable 表示 API key 错误或缺少某个值。Paymob could not start the payment 表示 Paymob 拒绝了请求，例如 integration ID 错误或账单信息不完整。This order cannot be paid with Paymob 表示订单总额为零。Paymob does not accept payments in 后面跟着币种，表示购物车币种不是所选 Paymob 国家的币种。

付款后订单处于 Paymob payment on hold 或 Awaiting Paymob payment：请阅读 Paymob payment 区块中的备注。付款处于待处理状态（现金或自助终端），交易仅被授权（请在 Paymob 后台扣款），金额或币种不一致，或付款是在订单取消之后到达的。

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

卸载

进入 Modules > Module Manager，打开 VibeFox Paymob Pay 旁边的菜单，然后选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。如果 Clean uninstall 已开启，模块设置和日志会被删除。如果已关闭，所有设置都会保留，以便日后重新安装。订单的 Paymob 付款尝试以及 Awaiting Paymob payment 和 Paymob payment on hold 订单状态始终会保留。现有订单会保留其付款备注、交易 ID 和 Paymob ID。

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