Plugins CMS & e-commerce

Nos plugins permettent d'accepter Orange Money Sierra Leone sans écrire de code. Ils fonctionnent tous de la même façon :

1. La commande est créée et le client est redirigé vers la page de paiement SOAMTAR (payment_url renvoyée par POST https://app.so-amtar.com/v1/payments).
2. Le client valide le paiement sur son téléphone avec son code PIN Orange Money.
3. SOAMTAR envoie un webhook signé à votre boutique, qui ne marque la commande payée que si le montant et la devise correspondent.
4. Les remboursements se font depuis le back-office de la boutique : SOAMTAR renvoie l'argent sur le numéro Orange Money du payeur (voir Remboursements).

Plateforme	Paquet / dossier	Version	Prérequis	Devises
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 uniquement

Pas encore sur les marketplaces

Les plugins ne sont pas encore publiés sur les places de marché WordPress, Magento, PrestaShop, Drupal ou Odoo. Installez-les depuis le dépôt (git clone ou zip) comme indiqué ci-dessous.

Configuration commune

Chaque plugin a besoin de trois valeurs issues du tableau de bord SOAMTAR :

Valeur	Provenance
Clé secrète de test sk_test_…	Clés API. Les paiements sont simulés sur le même hôte (https://app.so-amtar.com/v1) : aucun argent réel ne circule.
Clé secrète live sk_live_…	Clés API, une fois votre compte activé pour la production.
Secret du webhook	Le secret de signature d'un endpoint webhook enregistré dans le tableau de bord (Développeurs → Webhooks). Toujours requis, même avec callback_url.

Chaque plugin dispose d'un interrupteur Test mode qui choisit la clé de test ou la clé live. Les clés secrètes restent sur votre serveur : ne les placez jamais dans un thème ou un fichier JavaScript.

URL du webhook : automatique sur les boutiques HTTPS. Chaque plugin envoie sa propre URL de webhook comme callback_url avec chaque paiement. SOAMTAR livre alors les événements signés de ce paiement (et de ses remboursements) à la boutique, avec le même payload, la même signature et les mêmes relances qu'un endpoint enregistré. SOAMTAR signe ces envois avec le secret de votre plus ancien endpoint webhook actif du même environnement : il vous faut donc au moins un endpoint dans le tableau de bord, et son secret de signature dans le plugin.

callback_url doit être en HTTPS public. Si la boutique n'est pas servie en HTTPS, le plugin l'omet et vous demande (notice d'administration, log ou page de configuration) d'enregistrer l'URL de la boutique indiquée plus bas comme endpoint webhook dans le tableau de bord, abonné à payment.success, payment.failed, payment.cancelled, payment.expired, refund.success, refund.failed, payment.refunded et payment.partially_refunded (Odoo : tous les événements payment.* et refund.*). Gardez la version de payload par défaut (legacy).

Le bouton Send test event du tableau de bord (webhook.test) reçoit une réponse 200 de chaque plugin et ne modifie aucune commande.

Tous les plugins vérifient l'en-tête X-Soamtar-Signature (t=<unix>,v1=<hex>, plus v2= pendant une rotation de secret) : HMAC-SHA256 de "<t>.<corps brut>" avec le secret du webhook, tolérance de 300 s. Voir Webhooks.

Remboursements

Tous les plugins remboursent nativement depuis le back-office de la boutique. Ils appellent POST https://app.so-amtar.com/v1/refunds avec l'identifiant de transaction SOAMTAR et le montant (total ou partiel). SOAMTAR renvoie l'argent sur le numéro Orange Money du payeur et le débite de votre solde SOAMTAR. Le remboursement est asynchrone : le résultat final arrive avec refund.success ou refund.failed (plus payment.refunded / payment.partially_refunded). La clé API doit avoir le scope can_refund, et votre solde doit couvrir le montant.

Plateforme	Comment rembourser
WooCommerce	Refund via SOAMTAR sur la commande
Magento 2	Avoir en ligne (Refund, pas « Refund Offline ») depuis la facture
PrestaShop	Bon de réduction / avoir (remboursement standard, partiel ou retour produit), quand Refund through Orange Money (SOAMTAR_AUTO_REFUND, activé par défaut) est actif
Drupal Commerce	Refund sur le paiement (la passerelle implémente SupportsRefundsInterface)
Odoo	Bouton Refund sur le paiement (total ou partiel)

Voir Remboursements pour l'API.

WordPress / WooCommerce

Checkout classique et blocs Panier/Commande, compatible HPOS.

Installation

cd wp-content/plugins
git clone <URL du dépôt> soamtar-woocommerce-gateway

Ou téléversez un zip du dossier via Extensions → Ajouter → Téléverser une extension, puis activez SOAMTAR for WooCommerce. Réglez la devise de la boutique sur SLE, USD ou EUR.

Réglages

WooCommerce → Réglages → Paiements → SOAMTAR (libellés de l'interface en anglais) :

Réglage	Remarques
Enable/Disable	Affiche la passerelle au checkout.
Title / Description	Texte affiché au checkout (par défaut « Orange Money »).
Test mode	Utilise la clé secrète de test.
Live secret key / Test secret key	sk_live_… / sk_test_…, chiffrées au repos.
Webhook secret	Obligatoire.
Success redirect URL (optional)	Par défaut : la page « commande reçue » de WooCommerce.
Failure redirect URL (optional)	Par défaut : la page de paiement de la commande.
Debug log	WooCommerce → État → Journaux, source soamtar-gateway.

Tant qu'il manque une clé, le secret du webhook ou une devise prise en charge, la passerelle reste masquée et une notice s'affiche dans l'admin.

URL du webhook

https://votre-boutique.example/wp-json/soamtar/v1/webhook

Envoyée automatiquement comme callback_url sur les boutiques HTTPS ; sinon une notice d'administration vous demande de l'enregistrer dans le tableau de bord. L'ancienne URL https://votre-boutique.example/?wc-api=wc_soamtar_gateway fonctionne aussi.

Comportement

• payment.success : la commande n'est validée que si amount et currency correspondent ; sinon elle passe en attente avec une note.
• payment.failed, payment.cancelled, payment.expired : la commande passe en échec, sauf si elle est déjà payée.
• refund.success, refund.failed, payment.refunded, payment.partially_refunded : règlent le remboursement. La commande reçoit une note « remboursement envoyé », puis « remboursement terminé » ; sur refund.failed, le plugin ajoute une note avec le motif, supprime l'enregistrement de remboursement WooCommerce et met en attente une commande entièrement remboursée, pour que vous puissiez rembourser à nouveau.
• webhook.test : réponse 200, aucune commande n'est modifiée.
• Une nouvelle tentative après un échec utilise merchant_ref 1001-2, 1001-3, … (une référence n'est utilisable qu'une fois).
• Le téléphone de facturation est converti en +232XXXXXXXX si possible ; sinon le client saisit son numéro sur la page de paiement.
• Le webhook est protégé par une limite de débit par IP, un plafond de 1 Mo, une déduplication, un journal d'audit et une liste blanche d'IP optionnelle (filtre soamtar_webhook_ip_allowlist).

Magento 2

Installation

Copiez le module dans app/code/Soamtar/Payment/, ou déclarez le dépôt comme dépôt Composer VCS/path puis lancez composer require soamtar/magento2-payment. Ensuite :

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

Réglages

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

Champ	Chemin de configuration
Enabled	payment/soamtar/active
Title (par défaut « Orange Money »)	payment/soamtar/title
Test mode	payment/soamtar/testmode
Test secret key (sk_test_…)	payment/soamtar/test_secret_key (chiffrée)
Live secret key (sk_live_…)	payment/soamtar/live_secret_key (chiffrée)
Webhook secret	payment/soamtar/webhook_secret (chiffré)
Payment from applicable countries / specific countries	payment/soamtar/allowspecific, payment/soamtar/specificcountry
Debug log	payment/soamtar/debug
Sort order	payment/soamtar/sort_order

Le moyen de paiement n'est proposé que si la devise de la commande est SLE, USD ou EUR.

URL du webhook

https://votre-boutique.example/soamtar/webhook/notify

Envoyée automatiquement comme callback_url sur les boutiques HTTPS ; sinon le module journalise un avertissement et vous l'enregistrez dans le tableau de bord.

Comportement

• La commande est créée en pending_payment, puis /soamtar/payment/redirect crée le paiement SOAMTAR (Idempotency-Key: mage_<increment id>_<protect code>) et redirige vers payment_url. Si l'appel API échoue, la commande est annulée et le panier restauré.
• payment.success avec le bon montant et la bonne devise enregistre la capture (facture) et passe la commande en traitement ; en cas d'écart, la commande est mise en attente avec un commentaire.
• payment.failed, payment.cancelled, payment.expired : une commande pending_payment est annulée.
• refund.success, refund.failed, payment.refunded, payment.partially_refunded : le statut du remboursement est enregistré sur le paiement et commenté sur la commande (une fois par remboursement et par statut). webhook.test : HTTP 200, aucun changement.
• /soamtar/payment/cancel (URL d'échec) se contente de restaurer le panier.
• Remboursements : un avoir en ligne appelle POST/v1/refunds. L'avoir est créé immédiatement avec le remboursement pending ; si l'API refuse la demande (solde insuffisant, montant supérieur au restant remboursable), aucun avoir n'est créé et l'erreur est affichée.

PrestaShop

Installation

cd modules
git clone <URL du dépôt> soamtar

Le dossier doit s'appeler soamtar. Vous pouvez aussi le zipper sous la forme soamtar/… et le téléverser dans Modules → Gestionnaire de modules → Installer un module, puis installer SOAMTAR — Orange Money.

Réglages

Modules → SOAMTAR — Orange Money → Configurer

Champ	Clé de configuration	Remarques
Test mode	SOAMTAR_TEST_MODE	Activé par défaut.
Test secret key	SOAMTAR_TEST_SECRET_KEY	sk_test_…
Live secret key	SOAMTAR_LIVE_SECRET_KEY	sk_live_…
Webhook secret	SOAMTAR_WEBHOOK_SECRET	Depuis le tableau de bord SOAMTAR (Développeurs → Webhooks).
Refund through Orange Money	SOAMTAR_AUTO_REFUND	Activé par défaut : les avoirs sont remboursés via SOAMTAR.

Un champ mot de passe laissé vide conserve la valeur enregistrée. Activez aussi le module pour SLE, USD ou EUR dans Paiement → Préférences : l'option n'apparaît que si la clé active et le secret du webhook sont renseignés et que la devise du panier est prise en charge.

URL du webhook

https://votre-boutique.example/module/soamtar/webhook

L'URL exacte (selon vos réglages d'URL simplifiées) est affichée sur la page de configuration. Elle est envoyée automatiquement comme callback_url quand la boutique est en HTTPS.

Comportement

• La commande est créée à l'état « En attente de paiement Orange Money » ; si l'appel API échoue, elle passe en « Erreur de paiement » et le panier est restauré.
• Seules les commandes encore en attente sont modifiées : payment.success avec le bon montant et la bonne devise → « Paiement accepté » ; payment.failed → « Erreur de paiement » ; payment.cancelled / payment.expired → « Annulé ». Un montant ou une devise différents laissent la commande en attente et journalisent une erreur.
• refund.success / refund.failed ajoutent un message privé sur la commande (une fois par remboursement) ; payment.refunded pour un paiement entièrement remboursé passe la commande en « Remboursé ». webhook.test → 200, la commande n'est pas modifiée.
• module/soamtar/return affiche la confirmation ou restaure le panier ; il ne modifie jamais le statut de la commande.
• Remboursements : créer un avoir appelle POST/v1/refunds (montant = produits de l'avoir + frais de port, TTC ; Idempotency-Key: ps_refund_<id avoir> ; un remboursement par avoir). Les avoirs émis sous forme de bon de réduction ne sont pas remboursés. Si SOAMTAR refuse le remboursement, l'avoir est conservé et l'erreur est écrite en message privé sur la commande. Désactivez SOAMTAR_AUTO_REFUND pour ne rembourser que depuis le tableau de bord.

Drupal Commerce

Passerelle de paiement offsite. Le paiement est enregistré au retour (vérification du statut) ou par le webhook, selon ce qui arrive en premier.

Installation

Copiez le module dans modules/custom/soamtar_commerce (ou déclarez le dépôt comme dépôt Composer VCS/path et lancez composer require soamtar/drupal-commerce), puis :

drush en soamtar_commerce -y
drush cr

Réglages

Commerce → Configuration → Passerelles de paiement → Ajouter une passerelle, plugin SOAMTAR (Orange Money Sierra Leone).

Réglage	Remarques
Mode	Test utilise la clé de test, Live la clé live.
Test secret key (sk_test_…)	Laissez vide pour conserver la valeur enregistrée.
Live secret key (sk_live_…)	Laissez vide pour conserver la valeur enregistrée.
Webhook secret	L'URL du webhook s'affiche sous ce champ une fois la passerelle enregistrée.

URL du webhook

https://votre-site.example/payment/notify/<nom machine de la passerelle>

Envoyée automatiquement comme callback_url quand le site est en HTTPS ; sinon enregistrez-la dans le tableau de bord.

Comportement

• merchant_ref vaut <id commande>-<tentative>. Un numéro +232 est envoyé si le profil de facturation possède un champ field_phone.
• Au retour, le module interroge GET /v1/status/{id de transaction} : success enregistre le paiement ; failed, cancelled ou expired renvoie le client au checkout ; un paiement en attente laisse la commande se terminer et attend le webhook.
• payment.success enregistre un paiement terminé une seule fois par transaction SOAMTAR, uniquement si amount et currency correspondent au solde de la commande.
• Remboursements : Refund sur le paiement appelle POST/v1/refunds (amount omis pour tout le solde restant). Le paiement est marqué remboursé ou partiellement remboursé dès que SOAMTAR accepte la demande ; refund.failed retire le montant du paiement. Les remboursements faits depuis le tableau de bord sont ajoutés à réception de leur refund.success. webhook.test reçoit 200.

Odoo

Fournisseur de paiement pour l'eCommerce Odoo, les factures et les liens de paiement.

Installation

1. Copiez payment_soamtar/ dans le chemin des addons Odoo.
2. Redémarrez Odoo, mettez à jour la liste des applications, cherchez SOAMTAR Payment Provider et installez-le.
3. Activez la devise SLE (Comptabilité → Configuration → Devises). Le fournisseur n'est proposé que pour les commandes en SLE.

Réglages

Facturation / Site web → Configuration → Fournisseurs de paiement → SOAMTAR (Orange Money)

Champ	Valeur
État	Mode test (utilise sk_test_…) ou Activé (utilise sk_live_…)
Test Secret Key / Live Secret Key	Depuis le tableau de bord SOAMTAR
Webhook Secret	Secret de signature de l'endpoint ci-dessous

URL du webhook

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

Envoyée automatiquement comme callback_url quand web.base.url est en HTTPS ; sinon enregistrez-la dans le tableau de bord (événements payment.* et refund.*).

Comportement

• merchant_ref est la référence de transaction Odoo ; le client revient sur /payment/soamtar/return?outcome=success ou ?outcome=failed.
• Au retour comme à la réception du webhook, Odoo lit le statut du paiement auprès de l'API SOAMTAR (il ne se fie jamais à l'URL du navigateur ni au corps du webhook), vérifie montant et devise, puis confirme, annule ou met en échec la transaction.
• Remboursements : totaux et partiels, depuis le bouton Refund du paiement. La transaction de remboursement reste en attente jusqu'à refund.success (terminée) ou refund.failed (erreur) ; payment.refunded / payment.partially_refunded sont aussi traités.
• webhook.test est acquitté avec 200 et ne modifie rien.
• Le webhook répond 400 si le secret ne correspond pas (ou si l'horloge du serveur dérive de plus de 5 minutes) et 503 si le Webhook Secret n'est pas configuré.