Documentation API

Introduction

L'API SoamPay est une API RESTful qui vous permet d'accepter des paiements mobiles (Orange Money, MTN MoMo) et par carte bancaire en Guinée. Toutes les requêtes et réponses sont en JSON.

curl -X GET https://api.soamgroup.gn/api/v1/transactions \
  -H "Authorization: Bearer samp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Authentification

Tous les appels API s'authentifient avec une clé API (samp_...), créée dans la page Clés API du tableau de bord. Deux types de clés existent, chacune avec sa méthode d'authentification.

curl -X GET https://api.soamgroup.gn/api/v1/api/transactions/TXN-8F2K9XPZ3MQ \
  -H "X-API-Key: samp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

const response = await fetch('https://api.soamgroup.gn/api/v1/api/transactions/TXN-8F2K9XPZ3MQ', {
  headers: {
    'X-API-Key': process.env.SOAMPAY_API_KEY
  }
});
const data = await response.json();

<?php

$ch = curl_init('https://api.soamgroup.gn/api/v1/api/transactions/TXN-8F2K9XPZ3MQ');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: ' . getenv('SOAMPAY_API_KEY'),
]);
$response = curl_exec($ch);

Authentifie le marchand et retourne un jeton Bearer à transmettre dans Authorization: Bearer <token> pour toutes les routes de l'API marchand (dashboard, transactions, retraits, webhooks…).

Paramètres

{
  "data": {
    "user": {
      "id": "01HZ...",
      "name": "Mamadou Diallo",
      "email": "mamadou@example.com",
      "role": "merchant"
    },
    "token": "1|abc123...",
    "token_type": "Bearer"
  }
}

{
  "data": {
    "id": "01HZ...",
    "name": "Mamadou Diallo",
    "email": "mamadou@example.com",
    "role": "merchant"
  }
}

Autres endpoints : POST /api/v1/auth/logout (révoque le jeton courant) et POST /api/v1/auth/register (crée un compte marchand).

Crée un lien de paiement depuis vos serveurs (S2S) et retourne l'URL de paiement hébergée data.url à laquelle rediriger votre client. Authentification : en-tête X-API-Key. L'en-tête Idempotency-Key est recommandé pour éviter les doublons.

Paramètres

curl -X POST https://api.soamgroup.gn/api/v1/api/payment-links \
  -H "X-API-Key: samp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cmd-1024-a1b2c3d4" \
  -d '{
    "name": "Commande #1024",
    "amount": 50000,
    "currency": "GNF",
    "allowed_methods": ["orange_money", "mtn_momo", "card"]
  }'

const res = await fetch('https://api.soamgroup.gn/api/v1/api/payment-links', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.SOAMPAY_API_KEY,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'cmd-1024-a1b2c3d4'
  },
  body: JSON.stringify({
    name: 'Commande #1024',
    amount: 50000,
    currency: 'GNF',
    allowed_methods: ['orange_money', 'mtn_momo', 'card']
  })
});
const data = await res.json();

<?php

$data = json_encode([
    'name' => 'Commande #1024',
    'amount' => 50000,
    'currency' => 'GNF',
    'allowed_methods' => ['orange_money', 'mtn_momo', 'card'],
]);

$ch = curl_init('https://api.soamgroup.gn/api/v1/api/payment-links');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $data,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . getenv('SOAMPAY_API_KEY'),
        'Idempotency-Key: cmd-1024-a1b2c3d4',
        'Content-Type: application/json',
    ],
]);
$response = curl_exec($ch);

Réponse 200

{
  "data": {
    "id": 17,
    "token": "lnk_8f2k9xpz3m",
    "name": "Commande #1024",
    "description": null,
    "amount": 50000,
    "amount_formatted": "50 000 GNF",
    "currency": "GNF",
    "allowed_methods": ["orange_money", "mtn_momo", "card"],
    "status": "active",
    "usage_count": 0,
    "conversion_count": 0,
    "collected_amount": 0,
    "expires_at": null,
    "url": "https://pay.soamgroup.gn/pay/lnk_8f2k9xpz3m",
    "qr_code": "data:image/svg+xml;base64,...",
    "created_at": "2026-08-10T09:12:00+00:00"
  }
}

Réponse 422 — Erreur de validation

{
  "message": "The name field is required. (and 2 more errors)",
  "errors": {
    "name": ["The name field is required."],
    "amount": ["The amount field is required."]
  }
}

