Choisir son intégration
Lien de paiement hébergé ou API directe — ce que chaque approche demande, et ce qu'elle vous laisse à faire.
Choisir son intégration
Deux façons d'encaisser avec Genuka Pay. Elles utilisent les mêmes comptes, les mêmes tarifs et les mêmes webhooks — seule change la part d'interface que vous écrivez.
| Lien de paiement | API directe | |
|---|---|---|
| Vous construisez | Rien | Le formulaire de paiement |
| Le payeur | Est envoyé sur une page Genuka Pay | Reste chez vous |
| Numéro du payeur | Demandé sur la page | Vous le collectez |
| Choix de l'opérateur | Fait sur la page | À votre charge |
| Carte bancaire | Incluse | Non |
| Mise en place | Un appel API | Un appel API + gestion des états |
Commencez par le lien de paiement. Passez à l'API directe quand vous voulez maîtriser l'expérience de bout en bout.
Lien de paiement hébergé
Vous créez une session de paiement, vous redirigez le client vers l'URL renvoyée, Genuka Pay se charge du reste.
POST /api/v1/checkout| Paramètre | Type | Requis | Description |
|---|---|---|---|
amount | number | Oui | Montant à encaisser |
currency | string | Oui | XAF ou XOF |
description | string | Non | Affiché au payeur |
payer_name | string | Non | Pré-remplit la page |
payer_email | string | Non | Pré-remplit la page |
payer_phone | string | Non | Format E.164, ex. +237677001122 |
return_url | string | Non | Retour après paiement réussi |
cancel_url | string | Non | Retour après abandon |
expires_at | date | Non | Expiration du lien. Doit être dans le futur. |
metadata | object | Non | Vos propres références |
curl -X POST "{{BASE_URL}}/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",
"metadata": { "order_id": "10001" }
}'{
"data": {
"id": "01HR...",
"token": "chk_01HR...",
"amount": 10000,
"currency": "XOF",
"status": "CREATED",
"urls": {
"checkout": "https://api-pay.genuka.com/checkout/chk_01HR...",
"return": "https://boutique.example.com/merci",
"cancel": "https://boutique.example.com/panier"
},
"expires_at": null
}
}Redirigez le client vers urls.checkout. Relisez l'état d'une session à tout moment :
GET /api/v1/checkout/{token}Ne comptez pas sur le retour navigateur
return_url sert au confort du client, pas à la comptabilité : il peut fermer l'onglet avant d'y arriver. Le paiement n'est confirmé que par le webhook transaction.success.
API directe
Vous collectez le numéro du payeur, vous créez le paiement, l'opérateur pousse une demande de confirmation sur le téléphone du client.
curl -X POST "{{BASE_URL}}/api/v1/payments" \
-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",
"payer_phone": "+2250700000001",
"external_id": "order_10001",
"return_url": "https://maboutique.com/commandes/10001/merci"
}'Détail des champs et de la réponse : API Paiements.
Ce que le payeur doit faire ensuite
La réponse contient redirect_url, qui dit quoi faire du payeur :
redirect_url | Ce que vous en faites |
|---|---|
Non-null | Une page de paiement : redirigez le payeur. C'est le cas de la carte bancaire, et d'Orange, Wave et Djamo en Côte d'Ivoire. |
null | Le client valide sur son téléphone : affichez payment_token et attendez. |
MTN et Moov en Côte d'Ivoire
Ces deux opérateurs confirment par code USSD, mais renvoient quand même une URL dans payment_token — une page d'attente, pas une page de paiement. C'est pour cela que redirect_url existe et que c'est lui qu'il faut tester : le token porte une URL dans les deux cas et ne les distingue pas. Affichez un écran d'attente chez vous et suivez le statut.
Une redirection a besoin d'une adresse de retour
Dès que redirect_url peut être non-null, envoyez return_url — et cancel_url si l'échec a sa propre page — à la création du paiement. Le payeur quitte votre site pour l'opérateur ; sans ces adresses, Genuka Pay n'a nulle part où le ramener et il termine sur la page d'accueil de Genuka Pay. Les paramètres ajoutés à votre URL sont détaillés dans API Paiements.
Suivre le paiement
Dans l'ordre de préférence :
- le webhook
transaction.success/transaction.failed— la source de vérité ; GET /api/v1/payments/status/{track_id}— pour rafraîchir un écran d'attente ou réconcilier.
Un paiement reste en PROCESSING tant que le client n'a pas validé. Ne concluez jamais à un échec sur un simple délai : c'est le statut final qui tranche.
Et les liens de collecte ?
Les liens de collecte réutilisables (montant libre ou fixe, partagés par WhatsApp ou QR code) se créent depuis le dashboard, page Collectes. Ils ne demandent aucune intégration.
À voir ensuite
How is this guide?
Last updated on