CMS & e-commerce plugins

Our plugins let you accept Orange Money Sierra Leone without writing code. They all work the same way:

1. The order is created and the customer is redirected to the SOAMTAR payment page (payment_url returned by POST https://app.so-amtar.com/v1/payments).
2. The customer approves the payment on their phone with their Orange Money PIN.
3. SOAMTAR sends a signed webhook to your store, which marks the order paid only if the amount and currency match.
4. Refunds are made from the store back office: SOAMTAR sends the money back to the payer's Orange Money number (see Refunds).

Platform	Package / folder	Version	Requirements	Currencies
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 only

Not yet on the marketplaces

The plugins are not published on the WordPress, Magento, PrestaShop, Drupal or Odoo marketplaces yet. Install them from the repository (git clone or zip) as shown below.

Common setup

Every plugin needs three values from the SOAMTAR dashboard:

Value	Where it comes from
Test secret key sk_test_…	API keys. Payments are simulated on the same host (https://app.so-amtar.com/v1): no real money moves.
Live secret key sk_live_…	API keys, once your account is activated for production.
Webhook secret	The signing secret of a webhook endpoint registered in the dashboard (Developers → Webhooks). Always required, even when callback_url is used.

Each plugin has a Test mode switch that picks the test or the live key. Secret keys stay on your server; never put them in a theme or JavaScript file.

Webhook URL: automatic on HTTPS stores. Every plugin sends its own webhook URL as callback_url with each payment. SOAMTAR then delivers the signed events of that payment (and of its refunds) to the store, with the same payload, signature and retries as a registered endpoint. SOAMTAR signs these deliveries with the secret of your oldest active webhook endpoint in the same environment, so you still need at least one endpoint in the dashboard and its signing secret in the plugin.

callback_url must be public HTTPS. If the store is not served over HTTPS, the plugin omits it and asks you (admin notice, log or configuration page) to register the store URL given below as a webhook endpoint in the dashboard, subscribed to payment.success, payment.failed, payment.cancelled, payment.expired, refund.success, refund.failed, payment.refunded and payment.partially_refunded (Odoo: all payment.* and refund.* events). Keep the default (legacy) payload version.

The dashboard Send test event (webhook.test) is answered 200 by every plugin and changes no order.

All plugins verify the X-Soamtar-Signature header (t=<unix>,v1=<hex>, plus v2= during a secret rotation): HMAC-SHA256 of "<t>.<raw body>" with the webhook secret, 300 s tolerance. See Webhooks.

Refunds

All plugins refund natively from the store back office. They call POST https://app.so-amtar.com/v1/refunds with the SOAMTAR transaction id and the amount (full or partial). SOAMTAR sends the money back to the payer's Orange Money number and debits it from your SOAMTAR balance. The refund is asynchronous: the final result arrives with refund.success or refund.failed (plus payment.refunded / payment.partially_refunded). The API key needs the can_refund scope, and your balance must cover the amount.

Platform	How to refund
WooCommerce	Refund via SOAMTAR on the order
Magento 2	Online credit memo (Refund, not "Refund Offline") from the invoice
PrestaShop	Credit slip (standard refund, partial refund or product return), when Refund through Orange Money (SOAMTAR_AUTO_REFUND, on by default) is enabled
Drupal Commerce	Refund on the payment (gateway implements SupportsRefundsInterface)
Odoo	Refund button on the payment (full or partial)

See Refunds for the API.

WordPress / WooCommerce

Classic checkout and Cart/Checkout Blocks, HPOS compatible.

Installation

cd wp-content/plugins
git clone <repository URL> soamtar-woocommerce-gateway

Or upload a zip of the folder in Plugins → Add New → Upload Plugin, then activate SOAMTAR for WooCommerce. Set the store currency to SLE, USD or EUR.

Settings

WooCommerce → Settings → Payments → SOAMTAR

Setting	Notes
Enable/Disable	Shows the gateway at checkout.
Title / Description	Checkout text (default "Orange Money").
Test mode	Uses the test secret key.
Live secret key / Test secret key	sk_live_… / sk_test_…, encrypted at rest.
Webhook secret	Required.
Success redirect URL (optional)	Default: the WooCommerce "order received" page.
Failure redirect URL (optional)	Default: the order payment page.
Debug log	WooCommerce → Status → Logs, source soamtar-gateway.

The gateway stays hidden (with an admin notice) while a key, the webhook secret or a supported store currency is missing.

Webhook URL

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

Sent automatically as callback_url on HTTPS stores; otherwise an admin notice asks you to register it in the dashboard. The legacy URL https://your-store.example/?wc-api=wc_soamtar_gateway also works.

Behaviour

• payment.success: the order is completed only if amount and currency match the order; otherwise it is put on hold with a note.
• payment.failed, payment.cancelled, payment.expired: the order is marked failed, unless it is already paid.
• refund.success, refund.failed, payment.refunded, payment.partially_refunded: settle the refund. The order gets a "refund sent" note, then a "refund completed" note; on refund.failed the plugin adds a note with the reason, removes the WooCommerce refund record and puts a fully refunded order on hold so you can refund again.
• webhook.test: answered 200, no order is changed.
• A new attempt after a failed payment uses merchant_ref 1001-2, 1001-3, … (a reference can only be used once).
• Billing phones are converted to +232XXXXXXXX when possible; otherwise the customer types the number on the payment page.
• The webhook is protected by a per-IP rate limit, a 1 MB body cap, deduplication, an audit log and an optional IP allowlist (filter soamtar_webhook_ip_allowlist).

Magento 2

Installation

Copy the module to app/code/Soamtar/Payment/, or add the repository as a Composer VCS/path repository and run composer require soamtar/magento2-payment. Then:

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

Settings

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

Field	Config path
Enabled	payment/soamtar/active
Title (default "Orange Money")	payment/soamtar/title
Test mode	payment/soamtar/testmode
Test secret key (sk_test_…)	payment/soamtar/test_secret_key (encrypted)
Live secret key (sk_live_…)	payment/soamtar/live_secret_key (encrypted)
Webhook secret	payment/soamtar/webhook_secret (encrypted)
Payment from applicable countries / specific countries	payment/soamtar/allowspecific, payment/soamtar/specificcountry
Debug log	payment/soamtar/debug
Sort order	payment/soamtar/sort_order

The method is offered only when the order currency is SLE, USD or EUR.

Webhook URL

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

Sent automatically as callback_url on HTTPS stores; otherwise the module logs a warning and you register it in the dashboard.

Behaviour

• The order is placed in pending_payment, then /soamtar/payment/redirect creates the SOAMTAR payment (Idempotency-Key: mage_<increment id>_<protect code>) and redirects to payment_url. If the API call fails, the order is cancelled and the cart restored.
• payment.success with the right amount and currency registers the capture (invoice) and moves the order to processing; a mismatch puts it on hold with a comment.
• payment.failed, payment.cancelled, payment.expired: a pending_payment order is cancelled.
• refund.success, refund.failed, payment.refunded, payment.partially_refunded: the refund status is recorded on the payment and commented on the order (once per refund and status). webhook.test: HTTP 200, no change.
• /soamtar/payment/cancel (failure URL) only restores the cart.
• Refunds: an online credit memo calls POST /v1/refunds. The credit memo is created right away with the refund pending; if the API rejects the request (insufficient balance, amount above what remains refundable), no credit memo is created and the error is shown.

PrestaShop

Installation

cd modules
git clone <repository URL> soamtar

The folder must be named soamtar. Or zip it as soamtar/… and upload it in Modules → Module Manager → Upload a module, then install SOAMTAR — Orange Money.

Settings

Modules → SOAMTAR — Orange Money → Configure

Field	Configuration key	Notes
Test mode	SOAMTAR_TEST_MODE	On by default.
Test secret key	SOAMTAR_TEST_SECRET_KEY	sk_test_…
Live secret key	SOAMTAR_LIVE_SECRET_KEY	sk_live_…
Webhook secret	SOAMTAR_WEBHOOK_SECRET	From the SOAMTAR dashboard (Developers → Webhooks).
Refund through Orange Money	SOAMTAR_AUTO_REFUND	On by default: credit slips are refunded through SOAMTAR.

Leaving a password field empty keeps the saved value. Also enable the module for SLE, USD or EUR in Payment → Preferences: the option is shown only when the active key and the webhook secret are set and the cart currency is supported.

Webhook URL

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

The exact URL (depending on your friendly-URL settings) is shown on the configuration page. It is sent automatically as callback_url when the shop uses HTTPS.

Behaviour

• The order is created in the "Awaiting Orange Money payment" state; if the API call fails it goes to "Payment error" and the cart is restored.
• Only orders still awaiting payment are changed: payment.success with the right amount and currency → "Payment accepted"; payment.failed → "Payment error"; payment.cancelled / payment.expired → "Canceled". A different amount or currency leaves the order pending and logs an error.
• refund.success / refund.failed add a private order message (once per refund); payment.refunded for a fully refunded payment moves the order to "Refunded". webhook.test → 200, the order is not touched.
• module/soamtar/return shows the confirmation or restores the cart; it never changes the order status.
• Refunds: creating a credit slip calls POST /v1/refunds (amount = slip products + shipping, tax included; Idempotency-Key: ps_refund_<slip id>; one refund per slip). Slips issued as a voucher are not refunded. If SOAMTAR rejects the refund, the slip is kept and the error is written as a private order message. Turn SOAMTAR_AUTO_REFUND off to refund only from the dashboard.

Drupal Commerce

Offsite payment gateway. The payment is recorded on return (status check) or by the webhook, whichever comes first.

Installation

Copy the module to modules/custom/soamtar_commerce (or add the repository as a Composer VCS/path repository and run composer require soamtar/drupal-commerce), then:

drush en soamtar_commerce -y
drush cr

Settings

Commerce → Configuration → Payment gateways → Add payment gateway, plugin SOAMTAR (Orange Money Sierra Leone).

Setting	Notes
Mode	Test uses the test key, Live the live key.
Test secret key (sk_test_…)	Leave empty to keep the saved value.
Live secret key (sk_live_…)	Leave empty to keep the saved value.
Webhook secret	The webhook URL is shown under this field once the gateway is saved.

Webhook URL

https://your-site.example/payment/notify/<gateway machine name>

Sent automatically as callback_url when the site is HTTPS; otherwise register it in the dashboard.

Behaviour

• merchant_ref is <order id>-<attempt>. A +232 phone is sent when the billing profile has a field_phone field.
• On return, the module asks GET /v1/status/{transaction id}: success records the payment; failed, cancelled or expired sends the customer back to checkout; a pending payment lets the order complete and waits for the webhook.
• payment.success records a completed payment once per SOAMTAR transaction, only if amount and currency match the order balance.
• Refunds: Refund on the payment calls POST /v1/refunds (amount left out for the whole remaining balance). The payment is marked refunded or partially refunded as soon as SOAMTAR accepts the request; refund.failed takes the amount back off the payment. Refunds made from the dashboard are added when their refund.success arrives. webhook.test is answered 200.

Odoo

Payment provider for Odoo eCommerce, invoices and payment links.

Installation

1. Copy payment_soamtar/ into your Odoo addons path.
2. Restart Odoo, update the apps list, search for SOAMTAR Payment Provider and install it.
3. Activate the SLE currency (Accounting → Configuration → Currencies). The provider is offered for SLE orders only.

Settings

Invoicing / Website → Configuration → Payment Providers → SOAMTAR (Orange Money)

Field	Value
State	Test Mode (uses sk_test_…) or Enabled (uses sk_live_…)
Test Secret Key / Live Secret Key	From the SOAMTAR dashboard
Webhook Secret	Signing secret of the endpoint below

Webhook URL

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

Sent automatically as callback_url when web.base.url is HTTPS; otherwise register it in the dashboard (payment.* and refund.* events).

Behaviour

• merchant_ref is the Odoo transaction reference; the customer comes back to /payment/soamtar/return?outcome=success or ?outcome=failed.
• On return and on webhook, Odoo reads the payment status from the SOAMTAR API (it never trusts the browser URL or the webhook body), checks amount and currency, then confirms, cancels or fails the transaction.
• Refunds: full and partial, from the Refund button on the payment. The refund transaction stays pending until refund.success (done) or refund.failed (error); payment.refunded / payment.partially_refunded are handled too.
• webhook.test is acknowledged with 200 and changes nothing.
• Webhook answers 400 when the secret does not match (or the server clock is more than 5 minutes off) and 503 when the Webhook Secret is not configured.