Browser SDK (SoamtarSDK)

The SOAMTAR browser SDK (SoamtarSDK, version 1.0.0) sends your customers from your web page to the SOAMTAR checkout, where they approve the payment on their phone with their Orange Money PIN (Sierra Leone, amounts in leones, SLE).

Security

• The SDK uses your public key (pk_test_… / pk_live_…) only. A secret key (sk_…) throws an error immediately.
• Payments are always created by your backend with your secret key (POST /v1/payments, for instance with the Node.js SDK). The browser only opens the payment_url your backend returns.
• Payment URLs must be HTTPS (or a same-origin path).

Installation

From the SOAMTAR CDN (recommended, always the version the API serves):

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

The npm package @soamtar/browser is not published yet. Until it is, install it from the SDK repository:

npm install /path/to/soamtar-js-browser   # or a git URL to the repository

import '@soamtar/browser' // defines window.SoamtarSDK

Usage

1. Your backend already created the payment

const soamtar = SoamtarSDK('pk_live_your_public_key')

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

2. Let the SDK call your backend

The SDK POSTs the setup() object as JSON to requestTokenUrl, with the X-Public-Key header. Your backend creates the payment with POST /v1/payments and answers { "payment_url": "https://…" }.

SoamtarSDK('pk_live_your_public_key')
  .setup({
    merchant_ref: 'ORDER-1042',
    amount: '1250.00',            // leones, 2 decimals
    currency: 'SLE',
    payer_phone: '+23276123456'   // +232 followed by 8 digits
  })
  .withConfig({
    requestTokenUrl: '/api/create-payment',
    presentationMode: SoamtarSDK.REDIRECT_NEW,
    onError: (message) => alert(message),
  })
  .start()

payer_name, payer_phone, payer_email and provider from setup() are appended to the payment URL as name, phone, email and method to pre-fill the checkout.

A matching backend route, with the Node.js SDK (the backend maps payer_phone to the phone of 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,   // check it against your own order
    amount: req.body.amount,               // recompute it server side, never trust the browser
    phone: req.body.payer_phone,
    success_url: 'https://shop.example.sl/thanks',
    failed_url: 'https://shop.example.sl/payment-failed',
  })
  res.json({ payment_url: data.payment_url })
})

API

Member	Description
SoamtarSDK(publicKey)	Creates an instance. Trims spaces, a Bearer prefix and surrounding quotes. Throws on a missing, secret or malformed key.
.setup(config)	Payment data. config.url = a payment URL to open directly; otherwise the whole object is sent to requestTokenUrl. Chainable.
.withConfig(options)	Overrides the options below. Chainable.
.start()	Opens the checkout.
SoamtarSDK.version	1.0.0

Options

Option	Default	Description
presentationMode	SoamtarSDK.REDIRECT_SELF	REDIRECT_SELF (same tab) or REDIRECT_NEW (new tab). SoamtarSDK.MODAL is kept for compatibility and equals REDIRECT_SELF.
requestTokenUrl	—	Your backend route returning { payment_url } (or redirect_url).
method	POST	HTTP method used for requestTokenUrl.
headers	JSON + X-Public-Key	Headers for requestTokenUrl. Replace the whole object to add your CSRF token.
onBeforeStart()	no-op	Called before the checkout opens.
onError(message)	console.error	Configuration, network (15 s timeout) or backend error.
onSuccess, onCancel	no-op	Kept for compatibility, never called: the outcome arrives on your success_url / failed_url and by webhook.

Confirm on the server

The customer coming back to your success_url proves nothing. Deliver the order only after the payment.success webhook (or GET /v1/payments/{id} from your backend).