SDK 与客户端库

SOAMTAR 官方库覆盖服务器端语言、移动应用、浏览器、Unity 以及主流电商平台。它们全部面向塞拉利昂：金额以利昂（SLE）计价（同时接受 USD 和 EUR），唯一的支付提供商为 Orange Money Sierra Leone（orange_money_sl），付款人手机号格式为 +232 加 8 位数字。

可用性

下列版本已定稿，但尚未发布到公共仓库（npm、Packagist、PyPI、RubyGems、Maven Central、NuGet、pub.dev 等）。在此之前，请从 SOAMTAR 支持团队提供的源代码仓库安装。浏览器 SDK 已在 https://app.so-amtar.com/sdk/soamtar.js 提供（尚未发布到 npm）。

---

如何选择？

我的情况	建议
我是新手	按照 快速入门指南 操作。这是最简单的路径。
我使用 CMS	直接查看 CMS 与电商插件 部分。
我是后端开发者	在 服务器 部分选择您的语言。
我在开发移动应用或游戏	使用 移动端与前端 部分的库。支付始终由您的后端创建。

服务器端各语言页面和浏览器页面目前只有英文版。

两类库

	服务器 SDK	客户端 SDK（浏览器、移动端、Unity）
密钥	私钥 sk_test_… / sk_live_…	公钥 pk_test_… / pk_live_…（或无需密钥）
运行位置	仅在您的后端	付款人的浏览器、手机或游戏中
作用	创建支付（POST /v1/payments）、查询支付、验证 webhook	打开您的后端通过 POST /v1/payments 获得的 payment_url

客户端 SDK 从不创建支付，也从不持有私钥。没有单独的沙箱主机：使用 sk_test_ 密钥时，支付会在 https://app.so-amtar.com/v1 上以模拟方式处理。

---

服务器（后端）

语言	包	版本	入口
PHP / Laravel	soamtar/soamtar-php（Composer，PHP 8.2+）	1.1.0	Soamtar\SoamtarClient、Soamtar\Soamtar
Node.js / TypeScript	@soamtar/sdk（npm）	1.1.0	SoamtarClient
Python	soamtar（pip）	1.1.0	soamtar.SoamtarClient
Ruby	soamtar（gem）	1.1.0	Soamtar::Client
Java	com.soamtar:soamtar-java（Maven）	1.1.0	com.soamtar.sdk.SoamtarClient
Go	github.com/soamtar/soamtar-go-sdk	1.1.0	soamtar.NewClient
.NET / C#	Soamtar（NuGet）	1.1.0	Soamtar.SoamtarClient

移动端与前端

平台	包	版本	入口
浏览器（JavaScript）	@soamtar/browser，或 https://app.so-amtar.com/sdk/soamtar.js 提供的脚本	1.0.0	SoamtarSDK
iOS (Swift)	SoamtarSDK（Swift Package Manager，iOS 14+）	1.0.1	Soamtar、SoamtarCheckoutView
Android (Kotlin)	com.soamtar:soamtar-android（Gradle）	1.1.0	com.soamtar.sdk.Soamtar
Flutter	soamtar_sdk（pub）	1.0.1	package:soamtar_sdk/soamtar_sdk.dart
React Native	@soamtar/react-native（npm，需 react-native-webview）	1.1.0	SoamtarClient、SoamtarCheckout
Unity（游戏）	Assets/Soamtar 文件夹	1.0.1	Soamtar.SoamtarClient

CMS 与电商插件

平台	插件	版本
WordPress / WooCommerce	SOAMTAR for WooCommerce（soamtar-gateway）	1.1.0
Magento 2	soamtar/magento2-payment（模块 Soamtar_Payment）	1.1.0
PrestaShop 1.7.7+	soamtar 支付模块	1.1.0
Drupal Commerce	soamtar/drupal-commerce（模块 soamtar_commerce）	1.1.0
Odoo	payment_soamtar（SOAMTAR Payment Provider）	17.0.1.1.0

支付终端（POS / Smart POS）

