Integrar a SOAMTAR no seu site

Este guia mostra como aceitar pagamentos com o Orange Money Serra Leoa no seu site em três passos:

No servidor: criar uma transação (um pedido autenticado com a sua chave secreta).
No navegador: abrir a janela de pagamento da SOAMTAR com o SDK JS.
No servidor: receber e verificar o webhook final.

Arquitetura recomendada: a janela JS nunca comunica com a SOAMTAR usando a sua chave secreta. Chama uma rota do seu backend, que é quem chama a SOAMTAR. É a única forma de manter sk_live_… fora do navegador.

Visão geral do fluxo

Browser                 Your backend                SOAMTAR                 Customer's phone
   |  click "Pay"            |                          |                          |
   |------------------------>|  POST /v1/payments       |                          |
   |                         |------------------------->|                          |
   |                         |<-------------------------|  payment_url, id         |
   |<------------------------|  { paymentUrl }          |                          |
   |  SOAMTAR window opens   |                          |  Orange Money request    |
   |------------------------------------------------->  |------------------------->|
   |                         |                          |<-------------------------|
   |                         |                          |   customer enters PIN    |
   |                         |<-------------------------|                          |
   |                         |  signed webhook          |                          |
   |                         |  payment.success         |                          |
   |<------------------------|  return_url / JS callback|                          |

1. Pré-requisitos

Uma conta de comerciante em https://app.so-amtar.com (KYC aprovado para o modo live).
As suas chaves API, em Programadores → Chaves API:
- sk_test_… para o sandbox
- sk_live_… para produção
Um endpoint HTTPS público para os webhooks (o modo de teste aceita túneis ngrok / cloudflared).

Nunca exponha sk_live_ no navegador

Qualquer chave API da SOAMTAR é secreta. A janela JS nunca precisa dela: chama o seu backend, que faz o pedido de servidor para servidor.

2. Backend: criar uma transação

O seu backend expõe uma única rota interna (por exemplo POST /checkout/soamtar) chamada pelo navegador. Esta rota:

Verifica o utilizador e o carrinho.
Chama POST https://app.so-amtar.com/v1/payments.
Devolve payment_url e id ao navegador.

Endpoint da SOAMTAR

Método	URL
`POST`	`https://app.so-amtar.com/v1/payments`

Cabeçalhos:

Cabeçalho	Valor
`Authorization`	`Bearer sk_test_…` ou `sk_live_…`
`Content-Type`	`application/json`

Corpo:

Campo	Tipo	Obrigatório	Descrição
`merchant_ref`	string	sim	A sua referência única (número da encomenda).
`amount`	numeric	sim	Montante em leones, com duas casas decimais no máximo (por ex. `150.00` = Le 150.00).
`currency`	string	não	`SLE` por predefinição.
`provider`	string	não	`orange_money_sl`. Omita-o para usar a janela de pagamento da SOAMTAR (Hosted Checkout).
`payer.phone`	string	recomendado	Formato E.164 (`+232` seguido de 8 dígitos). Pré-preenche a janela de pagamento.
`payer.name`	string	não	Nome mostrado no recibo.
`return_url`	string	recomendado	Página onde o cliente chega após um pagamento bem-sucedido (alias de `success_url`).
`cancel_url`	string	recomendado	Página onde o cliente chega após uma falha ou um cancelamento (alias de `failed_url`).
`metadata`	object	não	Até 50 chaves livres, devolvidas no webhook.

Exemplos

PHP / LaravelNode.js / ExpressPython / FastAPI

php

// routes/web.php or routes/api.php
Route::post('/checkout/soamtar', function (Request $request) {
    $order = Order::findOrFail($request->integer('order_id'));

    $response = Http::withToken(config('services.soamtar.key'))
        ->acceptJson()
        ->post('https://app.so-amtar.com/v1/payments', [
            'merchant_ref' => $order->reference,
            'amount'       => $order->total_sle,
            'currency'     => 'SLE',
            'payer'        => [
                'phone' => $order->customer_phone,
                'name'  => $order->customer_name,
            ],
            'return_url'   => route('checkout.success', $order),
            'cancel_url'   => route('checkout.cancel', $order),
            'metadata'     => [
                'order_id' => $order->id,
                'user_id'  => $request->user()->id,
            ],
        ])
        ->throw()
        ->json('data');

    return response()->json([
        'id'         => $response['id'],
        'paymentUrl' => $response['payment_url'],
    ]);
})->middleware('auth');

