Integrating in Sierra Leone

Everything specific to accepting and sending payments in Sierra Leone with SOAMTAR. Read it once before you build; it saves most support questions.

• At a glance
• Currency: the leone (SLE)
  • Displaying amounts
• Phone numbers
• Collecting a payment
• Sending money (payouts)
• Refunds
• Settlements to your bank account
• KYC
• Time zone and business hours
• Go-live checklist (Sierra Leone)

At a glance

	Value
Country	Sierra Leone — ISO code SL
Currency	Leone — SLE, 2 decimals
Phone numbers	E.164: +232 + 8 digits, e.g. +23276123456
Payment channel	Orange Money Sierra Leone — provider orange_money_sl
Collections	Payment request pushed to the customer's phone, confirmed with their PIN
Payouts	To an Orange Money Sierra Leone wallet
Refunds	POST /v1/refunds — full or partial, credited back to the payer's Orange Money wallet
Time zone	Africa/Freetown — GMT all year, no daylight saving
Language of the payer's prompt	English

Currency: the leone (SLE)

• Always send amounts in SLE with at most two decimals, as a string: "150.00", "12.50". A more precise amount is rejected with 422, never rounded.
• SLL is not accepted. The leone was redenominated in 2022: one new leone (SLE) equals 1,000 old leones (SLL). If your catalogue or a customer still quotes old leones, divide by 1,000 before calling the API.
• USD and EUR are also accepted by the API; Orange Money collects in leones and the exchange rate is frozen when the payment is created.

Displaying amounts

Show leones the way customers in Freetown read them: the Le symbol, a comma for thousands, a point for cents.

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

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

Phone numbers

• Use E.164: +232 followed by the 8-digit national number, without spaces, dashes or a leading 0.

Customer types	Send
076 123 456	+23276123456
76123456	+23276123456
+232 76 123 456	+23276123456

• For payments, the leading + is optional (23276123456 is accepted).
• For payouts, the leading + is mandatory: the API refuses to send money to an ambiguous number.

// Normalise what the customer typed to 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('Enter an 8-digit Sierra Leone number')
  return `+232${digits}`
}

Collecting a payment

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": "Order #1001"
  }'

The response comes back immediately with status: "pending". Then:

1. Orange Money sends a payment request to the customer's phone, in English, showing your business name and the amount in leones.
2. The customer confirms with their Orange Money PIN. They have about 5 minutes to do so; after that Orange Money reports the request as failed.
3. SOAMTAR re-checks the outcome with Orange Money and sends you a signed payment.success or payment.failed webhook.

What to show while waiting:

Check your phone. We sent an Orange Money payment request of Le 150.00 to +232 76 123 456. Enter your PIN to confirm.

Deliver only after the payment.success webhook, never on the browser's word. If a payment stays pending, call POST /v1/payments/{id}/verify. An unfinished payment expires after 2 hours by default.

Do not have the customer's number? Omit provider and redirect them to the hosted checkout, where they enter it themselves.

Sending money (payouts)

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": "Supplier payment"
  }'

The amount is credited to the recipient's Orange Money wallet; you receive payout.success or payout.failed. Payouts require the can_payout scope and a live key (sk_live_…): with a test key the API answers payout_not_allowed_in_test_mode. Start with a small amount to a number you control.

Refunds

Refund a success payment with POST /v1/refunds (scope can_refund). Omit amount to refund the full remaining amount, or pass a decimal string for a partial refund:

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 credits the amount back to the payer's Orange Money number and debits it from your balance. The payment must have a payer phone (refund_payer_phone_missing otherwise).
• The Orange credit is asynchronous: the response (201) usually shows processing; the final outcome arrives as refund.success (plus payment.refunded or payment.partially_refunded) or refund.failed. With a test key the refund is success immediately.
• Several partial refunds are allowed until the payment is fully refunded.

See the Refunds reference.

Settlements to your bank account

Settlements are paid to your Sierra Leone bank account. Sierra Leone does not use IBANs: in the dashboard, enter your bank name and account number (5 to 50 letters or digits, no spaces). Timing depends on your agreement and is shown in the dashboard.

KYC

To go live you provide, in the dashboard:

• your company registration number and certificate;
• your tax identification number (TIN);
• an ID document of a director;
• your bank account details.

The review outcome and any missing document appear in the dashboard. Limits per verification level are shown once your account is active.

Time zone and business hours

• API timestamps are in UTC, which is the same as Freetown time (Africa/Freetown, GMT, no daylight saving).
• Support answers during business hours in Freetown, excluding Sierra Leone public holidays.

Go-live checklist (Sierra Leone)

• [ ] Amounts sent in SLE with two decimals; old SLL prices converted (÷ 1,000).
• [ ] Phone numbers normalised to +232 + 8 digits; + always present for payouts.
• [ ] "Check your phone" screen shown while the payment is pending.
• [ ] Orders delivered only after a verified payment.success webhook.
• [ ] Refunds issued with POST /v1/refunds; refund.success / refund.failed handled.
• [ ] KYC complete and bank account (account number) entered.
• [ ] Live secret key (sk_live_) stored on your server only.

See also the general go-live checklist.