API Marchand GeniusPay

Intégrez les paiements mobiles et par carte dans vos applications en quelques minutes.

Authentification

Toutes les requêtes doivent inclure vos clés API dans les headers HTTP.

Exemple avec cURL

curl -X POST https://pay.genius.ci/api/v1/merchant/payments \
  -H "X-API-Key: pk_sandbox_xxxxxxxx" \
  -H "X-API-Secret: sk_sandbox_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"amount": 5000, "customer": {"phone": "+221771234567"}}'

La façon la plus simple d'intégrer GeniusPay. Créez un paiement et redirigez votre client vers notre page de checkout sécurisée où il choisira son moyen de paiement.

// 1. Créer le paiement (sans spécifier payment_method)
$response = Http::withHeaders([
    'X-API-Key' => 'pk_live_xxx',
    'X-API-Secret' => 'sk_live_xxx',
])->post('https://pay.genius.ci/api/v1/merchant/payments', [
    'amount' => 15000,
    'description' => 'Commande #123',
]);

// 2. Rediriger vers la page de checkout GeniusPay
return redirect($response['data']['checkout_url']);

Crée une nouvelle transaction et retourne une URL de paiement.

Paramètres

{
  "amount": 15000,
  "payment_method": "wave",
  "description": "Commande #12345",
  "customer": {
    "name": "Amadou Diallo",
    "email": "amadou@example.com",
    "phone": "+221771234567"
  },
  "metadata": {
    "order_id": "12345"
  }
}

{
  "success": true,
  "data": {
    "id": 456,
    "reference": "MTX-A1B2C3D4E5",
    "amount": 15000,
    "fees": 450,
    "net_amount": 14550,
    "status": "pending",
    "payment_url": "https://wave.com/...",
    "gateway": "wave",
    "environment": "sandbox"
  }
}

Quand vous initiez un paiement sans spécifier de payment_method, l'API retourne une checkout_url vers notre page de paiement hébergée.

Aperçu de la page de checkout

🏪

Paiement sécurisé

Votre Boutique

15 000 FCFA

Wave

Orange Money

MTN MoMo

Carte bancaire

Réponse API (mode checkout)

{
  "success": true,
  "data": {
    "id": 123,
    "reference": "MTX-A1B2C3D4E5",
    "amount": 15000,
    "currency": "XOF",
    "status": "pending",
    "checkout_url": "https://pay.genius.ci/checkout/MTX-A1B2C3D4E5",
    "payment_url": "https://pay.genius.ci/checkout/MTX-A1B2C3D4E5",
    "environment": "sandbox",
    "expires_at": "2024-12-16T14:00:00.000000Z"
  }
}

Paramètres de query

PawaPay est un agrégateur de mobile money. GeniusPay intègre actuellement 12 pays africains avec 24 opérateurs MMO disponibles. Le système détecte automatiquement le pays depuis le numéro de téléphone et affiche uniquement les opérateurs disponibles.

Exemples d'utilisation

// Exemple: Client au Kenya
{
  "amount": 1000,
  "currency": "KES",
  "payment_method": "pawapay",
  "customer": {
    "phone": "+254712345678"
  }
}
// Détection auto: Kenya → M-Pesa Safaricom
// Conversion: 1000 KES × 4.5 = 4500 XOF stockés

// Exemple: Forcer Orange Money Sénégal
{
  "amount": 5000,
  "currency": "XOF",
  "payment_method": "pawapay",
  "mmo_provider": "ORANGE_SEN",
  "customer": {
    "phone": "+221771234567",
    "country": "SN"
  }
}

// Exemple: RD Congo en USD
{
  "amount": 10,
  "currency": "USD",
  "payment_method": "pawapay",
  "customer": {
    "phone": "+243XX XXX XXXX",
    "country": "CD"
  }
}
// Conversion: 10 USD × 600 = 6000 XOF

curl -X POST https://api.geniuspay.com/api/v1/merchant/payments \
  -H "X-API-Key: pk_live_xxx" \
  -H "X-API-Secret: sk_live_xxx" \
  -d '{
    "amount": 5000,
    "payment_method": "pawapay",
    "customer": {
      "phone": "+221771234567"
    }
  }'
# ✅ Auto-détection: Sénégal → Free/Orange Money → XOF

{
  "amount": 1000,
  "currency": "KES",
  "payment_method": "pawapay",
  "customer": {
    "phone": "+254712345678"
  }
}
// Kenya: 1000 KES → 4500 XOF stockés (taux: 4.5)

{
  "amount": 5000,
  "currency": "XOF",
  "payment_method": "pawapay",
  "mmo_provider": "MTN_MOMO_BEN",
  "customer": {
    "phone": "+229XXXXXXXX",
    "country": "BJ"
  }
}
// Force MTN Bénin même si le numéro est Moov

Endpoint de découverte pour lister les fournisseurs MMO par pays ou tous les pays supportés.

Paramètre

{
  "success": true,
  "data": {
    "country": "CI",
    "country_iso3": "CIV",
    "country_name": "Côte d'Ivoire",
    "currency": "XOF",
    "providers": [
      { "code": "ORANGE_CIV", "name": "Orange Money", "type": "MMO" },
      { "code": "MTN_MOMO_CIV", "name": "MTN Mobile Money", "type": "MMO" },
      { "code": "MOOV_CIV", "name": "Moov Money", "type": "MMO" },
      { "code": "WAVE_CIV", "name": "Wave", "type": "MMO" }
    ]
  }
}