import express from 'express'

const app = express()
app.use(express.json())

app.post('/checkout/soamtar', async (req, res) => {
  const order = await db.orders.findById(req.body.order_id)

  const r = await fetch('https://app.so-amtar.com/v1/payments', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.SOAMTAR_SECRET_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      merchant_ref: order.reference,
      amount: order.total_sle,
      currency: 'SLE',
      payer: { phone: order.customerPhone, name: order.customerName },
      return_url: `${process.env.APP_URL}/checkout/success?id=${order.id}`,
      cancel_url: `${process.env.APP_URL}/checkout/cancel?id=${order.id}`,
      metadata: { order_id: order.id, user_id: req.user.id },
    }),
  })

  if (!r.ok) return res.status(502).json({ error: await r.text() })
  const { data } = await r.json()
  res.json({ id: data.id, paymentUrl: data.payment_url })
})

python

import os, httpx
from fastapi import APIRouter, Depends, HTTPException

router = APIRouter()

@router.post("/checkout/soamtar")
async def checkout(order_id: int, user = Depends(auth)):
    order = await db.orders.get(order_id)

    async with httpx.AsyncClient(timeout=10) as client:
        r = await client.post(
            "https://app.so-amtar.com/v1/payments",
            headers={
                "Authorization": f"Bearer {os.environ['SOAMTAR_SECRET_KEY']}",
            },
            json={
                "merchant_ref": order.reference,
                "amount": order.total_sle,
                "currency": "SLE",
                "payer": {"phone": order.customer_phone, "name": order.customer_name},
                "return_url": f"{APP_URL}/checkout/success?id={order.id}",
                "cancel_url": f"{APP_URL}/checkout/cancel?id={order.id}",
                "metadata": {"order_id": order.id, "user_id": user.id},
            },
        )
    if r.status_code >= 400:
        raise HTTPException(502, r.text)
    data = r.json()["data"]
    return {"id": data["id"], "paymentUrl": data["payment_url"]}

Resposta da SOAMTAR

json

{
  "data": {
    "id": "0e85b3c2-4a01-4e8f-b8b8-b71e0e1c8d1a",
    "object": "transaction",
    "reference": "TXN-A1B2C3D4E5",
    "status": "pending",
    "amount": "150.00",
    "currency": "SLE",
    "payment_url": "https://app.so-amtar.com/pay/checkout/0e85b3c2-...",
    "expires_at": "2026-04-15T12:30:00+00:00"
  },
  "livemode": false
}

O seu backend deve guardar data.id e data.reference e associá-los ao seu order_id antes de responder ao navegador. É essa tabela que usa depois para reconciliar o webhook.

3. Frontend: a janela de pagamento da SOAMTAR

O SDK JS é um script sem dependências. Abre a payment_url numa janela modal, escuta os eventos de pagamento e avisa-o quando o pagamento termina.

Incluir o script

html

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

Servido pela SOAMTAR com uma cache de um dia.

Integração simples: janela

html

<button id="pay-btn" data-order-id="42">
  Pay Le 150.00
</button>

<script>
document.getElementById('pay-btn').addEventListener('click', async (e) => {
  const orderId = e.currentTarget.dataset.orderId;

  // 1) Ask YOUR backend to create the SOAMTAR transaction.
  const res = await fetch('/checkout/soamtar', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ order_id: orderId }),
  });
  const { id, paymentUrl } = await res.json();

  // 2) Open the window on the URL returned by SOAMTAR.
  new SOAMTAR({ transactionId: id, paymentUrl })
    .withOption({
      presentationMode: SOAMTAR.OPEN_IN_POPUP,
      locale: 'en',
      didReceivePayment: (event) => {
        // event.status === 'success' | 'failed' | 'cancelled'
        if (event.status === 'success') {
          window.location.href = '/checkout/success?id=' + orderId;
        }
      },
      didCancel: () => console.info('Payment cancelled by the customer'),
      didReceiveError: (err) => console.error('[SOAMTAR]', err),
    })
    .send();
});
</script>

