Plugins CMS y comercio electrónico

Nuestros plugins permiten aceptar Orange Money Sierra Leona sin escribir código. Todos funcionan igual:

1. Se crea el pedido y el cliente es redirigido a la página de pago de SOAMTAR (payment_url devuelta por POST https://app.so-amtar.com/v1/payments).
2. El cliente aprueba el pago en su teléfono con su PIN de Orange Money.
3. SOAMTAR envía un webhook firmado a su tienda, que marca el pedido como pagado solo si el importe y la divisa coinciden.

Plataforma	Paquete / carpeta	Versión	Requisitos	Divisas
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+	Solo SLE

Aún no están en los marketplaces

Los plugins todavía no se publican en los marketplaces de WordPress, Magento, PrestaShop, Drupal u Odoo. Instálelos desde el repositorio (git clone o zip) como se indica abajo.

Configuración común

Cada plugin necesita tres valores del panel de SOAMTAR:

Valor	Origen
Clave secreta de prueba sk_test_…	Claves API. Los pagos se simulan en el mismo host (https://app.so-amtar.com/v1): no se mueve dinero real.
Clave secreta live sk_live_…	Claves API, cuando su cuenta esté activada para producción.
Secreto del webhook	El secreto de firma de un endpoint de webhook registrado en el panel (Developers → Webhooks). Siempre obligatorio, incluso con callback_url.

Cada plugin tiene un interruptor Test mode que elige la clave de prueba o la live. Las claves secretas se quedan en su servidor: nunca las ponga en un tema ni en un archivo JavaScript.

URL del webhook: automática en tiendas HTTPS. Cada plugin envía su propia URL de webhook como callback_url con cada pago. SOAMTAR entrega entonces los eventos firmados de ese pago (y de sus reembolsos) a la tienda, con el mismo payload, la misma firma y los mismos reintentos que un endpoint registrado. SOAMTAR firma estos envíos con el secreto de su endpoint de webhook activo más antiguo del mismo entorno, así que necesita al menos un endpoint en el panel y su secreto de firma en el plugin.

callback_url debe ser HTTPS público. Si la tienda no usa HTTPS, el plugin lo omite y le pide (aviso de administración, log o página de configuración) registrar la URL de la tienda indicada abajo como endpoint de webhook en el panel, suscrito a payment.success, payment.failed, payment.cancelled, payment.expired, refund.success, refund.failed, payment.refunded y payment.partially_refunded (Odoo: todos los eventos payment.* y refund.*). Mantenga la versión de payload por defecto (legacy).

El botón Send test event del panel (webhook.test) recibe 200 de todos los plugins y no modifica ningún pedido.

Todos los plugins verifican la cabecera X-Soamtar-Signature (t=<unix>,v1=<hex>, más v2= durante una rotación del secreto): HMAC-SHA256 de "<t>.<cuerpo bruto>" con el secreto del webhook, tolerancia de 300 s. Vea Webhooks.

Reembolsos

Todos los plugins reembolsan de forma nativa desde el back office de la tienda. Llaman a POST https://app.so-amtar.com/v1/refunds con el id de transacción de SOAMTAR y el importe (total o parcial). SOAMTAR devuelve el dinero al número Orange Money del pagador y lo carga a su saldo SOAMTAR. El reembolso es asíncrono: el resultado final llega con refund.success o refund.failed (más payment.refunded / payment.partially_refunded). La clave API necesita el scope can_refund y su saldo debe cubrir el importe.

Plataforma	Cómo reembolsar
WooCommerce	Refund via SOAMTAR en el pedido
Magento 2	Nota de crédito online (Refund, no "Refund Offline") desde la factura
PrestaShop	Vale de abono (reembolso estándar, parcial o devolución), con Refund through Orange Money (SOAMTAR_AUTO_REFUND, activado por defecto)
Drupal Commerce	Refund en el pago (la pasarela implementa SupportsRefundsInterface)
Odoo	Botón Refund en el pago (total o parcial)

Vea Refunds para la API.

WordPress / WooCommerce

Checkout clásico y bloques de Carrito/Checkout, compatible con HPOS.

Instalación

cd wp-content/plugins
git clone <URL del repositorio> soamtar-woocommerce-gateway

O suba un zip de la carpeta en Plugins → Añadir nuevo → Subir plugin y active SOAMTAR for WooCommerce. Configure la divisa de la tienda en SLE, USD o EUR.

Ajustes

WooCommerce → Ajustes → Pagos → SOAMTAR (etiquetas en inglés):

Ajuste	Notas
Enable/Disable	Muestra la pasarela en el checkout.
Title / Description	Texto del checkout (por defecto "Orange Money").
Test mode	Usa la clave secreta de prueba.
Live secret key / Test secret key	sk_live_… / sk_test_…, cifradas en reposo.
Webhook secret	Obligatorio.
Success redirect URL (optional)	Por defecto: la página "pedido recibido" de WooCommerce.
Failure redirect URL (optional)	Por defecto: la página de pago del pedido.
Debug log	WooCommerce → Estado → Registros, fuente soamtar-gateway.

La pasarela permanece oculta (con un aviso en la administración) mientras falte una clave, el secreto del webhook o una divisa compatible.

URL del webhook

https://su-tienda.example/wp-json/soamtar/v1/webhook

La URL antigua https://su-tienda.example/?wc-api=wc_soamtar_gateway también funciona.

Comportamiento

• payment.success: el pedido se completa solo si amount y currency coinciden; si no, queda en espera con una nota.
• payment.failed, payment.cancelled, payment.expired: el pedido pasa a fallido, salvo si ya está pagado.
• Un nuevo intento tras un fallo usa merchant_ref 1001-2, 1001-3, … (una referencia solo puede usarse una vez).
• El teléfono de facturación se convierte a +232XXXXXXXX cuando es posible; si no, el cliente lo escribe en la página de pago.
• El webhook está protegido por un límite de peticiones por IP, un tope de 1 MB, deduplicación, un registro de auditoría y una lista blanca de IP opcional (filtro soamtar_webhook_ip_allowlist).

Magento 2

Instalación

Copie el módulo en app/code/Soamtar/Payment/, o declare el repositorio como repositorio Composer VCS/path y ejecute composer require soamtar/magento2-payment. Después:

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

Ajustes

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

Campo	Ruta de configuración
Enabled	payment/soamtar/active
Title (por defecto "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

El método solo se ofrece si la divisa del pedido es SLE, USD o EUR.

URL del webhook

https://su-tienda.example/soamtar/webhook/notify

Comportamiento

• El pedido se crea en pending_payment; luego /soamtar/payment/redirect crea el pago SOAMTAR (Idempotency-Key: mage_<increment id>_<protect code>) y redirige a payment_url. Si la llamada API falla, el pedido se cancela y el carrito se restaura.
• payment.success con el importe y la divisa correctos registra la captura (factura) y pasa el pedido a "processing"; si no coinciden, el pedido queda en espera con un comentario.
• payment.failed, payment.cancelled, payment.expired: se cancela un pedido pending_payment.
• /soamtar/payment/cancel (URL de fallo) solo restaura el carrito. Para reembolsar, cree una nota de crédito online (Refund): el módulo llama a POST/v1/refunds.

PrestaShop

Instalación

cd modules
git clone <URL del repositorio> soamtar

La carpeta debe llamarse soamtar. También puede comprimirla como soamtar/… y subirla en Módulos → Gestor de módulos → Subir un módulo, y luego instalar SOAMTAR — Orange Money.

Ajustes

Módulos → SOAMTAR — Orange Money → Configurar

Campo	Clave de configuración	Notas
Test mode	SOAMTAR_TEST_MODE	Activado por defecto.
Test secret key	SOAMTAR_TEST_SECRET_KEY	sk_test_…
Live secret key	SOAMTAR_LIVE_SECRET_KEY	sk_live_…
Webhook secret	SOAMTAR_WEBHOOK_SECRET

Un campo de contraseña vacío conserva el valor guardado. Active también el módulo para SLE, USD o EUR en Pago → Preferencias: la opción solo aparece si la clave activa y el secreto del webhook están definidos y la divisa del carrito es compatible.

URL del webhook

https://su-tienda.example/module/soamtar/webhook

La URL exacta (según sus URL amigables) se muestra en la página de configuración.

Comportamiento

• El pedido se crea en el estado "Awaiting Orange Money payment"; si la llamada API falla pasa a "Error en el pago" y el carrito se restaura.
• Solo se modifican los pedidos que siguen esperando el pago: payment.success con el importe y la divisa correctos → "Pago aceptado"; payment.failed → "Error en el pago"; payment.cancelled / payment.expired → "Cancelado". Un importe o una divisa distintos dejan el pedido pendiente y registran un error.
• module/soamtar/return muestra la confirmación o restaura el carrito; nunca cambia el estado del pedido.

Drupal Commerce

Pasarela de pago offsite. El pago se registra al volver (consulta del estado) o con el webhook, lo que llegue primero.

Instalación

Copie el módulo en modules/custom/soamtar_commerce (o declare el repositorio como repositorio Composer VCS/path y ejecute composer require soamtar/drupal-commerce), y luego:

drush en soamtar_commerce -y
drush cr

Ajustes

Commerce → Configuración → Pasarelas de pago → Añadir pasarela de pago, plugin SOAMTAR (Orange Money Sierra Leone).

Ajuste	Notas
Mode	Test usa la clave de prueba, Live la clave live.
Test secret key (sk_test_…)	Déjelo vacío para conservar el valor guardado.
Live secret key (sk_live_…)	Déjelo vacío para conservar el valor guardado.
Webhook secret	La URL del webhook aparece bajo este campo una vez guardada la pasarela.

URL del webhook

https://su-sitio.example/payment/notify/<nombre de máquina de la pasarela>

Comportamiento

• merchant_ref es <id del pedido>-<intento>. Se envía un teléfono +232 si el perfil de facturación tiene un campo field_phone.
• Al volver, el módulo consulta GET /v1/status/{id de transacción}: success registra el pago; failed, cancelled o expired devuelve al cliente al checkout; un pago pendiente deja completar el pedido y espera el webhook.
• payment.success registra un pago completado una sola vez por transacción SOAMTAR, solo si amount y currency coinciden con el saldo del pedido.

Odoo

Proveedor de pago para el eCommerce de Odoo, facturas y enlaces de pago.

Instalación

1. Copie payment_soamtar/ en la ruta de addons de Odoo.
2. Reinicie Odoo, actualice la lista de aplicaciones, busque SOAMTAR Payment Provider e instálelo.
3. Active la divisa SLE (Contabilidad → Configuración → Monedas). El proveedor solo se ofrece para pedidos en SLE.

Ajustes

Facturación / Sitio web → Configuración → Proveedores de pago → SOAMTAR (Orange Money)

Campo	Valor
Estado	Modo de prueba (usa sk_test_…) o Habilitado (usa sk_live_…)
Test Secret Key / Live Secret Key	Desde el panel de SOAMTAR
Webhook Secret	Secreto de firma del endpoint indicado abajo

URL del webhook

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

Comportamiento

• merchant_ref es la referencia de la transacción de Odoo; el cliente vuelve a /payment/soamtar/return.
• Al volver y al recibir el webhook, Odoo lee el estado del pago desde la API de SOAMTAR (nunca confía en la URL del navegador ni en el cuerpo del webhook), comprueba importe y divisa y confirma, cancela o marca como fallida la transacción.
• El webhook responde 400 si el secreto no coincide (o si el reloj del servidor se desvía más de 5 minutos) y 503 si el Webhook Secret no está configurado.