Paiements

Créer un paiement

POST /v1/payments

Envoie une demande de paiement Orange Money sur le téléphone du client. Le client la confirme avec son code PIN ; vous apprenez le résultat par webhook.

Headers

Authorization: Bearer sk_(test|live)_…
Idempotency-Key: <uuid> (recommandé — voir Idempotence)
Content-Type: application/json

Corps

json

{
  "merchant_ref": "ORDER-001",
  "amount": "150.00",
  "currency": "SLE",
  "provider": "orange_money_sl",
  "payer": {
    "phone": "+23276123456",
    "email": "customer@example.com",
    "name": "Aminata Kamara",
    "country": "SL"
  },
  "description": "Commande #001",
  "success_url": "https://shop.example.com/success",
  "failed_url": "https://shop.example.com/cancel",
  "callback_url": "https://shop.example.com/webhooks/soamtar",
  "metadata": { "cart_id": "abc-123" }
}

Champ	Type	Requis	Notes
`merchant_ref`	string, max 255	oui	Unique par marchand. Sert d'idempotence métier.
`amount`	décimal	oui	Montant en leones, au plus deux décimales (ex. `150.00`). Minimum 1. Un montant plus précis est rejeté, jamais arrondi.
`currency`	enum	optionnel	`SLE` (par défaut), `USD` ou `EUR`.
`provider`	string	optionnel	`orange_money_sl`. Si absent → page de paiement hébergée.
`phone` / `payer.phone`	string	optionnel	Numéro Orange Money du client, E.164 (`+232` + 8 chiffres). Nécessaire pour envoyer la demande sur le téléphone ; sinon, utilisez la page hébergée.
`payer.email`, `payer.name`, `payer.country`		optionnel	Si un téléphone est fourni, un profil client est créé ou mis à jour.
`success_url` / `failed_url`	url	optionnel	URL de retour (HTTPS publique). `return_url` / `cancel_url` sont acceptés comme alias. Par défaut : les URL configurées sur votre compte.
`callback_url`	url	optionnel	URL HTTPS publique qui reçoit tous les événements de cette transaction (même payload, même `X-Soamtar-Signature`, mêmes relances que vos endpoints), en plus de vos endpoints enregistrés. Signée avec le secret de votre plus ancien endpoint actif du même environnement : enregistrez au moins un endpoint, sinon le callback n'est pas envoyé. Voir Webhooks.
`metadata`	objet	optionnel	Renvoyé tel quel dans chaque webhook (50 clés max, valeurs scalaires).

Réponse `201`

json

{
  "data": {
    "id": "0e85b3c2-7c4f-4f1d-9b3a-1c8a2d4e5f6a",
    "object": "transaction",
    "reference": "TXN-1A2B3C4D-ABCDEF123456",
    "merchant_ref": "ORDER-001",
    "provider_ref": null,
    "type": "payment",
    "payment_method": "orange_money_sl",
    "status": "pending",
    "next_action": null,
    "amount": "150.00",
    "currency": "SLE",
    "payer": { "phone": "+23276123456", "name": "Aminata Kamara", ... },
    "payment_url": "https://app.so-amtar.com/pay/checkout/0e85b3c2-...",
    "is_test": true,
    "initiated_at": "2026-10-21T09:40:00+00:00",
    "expires_at": "2026-10-21T11:40:00+00:00"
  },
  "livemode": false
}

provider_ref reçoit l'identifiant de transaction Orange Money une fois le paiement confirmé.

Statuts

Statut	Sens
`initiated`	Créé sur SOAMTAR, pas encore envoyé à Orange Money (page hébergée)
`pending`	Demande envoyée sur le téléphone du client, en attente de sa confirmation par code PIN
`processing`	Une action du payeur est encore attendue
`success`	Paiement confirmé, fonds reçus
`failed`	Refusé par Orange Money (solde insuffisant, code PIN erroné, demande non confirmée à temps…)
`cancelled`	Annulé par le payeur
`expired`	`expires_at` dépassé sans statut final (2 heures par défaut)
`partially_refunded`	Paiement réussi dont une partie du montant a été remboursée
`refunded`	Les remboursements couvrent la totalité du paiement

Les transitions interdites sont rejetées pour garantir l'intégrité des états. Voir Statuts de paiement.

Ce que voit le client

Avec Orange Money Sierra Leone, il n'y a ni OTP ni redirection à gérer : le client reçoit une demande de paiement sur son téléphone (en anglais), vérifie le nom du marchand et le montant en leones, puis confirme avec son code PIN Orange Money. La demande reste ouverte environ 5 minutes. Affichez un écran « Vérifiez votre téléphone pour confirmer le paiement » et attendez le webhook.

Consulter un paiement

GET /v1/payments/{id_or_reference}

Accepte l'id UUID ou la référence (TXN-…).

Lister les paiements

GET /v1/payments?status=success&provider=orange_money_sl&created_from=2026-10-01&per_page=50

Filtres : status, provider, created_from. Tri : created_at DESC.

Forcer la vérification (interrogation d'Orange Money)

POST /v1/payments/{id}/verify

Pour les rares cas où le webhook est perdu. Idempotent : sans effet sur une transaction déjà finale.

Rembourser un paiement

Un paiement réussi peut être remboursé, totalement ou partiellement, avec POST /v1/refunds. Le montant est recrédité sur le numéro Orange Money du payeur. Voir Remboursements.

Erreurs

Code	HTTP	Cause
`payment_rejected`	422	Devise non prise en charge, trop de décimales, limite marchand dépassée, provider indisponible
`gateway_error`	502	Orange Money a refusé de démarrer le paiement (timeout, format)
`idempotency_conflict`	409	Même clé, corps différent
`transaction_not_found`	404	Identifiant ou référence inconnu pour ce marchand

Paiements ​

Créer un paiement ​

Headers ​

Corps ​

Réponse 201 ​

Statuts ​

Ce que voit le client ​

Consulter un paiement ​

Lister les paiements ​

Forcer la vérification (interrogation d'Orange Money) ​

Rembourser un paiement ​

Erreurs ​