Intégrer en Sierra Leone

Tout ce qui est propre aux encaissements et aux paiements sortants en Sierra Leone avec SOAMTAR. Lisez-le une fois avant de développer : il répond à la plupart des questions posées au support.

En bref

	Valeur
Pays	Sierra Leone — code ISO `SL`
Devise	Leone — `SLE`, 2 décimales
Numéros de téléphone	E.164 : `+232` + 8 chiffres, ex. `+23276123456`
Canal de paiement	Orange Money Sierra Leone — provider `orange_money_sl`
Encaissements	Demande de paiement envoyée sur le téléphone du client, confirmée avec son code PIN
Paiements sortants	Vers un compte Orange Money Sierra Leone
Remboursements	`POST /v1/refunds` — total ou partiel, recrédité sur le portefeuille Orange Money du payeur
Fuseau horaire	`Africa/Freetown` — GMT toute l'année, sans heure d'été
Langue de la demande reçue par le payeur	Anglais

La devise : le leone (SLE)

Envoyez toujours les montants en SLE, avec deux décimales au plus, sous forme de chaîne : "150.00", "12.50". Un montant plus précis est refusé (422), jamais arrondi.
SLL n'est pas accepté. Le leone a été redénominé en 2022 : un nouveau leone (SLE) vaut 1 000 anciens leones (SLL). Si votre catalogue ou un client indique encore des prix en anciens leones, divisez par 1 000 avant d'appeler l'API.
L'API accepte aussi USD et EUR ; Orange Money encaisse en leones et le taux de change est figé à la création du paiement.

Afficher les montants

Affichez les leones comme on les lit à Freetown : le symbole Le, une virgule pour les milliers, un point pour les centimes.

const formatLe = (amount) =>
  `Le ${Number(amount).toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`

formatLe('1250')   // "Le 1,250.00"

Numéros de téléphone

Utilisez le format E.164 : +232 suivi du numéro national à 8 chiffres, sans espace, tiret ni 0 initial.

Le client saisit	Envoyez
`076 123 456`	`+23276123456`
`76123456`	`+23276123456`
`+232 76 123 456`	`+23276123456`

Pour les paiements, le + initial est facultatif (23276123456 est accepté).
Pour les paiements sortants, le + initial est obligatoire : l'API refuse d'envoyer de l'argent vers un numéro ambigu.

// Normaliser la saisie du client au format E.164 (Sierra Leone)
function toE164SL(input) {
  let digits = input.replace(/\D/g, '')
  if (digits.startsWith('232')) digits = digits.slice(3)
  digits = digits.replace(/^0+/, '')
  if (digits.length !== 8) throw new Error('Saisissez un numéro sierra-léonais à 8 chiffres')
  return `+232${digits}`
}

Encaisser un paiement

bash

curl -X POST https://app.so-amtar.com/v1/payments \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_ref": "ORDER-1001",
    "amount": "150.00",
    "currency": "SLE",
    "provider": "orange_money_sl",
    "phone": "+23276123456",
    "description": "Commande #1001"
  }'

La réponse arrive immédiatement avec status: "pending". Ensuite :

Orange Money envoie une demande de paiement sur le téléphone du client, en anglais, avec le nom de votre entreprise et le montant en leones.
Le client confirme avec son code PIN Orange Money. Il dispose d'environ 5 minutes ; passé ce délai, Orange Money signale la demande comme échouée.
SOAMTAR revérifie le résultat auprès d'Orange Money et vous envoie un webhook signé payment.success ou payment.failed.

À afficher pendant l'attente :

Vérifiez votre téléphone. Nous avons envoyé une demande de paiement Orange Money de Le 150.00 au +232 76 123 456. Saisissez votre code PIN pour confirmer.

Ne livrez qu'après le webhook payment.success, jamais sur la foi du navigateur. Si un paiement reste pending, appelez POST /v1/payments/{id}/verify. Un paiement non finalisé expire au bout de 2 heures par défaut.

Vous n'avez pas le numéro du client ? Omettez provider et redirigez-le vers la page de paiement hébergée, où il le saisit lui-même.

Envoyer de l'argent (paiements sortants)

bash

