Logo GenukaGenuka Pay
Référence APIAbonnements

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

Liens d'abonnement

Le parcours du client

  1. Le client ouvre le lien (url, ou short_url plus court pour un QR code). Il voit votre marque et l'offre : produit, montant, rythme, essai.
  2. Il saisit son nom, son numéro WhatsApp, éventuellement son email et le bénéficiaire, et accepte de recevoir les rappels de paiement.
  3. 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.
  4. 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.
  5. Une fois payé, ou tout de suite s'il y a un essai, le client est renvoyé vers votre success_url si 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ètreTypeRequisDescription
price_idstringOuiFormule active d'un produit actif
namestringNonNom interne, 120 caractères au plus. Par exemple « Accueil, QR code ».
activebooleanNontrue par défaut
collect_beneficiarybooleanNonDemander le nom du bénéficiaire, par exemple l'élève. false par défaut.
success_urlstringNonPage http ou https où renvoyer le client après le paiement
expires_atdatetimeNonDate d'expiration, dans le futur. Une date seule AAAA-MM-JJ vaut jusqu'à la fin de ce jour, heure de votre entreprise.
metadataobjectNonDonné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"
  }
}
ChampDescription
url, short_urlPage 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.
availableLe lien accepte des inscriptions maintenant
unavailable_reasoninactive (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-links

PATCH 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_cancellation dans 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ètreTypeRequisDescription
customer_idstringOuiClient de l'application
return_urlstringNonPage 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 HTTPCas
404Client inconnu, supprimé ou d'une autre application : {"message": "Customer not found."}
422customer_id manquant, return_url invalide
429Plus de 60 sessions par minute

How is this guide?

Last updated on