CMS 与电商插件

我们的插件让您无需编写代码即可接受塞拉利昂 Orange Money 付款。所有插件的工作方式相同：

创建订单后，客户被重定向到 SOAMTAR 付款页面（POST https://app.so-amtar.com/v1/payments 返回的 payment_url）。
客户在手机上输入 Orange Money PIN 确认付款。
SOAMTAR 向您的商店发送已签名的 webhook；只有金额和币种一致时，订单才会被标记为已付款。

平台	包 / 目录	版本	要求	币种
WooCommerce	`soamtar-woocommerce-gateway`	1.1.0	WordPress 5.8+、WooCommerce 6.0+、PHP 7.4+	SLE、USD、EUR
Magento 2	`soamtar/magento2-payment`（`Soamtar_Payment`）	1.1.0	Magento 2.4.4+、PHP 8.1+	SLE、USD、EUR
PrestaShop	`soamtar`	1.1.0	PrestaShop 1.7.7+ / 8、PHP 7.4+	SLE、USD、EUR
Drupal Commerce	`soamtar_commerce`	1.1.0	Drupal 9.3+ / 10 / 11、Commerce 2.x、PHP 8.1+	SLE、USD、EUR
Odoo	`payment_soamtar`	17.0.1.1.0	Odoo 17.0、Python 3.10+	仅 SLE

尚未上架应用市场

这些插件尚未发布到 WordPress、Magento、PrestaShop、Drupal 或 Odoo 的应用市场。请按下文所示从代码仓库安装（git clone 或 zip）。

通用配置

每个插件都需要 SOAMTAR 控制台中的三个值：

值	来源
测试密钥 `sk_test_…`	API 密钥。付款在同一主机（`https://app.so-amtar.com/v1`）上模拟，不会产生真实资金流动。
正式密钥 `sk_live_…`	API 密钥，账户开通生产环境后可用。
Webhook 密钥	在控制台（Developers → Webhooks）注册的 webhook 端点的签名密钥。即使使用 `callback_url` 也始终必需。

每个插件都有一个 Test mode 开关，用于选择测试密钥或正式密钥。密钥只保存在您的服务器上，切勿放入主题或 JavaScript 文件。

Webhook URL：HTTPS 商店自动配置。 每个插件都会在每笔支付中把自己的 webhook URL 作为 callback_url 发送。SOAMTAR 随后把该支付（及其退款）的签名事件投递到商店，payload、签名和重试与已注册端点完全相同。SOAMTAR 使用同一环境中最早创建的有效 webhook 端点的密钥签名这些投递，因此您仍需在控制台中至少有一个端点，并把其签名密钥填入插件。

callback_url 必须是公网 HTTPS。如果商店未使用 HTTPS，插件会省略它，并提示您（管理通知、日志或配置页）在控制台中把下文给出的商店 URL 注册为 webhook 端点，订阅 payment.success、payment.failed、payment.cancelled、payment.expired、refund.success、refund.failed、payment.refunded 和 payment.partially_refunded（Odoo：所有 payment.* 和 refund.* 事件）。保持默认（legacy）payload 版本。

控制台的 Send test event（webhook.test）会得到所有插件的 200 响应，且不会修改任何订单。

所有插件都会校验 X-Soamtar-Signature 请求头（t=<unix>,v1=<hex>，密钥轮换期间还会带 v2=）：使用 webhook 密钥对 "<t>.<原始请求体>" 计算 HMAC-SHA256，容差 300 秒。参见 Webhooks。

退款

所有插件都支持在商店后台原生退款。它们使用 SOAMTAR 交易 id 和金额（全额或部分）调用 POST https://app.so-amtar.com/v1/refunds。SOAMTAR 把款项退回付款人的 Orange Money 号码，并从您的 SOAMTAR 余额中扣除。退款是异步的：最终结果通过 refund.success 或 refund.failed（以及 payment.refunded / payment.partially_refunded）通知。API 密钥需要 can_refund 权限，且余额必须足以覆盖金额。

平台	如何退款
WooCommerce	订单上的 Refund via SOAMTAR
Magento 2	从发票创建在线贷项凭证（Refund，而非 "Refund Offline"）
PrestaShop	贷项单（标准退款、部分退款或退货），需启用 Refund through Orange Money（`SOAMTAR_AUTO_REFUND`，默认开启）
Drupal Commerce	支付上的 Refund（网关实现 `SupportsRefundsInterface`）
Odoo	支付上的 Refund 按钮（全额或部分）

