Geniuspay - Api

L'authentification s'effectue en transmettant des clés API via les headers HTTP de chaque requête vers la Base URL https://geniuspay.ci/api/v1/merchant.

Headers requis :

• X-API-Key : Clé publique du marchand (pk_sandbox_... ou pk_live_...). Variable d'environnement recommandée : GENIUSPAY_API_KEY.
• X-API-Secret : Clé secrète du marchand (sk_sandbox_... ou sk_live_...). Variable d'environnement recommandée : GENIUSPAY_API_SECRET.
• Content-Type : application/json

Ne jamais exposer la clé secrète (GENIUSPAY_API_SECRET) côté client (frontend, application mobile).

Base URL : https://geniuspay.ci/api/v1/merchant

### 1. Initier un paiement

• Méthode / URL : POST /payments
• Paramètres du body :
  • amount (number, requis) : Montant en XOF (minimum : 200).
  • currency (string, optionnel) : Devise (XOF, EUR, USD). Défaut : XOF.
  • payment_method (string, optionnel) : wave, pawapay, paystack, orange_money, mtn_money, card. Si omis, une URL de checkout GeniusPay est générée.
  • gateway (string, optionnel) : Gateway explicite (wave, pawapay, orange_money, mtn_momo, moov_money).
  • mmo_provider (string, optionnel) : Code fournisseur MMO PawaPay (ex: ORANGE_CIV).
  • description (string, optionnel) : Description du paiement (max 500 caractères).
  • customer.name (string, optionnel) : Nom du client.
  • customer.email (string, optionnel) : Email du client.
  • customer.phone (string, optionnel) : Téléphone du client (format international recommandé).
  • customer.country (string, optionnel) : Code pays ISO2 (ex: CI, SN, CD).
  • success_url (string, optionnel) : URL de redirection après succès.
  • error_url (string, optionnel) : URL de redirection après échec.
  • metadata (object, optionnel) : Données personnalisées clé/valeur.
• Réponse succès (201) : Retourne un objet JSON contenant les détails de la transaction, incluant l'ID, la reference (ex: MTX-A1B2C3D4E5), le statut (pending), et l'URL de paiement ou de checkout (checkout_url / payment_url).

### 2. Lister les paiements

• Méthode / URL : GET /payments
• Paramètres de query : status, payment_method, from, to, search, per_page.
• Réponse succès (200) : Liste paginée des transactions.

### 3. Récupérer un paiement

• Méthode / URL : GET /payments/{reference}
• Paramètre d'URL : reference (string, requis) : Référence unique de la transaction (format MTX-XXXXXXXXXX).
• Réponse succès (200) : Détails complets de la transaction incluant les metadata.
• Erreur (404) : { "success": false, "error": { "code": "TRANSACTION_NOT_FOUND", "message": "Transaction not found" } }

### 4. Informations du compte

• Méthode / URL : GET /account
• Réponse succès (200) : Informations du compte marchand.

### 5. Solde du compte

• Méthode / URL : GET /account/balance
• Réponse succès (200) : Solde available, pending, total en XOF.

### 6. Fournisseurs MMO PawaPay

• Méthode / URL : GET /pawapay/providers
• Paramètre de query : country (string, optionnel) : Code pays ISO2.
• Réponse succès (200) : Liste des opérateurs MMO supportés par pays.

Toutes les erreurs suivent ce format :

1{2  "success": false,3  "error": {4    "code": "ERROR_CODE",5    "message": "Description lisible de l'erreur"6  }7}

Codes courants :

• MISSING_API_KEY (401) : Clé API manquante dans les headers.
• INVALID_API_KEY (401) : Clé API invalide ou expirée.
• MERCHANT_INACTIVE (403) : Compte marchand désactivé.
• PAYMENT_INIT_FAILED (400) : Échec d'initialisation du paiement.
• TRANSACTION_NOT_FOUND (404) : Transaction introuvable pour la référence donnée.
• VALIDATION_ERROR (422) : Données de requête invalides.
• COUNTRY_NOT_SUPPORTED (404) : Pays non supporté par PawaPay.

• Configuration : CRUD disponible via les endpoints /webhooks.
• Secret Webhook : whsec_... (fourni uniquement à la création). Variable d'environnement recommandée : GENIUSPAY_WEBHOOK_SECRET.
• Headers reçus :
  • X-Webhook-Signature : Signature HMAC-SHA256
  • X-Webhook-Timestamp : Timestamp Unix de l'envoi
  • X-Webhook-Event : Type d'événement (ex: payment.success)
  • X-Webhook-Environment : sandbox ou live
• Algorithme de vérification :

1. Construire la chaîne de données : timestamp + "." + json_payload

2. Calculer le HMAC-SHA256 avec le secret webhook (GENIUSPAY_WEBHOOK_SECRET).

3. Comparer avec X-Webhook-Signature en utilisant une comparaison sécurisée (hash_equals).

4. Vérifier que le timestamp n'est pas trop ancien (tolérance de 5 minutes / 300 secondes contre les attaques par rejeu).

• Événements principaux : payment.initiated, payment.success, payment.failed, payment.cancelled, payment.refunded, payment.expired, cashout.completed, webhook.test.

• Idempotence : Non documenté : à vérifier.
• Limites de débit : Non documenté : à vérifier.
• Montant minimum : 200 XOF.
• Expiration du lien de checkout : 24 heures.

1. Confondre ID interne et Référence : Utiliser l'ID numérique interne (ex: 456) à la place de la référence unique (MTX-A1B2C3D4E5) pour interroger les endpoints de récupération.

2. Exposer la clé secrète : Inclure X-API-Secret dans du code front-end (JavaScript client, application mobile).

3. Oublier les metadata : Ne pas transmettre le champ metadata à la création (POST) et s'attendre à le retrouver lors de la récupération (GET) ou dans les webhooks.

4. Mauvaise gestion de l'environnement : Mélanger les clés sandbox (pk_sandbox_... / sk_sandbox_...) et live (pk_live_... / sk_live_...).

5. Ne pas valider la signature des webhooks : Traiter les notifications sans vérifier le header X-Webhook-Signature et le timestamp.

• GENIUSPAY_API_KEY
• GENIUSPAY_API_SECRET
• GENIUSPAY_WEBHOOK_SECRET