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_SIGNATURELa 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/checkoutGET /api/v1/checkout/{token}
Créer une session
POST /api/v1/checkout| Paramètre | Type | Requis | Description |
|---|---|---|---|
amount | number | Oui | Montant à encaisser, minimum 1 |
currency | string | Oui | XAF ou XOF |
description | string | Non | Affiché au payeur (255 caractères max) |
payer_name | string | Non | Nom du payeur |
payer_email | string | Non | E-mail du payeur |
payer_phone | string | Non | Format E.164, ex. +237677001122. Pré-remplit le numéro sur la page. |
return_url | string | Non | Où ramener le payeur après le paiement |
cancel_url | string | Non | Où le ramener après un échec. À défaut, return_url sert aussi pour l'échec. |
expires_at | date ISO 8601 | Non | Expiration de la session, dans le futur. 15 minutes après la création par défaut. |
metadata | object | Non | Vos 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" }
}'{
"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
| Statut | Description |
|---|---|
CREATED | Session créée, aucune tentative de paiement |
INITIATED / PROCESSING | Une tentative est en cours |
SUCCESS | Payée. La session n'accepte plus de paiement. |
FAILED | La dernière tentative a échoué. Le payeur peut réessayer tant que la session n'a pas expiré. |
EXPIRED / CANCELLED | Session 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