Liste les liens de paiement du marchand (du plus récent au plus ancien), dans l'environnement de la clé API utilisée. Authentification : en-tête X-API-Key. Aucun paramètre requis.

Réponse 200

{
  "data": [
    {
      "id": 17,
      "token": "lnk_8f2k9xpz3m",
      "name": "Commande #1024",
      "amount": 50000,
      "amount_formatted": "50 000 GNF",
      "currency": "GNF",
      "status": "active",
      "url": "https://pay.soamgroup.gn/pay/lnk_8f2k9xpz3m",
      "created_at": "2026-08-10T09:12:00+00:00"
    }
    ]
}

La liste n'est pas paginée côté S2S. Pour une recherche avancée et de la pagination, utilisez GET /api/v1/transactions du dashboard.

Récupère le détail et le statut actuel d'une transaction (pending, success, failed, refunded) à partir de sa référence. Authentification : en-tête X-API-Key. 404 si la transaction est hors du scope de la clé.

Paramètres

Réponse 200

{
  "data": {
    "id": 204,
    "reference": "TXN-8F2K9XPZ3MQ",
    "payment_link_id": 17,
    "payment_link_token": "lnk_8f2k9xpz3m",
    "payer_name": null,
    "payer_phone": "+224620000000",
    "payer_email": null,
    "amount": 50000,
    "amount_formatted": "50 000 GNF",
    "currency": "GNF",
    "payment_method": "orange_money",
    "status": "success",
    "provider_reference": null,
    "description": "Commande #1024",
    "fee": 500,
    "fee_formatted": "500 GNF",
    "net_amount": 49500,
    "net_amount_formatted": "49 500 GNF",
    "paid_at": "2026-08-10T09:14:32+00:00",
    "created_at": "2026-08-10T09:12:00+00:00"
  }
}

Récupère le détail d'un lien de paiement : statut, montant encaissé, URL et QR code. Authentification : en-tête X-API-Key. 404 si le lien est hors du scope de la clé.

Paramètres

Réponse 200

{
  "data": {
    "id": 17,
    "token": "lnk_8f2k9xpz3m",
    "name": "Commande #1024",
    "description": null,
    "amount": 50000,
    "amount_formatted": "50 000 GNF",
    "currency": "GNF",
    "allowed_methods": ["orange_money", "mtn_momo", "card"],
    "status": "active",
    "usage_count": 3,
    "conversion_count": 2,
    "collected_amount": 100000,
    "expires_at": null,
    "url": "https://pay.soamgroup.gn/pay/lnk_8f2k9xpz3m",
    "qr_code": "data:image/svg+xml;base64,...",
    "created_at": "2026-08-10T09:12:00+00:00"
  }
}

Liste toutes vos transactions (API marchand) avec filtres et pagination, triées par date décroissante. Authentification : Authorization: Bearer samp_... (clé Dashboard).

Paramètres de requête

Réponse 200

