VibeFox Moyasar for WooCommerce — 帮助

系统要求

WordPress：6.0 或更高版本。

WooCommerce：8.0 或更高版本，已安装并启用。如果 WooCommerce 版本较旧，插件会显示通知且不会加载。

PHP：8.0 或更高版本。

货币：店铺或订单的货币必须是 SAR、AED、USD、EUR、KWD、BHD 或 OMR。对于其他货币，结账时会隐藏该付款方式。

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

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

安装

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

2. 点击 Activate。

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

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

5. 粘贴您的 Moyasar 秘密密钥并保存。在 Moyasar Dashboard 中，使用设置页面显示的 URL 和共享密钥配置 Webhook（参见「配置」）。

6. 开启 Enable/Disable。在测试模式下完成一笔测试订单，然后取消勾选 Test mode。

配置

所有设置都在同一个页面：WooCommerce > Settings > Payments > Moyasar。页面标题会显示 TEST MODE 或 LIVE 标识。在字段上方，如果当前模式没有秘密密钥（此时结账时会隐藏该付款方式）或店铺货币不受支持，页面会向您发出警告；测试模式开启时，页面会显示 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：Enable test mode 使用测试秘密密钥：付款会被模拟，不会扣除任何款项。默认：开启。关闭后，将使用正式秘密密钥接受真实付款。

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

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

付款通知（Webhook）

建议设置 Webhook，但并非必需。订单也会在顾客返回店铺时确认，并通过 Moyasar 在发票付款后自动发送给您店铺的发票通知进行确认。Webhook 可覆盖在返回前关闭浏览器的顾客，并会通知您在 Moyasar Dashboard 中进行的退款。请在 Moyasar Dashboard > Settings > Webhooks 中，使用本节中的 URL 和共享密钥添加 Webhook，HTTP 方法为 POST。

Webhook URL：以只读方式显示，并带有 Copy 按钮。格式类似：https://your-site/wp-json/moyasar_p/v1/webhook。HTTP 方法：POST。

Webhook shared secret：输入与 Moyasar 中 Webhook 的 Shared secret 相同的值。将此项留空并保存即可生成随机密钥，然后点击 Show 并将其复制到 Moyasar。没有正确共享密钥的 Webhook 会被拒绝。

请为 Webhook 选择以下事件：

Webhook 或通知本身不会被直接信任：对于每一项，插件都会使用订单所在模式的秘密密钥，通过 Moyasar API 读取发票，并核实该发票是为此订单创建的。同一 Moyasar 账户中其他集成的付款将被忽略。

订单

Status after payment：付款确认后订单设置的状态。状态会立即设置，不会再次变更。

高级

Debug log：Log API calls and notifications 会将详细信息写入 WooCommerce > Status > Logs，来源为 wcp_moyasar_payment_gateway。错误始终会被记录。API 密钥、银行卡数据和顾客信息从不记录。默认：关闭。

Clean uninstall：Delete the plugin settings and logs when the plugin is deleted。订单上保存的付款信息（Moyasar 发票和付款 ID）会保留，以便退款仍可追溯。默认：关闭。

结账

顾客选择付款方式（默认为 Pay with Moyasar）并提交订单。插件会以订单货币为订单总额创建 Moyasar 发票，并将顾客带到其付款页面。顾客可在该页面使用您 Moyasar 账户中启用的任意付款方式付款，例如 mada、Visa、Mastercard、Apple Pay 或 STC Pay。发票会显示 Order、订单号以及您的网站名称。

只有在 Moyasar 确认后，订单才会被标记为已付款：插件会通过 Moyasar API 读取发票，并核实其已付款、属于此订单，且金额和货币与订单完全一致。付款后，顾客会返回您店铺的订单接收页面。如果顾客未付款就返回（例如点击付款页面的返回按钮），他们会回到结账页面或 Pay for 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 无法发起付款，顾客会看到简短提示，例如 The Moyasar payment service is not responding. Please try again in a few minutes.，并可选择其他付款方式。详细信息会写入日志。