Integração declarativa: atributos `data-*`

Para um site estático ou um CMS, não precisa de JavaScript próprio:

html

<button
  data-soamtar
  data-soamtar-request-url="/checkout/soamtar"
  data-soamtar-body='{"order_id": 42}'
  data-soamtar-success-url="/checkout/success"
  data-soamtar-mode="popup">
  Pay
</button>

O SDK deteta [data-soamtar] ao carregar, chama o URL indicado com POST, lê paymentUrl na resposta JSON e abre a janela.

Modos de apresentação

Constante	Comportamento
`SOAMTAR.OPEN_IN_POPUP`	Janela modal centrada sobre a página (predefinição).
`SOAMTAR.OPEN_IN_NEW_TAB`	Abre um novo separador (alternativa se as janelas pop-up estiverem bloqueadas).
`SOAMTAR.OPEN_IN_SAME_TAB`	Redirecionamento de página inteira para `payment_url`.
`SOAMTAR.EMBED`	Integrada num `<div id="soamtar-frame"></div>` fornecido por si.
`SOAMTAR.HEADLESS`	Não abre nada e devolve `paymentUrl`: é o próprio a mostrá-lo.

Callbacks

Opção	Assinatura	Quando
`didReceivePayment`	`({ status, transactionId, reference })`	A janela recebeu um evento final.
`didCancel`	`()`	O cliente fechou a janela ou clicou em «cancelar».
`didReceiveError`	`(error)`	Erro de rede, token expirado, CSP…
`didClose`	`()`	Chamado sempre que a janela fecha (depois dos outros).

Evento ≠ prova de pagamento

Os callbacks JS são informativos (o cliente pode fechar o separador demasiado cedo, perder a rede, etc.). Nunca marque uma encomenda como paga a partir do navegador: só o webhook é fiável.

Vue.js / Inertia

vue

<script setup lang="ts">
import { ref } from 'vue'

const loading = ref(false)

async function pay(orderId: number) {
  loading.value = true
  const { id, paymentUrl } = await fetch('/checkout/soamtar', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'X-CSRF-TOKEN': csrf() },
    body: JSON.stringify({ order_id: orderId }),
  }).then(r => r.json())

  new window.SOAMTAR({ transactionId: id, paymentUrl })
    .withOption({
      presentationMode: window.SOAMTAR.OPEN_IN_POPUP,
      didReceivePayment: () => router.visit(`/orders/${orderId}`),
      didClose: () => (loading.value = false),
    })
    .send()
}
</script>

<template>
  <button :disabled="loading" @click="pay(42)">Pay</button>
</template>

React

tsx

import { useState } from 'react'

declare global { interface Window { SOAMTAR: any } }

export function PayButton({ orderId }: { orderId: number }) {
  const [loading, setLoading] = useState(false)

  async function pay() {
    setLoading(true)
    const { id, paymentUrl } = await fetch('/checkout/soamtar', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ order_id: orderId }),
    }).then(r => r.json())

    new window.SOAMTAR({ transactionId: id, paymentUrl })
      .withOption({
        presentationMode: window.SOAMTAR.OPEN_IN_POPUP,
        didReceivePayment: e => e.status === 'success' && (location.href = '/success'),
        didClose: () => setLoading(false),
      })
      .send()
  }

  return <button disabled={loading} onClick={pay}>Pay</button>
}

4. Webhook: a única fonte de verdade

A SOAMTAR envia um POST para o seu endpoint assim que o estado muda. O pedido é assinado no cabeçalho X-Soamtar-Signature (t=<timestamp>,v1=<hmac>).

php

Route::post('/webhooks/soamtar', function (Request $request) {
    $header = $request->header('X-Soamtar-Signature', '');
    $body   = $request->getContent();
    $secret = config('services.soamtar.webhook_secret');

    if (! preg_match('/^t=(\d+),v1=([a-f0-9]{64})/', $header, $m)) {
        abort(400, 'bad signature');
    }
    if (abs(time() - (int) $m[1]) > 300) {
        abort(401, 'expired');
    }
    $expected = hash_hmac('sha256', $m[1] . '.' . $body, $secret);
    if (! hash_equals($expected, $m[2])) {
        abort(401, 'invalid');
    }

    $event = json_decode($body, true);
    match ($event['event']) {
        'payment.success'   => Order::markPaid($event['data']['merchant_reference']),
        'payment.failed'    => Order::markFailed($event['data']['merchant_reference']),
        'payment.cancelled' => Order::markCancelled($event['data']['merchant_reference']),
        default             => null,
    };

    return response()->json(['received' => true]);
});

