Accept payments from your app
Your SaaS creates a checkout session for one of its users, sends them to pay on Kivoo, and activates their account on the webhook.
Your app (a SaaS, a platform) already knows its users. To have them pay a subscription, you need neither a cart nor a key to copy: you create a checkout session for the user, they pay on a Kivoo page, they come back to you, and you activate their account when Kivoo tells you.
What you sell is a license whose validity is the paid period, for example 30 days. Mobile Money never charges without the buyer’s consent: nothing renews on its own. Your app offers the renewal, and the user pays again.
The flow
- You create a license reserved for the app, for example “Plan Pro — 30 jours”.
- When user 42 clicks “Upgrade to Pro”, your server creates a checkout session with
externalReference: "42". - You redirect the user to the session’s
url. - They pay, then Kivoo sends them back to your
returnUrl, with?checkoutId=…. - Your server receives the
license_key.issuedwebhook, withexternalReference: "42"andexpiresAt, and opens the Pro plan until that date.
Prepare the license
In the dashboard, Produits › Créer un produit › Licence (Products › Create a product › License):
- Pricing: the price of one period. A license cannot have an open price.
- Keys: automatic keys. A session refuses a license in key stock mode.
- Validity: the paid period, for example 30 days. Without a validity, the license is permanent: a one-off purchase.
- Vendre seulement depuis mon application (sell only from my app): the license stays published but appears nowhere in your store. Only your checkout sessions sell it, and
GET /v1/productsreturns it withlicense.appOnly: trueand no page in the store (url: null).
Then create an API key with the Checkout sessions scope in read and write (checkouts:read and checkouts:write). Add License keys in read (license_keys:read) to resynchronise. See Authentication.
Create a session
Your server calls POST /v1/checkouts when the user clicks:
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/billing/return",
"metadata": { "plan": "pro", "workspace": "acme" },
"customer": { "email": "awa@example.com", "lastName": "Diallo", "firstName": "Awa" },
"country": "GA"
}'| Field | Required | Content |
|---|---|---|
productId | yes | The license sold. |
externalReference | yes | The user’s identifier in your system, 255 characters at most. Kivoo gives it back everywhere. Prefer an opaque id to an email address. |
returnUrl | yes | Where Kivoo sends the user back, in https://. http://localhost and http://127.0.0.1 are accepted for development. |
metadata | no | A little data of yours: 10 keys at most, of 40 characters at most (a-z, A-Z, 0-9, _), with text values of 500 characters at most. |
customer | no | email and lastName (required inside the object), firstName. When you give them, the page opens straight on the payment. |
country | no | The user’s country, as an ISO 3166-1 alpha-2 code (GA). The page opens on that country; the user may pick another one. Any country Kivoo knows is accepted, even one with no open payment method. |
The price is always the license’s: your app does not choose the amount, and a promo code never applies to a license. For a promotion, lower the license’s price or show a compare-at price.
Kivoo answers 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/billing/return",
"customer": { "email": "awa@example.com", "lastName": "Diallo", "firstName": "Awa" },
"country": "GA",
"order": null,
"licenseKey": null,
"createdAt": "2026-10-18T09:12:00.000Z"
}amount is the license’s price, then the order’s once it exists. Refusals:
| Status | code | When |
|---|---|---|
| 400 | validation_failed | A field is missing or out of bounds; details says which. |
| 404 | product_not_found | Unknown product, of another store, or not published. |
| 422 | checkout_product_not_license | The product is not a license. |
| 422 | checkout_license_stock_unsupported | The license is in key stock mode. |
| 422 | product_type_unavailable | Licenses are not open for now. |
One session per click
Kivoo does not deduplicate sessions: two calls give two sessions, and both may be paid. Create the session when the user clicks, and redirect them at once.
The payment page
The url opens a payment page of its own, with your store’s name and colours, without catalogue or cart:
- the amount to pay, the license’s price;
- the user’s details with “Modifier” (edit) if you gave them, otherwise the fields to fill in;
- the country, the one you gave in
countryif you did, and the Mobile Money methods of that country. The user may pick another country: the page then keeps their choice, even if they reload it; - a “Retour” (back) link to your
returnUrl, should the user give up.
A session takes one payment only and stays open 24 hours. A refused payment is retried on the same page. A paid session shows “Paiement reçu” (payment received); an expired one invites the user to go back to your app to create a new one.
Back to your app
Once the payment is received, the page shows “Paiement reçu”, then sends the user back to your returnUrl after three seconds, with the session’s id:
https://app.example.com/billing/return?checkoutId=7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0dThe “Retour” link leads to the same address. This return proves nothing: anyone can type that address. To know where the session stands, read it:
curl https://api.kivoo.africa/v1/checkouts/7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d \
-H "Authorization: Bearer $KIVOO_API_KEY"status is open, paid or expired. A paid session holds its order (order) and its key (licenseKey.id). A refunded session stays paid: the order tells the refund.
Activate the account
Subscribe a webhook to license_key.issued. It is the one that carries the expiry date, and the session that sold it:
{
"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" }
}
}
}- Find your user by
data.checkout.externalReference, and open access untildata.expiresAt. - The same event may arrive more than once: keep the event’s
id, and skip what you already handled (see Retries and journal). order.paidcarriescheckouttoo: use it for your accounting, but it does not give the expiry date.
The user gets a receipt e-mail from Kivoo, without any key: they have nothing to enter.
Renew
Offer the renewal before the end, with a new session for the same license and the same externalReference. The new period adds up to what is left: a user paid until 17 November who renews on the 14th is paid until 17 December. The new key’s license_key.issued webhook already carries that date.
- Kivoo sends no expiry e-mail for a license sold through a session: reminding your user is up to you, in your app or with your e-mails.
license_key.expiringgoes out seven days or less before the end, daily at 06:00 UTC;license_key.expiredwithin the hour after the end. Neither goes out for a key that has already been renewed.- Changing plan (from “Basic” to “Pro”) is buying another license: the new key runs from the payment, with no proration. What becomes of the old plan is up to your app.
To decide on access, compare today’s date yourself with the latest expiresAt of the user’s active keys. The webhooks tell you, your database decides.
Resynchronise
If your server missed webhooks, ask for the user’s keys:
curl "https://api.kivoo.africa/v1/license-keys?externalReference=42&status=active" \
-H "Authorization: Bearer $KIVOO_API_KEY"Refunds
A refund is requested from the dashboard by the store’s owner, for an order of at least 1,000 FCFA paid less than two days ago, and Kivoo validates it. When it goes through, you get order.refunded and license_key.revoked with reason: "refund": cut the access that key gave. The user’s other keys do not change.
Test your integration
Kivoo has no test mode: sessions and payments are real. Test with a cheap license, paid with your own Mobile Money number. The money lands in your store’s balance, minus Kivoo’s commission: that is all the test costs you.
returnUrlacceptshttp://localhost: you can come back to your app running locally.- A webhook, though, must be a public
https://address: expose your local server through a tunnel for the test. - Your webhook’s Envoyer un test (send a test) button checks that your server answers and that the signature is right, before the first payment.