Guides

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

  1. You create a license reserved for the app, for example “Plan Pro — 30 jours”.
  2. When user 42 clicks “Upgrade to Pro”, your server creates a checkout session with externalReference: "42".
  3. You redirect the user to the session’s url.
  4. They pay, then Kivoo sends them back to your returnUrl, with ?checkoutId=….
  5. Your server receives the license_key.issued webhook, with externalReference: "42" and expiresAt, 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/products returns it with license.appOnly: true and 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:

Terminal
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"
  }'
FieldRequiredContent
productIdyesThe license sold.
externalReferenceyesThe user’s identifier in your system, 255 characters at most. Kivoo gives it back everywhere. Prefer an opaque id to an email address.
returnUrlyesWhere Kivoo sends the user back, in https://. http://localhost and http://127.0.0.1 are accepted for development.
metadatanoA 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.
customernoemail and lastName (required inside the object), firstName. When you give them, the page opens straight on the payment.
countrynoThe 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:

201 Created
{
  "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:

StatuscodeWhen
400validation_failedA field is missing or out of bounds; details says which.
404product_not_foundUnknown product, of another store, or not published.
422checkout_product_not_licenseThe product is not a license.
422checkout_license_stock_unsupportedThe license is in key stock mode.
422product_type_unavailableLicenses 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 country if 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-5e6f7a8b9c0d

The “Retour” link leads to the same address. This return proves nothing: anyone can type that address. To know where the session stands, read it:

Terminal
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:

license_key.issued
{
  "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 until data.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.paid carries checkout too: 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.expiring goes out seven days or less before the end, daily at 06:00 UTC; license_key.expired within 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:

Terminal
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.

  • returnUrl accepts http://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.

On this page