Logo GenukaGenuka Pay
API ReferenceSubscriptions

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-links
  • POST /api/v1/subscription-links
  • PATCH /api/v1/subscription-links/{id}
  • POST /api/v1/portal-sessions

The customer journey

  1. The customer opens the link (url, or the shorter short_url for a QR code). They see your branding and the offer: product, amount, billing interval, trial.
  2. They enter their name, their WhatsApp number, optionally their email and the beneficiary, and agree to receive payment reminders.
  3. They receive a 6-digit code on WhatsApp and enter it. In sandbox, no message is sent: the code is shown on the page.
  4. 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.
  5. Once they have paid, or right away if there is a trial, the customer is sent back to your success_url if 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.

POST /api/v1/subscription-links
ParameterTypeRequiredDescription
price_idstringYesActive price of an active product
namestringNoInternal name, 120 characters max. For example "Front desk, QR code".
activebooleanNotrue by default
collect_beneficiarybooleanNoAsk for the beneficiary's name, for example the student. false by default.
success_urlstringNohttp or https page to send the customer back to after payment
expires_atdatetimeNoExpiry date, in the future. A date alone, YYYY-MM-DD, is valid until the end of that day, in your business's local time.
metadataobjectNoFree-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"
  }
}
FieldDescription
url, short_urlSign-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.
availableThe link accepts sign-ups right now
unavailable_reasoninactive (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 |

PATCH /api/v1/subscription-links/{id}
GET /api/v1/subscription-links

PATCH 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_cancellation in 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
ParameterTypeRequiredDescription
customer_idstringYesCustomer of the application
return_urlstringNohttp 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 codeCase
404Unknown or deleted customer, or one from another application: {"message": "Customer not found."}
422Missing customer_id, invalid return_url
429More than 60 sessions per minute

How is this guide?

Last updated on