SDK & bibliothèques clientes

Les bibliothèques officielles SOAMTAR couvrent les langages serveur, les applications mobiles, le navigateur, Unity et les principales plateformes e-commerce. Toutes ciblent la Sierra Leone : montants en leones (SLE, USD et EUR également acceptés), Orange Money Sierra Leone (orange_money_sl) comme unique fournisseur, numéros payeurs au format +232 suivi de 8 chiffres.

Disponibilité

Les versions ci-dessous sont finalisées, mais les paquets ne sont pas encore publiés sur les registres publics (npm, Packagist, PyPI, RubyGems, Maven Central, NuGet, pub.dev…). En attendant, installez-les depuis le dépôt source fourni par le support SOAMTAR. Le SDK navigateur est déjà servi sur https://app.so-amtar.com/sdk/soamtar.js.

---

Comment choisir ?

Mon profil	Ma recommandation
Je débute	Suivez le guide de démarrage rapide. C'est le chemin le plus simple.
J'utilise un CMS	Allez directement à la section Plugins CMS & e-commerce ci-dessous.
Je suis développeur backend	Choisissez votre langage dans la section Serveur.
Je crée une application mobile ou un jeu	Utilisez les bibliothèques de la section Mobile & frontend. C'est toujours votre backend qui crée le paiement.

Deux familles de bibliothèques

	SDK serveur	SDK client (navigateur, mobile, Unity)
Clé	Clé secrète sk_test_… / sk_live_…	Clé publique pk_test_… / pk_live_… (ou aucune clé)
Où il s'exécute	Uniquement sur votre backend	Dans le navigateur, le téléphone ou le jeu du payeur
Ce qu'il fait	Crée les paiements (POST /v1/payments), les consulte, vérifie les webhooks	Ouvre la payment_url obtenue par votre backend via POST /v1/payments

Un SDK client ne crée jamais de paiement et ne détient jamais de clé secrète. Il n'existe pas d'hôte sandbox séparé : avec une clé sk_test_, les paiements sont simulés sur https://app.so-amtar.com/v1.

---

Serveur (backend)

Langage	Paquet	Version	Point d'entrée
PHP / Laravel	soamtar/soamtar-php (Composer, PHP 8.2+)	1.1.0	Soamtar\SoamtarClient, Soamtar\Soamtar
Node.js / TypeScript	@soamtar/sdk (npm)	1.1.0	SoamtarClient
Python	soamtar (pip)	1.1.0	soamtar.SoamtarClient
Ruby	soamtar (gem)	1.1.0	Soamtar::Client
Java	com.soamtar:soamtar-java (Maven)	1.1.0	com.soamtar.sdk.SoamtarClient
Go	github.com/soamtar/soamtar-go-sdk	1.1.0	soamtar.NewClient
.NET / C#	Soamtar (NuGet)	1.1.0	Soamtar.SoamtarClient

Mobile & frontend

Plateforme	Paquet	Version	Point d'entrée
Navigateur (JavaScript)	Script servi sur https://app.so-amtar.com/sdk/soamtar.js (@soamtar/browser sur npm plus tard)	1.0.0	SoamtarSDK
iOS (Swift)	SoamtarSDK (Swift Package Manager, iOS 14+)	1.0.1	Soamtar, SoamtarCheckoutView
Android (Kotlin)	com.soamtar:soamtar-android (Gradle)	1.1.0	com.soamtar.sdk.Soamtar
Flutter	soamtar_sdk (pub)	1.0.1	package:soamtar_sdk/soamtar_sdk.dart
React Native	@soamtar/react-native (npm, avec react-native-webview)	1.1.0	SoamtarClient, SoamtarCheckout
Unity (jeux vidéo)	Dossier Assets/Soamtar	1.0.1	Soamtar.SoamtarClient

Plugins CMS & e-commerce

Plateforme	Plugin	Version
WordPress / WooCommerce	SOAMTAR for WooCommerce (soamtar-gateway)	1.1.0
Magento 2	soamtar/magento2-payment (module Soamtar_Payment)	1.1.0
PrestaShop 1.7.7+	Module de paiement soamtar	1.1.0
Drupal Commerce	soamtar/drupal-commerce (module soamtar_commerce)	1.1.0
Odoo 17	payment_soamtar (SOAMTAR Payment Provider)	17.0.1.1.0

Les cinq plugins prennent en charge les remboursements natifs depuis le back-office (voir Plugins CMS & e-commerce).

Terminaux de paiement (TPE / Smart POS)

Un SDK SOAMTAR pour terminaux de paiement Android est en préparation. Il s'appuie sur des endpoints /v1/pos/* qui ne sont pas encore disponibles dans l'API : ne l'utilisez pas en production.

---

Conventions communes

Les SDK serveur exposent la même surface, adaptée aux conventions de nommage de chaque langage (CreateAsync en .NET, Create(ctx, …) en Go, send_test en Python/Ruby) :

client.payments.create(params, idempotencyKey?)   POST /v1/payments
client.payments.retrieve(id)                      GET  /v1/payments/{id}
client.payments.list(filters)                     GET  /v1/payments
client.payments.status(idOrReference)             GET  /v1/status/{idOrReference}
client.payments.verify(id)                        POST /v1/payments/{id}/verify

client.payouts.create / retrieve / list           /v1/payouts
client.refunds.create / retrieve / list           /v1/refunds
client.balance.retrieve()                         GET  /v1/balance
client.webhooks.list / create / secret / sendTest /v1/webhooks

