Vue d'ensemble API
Comprenez la structure de l'API Genuka Pay et ses endpoints principaux.
Introduction
L'API Genuka Pay est une API REST basée sur JSON organisée autour de quelques familles de ressources : paiements, checkout hébergé, payouts, endpoints webhook, couverture opérateurs et abonnements.
URL de base
https://api-pay.genuka.com/api/v1Headers requis
X-Public-Key: YOUR_PUBLIC_KEY
X-Timestamp: UNIX_TIMESTAMP
X-Signature: HMAC_SHA256_SIGNATURELa signature est calculée avec votre secret_key d'application. Préférez les SDKs officiels quand c'est possible.
Langue des réponses
Les erreurs de validation et la plupart des messages d'erreur métier existent en français et en anglais. Certains messages sont encore renvoyés uniquement en anglais, notamment les erreurs d'authentification, de contexte (environnement, application) et les erreurs serveur génériques. Fiez-vous au code HTTP et aux champs d'erreur, pas au texte du message.
Choisissez la langue avec l'en-tête Accept-Language :
Accept-Language: fr- Les valeurs standard sont acceptées, avec leurs poids :
fr-FR,fr;q=0.9,en;q=0.8donnefr. - Une variante régionale est ramenée à sa langue :
fr-CMdonnefr,en-USdonneen. - Une langue pondérée
q=0est considérée comme refusée. - Une langue non supportée, ou
*, est ignorée sans erreur.
Si vous ne maîtrisez pas cet en-tête, passez la langue par cookie :
Cookie: language=frLe cookie n'est pris en compte que si l'en-tête est absent, vaut * ou ne désigne aucune langue supportée. L'API lit dans cet ordre : l'en-tête Accept-Language, puis le cookie Accept-Language, puis le cookie language. La première valeur qui désigne une langue supportée l'emporte. Si aucune n'est exploitable, l'API répond dans sa langue par défaut.
Les SDKs officiels n'envoient pas cet en-tête. Pour choisir la langue avec eux, passez un fetch personnalisé (TypeScript) ou un HttpTransport personnalisé (PHP) qui l'ajoute :
const genuka = new GenukaClient({
publicKey: process.env.GENUKA_PUBLIC_KEY!,
secretKey: process.env.GENUKA_SECRET_KEY!,
fetch: (url, init) =>
fetch(url, {
...init,
headers: { ...(init?.headers as Record<string, string>), "Accept-Language": "fr" },
}),
});Paiements
Initiez des encaissements, estimez les frais et suivez le statut des transactions.
Checkout hébergé
Créez une page de paiement Genuka Pay et redirigez-y votre client.
Payouts
Demandez un décaissement vers un numéro mobile money et suivez sa validation.
Abonnements
Facturez vos clients à intervalle régulier, avec relances et paiement mobile money.
Webhooks
Recevez les changements d'état asynchrones via les endpoints webhook.
Couverture
Lisez à l'exécution les opérateurs ouverts par pays et leurs plafonds.
Endpoints accessibles par clé API
Tous les endpoints ci-dessous acceptent les headers HMAC (X-Public-Key, X-Timestamp, X-Signature). Les chemins sont relatifs à https://api-pay.genuka.com.
Paiements
GET /api/v1/payments
POST /api/v1/payments
POST /api/v1/payments/quote
GET /api/v1/payments/status/{track_id}Il n'existe pas d'endpoint GET /api/v1/payments/{id} : un paiement se relit par son track_id.
Checkout hébergé
POST /api/v1/checkout
GET /api/v1/checkout/{token}Voir Checkout hébergé.
Payouts
GET /api/v1/payouts
POST /api/v1/payouts
GET /api/v1/payouts/balance
GET /api/v1/payouts/{id}
POST /api/v1/payouts/{id}/cancel
POST /api/v1/payouts/{id}/retryEndpoints webhook
GET /api/v1/webhook-endpoints
POST /api/v1/webhook-endpoints
GET /api/v1/webhook-endpoints/{id}
PUT /api/v1/webhook-endpoints/{id}
PATCH /api/v1/webhook-endpoints/{id}
DELETE /api/v1/webhook-endpoints/{id}
POST /api/v1/webhook-endpoints/{id}/regenerate-secret
POST /api/v1/webhook-endpoints/{id}/testCouverture opérateurs
GET /api/v1/operator-providersVoir Pays et opérateurs.
Abonnements
Produits, clients, abonnements, factures, liens d'abonnement et portail client : voir Abonnements.
Ce qui reste dans le dashboard
Les clés d'application (/api/v1/application), le KYC (/api/v1/kyc/*), les méthodes de paiement (/api/v1/payment-methods) et les liens de collecte n'acceptent que la session du dashboard. Appelés avec une clé API, ils répondent 401. Gérez-les depuis le dashboard : Clés API, KYC, Méthodes de paiement.
Toute l'API intégration exige un profil d'entreprise complet (forme juridique, pays, secteur) : tant qu'il ne l'est pas, ces endpoints répondent 403.
Environnements
Chaque entreprise a deux applications, donc deux paires de clés :
environment | Préfixe des clés | Effet |
|---|---|---|
SANDBOX | pk_test_… / sk_test_… | Aucun argent réel, numéros de test |
LIVE | pk_live_… / sk_live_… | Vrais débits, plafonds KYC appliqués |
L'environnement est porté par la clé : il n'y a pas de header à envoyer, ni d'URL distincte.
Conventions API
- Les montants sont envoyés et renvoyés en unités de la devise (
1000= 1 000 XAF), avec un code ISO expliciteXAFouXOF. - Les dates sont au format ISO 8601 en UTC (
2026-09-19T10:00:00.000000Z). Seul l'en-têteX-Timestampde la signature est en secondes Unix. - Les numéros de téléphone sont au format E.164 (
+237677001122). - Les identifiants (
id,token) sont des ULID.
Identifiants de suivi
Chaque paiement et payout reçoit un track_id préfixé selon le prestataire qui le traite, suivi d'un ULID en minuscules :
| Préfixe | Exemple |
|---|---|
PX, MV, TM, JK, EK | JK-01k7c4t9m2y8x5b3n6q0r1s2t3 |
GP | identifiant interne, quand aucun prestataire n'est encore connu |
Traitez le track_id comme une chaîne opaque : ne déduisez rien de son préfixe, qui peut varier d'un paiement à l'autre pour un même opérateur.
Enveloppe de réponse
Une ressource est renvoyée sous data :
{ "data": { "id": "01k7c4…", "status": "PROCESSING" } }Certaines réponses ajoutent un message technique à côté de data (par exemple "payin_fees_quoted"). Les listes sont aussi sous data.
Erreurs
{
"message": "The amount field must be at least 1.",
"errors": {
"amount": ["The amount field must be at least 1."]
}
}errors n'est présent que sur les erreurs de validation (422). Voir Gestion des erreurs.
Idempotence
POST /api/v1/payments et POST /api/v1/payouts acceptent un header Idempotency-Key. À défaut, votre external_id sert de clé. Une deuxième requête avec la même clé ne crée rien : elle renvoie la transaction existante. Les SDKs officiels envoient ce header via l'option idempotencyKey.
Authentification HMAC
Toutes les requêtes authentifiées utilisent HMAC-SHA256 :
- Concaténez, sans séparateur : la valeur de
X-Timestamp, la méthode HTTP en majuscules, le chemin avec sa query string (ex./api/v1/payments?per_page=20), puis le corps brut de la requête (chaîne vide s'il n'y en a pas)timestamp + HTTP_METHOD + path_with_query + raw_body - Calculez
HMAC_SHA256(secret_key, message) - Envoyez la signature hexadécimale en tant que
X-Signature
La clé publique ne fait pas partie de la chaîne signée : elle est seulement envoyée dans X-Public-Key. Le timestamp doit être à moins de 5 minutes de l'heure du serveur. Une signature invalide, un timestamp hors fenêtre ou une clé inactive donnent tous la même réponse 401 {"message": "Unauthenticated."}.
Utilisez les SDKs officiels pour cette logique plutôt que de l'implémenter manuellement.
How is this guide?
Last updated on