VibeFox Moyasar for OpenCart — 帮助

要求

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

PHP：8.0 或更高版本。

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

Moyasar 账户：您需要 Moyasar 账户的密钥 API 密钥（测试和正式）。仅使用密钥（secret key）。无需可公开的密钥（publishable key），因为付款在 Moyasar 页面上完成。建议在 Moyasar Dashboard 中设置一个 Webhook（参见配置）。

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

安装

下载文件是一个 zip 文件，内含两个 OpenCart 版本的软件包。请先解压到您的电脑上。其中包含 README.txt、OpenCart 3 软件包 wcp_moyasar_payment_gateway-oc3-(version).ocmod.zip 和 OpenCart 4 软件包 wcp_moyasar_payment_gateway.ocmod.zip。只需安装适合您 OpenCart 版本的软件包。两个版本的许可证密钥相同。

OpenCart 3

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

2. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox Moyasar Payment Gateway，点击 Install（绿色的 + 按钮）。您的管理员用户需要有修改付款扩展列表的权限。

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

4. 粘贴您的 Moyasar 密钥，然后点击 Save。首次保存时会生成 Webhook 共享密钥，并在设置上方显示一次。请使用它在 Moyasar Dashboard 中设置 Webhook（参见配置）。

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

OpenCart 4

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

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

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

4. 按照 OpenCart 3 的第 3 至 5 步输入许可证密钥、Moyasar 密钥和 Webhook。两个版本的设置页面及其字段相同。只有 Webhook URL 不同（参见 Webhook URL）。

新安装时，付款方式默认关闭，测试模式默认开启。

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox Moyasar Payment Gateway > Edit。各部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，当当前模式没有密钥时（此时结账时会隐藏该付款方式）、没有保存 Webhook 共享密钥时（此时 Webhook 会拒绝所有调用）或商店的默认货币不受支持时，页面会发出提醒。扩展在测试模式下启用时，会显示 测试模式已激活：付款将被模拟，不会扣除任何款项。 如果您没有修改该扩展的权限，页面会显示设置，但无法保存。

保存时，Title 必须为 1 至 128 个字符，Sort Order 必须为整数（允许负数），Total 必须为大于或等于 0 的数字，且地理区域和订单状态必须存在；否则不会保存任何内容。扩展会拒绝可公开密钥、另一模式的密钥或包含空格的密钥：其余内容将保存，并显示 设置已保存，但红色显示的密钥除外。，之前的密钥保持不变，并显示原因。如果在没有当前模式密钥的情况下启用扩展，设置会保存并显示警告。

Moyasar

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

Title：客户在结账时看到的付款方式名称。它也是保存在订单中的付款方式名称。默认：Pay with Moyasar。必填，最多 128 个字符。

Description：客户在 Confirm Order 步骤中、确认按钮上方看到的文字。默认：You will be redirected to the secure Moyasar payment page to pay with mada, Visa, Mastercard, Apple Pay or STC Pay. 在测试模式下，该步骤会追加 （测试模式：不会进行真实付款。）

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

Geo Zone：仅向付款地址位于所选地理区域内的客户提供 Moyasar。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。

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

API 密钥

请从 Moyasar Dashboard > Settings > API Keys 复制密钥（页面中有链接）。测试密钥和正式密钥是分开的。测试模式仅使用测试密钥；正式模式仅使用正式密钥。

Test mode：使用测试密钥：付款将被模拟，不会扣除任何款项。默认：开启。关闭后，将使用正式密钥接受真实付款。另一模式的发票在进行状态查询和退款时，仍会使用其自身模式的密钥。

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

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

已保存的密钥和机密信息不会再次显示。该字段保持为空，并显示 已保存——留空即可保留。 只有在需要更改时才输入新值。要删除已保存的值，请勾选字段下方的 Clear the saved value on save，然后点击 Save。

付款通知（Webhook）

建议设置 Webhook，但并非必需。客户返回商店时，以及 Moyasar 在发票付款后自动发送给您商店的发票通知，也会确认订单。Webhook 可覆盖在返回前关闭浏览器的客户，并报告在 Moyasar Dashboard 中所做的退款。请在 Moyasar Dashboard > Settings > Webhooks 中添加。