Webhook.constructEvent(rawBody, signatureHeader, secret)

• retrieve accepte l'identifiant ou la référence SOAMTAR (TXN-…), pas votre merchant_ref.
• Les clients serveur refusent toute clé qui ne commence pas par sk_. Sans clé fournie, ils lisent SOAMTAR_SECRET_KEY ; l'URL de base vient de SOAMTAR_API_URL (SOAMTAR_BASE_URL reste accepté en repli), par défaut https://app.so-amtar.com/v1.
• Chaque POST porte un en-tête Idempotency-Key : généré automatiquement, ou celui que vous passez.
• webhooks.create : subscribed_events est facultatif et vaut par défaut payment.success, payment.failed, payout.success, payout.failed.
• webhooks.sendTest() (send_test / SendTest selon le langage) demande à SOAMTAR d'envoyer un événement webhook.test à vos endpoints.
• Les anciens noms de méthodes (webhooks.test, webhooks.all, balance.show, status.retrieve…) restent disponibles comme alias dépréciés.
• Les erreurs lèvent une exception SOAMTAR qui expose le statut HTTP et le code d'erreur de l'API.

La signature facultative des requêtes (voir Authentification) est une option du client :

Langage	Option
Node.js	soamtar(key, { signRequests: true })
PHP	'sign_requests' => true
Python	SoamtarClient(..., sign_requests=True)
Ruby	Soamtar::Client.new(key, sign_requests: true)
Go	soamtar.WithSignRequests(true)
Java	new SoamtarClient(null, null, Duration.ofSeconds(30), true) (signRequests)
.NET	new SoamtarClient(signRequests: true)

Fonction de vérification des webhooks par langage :

Langage	Fonction
PHP	Soamtar\Webhook::constructEvent($rawBody, $signatureHeader, $secret)
Node.js	Webhook.constructEvent(rawBody, signatureHeader, secret)
Python	Webhook.construct_event(raw_body, signature_header, secret)
Ruby	Soamtar::Webhook.construct_event(raw_body, signature_header, secret)
Java	Webhook.constructEvent(payload, signatureHeader, secret)
Go	soamtar.ConstructEvent(payload, sigHeader, secret)
.NET	Webhook.ConstructEvent(payload, signatureHeader, secret)

Chaque fonction contrôle l'en-tête X-Soamtar-Signature (t=<unix>,v1=<hmac>, plus v2= pendant la rotation d'un secret), recalcule HMAC-SHA256(secret, "t.payload") sur le corps brut, rejette les horodatages de plus de 300 secondes et renvoie l'événement décodé (event, created, data). Voir Webhooks.

Remboursements

client.refunds.create({ transaction_id, amount? }) renvoie l'argent sur le numéro Orange Money du payeur, en débitant votre solde. Sans amount, tout le montant restant est remboursé ; les remboursements partiels sont permis. Le remboursement est asynchrone : le résultat arrive avec refund.success / refund.failed. La clé doit avoir le scope can_refund. Voir Remboursements.

Bonnes pratiques

Réutiliser le client

Créez un seul client par processus et réutilisez-le, plutôt que d'en instancier un à chaque requête :

import { SoamtarClient } from '@soamtar/sdk'

const soamtar = new SoamtarClient(process.env.SOAMTAR_SECRET_KEY)

export function pay(order: { id: string; amount: string; phone: string }) {
  return soamtar.payments.create({
    merchant_ref: order.id,
    amount: order.amount,          // "1250.00" → Le 1,250.00
    currency: 'SLE',
    provider: 'orange_money_sl',
    phone: order.phone,            // +232XXXXXXXX
  })
}

Réessayer avec backoff

Les SDK ne réessaient pas d'eux-mêmes. Si vous ajoutez des tentatives, réutilisez la même Idempotency-Key : un POST rejoué ne pourra jamais créer un second paiement.

import { randomUUID } from 'node:crypto'

async function withRetry<T>(fn: (key: string) => Promise<T>, max = 3): Promise<T> {
  const idempotencyKey = randomUUID()   // one key for every attempt
  for (let attempt = 0; ; attempt++) {
    try {
      return await fn(idempotencyKey)
    } catch (e: any) {
      const retryable = !e.status || e.status === 429 || e.status >= 500
      if (!retryable || attempt >= max) throw e
      await new Promise(r => setTimeout(r, 2 ** attempt * 1000))   // 1s, 2s, 4s
    }
  }
}

await withRetry(key => soamtar.payments.create(params, { idempotencyKey: key }))

Important

Réessayez les erreurs réseau, les 429 et les 5xx avec la même Idempotency-Key. Ne réessayez jamais les autres 4xx : corrigez d'abord la requête. Voir Idempotence.

Générer un client depuis la spécification OpenAPI

Pour un langage sans SDK, générez un client typé à partir de la spécification OpenAPI (openapi.yaml) :

# TypeScript types
npx openapi-typescript ./openapi.yaml -o src/soamtar.types.ts

# Python (openapi-generator)
openapi-generator-cli generate -i ./openapi.yaml -g python -o ./soamtar-py

# Go
oapi-codegen -package soamtar ./openapi.yaml > soamtar.gen.go

Demander un SDK

Votre langage manque à l'appel ? Écrivez à support@so-amtar.com en précisant :

• le langage / framework visé ;
• votre volume de transactions prévu ;
• votre cas d'usage principal.