{
  "data": [
    {
      "id": 204,
      "reference": "TXN-8F2K9XPZ3MQ",
      "payer_name": "Mamadou Diallo",
      "payer_phone": "+224620000000",
      "amount": 50000,
      "amount_formatted": "50 000 GNF",
      "currency": "GNF",
      "payment_method": "orange_money",
      "status": "success",
      "description": "Commande #1024",
      "paid_at": "2026-08-10T09:14:32+00:00",
      "created_at": "2026-08-10T09:12:00+00:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 15,
    "total": 142
  },
  "status_counts": {
    "total": 142,
    "pending": 4,
    "success": 136,
    "failed": 1,
    "refunded": 1
  }
}

Retourne le détail complet d'une transaction, incluant les frais prélevés (fee), le montant net crédité (net_amount) et le lien de paiement associé. Authentification : Authorization: Bearer samp_....

Réponse 200

{
  "data": {
    "id": 204,
    "reference": "TXN-8F2K9XPZ3MQ",
    "payment_link_id": 17,
    "payment_link_token": "lnk_8f2k9xpz3m",
    "payer_name": "Mamadou Diallo",
    "payer_phone": "+224620000000",
    "amount": 50000,
    "amount_formatted": "50 000 GNF",
    "currency": "GNF",
    "payment_method": "orange_money",
    "status": "success",
    "environment": "live",
    "provider_reference": "OM-GN-20260810-00042",
    "description": "Commande #1024",
    "fee": 750,
    "fee_formatted": "750 GNF",
    "net_amount": 49250,
    "net_amount_formatted": "49 250 GNF",
    "paid_at": "2026-08-10T09:14:32+00:00",
    "created_at": "2026-08-10T09:12:00+00:00"
  }
}

Ce endpoint existe aussi en version S2S : GET /api/v1/api/transactions/{reference} (même réponse, authentification X-API-Key).

Rembourse une transaction success en débitant le solde du marchand du montant net encaissé. Les transactions en mode test ne sont pas remboursables. Authentification : Authorization: Bearer samp_.... Header Idempotency-Key recommandé.

Paramètres

{
  "data": {
    "reference": "TXN-8F2K9XPZ3MQ",
    "status": "refunded",
    "refunded_at": "2026-08-11T10:02:11+00:00"
  },
  "message": "Transaction remboursée."
}

Erreurs

Télécharge toutes vos transactions au format CSV (UTF-8, séparateur virgule), pour vos exports comptables. Fichier nommé transactions_AAAA-MM-JJ.csv. Authentification : Authorization: Bearer samp_....

Structure du fichier

Référence,Payeur,Montant,Devise,Méthode,Statut,Date
TXN-8F2K9XPZ3MQ,Mamadou Diallo,50000,GNF,orange_money,success,10/08/2026 09:14
TXN-9A3L0YQZ4NR,Aminata Soumah,25000,GNF,mtn_momo,refunded,10/08/2026 11:02

Crée une demande de décaissement vers un compte mobile money ou une carte. Le montant est débité de votre solde disponible. Authentification : Authorization: Bearer samp_.... Header Idempotency-Key recommandé.

Paramètres

{
  "data": {
    "id": 42,
    "reference": "PYO-4HZQ2MTX8K9",
    "amount": 20000,
    "amount_formatted": "20 000 GNF",
    "currency": "GNF",
    "status": "pending",
    "method": "orange_money",
    "destination": "+224620000000",
    "provider_reference": null,
    "processed_at": null,
    "created_at": "2026-08-11T11:30:00+00:00"
  },
  "message": "Demande de décaissement créée."
}

Liste vos décaissements (tri décroissant) et retourne un tableau data d'objets Payout avec la même structure que ci-dessus. Suivez un décaissement précis avec GET /api/v1/payouts/{reference}.

Flux de paiement hébergé

Utilisez l'URL de paiement hébergée retournée par POST /api/v1/api/payment-links (data.url, ex. https://pay.soamgroup.gn/pay/lnk_...) : redirigez simplement votre client dessus, SoamPay affiche la page de paiement et notifie votre serveur par webhook. Ces endpoints publics ne requièrent aucune authentification.

Retourne les informations publiques du lien : nom, montant, devise, méthodes acceptées et nom du marchand. Utile pour pré-afficher le paiement dans votre propre interface.

Initie un paiement sur le lien. Sans authentification ni clé API — idéal pour intégrer SoamPay dans votre propre formulaire de paiement. Le header Idempotency-Key n'est pas appliqué sur cette route (protection par payment.duplicate_pending).

Paramètres

{
  "data": {
    "reference": "TXN-8F2K9XPZ3MQ",
    "status": "pending",
    "amount": 50000,
    "amount_formatted": "50 000 GNF",
    "payment_method": "orange_money",
    "message": "Paiement en cours de traitement"
  }
}

Interroge le statut d'un paiement initié (polling). Les statuts possibles sont pending, success, failed et refunded. Route limitée en débit — privilégiez les webhooks pour la confirmation finale.

{
  "data": {
    "reference": "TXN-8F2K9XPZ3MQ",
    "status": "success",
    "amount": 50000,
    "amount_formatted": "50 000 GNF",
    "payment_method": "orange_money",
    "paid_at": "2026-08-10T09:14:32+00:00"
  }
}

Idempotence

Les routes qui créent une ressource (liens de paiement, retraits, remboursements, webhooks, clés API) acceptent un header Idempotency-Key pour éviter les doublons lors d'un envoi retenté (réseau instable, timeout, double-clic).

Comportement

Les réponses idempotentes sont conservées 24 heures. En cas d'échec réseau sans réponse, réutilisez la même clé lors de la nouvelle tentative. La route publique POST /api/v1/pay/{token} n'utilise pas ce mécanisme — elle protège des doublons via payment.duplicate_pending.

Webhooks

Les webhooks vous permettent de recevoir des notifications en temps réel lorsqu'un événement se produit sur votre compte. Configurez vos endpoints dans la section Webhooks du dashboard.

Événements disponibles

Payload

{
  "event": "transaction.succeeded",
  "data": {
    "reference": "TXN-8F2K9XPZ3MQ",
    "amount": 50000,
    "currency": "GNF",
    "method": "orange_money",
    "status": "success",
    "created_at": "2025-06-14T09:12:00Z"
  }
}

const parts = Object.fromEntries(
  header.split(',').map(p => p.trim().split('='))
);
const expected = crypto.createHmac('sha256', webhookSecret)
  .update(`${parts.t}.` + rawBody)
  .digest('hex');

if (parts.v1 !== expected || Math.abs(Date.now()/1000 - Number(parts.t)) > 300) {
  res.status(401).send('Signature invalide');
}

Gestion des webhooks (API marchand)

Créez et pilotez vos endpoints de webhook par API (équivalent de la section Webhooks du dashboard). Authentification : Authorization: Bearer samp_....

Paramètres

curl -X POST https://api.soamgroup.gn/api/v1/webhooks \
  -H "Authorization: Bearer samp_1|abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hook",
    "events": ["transaction.succeeded", "transaction.failed"]
  }'