{
  "success": true,
  "data": {
    "countries": [
      {
        "country": "CI",
        "country_iso3": "CIV",
        "country_name": "Côte d'Ivoire",
        "currency": "XOF",
        "providers": [ ... ]
      },
      // ... 11 autres pays
    ],
    "total_countries": 12
  }
}

🌍 Pays et opérateurs disponibles

{
  "success": true,
  "data": {
    "available": 1250000,
    "pending": 75000,
    "total": 1325000,
    "currency": "XOF"
  }
}

Webhooks

Recevez des notifications en temps réel sur les événements de vos paiements. L'intégration webhook est identique pour Sandbox et Live, seules les clés changent.

Événements webhook

Configuration Webhook

curl -X POST https://api.geniuspay.ci/merchant/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mon webhook",
    "url": "https://example.com/webhooks/geniuspay",
    "events": ["payment.success", "payment.failed", "cashout.completed"]
  }'

Payload webhook

Le payload est identique pour Sandbox et Live. Seul le champ "environment" change.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "payment.success",
  "timestamp": 1735587600,
  "created_at": "2025-12-30T12:00:00.000000Z",
  "data": {
    "object": "transaction",
    "id": 12345,
    "reference": "TXN-2025-001",
    "amount": 10000.00,
    "currency": "XOF",
    "fees": 250.00,
    "net_amount": 9750.00,
    "status": "completed",
    "payment_method": "mobile_money",
    "provider": "wave",
    "customer_name": "Jean Kouassi",
    "customer_phone": "+2250748123456",
    "merchant_id": 25,
    "metadata": {
      "order_id": "ORD-2025-123",
      "customer_email": "jean@example.com"
    }
  },
  "environment": "live",
  "api_version": "2024-01-01"
}

Sécurité des webhooks

Vérifiez toujours la signature des webhooks pour vous assurer qu'ils proviennent bien de GeniusPay.

Headers webhook

Vérification de la signature

// Récupérer les headers
$signature = $request->header('X-Webhook-Signature');
$timestamp = $request->header('X-Webhook-Timestamp');
$event = $request->header('X-Webhook-Event');

// Récupérer le payload JSON
$payload = $request->all();

// Construire la donnée à vérifier
$data = $timestamp . '.' . json_encode($payload);

// Calculer la signature attendue
$secret = 'whsec_xxxxxxxx'; // Votre clé secrète webhook
$expectedSignature = hash_hmac('sha256', $data, $secret);

// Vérifier la signature
if (!hash_equals($expectedSignature, $signature)) {
    return response()->json([
        'status' => 401,
        'detail' => 'Invalid signature'
    ], 401);
}

// Vérifier le timestamp (protection replay attack)
if (abs(time() - (int)$timestamp) > 300) { // 5 minutes
    return response()->json([
        'status' => 400,
        'detail' => 'Timestamp too old'
    ], 400);
}

// Traiter l'événement selon son type
switch ($event) {
    case 'payment.success':
        // Marquer la commande comme payée
        break;
    case 'payment.failed':
        // Notifier le client
        break;
}

Statuts des paiements

Méthodes de paiement

Codes d'erreur

Exemples d'intégration

// Intégration en 2 lignes avec le SDK Laravel
$payment = GeniusPay::checkout(15000, 'Commande #123');
return redirect($payment->checkoutUrl);

// Ou avec Http natif
$response = Http::withHeaders([
    'X-API-Key' => 'pk_live_xxx',
    'X-API-Secret' => 'sk_live_xxx',
])->post('https://pay.genius.ci/api/v1/merchant/payments', [
    'amount' => 15000,
    'description' => 'Commande #123',
    // PAS de payment_method = Page checkout GeniusPay
]);

return redirect($response['data']['checkout_url']);

// Intégration simplifiée
const response = await fetch('https://pay.genius.ci/api/v1/merchant/payments', {
  method: 'POST',
  headers: {
    'X-API-Key': 'pk_live_xxx',
    'X-API-Secret': 'sk_live_xxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 15000,
    description: 'Commande #123',
    // PAS de payment_method = Page checkout GeniusPay
  }),
});

const { data } = await response.json();
window.location.href = data.checkout_url;

# Intégration simplifiée
import requests

response = requests.post(
    'https://pay.genius.ci/api/v1/merchant/payments',
    headers={
        'X-API-Key': 'pk_live_xxx',
        'X-API-Secret': 'sk_live_xxx',
    },
    json={
        'amount': 15000,
        'description': 'Commande #123',
        # PAS de payment_method = Page checkout GeniusPay
    }
)

checkout_url = response.json()['data']['checkout_url']
# Rediriger le client vers checkout_url

// Intégration en 2 lignes avec le SDK Flutter
final payment = await geniusPay.checkout(
  amount: 15000, 
  description: 'Commande #123',
);
launchUrl(Uri.parse(payment.checkoutUrl!));

$response = Http::withHeaders([
    'X-API-Key' => 'pk_live_xxx',
    'X-API-Secret' => 'sk_live_xxx',
])->post('https://pay.genius.ci/api/v1/merchant/payments', [
    'amount' => 15000,
    'payment_method' => 'wave', // Redirection directe vers Wave
    'customer' => [
        'phone' => '+221771234567',
    ],
]);

return redirect($response['data']['payment_url']);

const response = await fetch('https://pay.genius.ci/api/v1/merchant/payments', {
  method: 'POST',
  headers: {
    'X-API-Key': 'pk_live_xxx',
    'X-API-Secret': 'sk_live_xxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 15000,
    payment_method: 'wave', // Redirection directe vers Wave
    customer: { phone: '+221771234567' },
  }),
});

const { data } = await response.json();
window.location.href = data.payment_url;