Journal des modifications

Les changements notables de l'API SOAMTAR sont listés ici. Versionnement SemVer sur le préfixe d'URL.

[1.7.0] - 2026-10-22

Ajouté

• API de remboursement : POST/v1/refunds (total ou partiel ; omettez amount pour tout le montant restant), GET/v1/refunds/{id} et GET/v1/refunds. Le montant est recrédité sur le numéro Orange Money du payeur et débité de votre solde ; le crédit est asynchrone (processing, puis success ou failed). Scope can_refund requis. Voir Remboursements.
• Webhooks de remboursement : refund.success, refund.failed, et sur le paiement payment.refunded / payment.partially_refunded (avec data.refund). Un jeu d'événements par remboursement.
• callback_url livrée : la callback_url HTTPS facultative d'un paiement ou d'un paiement sortant reçoit désormais tous les événements de cette transaction, avec le même payload, la même X-Soamtar-Signature (secret de votre plus ancien endpoint webhook actif du même environnement) et les mêmes relances. Voir Webhooks.
• Signature facultative des requêtes : en-têtes Soamtar-Timestamp + Soamtar-Signature: v1=… sur les requêtes non-GET, disponible en option dans chaque SDK. Voir Authentification.

Modifié

• Catalogue des événements webhook : seuls les événements réellement émis par SOAMTAR peuvent être souscrits (payment.*, payout.*, refund.*, payout_request.*). Le bouton de test et POST/v1/webhooks/test envoient tous deux webhook.test, livré quelles que soient les souscriptions.
• SDK 1.1.0 : conventions communes à tous les langages — variables d'environnement SOAMTAR_SECRET_KEY et SOAMTAR_API_URL, ressources payments / payouts / refunds / webhooks / balance avec les mêmes noms de méthodes. Les anciens noms restent des alias dépréciés. Les plugins e-commerce gèrent les remboursements natifs. Voir SDK.

---

[1.6.0] - 2026-10-20

Modifié (impact sur les intégrations existantes)

• Sierra Leone uniquement : SOAMTAR opère désormais exclusivement en Sierra Leone (pays SL).
• Orange Money Sierra Leone, canal unique : provider orange_money_sl (Orange Money Business API) pour les encaissements et les paiements sortants.
• Devise leone (SLE) : montants avec au plus deux décimales (ex. 150.00) ; un montant plus précis est rejeté, jamais arrondi. L'API accepte aussi USD et EUR.
• Numéros de téléphone : format E.164, +232 suivi de 8 chiffres.
• Remboursements : disponibles via POST/v1/refunds depuis la 1.7.0.
• Les canaux et pays proposés auparavant sont retirés.

---

[1.2.0] - 2026-04-25

Ajouté (écosystème SDK)

• SDK et plugins officiels couvrant backend, mobile, web et CMS.
• SDK backend (7) : PHP/Laravel, Node.js, Python, Ruby, Java/Spring Boot, Go, .NET/C#.
• SDK mobile & jeux (5) : Android (Kotlin), iOS (Swift), React Native, Flutter, Unity (C#).
• SDK web frontend (1) : SOAMTAR.js pour les intégrations natives et les pop-ups sécurisées.
• Plugins CMS & e-commerce (6) : WordPress/WooCommerce, Magento 2, PrestaShop, Drupal, Odoo, WHMCS.
• Guide no-code : instructions pour Wix (Velo), Shopify et Webflow.

Sécurité (durcissement des SDK)

• Verrou clé publique : tous les SDK frontend/mobile refusent les clés secrètes (sk_...) pour éviter toute exposition accidentelle.
• Résistance aux attaques temporelles : comparaisons en temps constant dans tous les SDK serveur.
• Anti-DoS webhooks : limite de 1 Mo par contenu et contrôles d'horodatage (anti-rejeu) intégrés.
• Dépendances minimales : la plupart des SDK sont construits sans bibliothèque tierce pour réduire le risque de chaîne d'approvisionnement.

Sécurité (durcissement du backend)

• Hachage des clés API : les clés secrètes ne sont plus stockées en clair.
• Isolation des marchands : contrôle d'accès renforcé aux ressources au niveau SQL.
• Limitation de débit avancée : protection par IP et par marchand sur les routes sensibles (OTP).

---

[1.1.0]

Ajouté

• Validation plus stricte des URL d'endpoint de webhook : les URL non HTTPS, les hôtes loopback (localhost, 127.x), les IP privées et les TLD internes sont rejetés à la création.
• Masquage automatique des valeurs sensibles dans les logs d'API : si un marchand passe par erreur ?payer_phone=... ou ?api_key=... en query string, la valeur est remplacée par [REDACTED] avant stockage.

Modifié (compatible)

• Références publiques étendues à 16 caractères aléatoires après le préfixe, ex. TXN-A1B2C3D4E5F6G7H8. Si votre code fige la longueur, prévoyez au moins 20 caractères. Les anciennes références restent valides.
• Événements webhook du canal : seuls les événements réellement émis par le canal de paiement sont propagés. L'abandon et l'expiration restent émis par SOAMTAR sous la forme payment.cancelled / payment.expired.

Sécurité

• Les signatures horodatées peuvent être exigées par canal (option interne, gérée par SOAMTAR).
• Sécurité de concurrence renforcée sur les écritures multi-lignes (splits marketplace en particulier) : deux requêtes parallèles sur la même transaction parente sont sérialisées.
• Header X-XSS-Protection retiré (obsolète) ; la protection XSS repose sur la Content-Security-Policy.
• Quota sur la création de nouvelles valeurs d'Idempotency-Key par compte marchand, pour protéger la plateforme d'une clé compromise générant un UUID par requête. Les rejeux de clés existantes ne sont pas concernés.

[1.0.0]

Première version publique de l'API.

Ajouté

• Paiements : POST/v1/payments avec idempotence, page de paiement hébergée sans provider.
• Vérification à la demande : POST/v1/payments/{id}/verify.
• Webhooks signés HMAC-SHA256 horodatés, réessais exponentiels, rotation du secret sans coupure.
• Splits marketplace : POST et GET/v1/payments/{id}/splits avec invariants (total, bénéficiaire actif, immuabilité).
• Clients créés automatiquement à l'initiation.
• Gel du taux de change : taux figé à l'initiation quand les devises diffèrent.
• Rapprochement automatique pour rattraper les webhooks perdus.
• Expiration automatique des transactions non finalisées.

Sécurité

• TLS 1.2 minimum.
• Les URL de webhook marchand doivent utiliser HTTPS.
• Anti-rejeu sur les signatures entrantes et sortantes.
• Enregistrements conservés selon les exigences réglementaires applicables.

[Non publié]

Prévu

• Tokenisation mobile money pour les abonnements récurrents

---

Politique de versionnement

• Patch (1.0.x) : corrections et optimisations, aucun changement d'API.
• Mineure (1.x.0) : nouveaux endpoints, nouveaux champs optionnels. Compatible.
• Majeure (x.0.0) : changements incompatibles, annoncés plusieurs mois à l'avance, avec la version précédente maintenue pendant une période de transition.

Aucun champ existant n'est jamais supprimé ni renommé sans version majeure. De nouveaux champs optionnels peuvent apparaître dans n'importe quelle version mineure.

S'abonner aux annonces

• Dashboard → Paramètres → Notifications → Changements d'API
• Email récapitulatif pour les marchands en production