Webhook URL：以只读方式显示，并带有 Copy 按钮。OpenCart 3 的格式类似于 https://your-store/index.php?route=extension/payment/wcp_moyasar_payment_gateway/webhook，OpenCart 4 的格式类似于 https://your-store/index.php?route=extension/wcp_moyasar_payment_gateway/payment/wcp_moyasar_payment_gateway.webhook，由您的 OpenCart 安装的商店前台地址生成。请完全按照设置中显示的内容复制 URL。HTTP 方法：POST。该 URL 必须可以从互联网访问。

Webhook shared secret：输入与 Moyasar 中 Webhook 的 Shared secret 相同的值，或勾选 Generate a new secret 并保存。如果没有保存任何内容，Save 会生成一个随机密钥。保存后，生成的密钥会在设置上方显示一次，之后不再显示，因此请立即将其复制到 Moyasar 中。没有正确共享密钥的 Webhook 会被拒绝。同一个共享密钥适用于两种模式。

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

Webhook 或通知中的任何内容都不会被直接信任：对于每一条，扩展都会使用创建该发票所在模式的密钥，通过 Moyasar API 读取发票，并检查该发票是否由本商店创建。同一 Moyasar 账户上其他集成的付款会被忽略。

订单

OpenCart 在 Confirm Order 步骤创建订单时没有状态（缺失订单）。只有在 Moyasar 确认发票后，订单才会获得状态。下面的每个字段都会列出您的 OpenCart 订单状态。

Status after payment：确认付款后设置的状态。默认：处理中。如果希望已付款的订单立即完成，请选择 Complete；如果希望每笔已付款订单都等待人工审核，请选择您的审核状态。

Awaiting Moyasar payment status：Moyasar 会将付款保留以供审核；当 Moyasar 确认付款后，订单会转为 Status after payment。默认：待处理。

Moyasar payment on hold status：Moyasar 报告的金额或货币与订单总额不符，或者发票是在订单被取消或更改为其他状态之后才付款的。订单不会被标记为已付款。默认：待处理，因为 OpenCart 没有“暂停”状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择它。

Payment error status：正在审核的付款失败了。默认：失败。

Refunded status：在订单页面将付款全额退款后设置。默认：已退款。

高级

Debug log：将 API 调用和通知记录到 OpenCart 日志文件夹（storage/logs）中的 moyasar_p_debug.log.php。该文件无法通过网页打开，达到 5 MB 时会被移至 moyasar_p_debug.old.log.php。错误和警告始终会被记录。API 密钥、银行卡数据和客户详细信息绝不会被记录。默认：关闭。

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

Clean uninstall：开启后，卸载扩展会删除网关设置和日志。与订单一起保存的付款详情（Moyasar 发票和付款 ID）会被保留，以便退款仍可追溯。默认：关闭。

导入 / 导出

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

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

结账

在 Payment Method 步骤中，客户选择付款方式（默认为 Pay with Moyasar）。在 Confirm Order 步骤中，客户会看到您的描述。OpenCart 在此步骤创建订单，此时仍没有状态。当客户点击 Confirm Order 时，扩展会以订单货币为订单总额创建一张 Moyasar 发票，并将客户转到其付款页面。在那里，客户可使用您 Moyasar 账户中任何已启用的方式付款。在 OpenCart 4 中，客户在付款方式区块中点击 Choose 按钮，在 Payment method options 窗口中选择付款方式，然后点击结账页面底部的 Confirm Order。发票会显示 Order #、订单号和您的商店名称。

只有在 Moyasar 确认之后，订单才会被标记为已付款：扩展会通过 Moyasar API 读取发票，并检查其是否已付款、是否属于该订单，且金额和货币与订单完全一致。随后，订单会以 OpenCart 的标准方式获得状态，并发送常规的订单电子邮件、更新库存；客户会看到 OpenCart 的订单成功页面，显示 Moyasar 付款已收到。 如果 Moyasar 将付款保留以供审核，页面会显示 您的付款正在由 Moyasar 审核。Moyasar 确认后，订单将自动更新——请勿重复付款。 如果订单因您的审核而暂停，页面会显示 我们已收到您的付款，正在审核您的订单。如有需要，我们会与您联系——请勿重复付款。 如果正在审核的付款之后失败，页面会显示 您的 Moyasar 付款未完成。请就此订单与我们联系。

