API Marchand GeniusPay

Intégrez les paiements mobiles (Wave, Orange Money, MTN Money) 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

{
  "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;