SDK e bibliotecas cliente

As bibliotecas oficiais da SOAMTAR cobrem as linguagens de servidor, as apps móveis, o navegador, o Unity e as principais plataformas de comércio eletrónico. Todas visam a Serra Leoa: montantes em leones (SLE, sendo também aceites USD e EUR), Orange Money Sierra Leone (orange_money_sl) como único fornecedor, telefones do pagador no formato +232 seguido de 8 dígitos.

Disponibilidade

As versões abaixo são finais, mas os pacotes ainda não estão publicados nos registos públicos (npm, Packagist, PyPI, RubyGems, Maven Central, NuGet, pub.dev…). Até lá, instale-os a partir do repositório de código fornecido pelo suporte SOAMTAR. O SDK de navegador já é servido em https://app.so-amtar.com/sdk/soamtar.js (ainda não está no npm).

---

Como escolher?

O meu perfil	A minha recomendação
Estou a começar	Siga o guia de início rápido. É o caminho mais simples.
Uso um CMS	Vá diretamente à secção Plugins CMS e comércio eletrónico.
Sou programador backend	Escolha a sua linguagem na secção Servidor.
Crio uma app móvel ou um jogo	Use as bibliotecas da secção Móvel e frontend. É sempre o seu backend que cria o pagamento.

As páginas por linguagem de servidor e a do navegador estão disponíveis em inglês.

Dois tipos de bibliotecas

	SDK de servidor	SDK cliente (navegador, móvel, Unity)
Chave	Chave secreta sk_test_… / sk_live_…	Chave pública pk_test_… / pk_live_… (ou nenhuma)
Onde corre	Apenas no seu backend	No navegador, telefone ou jogo do pagador
O que faz	Cria pagamentos (POST /v1/payments), consulta-os, verifica os webhooks	Abre o payment_url que o seu backend obteve com POST /v1/payments

Um SDK cliente nunca cria um pagamento nem guarda uma chave secreta. Não existe um host sandbox separado: com uma chave sk_test_, os pagamentos são simulados em https://app.so-amtar.com/v1.

---

Servidor (backend)

Linguagem	Pacote	Versão	Ponto de entrada
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

Móvel e frontend

Plataforma	Pacote	Versão	Ponto de entrada
Navegador (JavaScript)	@soamtar/browser, ou o script servido em 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, com react-native-webview)	1.1.0	SoamtarClient, SoamtarCheckout
Unity (jogos)	Pasta Assets/Soamtar	1.0.1	Soamtar.SoamtarClient

Plugins CMS e comércio eletrónico

Plataforma	Plugin	Versão
WordPress / WooCommerce	SOAMTAR for WooCommerce (soamtar-gateway)	1.1.0
Magento 2	soamtar/magento2-payment (módulo Soamtar_Payment)	1.1.0
PrestaShop 1.7.7+	Módulo de pagamento soamtar	1.1.0
Drupal Commerce	soamtar/drupal-commerce (módulo soamtar_commerce)	1.1.0
Odoo	payment_soamtar (SOAMTAR Payment Provider)	17.0.1.1.0

Terminais de pagamento (TPA / Smart POS)

Está em preparação um SDK SOAMTAR para terminais de pagamento Android. Depende de endpoints /v1/pos/* que ainda não estão disponíveis na API: não o use em produção.

---

Convenções comuns

Os SDK de servidor expõem a mesma superfície, adaptada ao estilo de nomes de cada linguagem (CreateAsync em .NET, Create(ctx, …) em Go):

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 aceita o identificador ou a referência SOAMTAR (TXN-…), não o seu merchant_ref.
• Os clientes de servidor recusam qualquer chave que não comece por sk_. Sem chave passada, leem SOAMTAR_SECRET_KEY; o URL base vem de SOAMTAR_API_URL (SOAMTAR_BASE_URL continua aceite como alternativa), por omissão https://app.so-amtar.com/v1.
• Cada POST leva um cabeçalho Idempotency-Key: gerado automaticamente ou o que passar.
• webhooks.create: subscribed_events é opcional e por omissão vale payment.success, payment.failed, payout.success, payout.failed.
• webhooks.sendTest() (send_test / SendTest consoante a linguagem) pede à SOAMTAR que envie um evento webhook.test aos seus endpoints.
• Os nomes antigos (webhooks.test, webhooks.all, balance.show, status.retrieve…) continuam disponíveis como aliases obsoletos.
• Os erros lançam uma exceção SOAMTAR com o estado HTTP e o código de erro da API.

A assinatura opcional dos pedidos (ver Authentication) é uma opção do cliente:

Linguagem	Opção
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)

Função de verificação de webhooks por linguagem:

Linguagem	Função
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)

Cada função verifica o cabeçalho X-Soamtar-Signature (t=<unix>,v1=<hmac>, mais v2= durante a rotação de um segredo), recalcula HMAC-SHA256(secret, "t.payload") sobre o corpo bruto, rejeita carimbos temporais com mais de 300 segundos e devolve o evento descodificado (event, created, data). Consulte Webhooks.

Reembolsos

client.refunds.create({ transaction_id, amount? }) devolve o dinheiro ao número Orange Money do pagador, debitado do seu saldo. Sem amount, é reembolsado tudo o que resta; reembolsos parciais são permitidos. O reembolso é assíncrono: o resultado chega com refund.success / refund.failed. A chave precisa do scope can_refund. Ver Refunds.

Padrões recomendados

Reutilizar o cliente

Crie um único cliente por processo e reutilize-o, em vez de criar um por pedido:

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
  })
}

Repetir com backoff

Os SDK não repetem pedidos por si próprios. Se adicionar repetições, reutilize a mesma Idempotency-Key para que um POST repetido nunca crie um segundo pagamento:

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 }))

Importante

Repita os erros de rede, 429 e 5xx com a mesma Idempotency-Key. Nunca repita os outros 4xx: corrija primeiro o pedido. Consulte Idempotency (em inglês).

Gerar a partir da especificação OpenAPI

Para uma linguagem sem SDK, gere um cliente tipado a partir da especificação 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

Pedir um SDK

Falta a sua linguagem? Escreva para support@so-amtar.com indicando:

• a linguagem / framework pretendida;
• o volume de transações previsto;
• o seu caso de uso principal.