API 详见 Refunds。

WordPress / WooCommerce

支持经典结账和购物车/结账区块，兼容 HPOS。

安装

bash

cd wp-content/plugins
git clone <仓库地址> soamtar-woocommerce-gateway

或在 插件 → 安装插件 → 上传插件 中上传该目录的 zip 包，然后启用 SOAMTAR for WooCommerce。将商店币种设为 SLE、USD 或 EUR。

设置

WooCommerce → 设置 → 付款 → SOAMTAR（界面标签为英文）：

设置	说明
Enable/Disable	在结账页显示该网关。
Title / Description	结账页文字（默认 "Orange Money"）。
Test mode	使用测试密钥。
Live secret key / Test secret key	`sk_live_…` / `sk_test_…`，加密存储。
Webhook secret	必填。
Success redirect URL (optional)	默认：WooCommerce 的“订单已收到”页面。
Failure redirect URL (optional)	默认：订单付款页面。
Debug log	WooCommerce → 状态 → 日志，来源 `soamtar-gateway`。

只要缺少密钥、webhook 密钥或受支持的商店币种，网关就会隐藏，并在后台显示提示。

Webhook URL

https://your-store.example/wp-json/soamtar/v1/webhook

旧地址 https://your-store.example/?wc-api=wc_soamtar_gateway 也可使用。

行为

payment.success：仅当 amount 和 currency 与订单一致时才完成订单，否则订单被置为保留并附加备注。
payment.failed、payment.cancelled、payment.expired：订单标记为失败（已付款的订单除外）。
付款失败后重新尝试时使用 merchant_ref 1001-2、1001-3 ……（每个参考号只能使用一次）。
账单电话会尽可能转换为 +232XXXXXXXX；否则客户在付款页面输入号码。
Webhook 受到按 IP 限流、1 MB 请求体上限、去重、审计日志以及可选 IP 白名单（过滤器 soamtar_webhook_ip_allowlist）的保护。

Magento 2

安装

将模块复制到 app/code/Soamtar/Payment/，或将仓库声明为 Composer VCS/path 仓库后运行 composer require soamtar/magento2-payment。然后：

bash

php bin/magento module:enable Soamtar_Payment
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento cache:flush

设置

Stores → Configuration → Sales → Payment Methods → SOAMTAR — Orange Money (Sierra Leone)

字段	配置路径
Enabled	`payment/soamtar/active`
Title（默认 "Orange Money"）	`payment/soamtar/title`
Test mode	`payment/soamtar/testmode`
Test secret key (sk_test_…)	`payment/soamtar/test_secret_key`（加密）
Live secret key (sk_live_…)	`payment/soamtar/live_secret_key`（加密）
Webhook secret	`payment/soamtar/webhook_secret`（加密）
Payment from applicable countries / specific countries	`payment/soamtar/allowspecific`、`payment/soamtar/specificcountry`
Debug log	`payment/soamtar/debug`
Sort order	`payment/soamtar/sort_order`

仅当订单币种为 SLE、USD 或 EUR 时才提供该付款方式。

Webhook URL

https://your-store.example/soamtar/webhook/notify

行为

订单以 pending_payment 状态创建，随后 /soamtar/payment/redirect 创建 SOAMTAR 付款（Idempotency-Key: mage_<increment id>_<protect code>）并重定向到 payment_url。API 调用失败时订单被取消、购物车被恢复。
金额和币种正确的 payment.success 会登记收款（发票）并将订单转为 processing；不一致时订单被置为保留并附加评论。
payment.failed、payment.cancelled、payment.expired：取消处于 pending_payment 的订单。
/soamtar/payment/cancel（失败 URL）只恢复购物车。退款时，创建在线贷项凭证（Refund）：模块会调用 POST/v1/refunds。

PrestaShop

安装

bash

cd modules
git clone <仓库地址> soamtar

目录必须命名为 soamtar。也可以打包成 soamtar/… 的 zip，在 模块 → 模块管理器 → 上传模块 中上传，然后安装 SOAMTAR — Orange Money。

设置

模块 → SOAMTAR — Orange Money → 配置

字段	配置键	说明
Test mode	`SOAMTAR_TEST_MODE`	默认开启。
Test secret key	`SOAMTAR_TEST_SECRET_KEY`	`sk_test_…`
Live secret key	`SOAMTAR_LIVE_SECRET_KEY`	`sk_live_…`
Webhook secret	`SOAMTAR_WEBHOOK_SECRET`

