Logo GenukaGenuka Pay
Référence API

Checkout hébergé

Créez une page de paiement Genuka Pay, redirigez-y votre client et suivez le résultat.

Le checkout hébergé encaisse sans que vous construisiez de formulaire : vous créez une session, vous redirigez le client vers l'URL renvoyée, et la page Genuka Pay se charge du choix de l'opérateur, du numéro, de la confirmation et du reçu. Pour comparer avec l'API directe, voir Choisir son intégration.

Headers requis

X-Public-Key: YOUR_PUBLIC_KEY
X-Timestamp: UNIX_TIMESTAMP
X-Signature: HMAC_SHA256_SIGNATURE

La création d'une session exige une clé API : appelée depuis la session du dashboard, elle est refusée en 403.

Endpoints

  • POST /api/v1/checkout
  • GET /api/v1/checkout/{token}

Créer une session

POST /api/v1/checkout
ParamètreTypeRequisDescription
amountnumberOuiMontant à encaisser, minimum 1
currencystringOuiXAF ou XOF
descriptionstringNonAffiché au payeur (255 caractères max)
payer_namestringNonNom du payeur
payer_emailstringNonE-mail du payeur
payer_phonestringNonFormat E.164, ex. +237677001122. Pré-remplit le numéro sur la page.
return_urlstringNonOù ramener le payeur après le paiement
cancel_urlstringNonOù le ramener après un échec. À défaut, return_url sert aussi pour l'échec.
expires_atdate ISO 8601NonExpiration de la session, dans le futur. 15 minutes après la création par défaut.
metadataobjectNonVos propres références. Renvoyées dans les webhooks des paiements de cette session.
curl -X POST "https://api-pay.genuka.com/api/v1/checkout" \
  -H "X-Public-Key: YOUR_PUBLIC_KEY" \
  -H "X-Timestamp: UNIX_TIMESTAMP" \
  -H "X-Signature: HMAC_SHA256_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency": "XOF",
    "description": "Commande #10001",
    "return_url": "https://boutique.example.com/merci",
    "cancel_url": "https://boutique.example.com/panier",
    "expires_at": "2026-09-19T12:00:00Z",
    "metadata": { "order_id": "10001" }
  }'
Réponse — 201
{
  "data": {
    "id": "01k7c4t9m2y8x5b3n6q0r1s2t3",
    "token": "01k7c4t9m5a7b8c9d0e1f2g3h4",
    "company_id": "01k5...",
    "application_id": "01k5...",
    "amount": 10000,
    "currency": "XOF",
    "description": "Commande #10001",
    "status": "CREATED",
    "status_label": "Créée",
    "payer": { "name": null, "email": null, "phone": null },
    "urls": {
      "checkout": "https://api-pay.genuka.com/checkout/01k7c4t9m5a7b8c9d0e1f2g3h4",
      "return": "https://boutique.example.com/merci",
      "cancel": "https://boutique.example.com/panier"
    },
    "expires_at": "2026-09-19T12:00:00.000000Z",
    "metadata": { "order_id": "10001" },
    "created_at": "2026-09-19T11:45:00.000000Z",
    "updated_at": "2026-09-19T11:45:00.000000Z"
  }
}

Redirigez le client vers urls.checkout. Le token est l'identifiant de la session : c'est lui que vous passez à GET /api/v1/checkout/{token}.

Il n'y a pas de clé d'idempotence sur cet endpoint : chaque appel crée une nouvelle session. Gardez la correspondance entre votre commande et le token de votre côté.

Relire une session

GET /api/v1/checkout/{token}

Même forme que ci-dessus, avec en plus payins : la liste des tentatives de paiement de la session, au format des paiements (track_id, status, failure, frais…).

Statuts

StatutDescription
CREATEDSession créée, aucune tentative de paiement
INITIATED / PROCESSINGUne tentative est en cours
SUCCESSPayée. La session n'accepte plus de paiement.
FAILEDLa dernière tentative a échoué. Le payeur peut réessayer tant que la session n'a pas expiré.
EXPIRED / CANCELLEDSession close

Le statut suit celui de la dernière tentative. Une session dont expires_at est passé n'accepte plus de paiement — la page affiche un écran d'expiration (HTTP 410) — même si son statut n'a pas encore changé : fiez-vous à expires_at.

Ce que voit le payeur

La page urls.checkout :

  • affiche votre nom, votre logo, le montant et la description ;
  • laisse le payeur choisir son pays et son opérateur, puis saisir son numéro (pré-rempli avec payer_phone) ;
  • propose la carte bancaire si elle est activée sur votre compte (réglage du dashboard) ;
  • affiche les frais ajoutés au montant quand ils sont à la charge du client (fee_bearer = CUSTOMER) ;
  • suit le paiement en direct et permet de réessayer après un échec.

En sandbox, la page fonctionne avec les numéros de test.

Retour du payeur

Une fois le paiement terminé, le payeur est renvoyé sur return_url (ou cancel_url en cas d'échec) avec les paramètres status, reference (le track_id) et token (celui de la session) ajoutés à l'URL. Le détail est dans API Paiements.

Ne comptez pas sur le retour navigateur

Le client peut fermer l'onglet avant d'arriver sur return_url, et les paramètres de l'URL sont modifiables. Le paiement n'est confirmé que par le webhook transaction.success ou par GET /api/v1/checkout/{token}.

Webhooks

Les paiements faits sur la page déclenchent les mêmes événements transaction.* qu'un paiement API. Dans leur data.metadata, vous retrouvez le metadata de la session : c'est là qu'il faut mettre votre référence de commande.

Reçu

Une fois le paiement réussi, la page propose au payeur de télécharger un reçu PDF :

GET https://api-pay.genuka.com/checkout/{token}/receipt?track_id={track_id}

Cette URL est publique (elle ne demande pas de signature) mais ne répond qu'avec le track_id d'un paiement réussi de cette session ; sinon 404.

Reçu par WhatsApp

Si vous activez l'option reçu WhatsApp dans les réglages de votre entreprise, le payeur reçoit aussi son reçu sur WhatsApp après un paiement réussi. Conditions :

  • uniquement en LIVE ;
  • uniquement pour les paiements faits via un checkout hébergé ou un lien de collecte, pas via POST /api/v1/payments ;
  • uniquement si le numéro du payeur est au format international (un paiement par carte n'en a pas).

How is this guide?

Last updated on