Logo GenukaGenuka Pay
Référence API

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

URL de base
https://api-pay.genuka.com/api/v1

Headers requis

Headers de requête authentifiée
X-Public-Key: YOUR_PUBLIC_KEY
X-Timestamp: UNIX_TIMESTAMP
X-Signature: HMAC_SHA256_SIGNATURE

La 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 :

Choisir la langue par en-tête
Accept-Language: fr
  • Les valeurs standard sont acceptées, avec leurs poids : fr-FR,fr;q=0.9,en;q=0.8 donne fr.
  • Une variante régionale est ramenée à sa langue : fr-CM donne fr, en-US donne en.
  • Une langue pondérée q=0 est 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 :

Choisir la langue par cookie
Cookie: language=fr

Le 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 :

Choisir la langue avec le SDK TypeScript
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" },
    }),
});

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}

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}/retry

Endpoints 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}/test

Couverture opérateurs

GET /api/v1/operator-providers

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 :

environmentPréfixe des clésEffet
SANDBOXpk_test_… / sk_test_…Aucun argent réel, numéros de test
LIVEpk_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 explicite XAF ou XOF.
  • Les dates sont au format ISO 8601 en UTC (2026-09-19T10:00:00.000000Z). Seul l'en-tête X-Timestamp de 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éfixeExemple
PX, MV, TM, JK, EKJK-01k7c4t9m2y8x5b3n6q0r1s2t3
GPidentifiant 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 :

  1. 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
  2. Calculez HMAC_SHA256(secret_key, message)
  3. 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