面向 Android 支付终端的 SOAMTAR SDK 正在准备中。它依赖的 /v1/pos/* 端点在 API 中尚不可用：请勿在生产环境中使用。

---

通用约定

各服务器 SDK 提供相同的接口，并按各语言的命名习惯调整（.NET 中为 CreateAsync，Go 中为 Create(ctx, …)）：

client.payments.create(params, idempotencyKey?)   POST /v1/payments
client.payments.retrieve(id)                      GET  /v1/payments/{id}
client.payments.list(filters)                     GET  /v1/payments
client.payments.status(idOrReference)             GET  /v1/status/{idOrReference}
client.payments.verify(id)                        POST /v1/payments/{id}/verify

client.payouts.create / retrieve / list           /v1/payouts
client.refunds.create / retrieve / list           /v1/refunds
client.balance.retrieve()                         GET  /v1/balance
client.webhooks.list / create / secret / sendTest /v1/webhooks

Webhook.constructEvent(rawBody, signatureHeader, secret)

• retrieve 接受 SOAMTAR 的 id 或参考号（TXN-…），而不是您的 merchant_ref。
• 服务器客户端拒绝任何不以 sk_ 开头的密钥。未传入密钥时读取 SOAMTAR_SECRET_KEY；基础 URL 取自 SOAMTAR_API_URL（仍接受 SOAMTAR_BASE_URL 作为后备），默认 https://app.so-amtar.com/v1。
• 每个 POST 都带有 Idempotency-Key 请求头：自动生成，或使用您传入的值。
• webhooks.create：subscribed_events 可选，默认为 payment.success、payment.failed、payout.success、payout.failed。
• webhooks.sendTest()（视语言为 send_test / SendTest）请求 SOAMTAR 向您的端点发送一个 webhook.test 事件。
• 旧方法名（webhooks.test、webhooks.all、balance.show、status.retrieve 等）仍作为已弃用的别名保留。
• 出错时抛出 SOAMTAR 异常，其中包含 HTTP 状态码和 API 错误码。

可选的请求签名（见 Authentication）是一个客户端选项：

语言	选项
Node.js	soamtar(key, { signRequests: true })
PHP	'sign_requests' => true
Python	SoamtarClient(..., sign_requests=True)
Ruby	Soamtar::Client.new(key, sign_requests: true)
Go	soamtar.WithSignRequests(true)
Java	new SoamtarClient(null, null, Duration.ofSeconds(30), true) (signRequests)
.NET	new SoamtarClient(signRequests: true)

各语言的 webhook 验证函数：

语言	函数
PHP	Soamtar\Webhook::constructEvent($rawBody, $signatureHeader, $secret)
Node.js	Webhook.constructEvent(rawBody, signatureHeader, secret)
Python	Webhook.construct_event(raw_body, signature_header, secret)
Ruby	Soamtar::Webhook.construct_event(raw_body, signature_header, secret)
Java	Webhook.constructEvent(payload, signatureHeader, secret)
Go	soamtar.ConstructEvent(payload, sigHeader, secret)
.NET	Webhook.ConstructEvent(payload, signatureHeader, secret)

每个函数都会检查 X-Soamtar-Signature 请求头（t=<unix>,v1=<hmac>，密钥轮换期间还会有 v2=），在原始请求体上重新计算 HMAC-SHA256(secret, "t.payload")，拒绝超过 300 秒的时间戳，并返回解码后的事件（event、created、data）。参见 Webhooks。

退款

client.refunds.create({ transaction_id, amount? }) 会把款项退回付款人的 Orange Money 号码，并从您的余额中扣除。省略 amount 即退还剩余全部金额；允许部分退款。退款是异步的：结果通过 refund.success / refund.failed 通知。密钥需要 can_refund 权限。见 Refunds。

推荐模式

复用客户端

每个进程只创建一个客户端并重复使用，而不是每个请求都新建一个：

import { SoamtarClient } from '@soamtar/sdk'

const soamtar = new SoamtarClient(process.env.SOAMTAR_SECRET_KEY)

export function pay(order: { id: string; amount: string; phone: string }) {
  return soamtar.payments.create({
    merchant_ref: order.id,
    amount: order.amount,          // "1250.00" → Le 1,250.00
    currency: 'SLE',
    provider: 'orange_money_sl',
    phone: order.phone,            // +232XXXXXXXX
  })
}

指数退避重试

SDK 本身不会自动重试。如果您添加重试，请复用同一个 Idempotency-Key，这样重试的 POST 永远不会创建第二笔支付：

import { randomUUID } from 'node:crypto'

async function withRetry<T>(fn: (key: string) => Promise<T>, max = 3): Promise<T> {
  const idempotencyKey = randomUUID()   // one key for every attempt
  for (let attempt = 0; ; attempt++) {
    try {
      return await fn(idempotencyKey)
    } catch (e: any) {
      const retryable = !e.status || e.status === 429 || e.status >= 500
      if (!retryable || attempt >= max) throw e
      await new Promise(r => setTimeout(r, 2 ** attempt * 1000))   // 1s, 2s, 4s
    }
  }
}

await withRetry(key => soamtar.payments.create(params, { idempotencyKey: key }))

重要

网络错误、429 和 5xx 请使用相同的 Idempotency-Key 重试。其他 4xx 错误切勿重试：应先修正请求。参见 Idempotency（英文）。

基于 OpenAPI 规范生成

对于没有 SDK 的语言，可根据 OpenAPI 规范（openapi.yaml）生成类型化客户端：

# TypeScript types
npx openapi-typescript ./openapi.yaml -o src/soamtar.types.ts

# Python (openapi-generator)
openapi-generator-cli generate -i ./openapi.yaml -g python -o ./soamtar-py

# Go
oapi-codegen -package soamtar ./openapi.yaml > soamtar.gen.go

申请新的 SDK

缺少您使用的语言？请发送邮件至 support@so-amtar.com，并说明：

• 目标语言 / 框架；
• 预计交易量；
• 主要使用场景。