ZH
EUR
返回

VibeFox Moyasar for PrestaShop — 帮助

系统要求

PrestaShop：8.0 至 9.x。

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

货币：购物车货币必须为 SAR、AED、USD、EUR、KWD、BHD 或 OMR。使用其他任何货币时，结账时将隐藏该付款方式。

Moyasar 账户：您需要 Moyasar 账户的秘密 API 密钥（测试和正式）。模块只使用秘密密钥。无需可发布密钥，因为付款在 Moyasar 页面上完成。建议在 Moyasar Dashboard 中设置 Webhook（参见“配置”）。

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

安装

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

2. 上传完成后，点击 Configure；之后也可以在模块列表中找到 VibeFox Moyasar Payment Gateway 并点击 Configure。

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

4. 粘贴您的 Moyasar 秘密密钥，然后点击 Save。在 Moyasar Dashboard 中设置 Webhook（参见“配置”）。

5. 开启 Enable/Disable，然后点击 Save。在测试模式下下一个测试订单，然后关闭 Test mode。

安装时，模块会创建两个订单状态：Awaiting Moyasar payment 和 Moyasar payment on hold。PrestaShop 会为所有货币、国家和客户群组提供一个新的付款模块。您可以在 Payment > Preferences 中进行限制。

配置

所有设置都位于模块页面：Modules > Module Manager > VibeFox Moyasar Payment Gateway > Configure。每个部分都有各自的 Save 按钮，点击后会保存整个页面。在字段上方，如果当前模式没有秘密密钥（此时结账时会隐藏该付款方式），或未保存 Webhook 共享密钥（此时 Webhook 会拒绝所有调用），或店铺默认货币不受支持，页面会向您发出提示。模块在测试模式下启用时，会显示 Test mode is active: payments are simulated, no money is charged. 保存时，模块会拒绝可发布密钥、另一模式的密钥或含空格的密钥，保留之前的值并显示原因。

Moyasar

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

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

Description：结账时显示在付款方式下方的文本。默认：You will be redirected to the secure Moyasar payment page to pay with mada, Visa, Mastercard, Apple Pay or STC Pay。测试模式下，结账时会添加 (Test mode: no real payment is made.)

API 密钥

从 Moyasar Dashboard > Settings > API Keys 复制秘密密钥。测试密钥和正式密钥是分开的。测试模式只使用测试密钥，正式模式只使用正式密钥。

Test mode：使用测试秘密密钥：付款会被模拟，不会扣除任何款项。默认：开启。关闭后，将使用正式秘密密钥接受真实付款。

Test secret key：测试模式的秘密密钥。以 sk_test_ 开头。

Live secret key：正式模式的秘密密钥。以 sk_live_ 开头。

已保存的密钥和机密信息不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。

付款通知（Webhook）

建议设置 Webhook，但并非必需。订单也会在顾客返回店铺时确认，并通过 Moyasar 在发票付款后自动发送给您店铺的发票通知进行确认。Webhook 可覆盖在返回前关闭浏览器的顾客，并能获知在 Moyasar Dashboard 中进行的退款。请将其添加到 Moyasar Dashboard > Settings > Webhooks。

Webhook URL：以只读方式显示，并附带 Copy 按钮。启用友好 URL 时，其形式如 https://your-shop/module/wcp_moyasar_payment_gateway/webhook，可能带有语言代码，例如 /en/。请完全按照设置中显示的内容复制该 URL。HTTP 方法：POST。

Webhook shared secret：输入与 Moyasar 中 Webhook 的 Shared secret 相同的值。如果尚未保存任何内容，Save 会生成一个随机密钥；Generate a new secret 会替换已保存的密钥。生成的密钥在保存后仅在设置上方显示一次，之后不再显示，因此请立即将其复制到 Moyasar。没有正确共享密钥的 Webhook 会被拒绝。

为 Webhook 选择以下事件（本节也列出了这些事件）：

payment_paid：顾客已支付发票。
payment_failed：付款失败。
payment_refunded：付款已退款，例如在 Moyasar Dashboard 中退款。
payment_voided：付款已作废。

Webhook 或通知中的任何数据都不会被直接采信：对于每一条，模块都会使用发票创建时所在模式的秘密密钥，通过 Moyasar API 读取发票，并核实其是为此购物车创建的。同一 Moyasar 账户上其他集成的付款会被忽略。同一个共享密钥适用于两种模式。

订单

Status after payment：付款确认后设置的订单状态。订单会直接以此状态创建。

Processing (default)：PrestaShop 的标准状态 Payment accepted。
Completed：每个已付款订单都会变为 Delivered。
On hold：每个已付款订单都会进入 Moyasar payment on hold，并等待您的人工审核。付款仍会记录在订单中。

