Logo GenukaGenuka Pay
Guides

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:

  1. at each due date, Genuka Pay issues an invoice;
  2. it sends it to the customer on WhatsApp (or by email), with a button to pay;
  3. the customer pays in one click: a payment request arrives on their phone and they approve it;
  4. as long as they don't pay, Genuka Pay sends reminders, then suspends their subscription, then ends it;
  5. 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

ObjectRole
ProductWhat 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
SubscriptionA customer subscribed to a price, with its status and current period
InvoiceWhat 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.

POST /api/v1/customers
{
  "name": "Awa Ngono",
  "external_id": "user_4821",
  "contacts": [{ "channel": "whatsapp", "value": "+237690112233", "is_preferred": true }]
}

Create the subscription

POST /api/v1/subscriptions
{
  "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:

EventAction in your application
subscription.activated, subscription.renewed, subscription.reactivatedGrant access
subscription.past_dueKeep access, warn the user that their payment is late
subscription.suspended, subscription.cancelled, subscription.completedRevoke 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 incomplete and becomes active on the first payment. With a trial, it starts as trialing.
  • On each unpaid renewal: past_due the day after the due date, suspended at the end of the grace period, cancelled 30 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:

WhenMessage
J − 3Upcoming invoice (except for weekly prices)
J − 1Upcoming invoice
JInvoice due today
J + 1Invoice overdue
J + 3Invoice overdue
End of grace periodSubscription suspended
EndSubscription 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}/advance moves a subscription to its next step, with the real webhooks.

A complete scenario:

  1. create a customer and a monthly subscription with payment_phone: "+237670000001" and send_payment_request: true: the request succeeds, you receive invoice.paid then subscription.activated;
  2. call advance: the next month's invoice is issued (invoice.created);
  3. call advance twice: due date, then subscription.past_due;
  4. call advance: subscription.suspended, check that your application revokes access;
  5. pay the invoice with POST /invoices/{id}/payment-requests and the number +237670000001: subscription.reactivated.

Go live

  1. 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.
  2. Fill in your settings: legal name, address and legal identifier printed on invoices, support contact, logo.
  3. Create your catalog in live: sandbox products and prices are not copied.
  4. Create a live webhook endpoint and subscribe it to the same events.
  5. Replace your sandbox keys with your live keys.

How is this guide?

Last updated on