密码字段留空会保留已保存的值。还需在 付款 → 偏好设置 中为 SLE、USD 或 EUR 启用该模块：只有当前密钥和 webhook 密钥已设置且购物车币种受支持时，才会显示该付款选项。

Webhook URL

https://your-shop.example/module/soamtar/webhook

确切的 URL（取决于友好 URL 设置）显示在配置页面上。

行为

订单以 “Awaiting Orange Money payment” 状态创建；API 调用失败时转为 “付款错误” 并恢复购物车。
只修改仍在等待付款的订单：金额和币种正确的 payment.success → “付款已接受”；payment.failed → “付款错误”；payment.cancelled / payment.expired → “已取消”。金额或币种不同时订单保持待付款并记录错误。
module/soamtar/return 显示确认页或恢复购物车，从不更改订单状态。

Drupal Commerce

站外（offsite）支付网关。付款在客户返回时（查询状态）或收到 webhook 时记录，以先到者为准。

安装

将模块复制到 modules/custom/soamtar_commerce（或将仓库声明为 Composer VCS/path 仓库后运行 composer require soamtar/drupal-commerce），然后：

bash

drush en soamtar_commerce -y
drush cr

设置

Commerce → 配置 → 支付网关 → 添加支付网关，插件选择 SOAMTAR (Orange Money Sierra Leone)。

设置	说明
Mode	Test 使用测试密钥，Live 使用正式密钥。
Test secret key (sk_test_…)	留空则保留已保存的值。
Live secret key (sk_live_…)	留空则保留已保存的值。
Webhook secret	保存网关后，webhook URL 会显示在该字段下方。

Webhook URL

https://your-site.example/payment/notify/<网关机器名>

行为

merchant_ref 为 <订单 id>-<尝试次数>。如果账单资料有 field_phone 字段，会发送 +232 号码。
客户返回时，模块调用 GET /v1/status/{交易 id}：success 记录付款；failed、cancelled 或 expired 将客户送回结账页；待处理的付款会让订单完成并等待 webhook。
payment.success 对每笔 SOAMTAR 交易只记录一次已完成付款，且仅当 amount 和 currency 与订单余额一致时。

Odoo

适用于 Odoo 电商、发票和付款链接的支付提供商。

安装

将 payment_soamtar/ 复制到 Odoo 的 addons 路径。
重启 Odoo，更新应用列表，搜索 SOAMTAR Payment Provider 并安装。
启用 SLE 币种（会计 → 配置 → 币种）。该提供商仅对 SLE 订单提供。

设置

开票 / 网站 → 配置 → 支付提供商 → SOAMTAR (Orange Money)

字段	值
状态	测试模式（使用 `sk_test_…`）或已启用（使用 `sk_live_…`）
Test Secret Key / Live Secret Key	来自 SOAMTAR 控制台
Webhook Secret	下方端点的签名密钥

Webhook URL

https://your-odoo.example/payment/soamtar/webhook

行为

merchant_ref 为 Odoo 交易参考号；客户返回到 /payment/soamtar/return。
无论是客户返回还是收到 webhook，Odoo 都会通过 SOAMTAR API 读取付款状态（从不信任浏览器 URL 或 webhook 请求体），校验金额和币种后确认、取消或将交易标记为失败。
密钥不匹配（或服务器时钟偏差超过 5 分钟）时 webhook 返回 400；未配置 Webhook Secret 时返回 503。

CMS 与电商插件 ​

通用配置 ​

退款 ​

WordPress / WooCommerce ​

安装 ​

设置 ​

Webhook URL ​

行为 ​

Magento 2 ​

安装 ​

设置 ​

Webhook URL ​

行为 ​

PrestaShop ​

安装 ​

设置 ​

Webhook URL ​

行为 ​

Drupal Commerce ​

安装 ​

设置 ​

Webhook URL ​

行为 ​

Odoo ​

安装 ​

设置 ​

Webhook URL ​

行为 ​

CMS 与电商插件

通用配置

退款

WordPress / WooCommerce

安装

设置

Webhook URL

行为

Magento 2

安装

设置

Webhook URL

行为

PrestaShop

安装

设置

Webhook URL

行为

Drupal Commerce

安装

设置

Webhook URL

行为

Odoo

安装

设置

Webhook URL

行为