Links and portal
Let your customers subscribe on their own through a link, and manage their subscription from a hosted customer portal.
Two pages hosted by Genuka Pay, with your branding, save you from building these screens yourself:
- the subscription link: a self-service sign-up page, to share or to display as a QR code;
- the customer portal: where a subscriber views and manages their subscriptions.
Endpoints
GET /api/v1/subscription-linksPOST /api/v1/subscription-linksPATCH /api/v1/subscription-links/{id}POST /api/v1/portal-sessions
Subscription links
The customer journey
- The customer opens the link (
url, or the shortershort_urlfor a QR code). They see your branding and the offer: product, amount, billing interval, trial. - They enter their name, their WhatsApp number, optionally their email and the beneficiary, and agree to receive payment reminders.
- They receive a 6-digit code on WhatsApp and enter it. In sandbox, no message is sent: the code is shown on the page.
- Genuka Pay creates the customer (or finds the one with that number), their verified WhatsApp contact, and the subscription. A mobile money payment request is sent to their number right away for the first invoice.
- Once they have paid, or right away if there is a trial, the customer is sent back to your
success_urlif you provided one.
If the customer is already subscribed to the same price for the same beneficiary, nothing is created again: they are shown the open invoice again.
You follow the journey through webhooks: customer.created, customer.contact_verified, subscription.created, invoice.created, then invoice.paid and subscription.activated. The subscription carries metadata.source: "signup_link" and metadata.subscription_link_id.
Create a link
POST /api/v1/subscription-links| Parameter | Type | Required | Description |
|---|---|---|---|
| price_id | string | Yes | Active price of an active product |
| name | string | No | Internal name, 120 characters max. For example "Front desk, QR code". |
| active | boolean | No | true by default |
| collect_beneficiary | boolean | No | Ask for the beneficiary's name, for example the student. false by default. |
| success_url | string | No | http or https page to send the customer back to after payment |
| expires_at | datetime | No | Expiry date, in the future. A date alone, YYYY-MM-DD, is valid until the end of that day, in your business's local time. |
| metadata | object | No | Free-form data |
curl -X POST "https://api-pay.genuka.com/api/v1/subscription-links" \
-H "X-Public-Key: YOUR_PUBLIC_KEY" \
-H "X-Timestamp: UNIX_TIMESTAMP" \
-H "X-Signature: HMAC_SHA256_SIGNATURE" \
-H "Content-Type: application/json" \
-d '{
"price_id": "01k6z9y8x7w6v5t4s3r2q1p0n9",
"name": "Front desk, QR code",
"collect_beneficiary": true,
"success_url": "https://olympe.example/thanks"
}'201 response:
{
"data": {
"id": "01k7b2c3d4e5f6g7h8j9k0m1n2",
"object": "subscription_link",
"name": "Front desk, QR code",
"url": "https://pay.genuka.com/billing/join/k3v9x2m7q8w4e5r6t1y2z3a4",
"short_code": "k7mpq2x",
"short_url": "https://pay.genuka.com/j/k7mpq2x",
"token": "k3v9x2m7q8w4e5r6t1y2z3a4",
"price_id": "01k6z9y8x7w6v5t4s3r2q1p0n9",
"price": { "id": "01k6z9y8x7w6v5t4s3r2q1p0n9", "object": "price", "amount": 15000, "currency": "XAF", "interval": "month" },
"product_name": "Gym, unlimited access",
"active": true,
"available": true,
"unavailable_reason": null,
"collect_beneficiary": true,
"signups_count": 0,
"success_url": "https://olympe.example/thanks",
"expires_at": null,
"metadata": null,
"created_at": "2026-10-10T09:00:00.000000Z",
"updated_at": "2026-10-10T09:00:00.000000Z"
}
}| Field | Description |
|---|---|
| url, short_url | Sign-up page. These addresses never change, even if you change the link's price: a printed QR code stays valid. Generate the QR code yourself from either of them. |
| available | The link accepts sign-ups right now |
| unavailable_reason | inactive (deactivated), expired (expired) or price_unavailable (price archived or product deactivated). null if the link is available. |
In live on the Free plan, once the active subscription limit is reached, the sign-up page stops accepting new subscribers. available does not reflect this limit: check your usage with GET /billing/addon.
| signups_count | Number of subscriptions created through this link |
Update and list links
PATCH /api/v1/subscription-links/{id}
GET /api/v1/subscription-linksPATCH accepts the same fields as creation. Only the fields you send change; null clears name, success_url, expires_at and metadata.
The list accepts filter[active], filter[price_id] and sort on created_at or signups_count (prefix with - for descending order, -created_at by default).
Links do not emit webhooks themselves; sign-ups do.
Customer portal
The portal lets a subscriber, without an account with you:
- view their subscriptions, their status and their next due date;
- pay an invoice by mobile money, download their invoices as PDF and see their credit;
- cancel, or withdraw a scheduled cancellation, if you allow it (
allow_portal_cancellationin the settings); - change the mobile money number of a subscription, confirmed with a code;
- manage their contacts: add new ones (confirmed with a code), choose the preferred one, unsubscribe from a channel.
The customer gets there through the "Manage my subscription" link in their messages, by signing in with a code sent to one of their contacts, or through a session you create from your application.
Open the portal from your application
POST /api/v1/portal-sessions| Parameter | Type | Required | Description |
|---|---|---|---|
| customer_id | string | Yes | Customer of the application |
| return_url | string | No | http or https page of your application. The portal shows a "Back" link to it. |
{
"data": {
"url": "https://pay.genuka.com/billing/portal/01k78a1b2c3d4e5f6g7h8j9k0m/sessions/Zq3...",
"expires_at": "2026-10-11T10:30:00.000000Z"
}
}Redirect your user to url right away:
- the link works only once, and only before
expires_at(30 minutes); - once opened, the session stays active as long as the customer uses it, and expires after 30 minutes of inactivity;
- a link that was already used or has expired leads to the portal's sign-in page.
So create a session each time the user clicks "Manage my subscription", never in advance. Limit: 60 sessions per minute. If you replay an Idempotency-Key, you get the same URL back, which may already have been used.
| HTTP code | Case |
|---|---|
404 | Unknown or deleted customer, or one from another application: {"message": "Customer not found."} |
422 | Missing customer_id, invalid return_url |
429 | More than 60 sessions per minute |
How is this guide?
Last updated on