Liens et portail
Laissez vos clients s'abonner seuls par un lien, et gérer leur abonnement depuis un espace client hébergé.
Deux pages hébergées par Genuka Pay, à votre marque, évitent de construire ces écrans vous-même :
- le lien d'abonnement : une page d'inscription en libre-service, à partager ou à afficher en QR code ;
- le portail client : l'espace où un abonné consulte et gère ses abonnements.
Endpoints
GET /api/v1/subscription-linksPOST /api/v1/subscription-linksPATCH /api/v1/subscription-links/{id}POST /api/v1/portal-sessions
Liens d'abonnement
Le parcours du client
- Le client ouvre le lien (
url, oushort_urlplus court pour un QR code). Il voit votre marque et l'offre : produit, montant, rythme, essai. - Il saisit son nom, son numéro WhatsApp, éventuellement son email et le bénéficiaire, et accepte de recevoir les rappels de paiement.
- Il reçoit un code à 6 chiffres sur WhatsApp et le saisit. En sandbox, aucun message ne part : le code est affiché sur la page.
- Genuka Pay crée le client (ou retrouve celui qui a ce numéro), son contact WhatsApp vérifié, et l'abonnement. Une demande de paiement mobile money part aussitôt sur son numéro pour la première facture.
- Une fois payé, ou tout de suite s'il y a un essai, le client est renvoyé vers votre
success_urlsi vous en avez donné une.
Si le client est déjà abonné à la même formule pour le même bénéficiaire, rien n'est recréé : la facture ouverte lui est présentée à nouveau.
Vous suivez le parcours par webhooks : customer.created, customer.contact_verified, subscription.created, invoice.created, puis invoice.paid et subscription.activated. L'abonnement porte metadata.source: "signup_link" et metadata.subscription_link_id.
Créer un lien
POST /api/v1/subscription-links| Paramètre | Type | Requis | Description |
|---|---|---|---|
| price_id | string | Oui | Formule active d'un produit actif |
| name | string | Non | Nom interne, 120 caractères au plus. Par exemple « Accueil, QR code ». |
| active | boolean | Non | true par défaut |
| collect_beneficiary | boolean | Non | Demander le nom du bénéficiaire, par exemple l'élève. false par défaut. |
| success_url | string | Non | Page http ou https où renvoyer le client après le paiement |
| expires_at | datetime | Non | Date d'expiration, dans le futur. Une date seule AAAA-MM-JJ vaut jusqu'à la fin de ce jour, heure de votre entreprise. |
| metadata | object | Non | Données libres |
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": "Accueil, QR code",
"collect_beneficiary": true,
"success_url": "https://olympe.example/merci"
}'Réponse 201 :
{
"data": {
"id": "01k7b2c3d4e5f6g7h8j9k0m1n2",
"object": "subscription_link",
"name": "Accueil, 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": "Salle de sport, accès illimité",
"active": true,
"available": true,
"unavailable_reason": null,
"collect_beneficiary": true,
"signups_count": 0,
"success_url": "https://olympe.example/merci",
"expires_at": null,
"metadata": null,
"created_at": "2026-10-10T09:00:00.000000Z",
"updated_at": "2026-10-10T09:00:00.000000Z"
}
}| Champ | Description |
|---|---|
| url, short_url | Page d'inscription. Ces adresses ne changent jamais, même si vous changez la formule du lien : un QR code imprimé reste valable. Générez le QR code vous-même à partir de l'une d'elles. |
| available | Le lien accepte des inscriptions maintenant |
| unavailable_reason | inactive (désactivé), expired (expiré) ou price_unavailable (formule archivée ou produit désactivé). null si le lien est disponible. |
En live sur l'offre Gratuite, une fois la limite d'abonnements actifs atteinte, la page d'inscription n'accepte plus de nouveaux abonnés. available ne tient pas compte de cette limite : suivez votre consommation avec GET /billing/addon.
| signups_count | Nombre d'abonnements créés par ce lien |
Modifier et lister les liens
PATCH /api/v1/subscription-links/{id}
GET /api/v1/subscription-linksPATCH accepte les mêmes champs que la création. Seuls les champs envoyés changent, null efface name, success_url, expires_at et metadata.
La liste accepte filter[active], filter[price_id] et sort sur created_at ou signups_count (préfixe - pour l'ordre décroissant, -created_at par défaut).
Les liens n'émettent pas de webhook eux-mêmes ; les inscriptions, si.
Portail client
Le portail permet à un abonné, sans compte chez vous :
- de voir ses abonnements, leur statut et leur prochaine échéance ;
- de payer une facture par mobile money, de télécharger ses factures en PDF et de voir son crédit ;
- de résilier ou d'annuler une résiliation programmée, si vous l'autorisez (
allow_portal_cancellationdans les réglages) ; - de changer le numéro mobile money d'un abonnement, confirmé par un code ;
- de gérer ses contacts : en ajouter (confirmés par un code), choisir le préféré, se désabonner d'un canal.
Le client y accède par le lien « Gérer mon abonnement » de ses messages, en se connectant avec un code envoyé à l'un de ses contacts, ou par une session que vous créez depuis votre application.
Ouvrir le portail depuis votre application
POST /api/v1/portal-sessions| Paramètre | Type | Requis | Description |
|---|---|---|---|
| customer_id | string | Oui | Client de l'application |
| return_url | string | Non | Page http ou https de votre application. Le portail affiche un lien « Retour » vers elle. |
{
"data": {
"url": "https://pay.genuka.com/billing/portal/01k78a1b2c3d4e5f6g7h8j9k0m/sessions/Zq3...",
"expires_at": "2026-10-11T10:30:00.000000Z"
}
}Redirigez votre utilisateur vers url tout de suite :
- le lien ne fonctionne qu'une fois, et seulement avant
expires_at(30 minutes) ; - une fois ouvert, la session reste active tant que le client s'en sert, et expire après 30 minutes d'inactivité ;
- un lien déjà utilisé ou expiré mène à la page de connexion du portail.
Créez donc une session à chaque clic sur « Gérer mon abonnement », jamais à l'avance. Limite : 60 sessions par minute. Avec une Idempotency-Key rejouée, vous recevez la même URL, peut-être déjà utilisée.
| Code HTTP | Cas |
|---|---|
404 | Client inconnu, supprimé ou d'une autre application : {"message": "Customer not found."} |
422 | customer_id manquant, return_url invalide |
429 | Plus de 60 sessions par minute |
How is this guide?
Last updated on