该付款方式适用于经典结账、结账区块和 Pay for order 页面。它兼容 WooCommerce 高性能订单存储（HPOS）。

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

订单与退款

订单状态

Pending payment：发票已创建，顾客尚未付款。订单备注会显示发票 ID、金额和模式。

Processing、Completed 或 On hold：付款已确认。状态遵循 Status after payment 的设置。订单备注会显示付款的确认方式（Webhook、发票通知、顾客返回或结账）、发票 ID、付款 ID 和付款方式。交易 ID 即 Moyasar 付款 ID。

付款后 On hold：Moyasar 报告的金额或货币与订单总额不一致（订单不会标记为已付款），或者发票是在订单取消后才付款的。订单备注会说明原因。请在 Moyasar Dashboard 中核查该付款，然后完成订单或退款。

付款前 On hold：Moyasar 正在对该付款进行审核。Moyasar 作出决定后，订单会更新。

Failed：未付款订单的最新发票失败、过期或被取消。顾客可以重新尝试付款。

Cancelled：订单被顾客、您或 WooCommerce 库存保留超时取消。订单的 Moyasar 未结发票也会被取消，因此无法再付款。

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

退款

打开订单，点击 Refund，输入金额，然后点击 Refund via Pay with Moyasar（该按钮使用付款方式的标题）。使用 Moyasar 付款的订单支持全额和部分退款。两小时内完成的银行卡付款进行全额退款时，将以撤销（void，结算前取消）方式处理；否则为退款。退款使用付款时所在模式（测试或正式）的秘密密钥，因此必须已设置该密钥。退款前，插件会在 Moyasar 核查付款的货币、状态以及仍可退款的金额。如果 Moyasar 不接受退款，WooCommerce 会显示错误，且不会记录退款。成功的退款或撤销会添加到订单备注中。

在 Moyasar Dashboard 中进行的退款和撤销会通过 Webhook 送达。如果 Moyasar 显示的退款金额高于 WooCommerce 记录的金额，订单中会添加备注。这些退款不会自动记录为 WooCommerce 退款。如有需要，请在 WooCommerce 中创建手动退款，而不要使用 Refund via Pay with Moyasar。

许可证密钥

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

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

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

许可证到期后，插件仍可继续运行，但更新和技术支持需要续费。状态会在后台自动重新检查。

故障排除

结账时没有显示 Moyasar：请检查许可证是否有效、Enable/Disable 是否已开启、当前模式是否设置了秘密密钥（测试模式为 Test secret key，正式模式为 Live secret key），以及店铺或订单货币是否为 SAR、AED、USD、EUR、KWD、BHD 或 OMR。如果缺少密钥或货币不受支持，设置页面会显示警告。

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

Webhook 返回 Unauthorized：Moyasar 中的共享密钥与 Webhook shared secret 不一致。请点击 Show，复制该值，并将其粘贴到 Moyasar 中的 Webhook 里。

Webhook 返回 Webhook secret not configured：设置尚未保存共享密钥。请保存设置以生成共享密钥，并将其复制到 Moyasar。

Webhook 返回 Key not configured：该订单是在秘密密钥为空的模式（测试或正式）下付款的。请输入该密钥。

Webhook 返回 Verification failed 或 Try again later：无法通过 Moyasar API 读取发票，或订单在同一时刻正被另一请求更新。Moyasar 会重试该 Webhook。

保存时出现与密钥相关的错误：粘贴了可发布密钥（pk_...）或其他模式的密钥。已保留原值。测试密钥以 sk_test_ 开头，正式密钥以 sk_live_ 开头。

顾客下单时出现错误：请开启 Debug log，并查看 WooCommerce > Status > Logs，来源为 wcp_moyasar_payment_gateway。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. 表示该订单已有一张需要您审核的已付款发票。

订单显示 On hold after payment：请阅读订单备注。已付金额或货币与订单不一致，或付款是在订单取消之后到达的。请完成订单或为付款退款。

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

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

卸载

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

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