Encaisser depuis ton application
Ton SaaS crée une session de paiement pour un de ses utilisateurs, l’envoie payer chez Kivoo, et active son compte sur le webhook.
Ton application (un SaaS, une plateforme) connaît déjà ses utilisateurs. Pour leur faire payer un abonnement, tu n’as besoin ni de panier ni de clé à recopier : tu crées une session de paiement pour l’utilisateur, il paie sur une page de Kivoo, il revient chez toi, et tu actives son compte quand Kivoo te prévient.
Ce que tu vends est une licence dont la durée de validité est la période payée, par exemple 30 jours. Mobile Money ne prélève jamais sans l’accord de l’acheteur : rien ne se renouvelle tout seul. Ton application propose le renouvellement, et l’utilisateur paie à nouveau.
Le parcours
- Tu crées une licence réservée à l’application, par exemple « Plan Pro — 30 jours ».
- Quand l’utilisateur 42 clique sur « Passer au Pro », ton serveur crée une session de paiement avec
externalReference: "42". - Tu rediriges l’utilisateur vers l’
urlde la session. - Il paie, puis Kivoo le renvoie sur ton
returnUrl, avec?checkoutId=…. - Ton serveur reçoit le webhook
license_key.issued, avecexternalReference: "42"etexpiresAt, et ouvre le plan Pro jusqu’à cette date.
Préparer la licence
Dans le dashboard, Produits › Créer un produit › Licence :
- Tarif : le prix d’une période. Un prix libre n’est pas possible pour une licence.
- Clés : clés automatiques. Une session refuse une licence en stock de clés.
- Durée de validité : la période payée, par exemple 30 jours. Sans durée, la licence est permanente : un achat unique.
- Vendre seulement depuis mon application : la licence reste publiée, mais n’apparaît nulle part dans ta boutique. Seules tes sessions de paiement la vendent, et
GET /v1/productsla renvoie aveclicense.appOnly: trueet sans page dans la boutique (url: null).
Puis crée une clé API avec la portée Sessions de paiement en lecture et écriture (checkouts:read et checkouts:write). Ajoute Clés de licence en lecture (license_keys:read) pour te resynchroniser. Voir Authentification.
Créer une session
Ton serveur appelle POST /v1/checkouts au moment du clic :
curl https://api.kivoo.africa/v1/checkouts \
-H "Authorization: Bearer $KIVOO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"productId": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
"externalReference": "42",
"returnUrl": "https://app.example.com/facturation/retour",
"metadata": { "plan": "pro", "workspace": "acme" },
"customer": { "email": "awa@example.com", "lastName": "Diallo", "firstName": "Awa" },
"country": "GA"
}'| Champ | Obligatoire | Contenu |
|---|---|---|
productId | oui | La licence vendue. |
externalReference | oui | L’identifiant de l’utilisateur chez toi, 255 caractères au plus. Kivoo te le rend partout. Préfère un identifiant opaque à une adresse e-mail. |
returnUrl | oui | L’adresse où Kivoo renvoie l’utilisateur, en https://. http://localhost et http://127.0.0.1 sont acceptés pour développer. |
metadata | non | Quelques informations à toi : 10 clés au plus, de 40 caractères au plus (a-z, A-Z, 0-9, _), et des valeurs texte de 500 caractères au plus. |
customer | non | email et lastName (obligatoires dans l’objet), firstName. Si tu les donnes, la page s’ouvre directement sur le paiement. |
country | non | Le pays de l’utilisateur, en code ISO 3166-1 alpha-2 (GA). La page s’ouvre sur ce pays ; il peut en choisir un autre. Tout pays connu de Kivoo est accepté, même sans moyen de paiement ouvert. |
Le prix est toujours celui de la licence : ton application ne choisit pas le montant, et un code promo ne s’applique jamais à une licence. Pour une promotion, baisse le prix de la licence ou affiche un prix barré.
Kivoo répond 201 :
{
"id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
"url": "https://atelier-nour.kivoo.co/checkout/Xk2Lp9QwRt5vZb8NcY3mHs7JdF4gA6eU",
"status": "open",
"expiresAt": "2026-10-19T09:12:00.000Z",
"product": { "id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b", "title": "Plan Pro — 30 jours" },
"amount": 4500,
"currency": "XAF",
"externalReference": "42",
"metadata": { "plan": "pro", "workspace": "acme" },
"returnUrl": "https://app.example.com/facturation/retour",
"customer": { "email": "awa@example.com", "lastName": "Diallo", "firstName": "Awa" },
"country": "GA",
"order": null,
"licenseKey": null,
"createdAt": "2026-10-18T09:12:00.000Z"
}amount est le prix de la licence, puis celui de la commande une fois qu’elle existe. Les refus :
| Statut | code | Quand |
|---|---|---|
| 400 | validation_failed | Un champ manque ou sort de ses limites ; details dit lequel. |
| 404 | product_not_found | Produit inconnu, d’une autre boutique, ou pas publié. |
| 422 | checkout_product_not_license | Le produit n’est pas une licence. |
| 422 | checkout_license_stock_unsupported | La licence est en stock de clés. |
| 422 | product_type_unavailable | Les licences ne sont pas ouvertes pour le moment. |
Une session par clic
Kivoo ne dédoublonne pas les sessions : deux appels donnent deux sessions, et les deux peuvent être payées. Crée la session au moment où l’utilisateur clique, et redirige-le aussitôt.
La page de paiement
L’url ouvre une page de paiement seule, au nom et aux couleurs de ta boutique, sans catalogue ni panier :
- le montant à payer, le prix de la licence ;
- les informations de l’utilisateur avec « Modifier » si tu les as données, sinon les champs à remplir ;
- le pays, celui que tu as donné dans
countrysi tu l’as fait, et les moyens de paiement Mobile Money de ce pays. L’utilisateur peut choisir un autre pays : la page garde alors son choix, même s’il la recharge ; - un lien « Retour » vers ton
returnUrl, si l’utilisateur abandonne.
Une session ne prend qu’un paiement et reste ouverte 24 heures. Un paiement refusé se retente sur la même page. Une session payée affiche « Paiement reçu » ; une session expirée invite l’utilisateur à revenir sur ton application pour en créer une nouvelle.
Le retour sur ton application
Une fois le paiement reçu, la page affiche « Paiement reçu », puis renvoie l’utilisateur sur ton returnUrl au bout de trois secondes, avec l’identifiant de la session :
https://app.example.com/facturation/retour?checkoutId=7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0dLe lien « Retour » mène à la même adresse. Ce retour ne prouve rien : n’importe qui peut taper cette adresse. Pour savoir où en est la session, lis-la :
curl https://api.kivoo.africa/v1/checkouts/7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d \
-H "Authorization: Bearer $KIVOO_API_KEY"status vaut open, paid ou expired. Une session payée porte sa commande (order) et sa clé (licenseKey.id). Une session remboursée reste paid : c’est la commande qui dit le remboursement.
Activer le compte
Abonne un webhook à license_key.issued. C’est lui qui porte la date d’expiration, et la session qui l’a vendue :
{
"id": "0b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
"type": "license_key.issued",
"createdAt": "2026-10-18T09:14:05.000Z",
"store": { "id": "6f1c2d3e-4b5a-4c6d-8e9f-0a1b2c3d4e5f", "slug": "atelier-nour" },
"data": {
"id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
"keyHint": "K7M2-…-Q4RT",
"status": "active",
"isActive": true,
"issuedAt": "2026-10-18T09:14:03.000Z",
"expiresAt": "2026-11-17T09:14:03.000Z",
"revokedAt": null,
"activations": { "count": 0, "max": 1, "remaining": 1 },
"product": { "id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b", "title": "Plan Pro — 30 jours" },
"customer": { "id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e", "email": "awa@example.com" },
"order": { "id": "4d5e6f7a-8b9c-4d0e-1f2a-3b4c5d6e7f8a", "reference": "KV-7F3K9QA2" },
"checkout": {
"id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
"externalReference": "42",
"metadata": { "plan": "pro", "workspace": "acme" }
}
}
}- Retrouve ton utilisateur par
data.checkout.externalReference, et ouvre l’accès jusqu’àdata.expiresAt. - Le même événement peut arriver plusieurs fois : garde l’
idde l’événement, et ignore ce que tu as déjà traité (voir Tentatives et journal). order.paidporte aussicheckout: sers-t’en pour ta comptabilité, mais il ne donne pas la date d’expiration.
L’utilisateur reçoit de Kivoo un reçu par e-mail, sans clé : il n’a rien à saisir.
Renouveler
Propose le renouvellement avant l’échéance, avec une nouvelle session pour la même licence et la même externalReference. La nouvelle période s’ajoute à celle qui reste : l’utilisateur payé jusqu’au 17 novembre qui renouvelle le 14 l’est jusqu’au 17 décembre. Le webhook license_key.issued de la nouvelle clé porte déjà cette date.
- Kivoo n’envoie aucun e-mail d’expiration pour une licence vendue par une session : c’est à toi de relancer ton utilisateur, dans ton application ou par tes e-mails.
license_key.expiringpart sept jours au plus avant l’échéance, chaque jour à 06:00 UTC ;license_key.expireddans l’heure qui suit l’échéance. Ni l’un ni l’autre ne part pour une clé déjà renouvelée.- Changer de plan (de « Basic » à « Pro ») est l’achat d’une autre licence : la nouvelle clé court dès le paiement, sans prorata. C’est à ton application de décider ce que devient l’ancien plan.
Pour décider de l’accès, compare toi-même la date du jour à la plus lointaine expiresAt des clés actives de l’utilisateur. Les webhooks te préviennent, ta base de données décide.
Se resynchroniser
Si ton serveur a manqué des webhooks, demande les clés de l’utilisateur :
curl "https://api.kivoo.africa/v1/license-keys?externalReference=42&status=active" \
-H "Authorization: Bearer $KIVOO_API_KEY"Remboursements
Un remboursement se demande depuis le dashboard, par le propriétaire de la boutique, pour une commande d’au moins 1 000 FCFA payée depuis moins de deux jours, et Kivoo le valide. Quand il aboutit, tu reçois order.refunded et license_key.revoked avec reason: "refund" : coupe l’accès que cette clé donnait. Les autres clés de l’utilisateur ne changent pas.
Tester ton intégration
Kivoo n’a pas de mode test : les sessions et les paiements sont réels. Teste avec une licence à petit prix, payée avec ton propre numéro Mobile Money. L’argent arrive dans le solde de ta boutique, moins la commission de Kivoo : c’est tout ce que le test te coûte.
returnUrlacceptehttp://localhost: tu peux revenir sur ton application en local.- Un webhook, lui, doit être une adresse publique en
https://: expose ton serveur local par un tunnel le temps du test. - Le bouton Envoyer un test de ton webhook vérifie que ton serveur répond et que la signature est bonne avant le premier paiement.