Overview
Bill your customers on a recurring schedule through mobile money, with WhatsApp and email reminders, from the API.
The Subscriptions module replaces direct debit, which does not exist in mobile money: each due date becomes an invoice, sent to the customer on WhatsApp or by email, followed up with reminders until it is paid, and payable in one click through a mobile money payment request. Genuka Pay suspends and then ends unpaid subscriptions, and notifies you by webhook at every step.
To understand how it works and the steps of an integration, start with the subscriptions guide.
Catalog
Products and prices: amount, billing interval, trial, grace period.
Customers
Subscribers, reminder contacts, current access.
Subscriptions
Creation, statuses, cancellation, sandbox testing.
Invoices
Mobile money or cash payment, reminders, due date extensions.
Links and portal
Self-service sign-up, hosted customer portal.
Settings and import
Business identity on invoices, metrics, CSV import.
Webhooks
Customer, subscription, and invoice events.
Authentication
Subscription routes use the same keys and the same HMAC signature as the Payments API. See Authentication.
X-Public-Key: YOUR_PUBLIC_KEY
X-Timestamp: UNIX_TIMESTAMP
X-Signature: HMAC_SHA256_SIGNATUREOn lists, the signed string contains the path with its query string, exactly as sent: /api/v1/subscriptions?filter[status]=active&per_page=50.
Sandbox and live
The key determines the environment: a sandbox key reads and writes sandbox data, a live key reads and writes live data. Neither environment can see the other: an ID from the other environment returns 404.
- Sandbox: always available, free. Messages to customers are simulated (no real WhatsApp message or email is sent), payments follow the test numbers, and you can advance time to watch a subscription go through its stages.
- Live: always available. Without the paid add-on (Starter plan), your account is on the Free plan: at most 50 live subscriptions not yet cancelled or completed, a monthly quota of WhatsApp and SMS messages (100 by default; reminders then go out by email, one-time codes are never held back), no recording of cash payments, and higher fees on each subscriber payment. The limits and your usage show in the dashboard, on the Subscriptions add-on page, and through
GET /billing/addon. When a limit refuses a request, the response is402with acode:free_plan_subscription_limitonPOST /subscriptions(and as a row error of the CSV import): the maximum number of active subscriptions is reached;free_plan_manual_paymentsonPOST /invoices/{invoice}/manual-payments: the Free plan does not record cash payments.
Your company profile must also be complete, in sandbox and live alike. Otherwise: 403 COMPANY_PROFILE_INCOMPLETE.
Idempotency
Every POST route accepts the Idempotency-Key header. Retrying a request with the same key creates nothing new: you get the first response back, with the Idempotent-Replayed: true header.
Idempotency-Key: sub-acct-42-gym- The key is scoped to your application (sandbox and live are separate) and kept for 24 hours. 255 characters at most.
- Reusing a key with a different request (another path or another body) is rejected:
422idempotency_key_reused. - Two concurrent requests with the same key: the second one gets
409idempotency_request_in_progress. - Every response is replayed, validation errors included. After a
422, fix the request and use a new key.5xx,409, and429responses are not stored: retry with the same key.
Idempotency does not apply to PATCH and DELETE routes.
Formats
- IDs: 26-character lowercase strings, for example
01k79z2a4b6c8d0e2f4g6h8j0k. - Amounts: integers in the minor unit. XAF and XOF have no decimals:
15000means 15,000 FCFA. Only these two currencies are accepted. - Dates: ISO 8601 in UTC, for example
2026-10-09T23:00:00.000000Z. - Days: everything counted in days (due dates, trial, grace period, reminders) follows your business's time zone,
Africa/Doualaby default, configurable in the settings. A period starts at midnight local time: midnight in Douala is written23:00:00Zon the previous day. Dates you send inYYYY-MM-DDformat are read in that time zone. - Language: error messages follow the
Accept-Languageheader (froren). Validation messages are translated; most business error messages stay in English.
Pagination, filters and sorting
Lists are paginated:
GET /api/v1/subscriptions?filter[status]=past_due,suspended&sort=-created_at&per_page=50&page=2| Parameter | Description |
|---|---|
| page | Page number, starting at 1 |
| per_page | Items per page, from 1 to 100. 15 by default. |
| filter[field] | Filter. Separate multiple values with commas. |
| sort | Sort field, prefix with - for descending order |
| include | Related objects to include, on some routes |
{
"data": [ { "id": "01k79z2a4b6c8d0e2f4g6h8j0k", "object": "subscription" } ],
"links": { "first": "...&page=1", "last": "...&page=2", "prev": "...&page=1", "next": null },
"meta": { "current_page": 2, "from": 51, "last_page": 2, "per_page": 50, "to": 63, "total": 63 }
}A filter, sort, or include that the route does not support returns 400.
Errors
Base your logic on the HTTP status code, then on code when it is present, then on errors for a 422. Do not rely on message, which can change.
| Shape | Example |
|---|---|
| Validation | 422 {"message": "...", "errors": {"price_id": ["..."]}} |
| Business error | 422 {"message": "Only an open invoice can be changed; this one is paid.", "code": "invoice_not_open"} |
| Resource not found | 404 {"message": "Subscription not found."} |
| HTTP status | code | Cause |
|---|---|---|
400 | Filter, sort, or include not allowed | |
401 | Missing headers or invalid signature, timestamp more than 5 minutes off, inactive application | |
402 | free_plan_subscription_limit, free_plan_manual_payments | Free plan limit reached (live, without the paid add-on) |
403 | COMPANY_PROFILE_INCOMPLETE | Incomplete company profile (missing fields listed in missing_fields) |
404 | Object unknown, from another business, or from the other environment | |
409 | idempotency_request_in_progress | A request with the same Idempotency-Key is in progress |
422 | idempotency_key_reused, idempotency_key_invalid | Idempotency key reused or too long |
429 | Too many requests, with the Retry-After header |
Route-specific codes are listed on each route's page.
How is this guide?
Last updated on