Idempotência

Cada evento é entregue pelo menos uma vez. Use o par event + data.id como chave única na sua base de dados: se já o processou, responda 200 e não faça nada.

Detalhes completos, rotação do segredo e formatos versionados: veja Webhooks.

5. Sandbox versus produção

	Sandbox	Produção
Chave	`sk_test_…`	`sk_live_…`
URL base	`https://app.so-amtar.com/v1`	o mesmo
Orange Money	Simulado (botões Simular sucesso / falha)	Real, KYC obrigatório
Dinheiro movimentado	Nenhum	Montante exato
`livemode` nas respostas	`false`	`true`

Para forçar um estado no sandbox, abra a payment_url na janela e clique no botão correspondente. O webhook é enviado exatamente como em produção.

6. Lista de verificação antes da produção

[ ] O seu backend guarda transaction.id e merchant_ref antes de responder ao navegador.
[ ] A janela nunca decide sozinha o estado da encomenda: o webhook é a fonte de verdade.
[ ] O seu endpoint de webhook verifica t, v1 e a janela de 5 minutos, e responde 2xx em menos de 5 s.
[ ] return_url e cancel_url mostram o estado real (a partir da sua base de dados, alimentada pelo webhook), não uma confirmação otimista.
[ ] Os registos nunca guardam a chave API em claro.
[ ] A sua CSP autoriza https://app.so-amtar.com (script-src, frame-src, connect-src) se usar a janela.
[ ] Teste completo no sandbox: sucesso, falha, cancelamento, expiração, webhook duplicado.

Veja também a lista de integração detalhada e Do teste à produção (em inglês).

7. Perguntas frequentes

A janela é obrigatória? Não. Pode redirecionar diretamente para payment_url (window.location.href = paymentUrl). A janela oferece uma melhor experiência porque o cliente fica na sua página.

Posso chamar /v1/payments diretamente a partir do navegador? Não, nunca. Exporia a sua chave API. A rota interna /checkout/soamtar é a única forma segura.

Durante quanto tempo é válida uma payment_url? Até expires_at, devolvido na criação (2 horas por predefinição na plataforma). Depois disso, a SOAMTAR envia payment.expired.

Posso ter vários pagamentos simultâneos para a mesma encomenda? Sim, mas evite-o. Use um merchant_ref único por tentativa (por ex. ORDER-42-v2) para manter uma relação 1:1 na reconciliação.

O que vê o cliente no telemóvel? Um pedido do Orange Money da sua empresa pelo montante exato em leones. Aprova-o com o seu PIN Orange Money; não tem de instalar mais nada.

Integrar a SOAMTAR no seu site ​

Visão geral do fluxo ​

1. Pré-requisitos ​

2. Backend: criar uma transação ​

Endpoint da SOAMTAR ​

Exemplos ​

Resposta da SOAMTAR ​

3. Frontend: a janela de pagamento da SOAMTAR ​

Incluir o script ​

Integração simples: janela ​

Integração declarativa: atributos data-* ​

Modos de apresentação ​

Callbacks ​

Vue.js / Inertia ​

React ​

4. Webhook: a única fonte de verdade ​

5. Sandbox versus produção ​

6. Lista de verificação antes da produção ​

7. Perguntas frequentes ​

Integrar a SOAMTAR no seu site

Visão geral do fluxo

1. Pré-requisitos

2. Backend: criar uma transação

Endpoint da SOAMTAR

Exemplos

Resposta da SOAMTAR

3. Frontend: a janela de pagamento da SOAMTAR

Incluir o script

Integração simples: janela

Integração declarativa: atributos `data-*`

Modos de apresentação

Callbacks

Vue.js / Inertia

React

4. Webhook: a única fonte de verdade

5. Sandbox versus produção

6. Lista de verificação antes da produção

7. Perguntas frequentes