Conventions de l'API

URL de base

https://app.so-amtar.com/v1

Toutes les routes documentées sont relatives à cette base. Test et live partagent la même URL : c'est le mode de la clé (sk_test_ / sk_live_) qui choisit l'environnement.

Format

• Encodage : UTF-8
• Type de contenu des requêtes : application/json
• Type de contenu des réponses : application/json; charset=utf-8

Headers communs

Header	Sens	Notes
Authorization: Bearer sk_...	vers l'API	Toujours requis
Idempotency-Key: <uuid>	vers l'API	Recommandé sur POST/PUT/PATCH/DELETE
Content-Type: application/json	vers l'API	Requis avec un corps
Accept: application/json	vers l'API	Optionnel, JSON par défaut
Soamtar-Timestamp / Soamtar-Signature	vers l'API	Signature de requête optionnelle (v1=HMAC-SHA256(timestamp.METHOD.path, clé secrète))
X-Request-Id: <id>	depuis l'API	À inclure dans vos signalements d'incident
Idempotent-Replay: true	depuis l'API	Présent quand la réponse provient du cache d'idempotence

Enveloppe de réponse

Succès (objet unique)

{
  "data": { "id": "...", "object": "transaction" },
  "livemode": false
}

Succès (collection paginée)

{
  "data": [ {}, {} ],
  "pagination": {
    "total": 142,
    "per_page": 25,
    "current_page": 1,
    "last_page": 6
  },
  "livemode": false
}

Erreur

{
  "error": {
    "code": "payment_rejected",
    "message": "The selected currency is invalid.",
    "documentation_url": "https://app.so-amtar.com/docs/errors#payment_rejected"
  }
}

Identifiants

Type	Format	Exemple
id (toutes ressources)	UUID v4	0e85b3c2-7c4f-4f1d-9b3a-1c8a2d4e5f6a
Référence de transaction	TXN- + alphanumériques majuscules	TXN-1A2B3C4D-ABCDEF123456

Les références font au plus 36 caractères ; prévoyez au moins 50 caractères dans votre schéma pour les évolutions. Les routes acceptent l'UUID OU la référence en paramètre de chemin.

Pagination

• ?per_page=N (un maximum raisonnable et une valeur par défaut s'appliquent)
• ?page=N (1 par défaut)
• La réponse contient pagination.{total,per_page,current_page,last_page}

Filtres communs

Paramètre	Effet
status=success	Filtre par statut
created_from=2026-10-01	created_at >=
created_to=2026-10-31	created_at <=
provider=orange_money_sl	Filtre par provider
customer_id=<uuid>	Filtre par client

Devises

Code	Décimales	Plus petit montant
SLE	2	0.01
USD	2	0.01
EUR	2	0.01

Les montants sont en unités principales avec au plus deux décimales : 150.00 = 150 leones, 12.50 = 12 leones et 50 cents. Un montant plus précis est rejeté, jamais arrondi. SLL (code d'avant 2022) n'est pas accepté. Affichez les leones sous la forme Le 1,250.00.

Numéros de téléphone

E.164 strict : +23276000001 — +232 puis le numéro national à 8 chiffres. Sans espace ni tiret. Les paiements sortants exigent le + initial.

Dates

ISO-8601 avec fuseau : 2026-10-21T09:41:00+00:00. Les horodatages sont en UTC, qui est aussi l'heure de Freetown (Africa/Freetown, GMT, pas d'heure d'été).

Codes HTTP

Code	Sens
200	Succès, ressource renvoyée
201	Créé, ressource renvoyée
202	Accepté, traitement asynchrone
204	Succès sans contenu (ex. DELETE)
400	Requête malformée
401	Authentification absente ou invalide
403	Authentification valide, droits insuffisants
404	Ressource introuvable
409	Conflit (idempotence)
422	Validation métier échouée
429	Limite de débit
500	Erreur interne (à signaler)
502	Orange Money indisponible en aval
503	Maintenance planifiée

Versionnement

L'URL contient la version : /v1. Voir la politique de versionnement.

Limitation de débit

Des limites s'appliquent par clé API et par endpoint sensible. Les valeurs exactes dépendent de votre profil d'activité ; en cas de dépassement, vous recevez 429 Too Many Requests avec un header Retry-After. Contactez le support avant une hausse de trafic prévue.

Compression

Accept-Encoding: gzip est pris en charge.

CORS

L'API n'est pas faite pour être appelée depuis un navigateur (cela exposerait votre clé secrète). Passez par votre serveur ; dans le navigateur, utilisez SOAMTAR.js avec votre clé publique.