Plugins CMS e comércio eletrónico

Os nossos plugins permitem aceitar Orange Money Serra Leoa sem escrever código. Todos funcionam da mesma forma:

1. A encomenda é criada e o cliente é redirecionado para a página de pagamento SOAMTAR (payment_url devolvida por POST https://app.so-amtar.com/v1/payments).
2. O cliente aprova o pagamento no telemóvel com o PIN Orange Money.
3. A SOAMTAR envia um webhook assinado à sua loja, que só marca a encomenda como paga se o montante e a moeda coincidirem.

Plataforma	Pacote / pasta	Versão	Requisitos	Moedas
WooCommerce	soamtar-woocommerce-gateway	1.1.0	WordPress 5.8+, WooCommerce 6.0+, PHP 7.4+	SLE, USD, EUR
Magento 2	soamtar/magento2-payment (Soamtar_Payment)	1.1.0	Magento 2.4.4+, PHP 8.1+	SLE, USD, EUR
PrestaShop	soamtar	1.1.0	PrestaShop 1.7.7+ / 8, PHP 7.4+	SLE, USD, EUR
Drupal Commerce	soamtar_commerce	1.1.0	Drupal 9.3+ / 10 / 11, Commerce 2.x, PHP 8.1+	SLE, USD, EUR
Odoo	payment_soamtar	17.0.1.1.0	Odoo 17.0, Python 3.10+	Apenas SLE

Ainda não estão nos marketplaces

Os plugins ainda não estão publicados nos marketplaces do WordPress, Magento, PrestaShop, Drupal ou Odoo. Instale-os a partir do repositório (git clone ou zip) como indicado abaixo.

Configuração comum

Cada plugin precisa de três valores do painel SOAMTAR:

Valor	Origem
Chave secreta de teste sk_test_…	Chaves API. Os pagamentos são simulados no mesmo host (https://app.so-amtar.com/v1): não circula dinheiro real.
Chave secreta live sk_live_…	Chaves API, depois de a sua conta ser ativada para produção.
Segredo do webhook	O segredo de assinatura de um endpoint de webhook registado no painel (Developers → Webhooks). Sempre obrigatório, mesmo com callback_url.

Cada plugin tem um interruptor Test mode que escolhe a chave de teste ou a live. As chaves secretas ficam no seu servidor: nunca as coloque num tema ou ficheiro JavaScript.

URL do webhook: automático em lojas HTTPS. Cada plugin envia o seu próprio URL de webhook como callback_url com cada pagamento. A SOAMTAR entrega então os eventos assinados desse pagamento (e dos seus reembolsos) à loja, com o mesmo payload, a mesma assinatura e as mesmas novas tentativas que um endpoint registado. A SOAMTAR assina estes envios com o segredo do seu endpoint de webhook ativo mais antigo do mesmo ambiente, por isso precisa de pelo menos um endpoint no painel e do respetivo segredo de assinatura no plugin.

callback_url tem de ser HTTPS público. Se a loja não usar HTTPS, o plugin omite-o e pede-lhe (aviso de administração, log ou página de configuração) que registe o URL da loja indicado abaixo como endpoint de webhook no painel, subscrito a payment.success, payment.failed, payment.cancelled, payment.expired, refund.success, refund.failed, payment.refunded e payment.partially_refunded (Odoo: todos os eventos payment.* e refund.*). Mantenha a versão de payload por omissão (legacy).

O botão Send test event do painel (webhook.test) recebe 200 de todos os plugins e não altera nenhuma encomenda.

Todos os plugins verificam o cabeçalho X-Soamtar-Signature (t=<unix>,v1=<hex>, mais v2= durante uma rotação do segredo): HMAC-SHA256 de "<t>.<corpo bruto>" com o segredo do webhook, tolerância de 300 s. Veja Webhooks.

Reembolsos

Todos os plugins reembolsam nativamente a partir do back office da loja. Chamam POST https://app.so-amtar.com/v1/refunds com o id de transação SOAMTAR e o montante (total ou parcial). A SOAMTAR devolve o dinheiro ao número Orange Money do pagador e debita-o do seu saldo SOAMTAR. O reembolso é assíncrono: o resultado final chega com refund.success ou refund.failed (mais payment.refunded / payment.partially_refunded). A chave API precisa do scope can_refund e o seu saldo tem de cobrir o montante.

Plataforma	Como reembolsar
WooCommerce	Refund via SOAMTAR na encomenda
Magento 2	Nota de crédito online (Refund, não "Refund Offline") a partir da fatura
PrestaShop	Nota de crédito (reembolso padrão, parcial ou devolução), com Refund through Orange Money (SOAMTAR_AUTO_REFUND, ativo por omissão)
Drupal Commerce	Refund no pagamento (o gateway implementa SupportsRefundsInterface)
Odoo	Botão Refund no pagamento (total ou parcial)

Ver Refunds para a API.

WordPress / WooCommerce

Checkout clássico e blocos Carrinho/Checkout, compatível com HPOS.

Instalação

cd wp-content/plugins
git clone <URL do repositório> soamtar-woocommerce-gateway

Ou carregue um zip da pasta em Plugins → Adicionar novo → Carregar plugin e ative SOAMTAR for WooCommerce. Defina a moeda da loja como SLE, USD ou EUR.

Definições

WooCommerce → Definições → Pagamentos → SOAMTAR (etiquetas em inglês):

Definição	Notas
Enable/Disable	Mostra o gateway no checkout.
Title / Description	Texto do checkout (predefinido "Orange Money").
Test mode	Usa a chave secreta de teste.
Live secret key / Test secret key	sk_live_… / sk_test_…, cifradas em repouso.
Webhook secret	Obrigatório.
Success redirect URL (optional)	Predefinido: a página "encomenda recebida" do WooCommerce.
Failure redirect URL (optional)	Predefinido: a página de pagamento da encomenda.
Debug log	WooCommerce → Estado → Registos, origem soamtar-gateway.

O gateway fica oculto (com um aviso na administração) enquanto faltar uma chave, o segredo do webhook ou uma moeda suportada.

URL do webhook

https://sua-loja.example/wp-json/soamtar/v1/webhook

O URL antigo https://sua-loja.example/?wc-api=wc_soamtar_gateway também funciona.

Comportamento

• payment.success: a encomenda só é concluída se amount e currency coincidirem; caso contrário fica em espera com uma nota.
• payment.failed, payment.cancelled, payment.expired: a encomenda passa a falhada, salvo se já estiver paga.
• Uma nova tentativa após uma falha usa merchant_ref 1001-2, 1001-3, … (uma referência só pode ser usada uma vez).
• O telefone de faturação é convertido para +232XXXXXXXX quando possível; caso contrário o cliente escreve-o na página de pagamento.
• O webhook é protegido por um limite de pedidos por IP, um teto de 1 MB, deduplicação, um registo de auditoria e uma lista de IP permitidos opcional (filtro soamtar_webhook_ip_allowlist).

Magento 2

Instalação

Copie o módulo para app/code/Soamtar/Payment/, ou declare o repositório como repositório Composer VCS/path e execute composer require soamtar/magento2-payment. Depois:

php bin/magento module:enable Soamtar_Payment
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento cache:flush

Definições

Stores → Configuration → Sales → Payment Methods → SOAMTAR — Orange Money (Sierra Leone)

Campo	Caminho de configuração
Enabled	payment/soamtar/active
Title (predefinido "Orange Money")	payment/soamtar/title
Test mode	payment/soamtar/testmode
Test secret key (sk_test_…)	payment/soamtar/test_secret_key (cifrada)
Live secret key (sk_live_…)	payment/soamtar/live_secret_key (cifrada)
Webhook secret	payment/soamtar/webhook_secret (cifrado)
Payment from applicable countries / specific countries	payment/soamtar/allowspecific, payment/soamtar/specificcountry
Debug log	payment/soamtar/debug
Sort order	payment/soamtar/sort_order

O método só é oferecido se a moeda da encomenda for SLE, USD ou EUR.

URL do webhook

https://sua-loja.example/soamtar/webhook/notify

Comportamento

• A encomenda é criada em pending_payment; depois /soamtar/payment/redirect cria o pagamento SOAMTAR (Idempotency-Key: mage_<increment id>_<protect code>) e redireciona para payment_url. Se a chamada API falhar, a encomenda é cancelada e o carrinho reposto.
• payment.success com o montante e a moeda corretos regista a captura (fatura) e passa a encomenda a "processing"; se não coincidirem, a encomenda fica em espera com um comentário.
• payment.failed, payment.cancelled, payment.expired: uma encomenda pending_payment é cancelada.
• /soamtar/payment/cancel (URL de falha) apenas repõe o carrinho. Para reembolsar, crie uma nota de crédito online (Refund): o módulo chama POST/v1/refunds.

PrestaShop

Instalação

cd modules
git clone <URL do repositório> soamtar

A pasta tem de se chamar soamtar. Também pode comprimi-la como soamtar/… e carregá-la em Módulos → Gestor de módulos → Carregar um módulo, e depois instalar SOAMTAR — Orange Money.

Definições

Módulos → SOAMTAR — Orange Money → Configurar

Campo	Chave de configuração	Notas
Test mode	SOAMTAR_TEST_MODE	Ativo por predefinição.
Test secret key	SOAMTAR_TEST_SECRET_KEY	sk_test_…
Live secret key	SOAMTAR_LIVE_SECRET_KEY	sk_live_…
Webhook secret	SOAMTAR_WEBHOOK_SECRET

Um campo de palavra-passe vazio mantém o valor guardado. Ative também o módulo para SLE, USD ou EUR em Pagamento → Preferências: a opção só aparece se a chave ativa e o segredo do webhook estiverem definidos e a moeda do carrinho for suportada.

URL do webhook

https://sua-loja.example/module/soamtar/webhook

O URL exato (consoante os URL amigáveis) é mostrado na página de configuração.

Comportamento

• A encomenda é criada no estado "Awaiting Orange Money payment"; se a chamada API falhar passa a "Erro de pagamento" e o carrinho é reposto.
• Só são alteradas as encomendas ainda à espera de pagamento: payment.success com o montante e a moeda corretos → "Pagamento aceite"; payment.failed → "Erro de pagamento"; payment.cancelled / payment.expired → "Cancelada". Um montante ou moeda diferentes deixam a encomenda pendente e registam um erro.
• module/soamtar/return mostra a confirmação ou repõe o carrinho; nunca altera o estado da encomenda.

Drupal Commerce

Gateway de pagamento offsite. O pagamento é registado no regresso (consulta do estado) ou pelo webhook, o que chegar primeiro.

Instalação

Copie o módulo para modules/custom/soamtar_commerce (ou declare o repositório como repositório Composer VCS/path e execute composer require soamtar/drupal-commerce), e depois:

drush en soamtar_commerce -y
drush cr

Definições

Commerce → Configuração → Gateways de pagamento → Adicionar gateway de pagamento, plugin SOAMTAR (Orange Money Sierra Leone).

Definição	Notas
Mode	Test usa a chave de teste, Live a chave live.
Test secret key (sk_test_…)	Deixe vazio para manter o valor guardado.
Live secret key (sk_live_…)	Deixe vazio para manter o valor guardado.
Webhook secret	O URL do webhook aparece sob este campo depois de guardar o gateway.

URL do webhook

https://seu-site.example/payment/notify/<nome de máquina do gateway>

Comportamento

• merchant_ref é <id da encomenda>-<tentativa>. É enviado um telefone +232 se o perfil de faturação tiver um campo field_phone.
• No regresso, o módulo consulta GET /v1/status/{id da transação}: success regista o pagamento; failed, cancelled ou expired devolve o cliente ao checkout; um pagamento pendente deixa concluir a encomenda e aguarda o webhook.
• payment.success regista um pagamento concluído uma única vez por transação SOAMTAR, só se amount e currency coincidirem com o saldo da encomenda.

Odoo

Fornecedor de pagamento para o eCommerce do Odoo, faturas e links de pagamento.

Instalação

1. Copie payment_soamtar/ para o caminho de addons do Odoo.
2. Reinicie o Odoo, atualize a lista de aplicações, procure SOAMTAR Payment Provider e instale-o.
3. Ative a moeda SLE (Contabilidade → Configuração → Moedas). O fornecedor só é oferecido para encomendas em SLE.

Definições

Faturação / Website → Configuração → Fornecedores de pagamento → SOAMTAR (Orange Money)

Campo	Valor
Estado	Modo de teste (usa sk_test_…) ou Ativado (usa sk_live_…)
Test Secret Key / Live Secret Key	Do painel SOAMTAR
Webhook Secret	Segredo de assinatura do endpoint abaixo

URL do webhook

https://seu-odoo.example/payment/soamtar/webhook

Comportamento

• merchant_ref é a referência da transação Odoo; o cliente regressa a /payment/soamtar/return.
• No regresso e na receção do webhook, o Odoo lê o estado do pagamento na API SOAMTAR (nunca confia no URL do navegador nem no corpo do webhook), verifica montante e moeda e confirma, cancela ou marca a transação como falhada.
• O webhook responde 400 se o segredo não coincidir (ou se o relógio do servidor estiver desfasado mais de 5 minutos) e 503 se o Webhook Secret não estiver configurado.