高级

Clear saved secrets：勾选 Test secret key、Live secret key 或 Webhook shared secret，然后点击 Save 即可将其删除。空字段会保留已保存的值。

Debug log：将 API 调用和通知记录到模块文件夹中的 logs/moyasar_p_debug.log.php。该文件无法通过网页打开。错误和警告始终会被记录。API 密钥、银行卡数据和顾客信息从不记录。默认：关闭。

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

Clean uninstall：开启时，卸载模块会删除模块设置和日志。与订单一同保存的付款信息（Moyasar 发票和付款 ID）会被保留，以便退款仍可追溯。默认：关闭。

结账

在付款步骤中，顾客选择付款方式（默认为 Pay with Moyasar）并确认。模块会以购物车货币为购物车总额创建一张 Moyasar 发票，并将顾客引导至该发票的付款页面。顾客可在该页面使用您 Moyasar 账户中启用的任何方式付款。发票上会显示 Order #、购物车编号以及您的店铺名称。此时尚未创建订单。

只有在 Moyasar 确认后，订单才会被标记为已付款：模块会通过 Moyasar API 读取发票，并核实其已付款、属于此购物车，且金额和货币与购物车完全一致。随后订单会被创建，顾客会看到标准的订单确认页面，并显示 Your payment with Moyasar has been received. 如果 Moyasar 将付款留待审核，页面会显示 Your payment is being reviewed by Moyasar. The order will be updated automatically when Moyasar confirms it — please do not pay again. 如果订单因您的审核而处于保留状态，页面会说明已收到付款，且订单正在审核中。如果正在审核的付款之后失败，或未付款的订单被取消，页面会显示 Your Moyasar payment was not completed. Please contact us about this order.

如果顾客没有付款就返回（例如使用付款页面的返回按钮），他们会回到结账页面，并看到以下信息之一：The payment at Moyasar was not completed. You can try again or choose another payment method.、Your Moyasar payment was declined or has expired. Please try again or choose another payment method.，或者在付款暂时无法核实时显示 We could not confirm your payment with Moyasar yet. If you completed the payment, the order will be updated automatically in a few minutes — please check your e-mail before paying again. 购物车会被保留。

顾客可以重试。如果购物车仍有一个未关闭的付款页面，且金额和货币未变，则会重复使用该页面。如果购物车总额已变更，旧的付款页面会在 Moyasar 被取消并创建新的页面，因此旧页面将无法再付款。如果先前的发票结果已经付款，则会直接创建订单，而不会再创建新的付款。

如果 Moyasar 无法启动付款，顾客会留在结账页面，并看到简短提示，例如 The Moyasar payment service is not responding. Please try again in a few minutes.，并可以选择其他付款方式。详细信息会写入日志。

即使店铺处于维护模式，Webhook 和发票通知仍会正常工作，且不受店铺国家限制的影响。

模块仅在 Moyasar 页面上接受一次性付款。您自己的结账页面上没有银行卡表单，也不支持保存银行卡或令牌化、订阅，以及单独的授权和扣款。

订单与退款

订单状态

尚无订单：顾客已被引导至 Moyasar 但尚未付款，或 Moyasar 尚未确认付款。此时仅存在购物车。

Payment accepted、Delivered 或 Moyasar payment on hold：付款已确认。状态与 Status after payment 一致。付款会以 Moyasar 付款 ID 作为交易 ID 记录，备注会显示付款的确认方式（Webhook、发票通知、顾客返回或结账）、发票 ID、付款 ID 和付款方式。

Awaiting Moyasar payment：Moyasar 将付款留待审核。Moyasar 确认付款后，订单会转为已付款状态。

付款错误：正在审核的付款失败。

Moyasar payment on hold after payment：Moyasar 报告的金额或货币与购物车总额不一致（例如付款开始后，购物车在另一个标签页中被修改），或者您在取消订单后该发票才被支付。订单不会被标记为已付款，但当实际收到的金额为订单货币时，该金额会被记录。备注对此有说明。请在 Moyasar Dashboard 中核对付款，然后处理订单或退还付款。

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

已付款的订单不会因后续事件而被改回。如果同一已付款购物车的第二张发票也被付款（例如来自两个浏览器标签页），订单不会被更改。备注会提醒您在 Moyasar Dashboard 中退还重复的付款。

Moyasar 付款区块

订单页面会显示一个 Moyasar payment 区块，其中包含 Moyasar 发票 ID、付款 ID、付款方式（例如银行卡品牌和后四位数字）、状态、已付和已退款金额、测试付款的 Test mode 标识、退款记录以及订单的 Moyasar notes。