如果客户未付款就返回（例如使用付款页面的后退按钮），他们会回到结账页面，并看到以下消息之一：Moyasar 上的付款未完成。您可以重试，或选择其他付款方式。、您的 Moyasar 付款被拒绝或已过期。请重试，或选择其他付款方式。，或者当付款暂时无法核实时，显示 我们尚无法确认您在 Moyasar 上的付款。如果您已完成付款，订单将在几分钟内自动更新——请在再次付款前检查您的电子邮件。 在 OpenCart 4 中，这些消息显示在结账页面上方。购物车会被保留。

客户可以重试。OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单，OpenCart 4 则为结账保留一个订单，并重新支付同一订单。扩展会先检查同一购物车的未结发票：如果此订单当前未结的付款页面仍具有相同的模式、金额和货币，则会重复使用；否则，旧发票会在 Moyasar 中被取消，并创建新发票，因此旧发票将无法再付款。如果发现购物车的某张先前发票已经付款，则会确认该付款，而不是创建新付款。

OpenCart 4 会在显示成功页面之前将订单保留在结账流程中。如果该订单在此期间未付款即被关闭（例如您取消了它，或其付款失败），客户会被送回结账页面，并看到 Your previous order was cancelled or its payment failed. Please confirm the order again.，下一次点击 Confirm Order 将为新订单付款。已付款后又被取消或退款的购物车订单，不再占用该购物车。

如果 Moyasar 无法开始付款，客户会停留在 Confirm Order 步骤，并在按钮上方看到一条简短提示，例如 Moyasar 付款服务无响应。请在几分钟后重试。，并可选择其他付款方式。详细信息会写入日志。

即使商店处于维护模式，Webhook 和发票通知也能正常工作，因为 OpenCart 3 允许付款扩展的请求通过，而在 OpenCart 4 中，扩展会为这些请求添加启动操作（startup action），这也使客户能够从 Moyasar 返回。

该扩展仅在 Moyasar 页面上处理一次性付款。您自己的结账页面上没有银行卡表单，不支持已保存的银行卡或令牌化，不支持订阅，也不支持分开的授权和扣款。

订单与退款

订单状态

无状态（缺失订单）：客户已被转到 Moyasar 但未付款，Moyasar 尚未确认付款，或付款被拒绝、已过期或已取消。在 Sales > Orders 中，此类订单仅在 Order Status 筛选器设置为 Missing Orders 时显示。

Status after payment（默认 处理中）：付款已确认。备注会显示付款是如何确认的（Webhook、发票通知、客户返回或结账页面）、发票 ID、付款 ID 以及付款方式，例如银行卡品牌和后四位数字。

Awaiting Moyasar payment status（默认 待处理）：Moyasar 会将付款保留以供审核。当 Moyasar 确认付款时，订单会转为 Status after payment；付款失败时则转为 Payment error status。

Moyasar payment on hold status（默认 待处理）：Moyasar 报告的金额或货币与订单总额不符，或者发票是在您取消订单或更改其状态之后才付款的。订单不会被标记为已付款，但实际扣款金额会被记录，以便退款。备注会解释原因。请在 Moyasar Dashboard 中检查付款，然后履行订单或为付款退款。

Payment error status（默认 失败）：正在审核的付款失败了。

Refunded status（默认 已退款）：付款已通过该扩展全额退款。

已付款或已退款的订单不会因后续事件而被改回。如果您自己已经设置了已付款状态，付款会被记录，但状态不会更改。如果一个已付款购物车的第二张发票也被付款（例如从两个浏览器标签页付款），已付款的订单不会被更改。备注会要求您在 Moyasar Dashboard 中为重复付款退款。

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

VibeFox Moyasar Payment Gateway 选项卡

在 Sales > Orders 中，打开一笔通过 Moyasar 付款的订单。在订单页面底部，紧挨 History 和 Additional 的位置，VibeFox Moyasar Payment Gateway 选项卡会显示 Moyasar invoice（测试付款带有 Test mode 标签）、Moyasar payment、Method、Status、Paid / refunded 金额、退款表单、退款历史以及该订单的 Moyasar notes。该选项卡对有权访问该扩展的用户可见。

退款