curl -X POST https://app.so-amtar.com/v1/payouts \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_ref": "PAYOUT-2001",
    "amount": "50.00",
    "currency": "SLE",
    "provider": "orange_money_sl",
    "recipient": { "phone": "+23276123456", "name": "Aminata Kamara" },
    "description": "Paiement fournisseur"
  }'

Le montant est crédité sur le compte Orange Money du bénéficiaire ; vous recevez payout.success ou payout.failed. Les paiements sortants exigent le scope can_payout et une clé live (sk_live_…) : avec une clé de test, l'API répond payout_not_allowed_in_test_mode. Commencez par un petit montant vers un numéro que vous contrôlez.

Remboursements

Remboursez un paiement success avec POST /v1/refunds (scope can_refund). Omettez amount pour rembourser tout le montant restant, ou passez une chaîne décimale pour un remboursement partiel :

bash

curl -X POST https://app.so-amtar.com/v1/refunds \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: refund-ORDER-1001-1" \
  -d '{ "transaction_id": "TXN-...", "amount": "40.00", "reason": "customer_request" }'

SOAMTAR recrédite le montant sur le numéro Orange Money du payeur et le débite de votre solde. Le paiement doit comporter le téléphone du payeur (sinon refund_payer_phone_missing).
Le crédit Orange est asynchrone : la réponse (201) indique en général processing ; le résultat final arrive par refund.success (avec payment.refunded ou payment.partially_refunded) ou refund.failed. Avec une clé de test, le remboursement est success immédiatement.
Plusieurs remboursements partiels sont possibles jusqu'au remboursement total du paiement.

Voir la référence Remboursements.

Reversements sur votre compte bancaire

Les reversements sont versés sur votre compte bancaire en Sierra Leone. La Sierra Leone n'utilise pas l'IBAN : dans le dashboard, saisissez le nom de votre banque et votre numéro de compte (5 à 50 lettres ou chiffres, sans espace). Le rythme dépend de votre contrat et est affiché dans le dashboard.

KYC

Pour passer en production, vous fournissez dans le dashboard :

le numéro d'enregistrement de votre entreprise et son certificat ;
votre numéro d'identification fiscale (TIN) ;
une pièce d'identité d'un dirigeant ;
vos coordonnées bancaires.

Le résultat de la vérification et les pièces manquantes s'affichent dans le dashboard. Les plafonds par niveau de vérification sont visibles une fois le compte activé.

Fuseau horaire et heures ouvrées

Les horodatages de l'API sont en UTC, c'est-à-dire l'heure de Freetown (Africa/Freetown, GMT, sans heure d'été).
Le support répond aux heures ouvrées de Freetown, hors jours fériés sierra-léonais.

Checklist de mise en production (Sierra Leone)

[ ] Montants envoyés en SLE avec deux décimales ; anciens prix en SLL convertis (÷ 1 000).
[ ] Numéros normalisés en +232 + 8 chiffres ; + toujours présent pour les paiements sortants.
[ ] Écran « Vérifiez votre téléphone » affiché tant que le paiement est pending.
[ ] Commandes livrées uniquement après un webhook payment.success vérifié.
[ ] Remboursements émis avec POST /v1/refunds ; refund.success / refund.failed gérés.
[ ] KYC complet et compte bancaire (numéro de compte) renseigné.
[ ] Clé secrète live (sk_live_) stockée uniquement sur votre serveur.

Voir aussi la checklist générale de mise en production.

Intégrer en Sierra Leone ​

En bref ​

La devise : le leone (SLE) ​

Afficher les montants ​

Numéros de téléphone ​

Encaisser un paiement ​

Envoyer de l'argent (paiements sortants) ​

Remboursements ​

Reversements sur votre compte bancaire ​

KYC ​

Fuseau horaire et heures ouvrées ​

Checklist de mise en production (Sierra Leone) ​

Intégrer en Sierra Leone

En bref

La devise : le leone (SLE)

Afficher les montants

Numéros de téléphone

Encaisser un paiement

Envoyer de l'argent (paiements sortants)

Remboursements

Reversements sur votre compte bancaire

KYC

Fuseau horaire et heures ouvrées

Checklist de mise en production (Sierra Leone)