SDK navigateur (SoamtarSDK)

Le SDK navigateur SOAMTAR (SoamtarSDK, version 1.0.0) envoie vos clients depuis votre page web vers le checkout SOAMTAR, où ils valident le paiement sur leur téléphone avec leur code PIN Orange Money (Sierra Leone, montants en leones, SLE).

Sécurité

• Le SDK n'accepte que votre clé publique (pk_test_… / pk_live_…). Une clé secrète (sk_…) déclenche immédiatement une erreur.
• Le paiement est toujours créé par votre backend avec votre clé secrète (POST/v1/payments, par exemple avec le SDK Node.js). Le navigateur se contente d'ouvrir le payment_url renvoyé par votre backend.
• Les URL de paiement doivent être en HTTPS (ou un chemin relatif du même domaine).

Installation

Depuis le CDN SOAMTAR (recommandé, toujours la version servie par l'API) :

<script src="https://app.so-amtar.com/sdk/soamtar.js"></script>

Le paquet npm @soamtar/browser n'est pas encore publié. En attendant, installez-le depuis le dépôt du SDK :

npm install /chemin/vers/soamtar-js-browser   # ou une URL git du dépôt

import '@soamtar/browser' // définit window.SoamtarSDK

Utilisation

1. Votre backend a déjà créé le paiement

const soamtar = SoamtarSDK('pk_live_votre_cle_publique')

soamtar
  .setup({ url: paymentUrlRenvoyeeParVotreBackend }) // https://app.so-amtar.com/pay/checkout/…
  .start()

2. Le SDK appelle votre backend

Le SDK envoie l'objet passé à setup() en JSON (POST) vers requestTokenUrl, avec l'en-tête X-Public-Key. Votre backend crée le paiement via POST/v1/payments et répond { "payment_url": "https://…" }.

SoamtarSDK('pk_live_votre_cle_publique')
  .setup({
    merchant_ref: 'ORDER-1042',
    amount: '1250.00',            // en leones, 2 décimales
    currency: 'SLE',
    payer_phone: '+23276000001'   // +232 suivi de 8 chiffres
  })
  .withConfig({
    requestTokenUrl: '/api/create-payment',
    presentationMode: SoamtarSDK.REDIRECT_NEW,
    onError: (message) => alert(message),
  })
  .start()

Les champs payer_name, payer_phone, payer_email et provider de setup() sont ajoutés à l'URL de paiement (name, phone, email, method) pour pré-remplir le checkout.

La route backend correspondante, avec le SDK Node.js (le backend reporte payer_phone dans le phone de POST/v1/payments) :

app.post('/api/create-payment', express.json(), async (req, res) => {
  const { data } = await soamtar.payments.create({
    merchant_ref: req.body.merchant_ref,   // à vérifier contre votre propre commande
    amount: req.body.amount,               // à recalculer côté serveur : ne faites jamais confiance au navigateur
    phone: req.body.payer_phone,
    success_url: 'https://shop.example.sl/merci',
    failed_url: 'https://shop.example.sl/paiement-echoue',
  })
  res.json({ payment_url: data.payment_url })
})

API

Membre	Description
SoamtarSDK(publicKey)	Crée une instance. Retire les espaces, un préfixe Bearer et les guillemets éventuels. Lève une erreur si la clé est absente, secrète ou mal formée.
.setup(config)	Données du paiement. config.url : URL de paiement à ouvrir directement ; sinon, l'objet entier est envoyé à requestTokenUrl. Chaînable.
.withConfig(options)	Remplace les options ci-dessous. Chaînable.
.start()	Ouvre le checkout.
SoamtarSDK.version	1.0.0

Options

Option	Défaut	Description
presentationMode	SoamtarSDK.REDIRECT_SELF	REDIRECT_SELF (même onglet) ou REDIRECT_NEW (nouvel onglet). SoamtarSDK.MODAL est conservé pour compatibilité et équivaut à REDIRECT_SELF.
requestTokenUrl	—	Route de votre backend qui renvoie { payment_url } (ou redirect_url).
method	POST	Méthode HTTP utilisée pour requestTokenUrl.
headers	JSON + X-Public-Key	En-têtes envoyés à requestTokenUrl. Remplacez l'objet complet pour ajouter votre jeton CSRF.
onBeforeStart()	aucun effet	Appelé juste avant l'ouverture du checkout.
onError(message)	console.error	Erreur de configuration, réseau (délai de 15 s) ou renvoyée par votre backend.
onSuccess, onCancel	aucun effet	Conservés pour compatibilité, jamais appelés : le résultat arrive sur votre success_url / failed_url et par webhook.

Confirmez côté serveur

Le retour du client sur votre success_url ne prouve rien. Ne livrez la commande qu'après réception du webhook payment.success (ou un GET/v1/payments/{id} depuis votre backend).