Subscriptions
Bill your customers every week, month, quarter or year, with WhatsApp reminders and one-click mobile money payments.
Mobile money does not support automatic debits: you cannot charge a customer every month without their approval. The Subscriptions module fills that gap:
- at each due date, Genuka Pay issues an invoice;
- it sends it to the customer on WhatsApp (or by email), with a button to pay;
- the customer pays in one click: a payment request arrives on their phone and they approve it;
- as long as they don't pay, Genuka Pay sends reminders, then suspends their subscription, then ends it;
- you are notified of every step by webhook, so you can grant or revoke access to your service.
It suits schools, gyms, software, associations, content or service subscriptions: anything paid at regular intervals.
The objects
| Object | Role |
|---|---|
| Product | What you sell: "Gym, unlimited access" |
Price (price) | One rate for the product: 15,000 XAF per month, with a 7-day trial and a 7-day grace period |
Customer (customer) | The person who pays, with their WhatsApp and email contacts |
| Subscription | A customer subscribed to a price, with its status and current period |
| Invoice | What the customer owes for a period |
Three ways to sell a subscription
- Subscription link, no coding required. Create a link in the dashboard, share it or display it as a QR code. The customer signs up on their own, confirms their WhatsApp number and pays their first month. See subscription links.
- From the dashboard. Add your subscribers by hand, or import a CSV file of your existing subscribers.
- Through the API. Create customers and subscriptions from your application, when your user picks an offer. That is what the rest of this guide covers.
You can combine all three: a subscriber who signed up through a link appears in the API like any other.
Integrate through the API
Create your catalog
Once and for all, create your products and their prices, from the dashboard or through the API. Note the price_id values: the dashboard shows them with a copy button.
Create the customer
When your user subscribes, create them as a customer with at least one WhatsApp contact. Pass your own identifier in external_id so you can find them again.
{
"name": "Awa Ngono",
"external_id": "user_4821",
"contacts": [{ "channel": "whatsapp", "value": "+237690112233", "is_preferred": true }]
}Create the subscription
{
"customer_id": "01k79z1e8s0t2v4w6x8y0z2a4b",
"price_id": "01k79y8m0n2p4q6r8s0t2v4w6x",
"payment_phone": "+237690112233",
"send_payment_request": true
}Without a trial, the first invoice is issued right away and, with send_payment_request, a payment request is sent to the customer's phone. They approve it and the subscription becomes active. You can also show them the invoice's payment_url, where they choose their operator or another number.
Send an Idempotency-Key with every POST: if the network drops, you can retry without creating a duplicate.
Grant access when webhooks arrive
Subscribe your endpoint to subscription events and keep your user's access up to date:
| Event | Action in your application |
|---|---|
subscription.activated, subscription.renewed, subscription.reactivated | Grant access |
subscription.past_due | Keep access, warn the user that their payment is late |
subscription.suspended, subscription.cancelled, subscription.completed | Revoke access |
The subscription object carries has_access and access_until: store them on every event. When in doubt, GET /customers/{id}/access returns the current state.
Add a "Manage my subscription" button
On click, create a portal session and redirect your user to its url. There they pay their invoices, change their number, manage their contacts and cancel if you allow it, without you having to build these screens.
The lifecycle
In the diagram below, J is the due date.
incomplete ── first payment ─────────────────► active
trialing ──── payment ───────────────────────► active
active ────── J+1 without payment ───────────► past_due (access kept)
past_due ──── end of grace period ───────────► suspended (access cut off)
suspended ─── J+30 without payment ──────────► cancelled
past_due, suspended ── payment ──────────────► active
active ────── last period of a fixed-term price ─► completed
incomplete ── 7 days without payment ────────► cancelled- A subscription without a trial starts as
incompleteand becomesactiveon the first payment. With a trial, it starts astrialing. - On each unpaid renewal:
past_duethe day after the due date,suspendedat the end of the grace period,cancelled30 days after the due date (or 7 days after suspension if the grace period is long). - A payment at any point before the end puts the subscription back to
active. - A cancellation takes effect at the end of the paid period, or immediately if you ask for it.
Statuses and timings are detailed in the subscriptions reference.
Reminders
For each invoice, the customer receives reminders at 9 a.m., your business's local time:
| When | Message |
|---|---|
| J − 3 | Upcoming invoice (except for weekly prices) |
| J − 1 | Upcoming invoice |
| J | Invoice due today |
| J + 1 | Invoice overdue |
| J + 3 | Invoice overdue |
| End of grace period | Subscription suspended |
| End | Subscription ended |
- Reminders stop as soon as the invoice is paid, and while a payment is in progress.
- A customer receives at most one reminder per day, and none between 9 p.m. and 8 a.m.
- On WhatsApp, messages have buttons: Pay (sends the payment request), Manage my subscription (opens the portal) and Stop (the customer no longer receives messages on this channel).
- An undelivered message is resent on the next channel: WhatsApp, then email.
- You can send a reminder for an invoice right away with
POST /invoices/{id}/remind, once per hour.
The customer also receives a welcome message with the link to the portal, a receipt for every payment, and a warning 3 days before a trial ends.
Reminders are sent from Genuka Pay's WhatsApp number, under your name. To use your own number, contact Genuka.
Payments
An invoice can be paid:
- by mobile money payment request, from the Pay button in the message, the portal, or the API;
- on the invoice page (
payment_url), where the customer chooses their operator or pays by card if you have enabled it; - in cash, which you record;
- with credit: an overpayment or a duplicate payment is kept as credit for the customer and applied automatically to their next invoices.
Mobile money payments follow the same fees, limits and settlements as your other collections.
A payment must settle the invoice: partial payments are not accepted.
Test in sandbox
In sandbox, everything works without the paid add-on and without real effects:
- messages to customers are simulated and marked as delivered; the code for a subscription link is shown on the page;
- the outcome of a payment depends on the number, see the test numbers;
POST /sandbox/subscriptions/{id}/advancemoves a subscription to its next step, with the real webhooks.
A complete scenario:
- create a customer and a monthly subscription with
payment_phone: "+237670000001"andsend_payment_request: true: the request succeeds, you receiveinvoice.paidthensubscription.activated; - call
advance: the next month's invoice is issued (invoice.created); - call
advancetwice: due date, thensubscription.past_due; - call
advance:subscription.suspended, check that your application revokes access; - pay the invoice with
POST /invoices/{id}/payment-requestsand the number+237670000001:subscription.reactivated.
Go live
- Choose your plan from the dashboard (Subscriptions → Subscriptions add-on). Without the paid add-on, your account is on the Free plan: up to 50 active subscriptions, a monthly quota of WhatsApp and SMS messages (100 by default), no recorded cash payments, higher fees. A reached limit responds with
402(free_plan_subscription_limit,free_plan_manual_payments); the Starter plan lifts them. - Fill in your settings: legal name, address and legal identifier printed on invoices, support contact, logo.
- Create your catalog in live: sandbox products and prices are not copied.
- Create a live webhook endpoint and subscribe it to the same events.
- Replace your sandbox keys with your live keys.
How is this guide?
Last updated on