Changelog

Notable changes to the SOAMTAR API are listed here. SemVer versioning on the URL prefix.

[1.7.0] - 2026-10-22

Added

• Refunds API: POST /v1/refunds (full or partial; omit amount for the full remaining amount), GET /v1/refunds/{id} and GET /v1/refunds. The amount is credited back to the payer's Orange Money number and debited from your balance; the credit is asynchronous (processing, then success or failed). Requires the can_refund scope. See Refunds.
• Refund webhooks: refund.success, refund.failed, and on the payment payment.refunded / payment.partially_refunded (with data.refund). One set of events per refund.
• callback_url delivered: the optional per-payment / per-payout HTTPS callback_url now receives every event of that transaction, with the same payload, X-Soamtar-Signature (secret of your oldest active webhook endpoint in the same environment) and retries. See Webhooks.
• Optional request signing: Soamtar-Timestamp + Soamtar-Signature: v1=… headers on non-GET requests, available as an option in every SDK. See Authentication.

Changed

• Webhook event catalog: only events SOAMTAR actually sends can be subscribed to (payment.*, payout.*, refund.*, payout_request.*). The test button and POST /v1/webhooks/test both send webhook.test, delivered regardless of subscriptions.
• SDKs 1.1.0: common conventions across languages — SOAMTAR_SECRET_KEY and SOAMTAR_API_URL environment variables, payments / payouts / refunds / webhooks / balance resources with the same method names. Old names remain as deprecated aliases. E-commerce plugins support native refunds. See SDKs.

---

[1.6.0] - 2026-10-20

Changed (impact on existing integrations)

• Sierra Leone only: SOAMTAR now operates exclusively in Sierra Leone (country SL).
• Orange Money Sierra Leone, single channel: provider orange_money_sl (Orange Money Business API) for collections and payouts.
• Leone currency (SLE): amounts with at most two decimals (e.g. 150.00); a more precise amount is rejected, never rounded. The API also accepts USD and EUR.
• Phone numbers: E.164 format, +232 followed by 8 digits.
• Refunds: available through POST /v1/refunds since 1.7.0.
• The channels and countries previously offered are removed.

---

[1.2.0] - 2026-04-25

Added (SDK ecosystem)

• Official SDKs and plugins covering backend, mobile, web and CMS.
• Backend SDKs (7): PHP/Laravel, Node.js, Python, Ruby, Java/Spring Boot, Go, .NET/C#.
• Mobile & gaming SDKs (5): Android (Kotlin), iOS (Swift), React Native, Flutter, Unity (C#).
• Web frontend SDK (1): SOAMTAR.js for native integrations and secure pop-ups.
• CMS & e-commerce plugins (6): WordPress/WooCommerce, Magento 2, PrestaShop, Drupal, Odoo, WHMCS.
• No-code guide: instructions for Wix (Velo), Shopify and Webflow.

Security (SDK hardening)

• Public key lock: all frontend/mobile SDKs reject secret keys (sk_...) to prevent accidental exposure.
• Timing-attack resistance: constant-time comparisons in all server SDKs.
• Webhook anti-DoS: 1 MB payload limit and built-in timestamp (anti-replay) checks.
• Minimal dependencies: most SDKs are built without third-party libraries to reduce supply-chain risk.

Security (backend hardening)

• API key hashing: secret keys are no longer stored in clear text.
• Tenant isolation: stronger access control on resources at the SQL level.
• Advanced rate limiting: per-IP and per-merchant protection on sensitive routes (OTP).

---

[1.1.0]

Added

• Stricter webhook endpoint URL validation: non-HTTPS URLs, loopback hosts (localhost, 127.x), private IPs and internal TLDs are rejected at creation.
• Automatic masking of sensitive values in API logs: if a merchant passes ?payer_phone=... or ?api_key=... in a query string by mistake, the value is replaced with [REDACTED] before it is stored.

Changed (compatible)

• Public references extended to 16 random characters after the prefix, e.g. TXN-A1B2C3D4E5F6G7H8. If your code hard-codes the length, allow at least 20 characters. Older references remain valid.
• Channel webhook events: only events actually emitted by the payment channel are propagated. Abandonment and expiry are still emitted by SOAMTAR as payment.cancelled / payment.expired.

Security

• Timestamped signatures can be required per channel (internal flag, managed by SOAMTAR).
• Stronger concurrency safety on multi-row writes (marketplace splits in particular): two parallel requests on the same parent transaction are serialised.
• X-XSS-Protection header removed (deprecated); XSS protection relies on the Content-Security-Policy.
• Quota on the creation of new Idempotency-Key values per merchant account, to protect the platform from a compromised key generating a UUID per request. Replays of existing keys are not affected.

[1.0.0]

First public API version.

Added

• Payments: POST /v1/payments with idempotency, hosted checkout without provider.
• Pull verification: POST /v1/payments/{id}/verify.
• Timestamped HMAC-SHA256 signed webhooks, exponential retries, zero-downtime secret rotation.
• Marketplace splits: POST and GET /v1/payments/{id}/splits with invariants (total, active beneficiary, immutability).
• Customers created automatically at initiation.
• FX freeze: rate frozen at initiation when currencies differ.
• Automatic reconciliation to catch lost webhooks.
• Automatic expiry of unfinished transactions.

Security

• TLS 1.2 minimum.
• Merchant webhook URLs must use HTTPS.
• Anti-replay on inbound and outbound signatures.
• Records retained as required by the applicable regulations.

[Unreleased]

Planned

• Mobile money tokenisation for recurring subscriptions

---

Versioning policy

• Patch (1.0.x): bug fixes and optimisations, no API change.
• Minor (1.x.0): new endpoints, new optional fields. Compatible.
• Major (x.0.0): breaking changes, announced several months ahead, with the previous version supported during a transition period.

No existing field is ever removed or renamed without a major version. New optional fields can appear in any minor version.

Subscribing to announcements

• Dashboard → Settings → Notifications → API changes
• Summary email for merchants in production