在 VibeFox Moyasar Payment Gateway 选项卡中输入 Amount（会自动填入尚未退款的金额），可选填写 Reason (optional)，然后点击 Refund via Moyasar。确认提示 通过 Moyasar 退还此金额？此操作无法撤销。 支持全额退款和部分退款。您需要拥有修改该扩展的权限（在 System > Users > User Groups 中设置）。退款以 Moyasar 扣款的金额和货币进行，因此在金额不一致的情况下，您最多只能退还客户实际支付的金额，而不是订单总额。对于 2 小时以内完成的银行卡付款，全额退款会以作废（void，结算前取消，不收取费用）的方式发送；STC Pay 付款及所有其他情况则正常退款。退款使用付款所在模式（测试或正式）的密钥，因此该模式的密钥必须已设置。扩展会先在 Moyasar 处检查该付款的货币、状态和可退款金额。如果 Moyasar 不接受退款，选项卡会显示错误，且不会记录任何退款。退款或作废成功后，会添加到退款历史和备注中。全额退款会将订单设为 Refunded status，且不会通知客户，也不会将商品退回库存，与手动更改状态的效果相同。部分退款不会更改状态。只有在 Moyasar 确认付款后，退款才可用。

Sales > Returns 中的商品退货不会通过 Moyasar 退还款项。

在 Moyasar Dashboard 中完成的退款和作废会通过 Webhook 送达。如果 Moyasar 显示的退款金额超过扩展已记录的金额，订单中会添加一条备注。订单状态不会自动更改。如有需要，请手动更新，无需使用 Refund via Moyasar。

许可证密钥

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

如果密钥未被接受，区块会说明原因，例如 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. 以同一浏览器登录管理后台的管理员用户，仍会在商店中看到该付款方式，并标记为 (unlicensed — visible to admins only)，这样您可以在购买密钥之前设置和测试该扩展。在 OpenCart 4 上此预览不可用：商店无法看到管理员的登录状态，因此没有有效密钥时，该付款方式对所有人都隐藏。打开一次 Edit 页面后，管理后台的 Dashboard 上会出现一条提醒。点击 × 可将其隐藏 7 天。现有订单不受影响：已发起的付款仍会被确认，退款也仍然可用。

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

故障排除

Moyasar 未出现在结账页面：请检查许可证是否有效、Enable/Disable 是否开启，以及当前模式是否有密钥：测试模式需要 Test secret key，正式模式需要 Live secret key。缺少密钥时，设置页面会显示警告。客户必须使用 SAR、AED、USD、EUR、KWD、BHD 或 OMR 付款（即商店中选择的货币）。另外，请检查付款地址是否位于所选的 Geo Zone 内，以及订单是否达到设置中的 Total。

付款已完成，但订单仍无状态：确认信息未能到达您的商店。请设置 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 the saved value on save 将其移除之后。请点击 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_ 开头。

客户在 Confirm Order 之后看到错误：请开启 Debug log，并查看扩展页面上的 Log 字段。This payment method is not available. 表示结账会话已与订单不匹配，或付款方式在此期间已被关闭：客户需要重新加载结账页面。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. 表示购物车已有一张已付款的发票，但无法设置其订单状态；请检查日志。

订单在付款后处于暂停状态：请阅读 VibeFox Moyasar Payment Gateway 选项卡中的 Moyasar notes。付款金额或货币与订单不一致，或付款是在订单取消之后到达的。请履行订单或为付款退款。

选项卡中没有退款表单：选项卡会说明原因：付款尚未确认、已全额退款，或您的用户组没有修改该扩展的权限。

退款失败：请阅读提示信息。如果付款是在另一模式下完成的，请输入该模式的密钥。如果金额大于 Moyasar 处仍可退还的金额，说明部分付款已经退款，例如在 Moyasar Dashboard 中。如果 Moyasar 未确认已退款的金额，请先在 Moyasar Dashboard 中检查该付款，然后再重试。

对于开发人员：扩展会触发 OpenCart 事件 moyasar_p_supported_currencies 和 moyasar_p_invoice_params，以更改支持的货币和发票数据。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Moyasar Payment Gateway 旁边的 Uninstall（红色的 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除该扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Orders 部分中的订单状态（重新安装时恢复为默认值）。该扩展的 OpenCart 事件也会被删除（在 OpenCart 4 中，还会删除其事件以及允许 Webhook 通过维护模式的启动操作）。如果开启了 Clean uninstall，其余网关设置（标题、描述、测试模式、密钥、Webhook 共享密钥、调试日志）和日志也会被删除。如果关闭，它们会被保留，以便日后重新安装时使用。Moyasar 的发票、付款和退款记录始终会被保留，因此旧订单在重新安装后仍可退款。现有订单会保留其付款备注。

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

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