退款

在 Moyasar payment 区块中输入金额（会预填尚未退款的金额），可选填写原因，然后点击 Refund via Moyasar。确认提示 Refund this amount through Moyasar? This cannot be undone.。支持全额和部分退款。您需要具有编辑订单的权限；无需访问“模块”页面。退款会以 Moyasar 扣款时的金额和货币进行，因此在金额不一致的情况下，您最多只能退还顾客实际支付的金额，而不是订单总额。两小时内完成的银行卡付款进行全额退款时，将以撤销（void）方式处理：在结算前取消，不收取手续费。否则将作为退款处理。退款会使用付款时所用模式（测试或正式）的秘密密钥，因此必须已设置该密钥。模块会先在 Moyasar 核对付款的货币、状态和可退款金额。如果 Moyasar 不接受退款，区块会显示错误，且不会记录任何退款。成功的退款或撤销会添加到退款记录和备注中。全额退款会将订单设为 Refunded。部分退款不会更改订单状态。Moyasar 确认付款后，即可进行退款。

模块不会创建退款单（credit slip）。订单页面上标准的 PrestaShop 退款按钮不会通过 Moyasar 退款。

在 Moyasar Dashboard 中进行的退款和撤销会通过 Webhook 送达。如果 Moyasar 显示的已退款金额多于模块记录的金额，订单中会添加备注。订单状态和退款单不会自动更改。如有需要，请手动更新，而不要使用 Refund via Moyasar。

许可证密钥

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

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

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

故障排除

结账时不显示 Moyasar：请检查许可证是否有效，Enable/Disable 是否已开启，当前模式是否设置了秘密密钥（测试模式为 Test secret key，正式模式为 Live secret key），以及购物车货币是否为 SAR、AED、USD、EUR、KWD、BHD 或 OMR。当密钥缺失或店铺货币不受支持时，设置页面会显示警告。在 Payment > Preferences 中，请检查模块是否允许用于该购物车货币、顾客所在国家和顾客群组。

付款已完成，但未创建订单：确认信息没有到达您的店铺。请设置 Webhook：在 Moyasar Dashboard 中检查它是否存在、其 URL 是否与设置中的 Webhook URL 完全一致、方法是否为 POST、四个事件是否都已选中，以及其共享密钥是否与 Webhook shared secret 中保存的密钥相同。当顾客返回店铺或尝试再次支付同一购物车时，也会创建订单。

Webhook 返回 Unauthorized：Moyasar 中的共享密钥与已保存的不同。请将 Moyasar Webhook 的密钥输入 Webhook shared secret 并保存，或勾选 Generate a new secret，保存后将显示的密钥粘贴到 Moyasar 中。

Webhook 返回 Webhook secret not configured：没有保存共享密钥，例如在使用 Clear saved secrets 删除之后。请点击 Save 生成密钥，并复制到 Moyasar。

Webhook 返回 Key not configured：发票是在秘密密钥为空的模式（测试或正式）下创建的。请输入该密钥。

Webhook 返回 Verification failed 或 Try again later：无法通过 Moyasar API 读取发票，或购物车在同一时刻正被另一请求更新，或无法创建订单（例如模块已禁用）。Moyasar 会重试 Webhook。请开启 Debug log 查看原因。

Webhook URL 在浏览器中显示 Method not allowed：这是正常现象。该 URL 只接受来自 Moyasar 的 POST 请求。

保存时出现与密钥相关的错误：粘贴了可发布密钥（pk_...）或另一模式的密钥，或密钥包含空格。已保留之前的值。测试密钥以 sk_test_ 开头，正式密钥以 sk_live_ 开头。

顾客在选择 Moyasar 时看到错误：请开启 Debug log，并查看模块页面上的 Log 字段。This payment method is temporarily unavailable. Please choose another payment method or contact us. 通常表示秘密密钥错误或缺失。A payment for this order has already been received and is being reviewed. Please contact us instead of paying again. 表示该购物车已有一张已付款的发票，但无法转换为订单；请查看日志。

Order is Moyasar payment on hold after payment：请阅读 Moyasar payment 区块中的 Moyasar notes。已付金额或货币与购物车不一致，或付款是在订单取消之后到达的。请处理订单或退还付款。

退款失败：请阅读提示信息。如果付款是在另一模式下进行的，请输入该模式的秘密密钥。如果金额大于 Moyasar 中仍可退还的金额，说明部分付款已经退款，例如在 Moyasar Dashboard 中退款。如果 Moyasar 未确认已退款金额，请在重试之前，先在 Moyasar Dashboard 中核对付款。

卸载

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

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