{
  "data": {
    "id": "01J5C...",
    "url": "https://example.com/hook",
    "events": ["transaction.succeeded", "transaction.failed"],
    "is_active": true,
    "success_count": 0,
    "failure_count": 0,
    "success_rate": null,
    "last_triggered_at": null,
    "created_at": "2026-08-11T10:00:00+00:00"
  }
}

Liste vos webhooks avec leurs statistiques de livraison (success_rate, last_triggered_at).

Gestion des clés API (API marchand)

Créez et révoquez vos clés API (équivalent de la section Clés API du dashboard). Authentification : Authorization: Bearer samp_.... La clé en clair n'est affichée qu'une seule fois à la création — conservez-la dans un gestionnaire de secrets.

Paramètres

{
  "data": {
    "id": "01J5C...",
    "name": "Production",
    "type": "server",
    "company_id": "01J5B...",
    "key_prefix": "samp_live_",
    "key_masked": "samp_live_••••••••••••••••••••••",
    "environment": "live",
    "is_active": true,
    "expires_at": null,
    "created_at": "2026-08-11T10:05:00+00:00"
  },
  "key": "samp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "message": "Clé API créée. Conservez-la précieusement : elle ne sera plus affichée."
}

Liste vos clés API (jamais la clé en clair, uniquement key_masked).

Frais

SoamPay prélève une commission sur chaque paiement réussi. La commission est calculée au moment de la transaction : fee = round(amount × fee_percent / 100). Votre solde est crédité du montant net (montant encaissé − frais).

Taux par moyen de paiement

Le taux appliqué est figé au moment du paiement (les transactions passées ne sont pas affectées par un changement de tarif ultérieur). Les frais et le net apparaissent sur les détails de transaction (fee, net_amount) et sur l'affiche de vos revenus. Un remboursement débite votre solde du montant net initialement encaissé.

Codes d'erreur

L'API utilise des codes HTTP standard pour indiquer le succès ou l'échec d'une requête. Les erreurs retournent toujours un objet JSON avec un champ message (et errors pour les erreurs de validation).

Erreurs métier

En plus du statut HTTP, certaines erreurs portent un code métier interne et un message localisé en français. Exemple de réponse :

{
  "message": "Cette transaction a déjà été remboursée."
}

Format d'erreur

{
  "message": "The amount field must be at least 1000.",
  "errors": {
    "amount": ["The amount field must be at least 1000."]
  }
}

Limites de débit

L'API impose des limites de débit pour garantir la stabilité du service. Les limites sont appliquées par clé API et par groupe d'endpoints.

Headers de réponse

Mode test

Le mode test vous permet de tester l'intégralité de votre parcours sans argent réel : clés API samp_test_..., liens de paiement Test et webhooks (champ environment: "test") — seul le paiement est simulé.

OpenAPI & versioning

L'API SoamPay est documentée selon la spécification OpenAPI 3.0. Une interface interactive (Swagger UI) permet d'explorer chaque endpoint et d'exécuter des requêtes de test : /docs. La spécification JSON brute est disponible sur /docs.json et peut alimenter vos outils (Postman, générateurs de clients).