Skip to content
ABUNA
DocumentationSessions

Référence de l'API

Sessions

Envoyez un client vers une page hébergée pour s'abonner, payer une facture, changer de formule, résilier ou ouvrir son espace client. Puis listez, lisez et expirez ces sessions.

Voir en Markdown

Les sessions permettent à un client de s'abonner, de payer une facture, de changer de formule, de résilier ou de gérer son abonnement, sur une page hébergée par Abuna. Vous envoyez le client vers l'url de la session. Abuna indique à votre serveur comment elle s'est terminée avec un événement session.completed ou session.expired. Le guide Sessions décrit tout le déroulement.

Vous créez chaque session avec POST /v1/apps/{appID}/sessions. Le type du corps indique ce que fait le client et quels autres champs le corps accepte  :

  • checkout  : une page d'abonnement qui vend un prix. Envoyez price_id.
  • payment  : une page de paiement pour une facture ouverte. Envoyez invoice_id.
  • plan_change  : le client confirme le passage à un autre prix. Envoyez subscription_id et price_id.
  • cancel  : le client confirme la résiliation. Envoyez subscription_id.
  • portal  : l'espace client avec un lien de retour vers votre application. Envoyez subscription_id et return_url.

Chaque type renvoie le même objet session. Vous listez, récupérez et expirez les sessions de tout type avec les mêmes endpoints. Un type qu'Abuna ne connaît pas renvoie 422 avec le code invalid et un élément errors pour type.

Ces endpoints n'acceptent qu'une clé secrète. Une clé publiable ou une connexion au tableau de bord reçoit 403 avec le code forbidden. Un champ du corps que le type de la session n'accepte pas renvoie 400 avec le code invalid_json.

L'objet session

Attributs

  • idstring

    Identifiant unique de la session.
  • typestring

    Ce à quoi sert la session  : checkout, payment, plan_change, cancel ou portal, tel que vous l'avez envoyé à la création.
  • statusstring

    open jusqu'à sa fin. completed dès que le client termine, selon la définition de chaque type, ou expired lorsqu'elle expire ou que vous l'expirez. Une session terminée ne change plus jamais.
  • urlstring

    La page vers laquelle envoyer le client. Elle appartient à ce client, ne la partagez pas.
  • success_urlstringnullable

    Où va le client après avoir terminé, tel que vous l'avez envoyé, ou l'URL de retour après paiement de votre application si vous n'en avez pas envoyé. Les jetons comme {SESSION_ID} apparaissent tels quels. Null quand ni l'un ni l'autre n'est défini, et toujours null pour portal. Voir Jetons de l'URL de retour après paiement.
  • cancel_urlstringnullable

    Où va le client s'il part avant de payer, ou si la session expire. L'URL d'annulation de votre application si vous n'en avez pas envoyé. Null quand ni l'une ni l'autre n'est définie, et toujours null pour portal.
  • return_urlstringnullable

    Pour portal, où mène le lien « Retour » de l'espace client. Null pour les autres types.
  • metadataobject

    Vos propres clés et valeurs, telles que vous les avez envoyées. {} quand vous n'en avez pas envoyé.
  • customer_idstringnullable

    Le client que vous avez transmis, ou celui créé par les coordonnées du client. Pour les autres types, le client de l'abonnement. Null tant qu'il est inconnu.
  • price_idstringnullable

    Pour checkout, le prix que vend la session. Pour plan_change, le nouveau prix. Null pour les autres types.
  • subscription_idstringnullable

    Pour checkout, l'abonnement que la session a démarré, défini dès que le client envoie ses coordonnées, ou l'abonnement existant du client quand la page d'abonnement l'y ramène (voir Clients qui reviennent). Pour les autres types, l'abonnement sur lequel agit la session. Null tant qu'il est inconnu.
  • invoice_idstringnullable

    Pour payment, la facture que paie le client. Null pour les autres types.
  • plan_offer_idstringnullable

    Pour plan_change, l'proposition de changement de formule créée par la session. Pour checkout, l'proposition de changement de formule faite quand la page d'abonnement propose à un client qui revient de changer de formule, ou null. Null pour les autres types.
  • at_period_endbooleannullable

    Pour cancel, si la résiliation attend la fin de la période payée (true) ou met fin à l'abonnement immédiatement (false). Défini à la création de la session, d'après votre requête ou le customer_cancel de l'application. Null pour les autres types.
  • updates_channelstringnullable

    Pour checkout, la messagerie que la page d'abonnement propose en premier pour les rappels de paiement une fois que le client a payé, telle qu'elle s'applique maintenant : ask, telegram, whatsapp ou email. Un canal que votre application ne propose pas s'affiche ask. Voir Créer une session checkout. Null pour les autres types.
  • upgrade_timingstringnullable

    Pour checkout, quand le changement de formule d'un client qui revient vers un prix supérieur prend effet : now ou next_renewal, tel que vous l'avez envoyé, ou now par défaut. Null pour les autres types.
  • expires_attimestamp

    Quand la session expire, en secondes Unix. 24 heures après sa création pour checkout, payment et cancel. 7 jours, ou la fin de la période en cours si elle arrive avant, pour plan_change. 1 heure pour portal, qui doit être ouvert avant. Une session checkout qui a proposé un changement de formule prend la fin de la proposition à la place.
  • trial_daysintegernullable

    Pour checkout, la durée demandée : 1 à 365 jours, ou 0 pour désactiver l'essai. Null utilise la durée du prix. Null pour les autres types. Le droit à l'essai est vérifié au démarrage de l'abonnement.
  • allow_promotion_codesbooleannullable

    Pour checkout, la valeur que vous avez envoyée : true affiche toujours le champ de code promotionnel, false le masque, et null l'affiche tant qu'un code est utilisable sur le prix. false aussi quand vous avez envoyé discounts. Null pour les autres types.
  • discountobjectnullable

    Pour checkout, la réduction de la session : coupon, le coupon, et promotion_code, l'ID du code qui l'a apporté, ou null. C'est celle envoyée dans discounts, ou le code appliqué par le client. Null sans réduction, et pour les autres types.
  • amount_subtotalintegernullable

    Pour checkout, le montant du prix avant réduction, dans la plus petite unité de la devise. Null pour les autres types.
  • amount_discountintegernullable

    Pour checkout, ce que la réduction retire du premier paiement. 0 sans réduction, ou quand la réduction ne peut plus être utilisée ; la page d'abonnement la refuse alors. Null pour les autres types.
  • amount_totalintegernullable

    Pour checkout, le coût du premier paiement : amount_subtotal moins amount_discount. Avec un essai, le client le paie à la fin de l'essai. Null pour les autres types.
  • completed_attimestampnullable

    Quand la session s'est terminée.
  • created_attimestamp

    Quand la session a été créée, en secondes Unix.
L'objet session
{
  "id": "A4kN1oSs",
  "type": "checkout",
  "status": "open",
  "url": "https://app.abuna.app/checkout/7f2c9e4a1b8d3f6e0c5a9d2b7e4f1a8c3d6b",
  "success_url": "https://example.com/welcome",
  "cancel_url": "https://example.com/pricing",
  "return_url": null,
  "metadata": {
    "user_id": "42"
  },
  "customer_id": null,
  "price_id": "Zt6YbN3q",
  "subscription_id": null,
  "invoice_id": null,
  "plan_offer_id": null,
  "at_period_end": null,
  "updates_channel": "telegram",
  "upgrade_timing": "next_renewal",
  "trial_days": null,
  "allow_promotion_codes": null,
  "discount": null,
  "amount_subtotal": 5000,
  "amount_discount": 0,
  "amount_total": 5000,
  "expires_at": 1727686400,
  "completed_at": null,
  "created_at": 1727600000
}

Créer une session checkout

POST/v1/apps/{appID}/sessions

Accepte un en-tête Idempotency-Key.

Crée une session checkout  : une page d'abonnement qui vend un prix à un nouvel abonné. Envoyez le client vers son url. Pour démarrer un abonnement sans page d'abonnement, utilisez Créer un abonnement.

Paramètres du corps

  • typestringobligatoire

    checkout.
  • price_idstringobligatoire

    Le prix à vendre. Il ne doit pas être archivé.
  • trial_daysinteger

    Remplace la durée du prix par 1 à 365 jours. Envoyez 0 pour ne pas proposer d'essai. Omettez ce champ pour utiliser la durée du prix. Un seul essai par client, produit et application ; ensuite, la facturation habituelle s'applique sans erreur. Voir Essais gratuits.
  • allow_promotion_codesboolean

    Si la page affiche un champ où le client tape un code promotionnel. Omettez-le pour afficher le champ tant que votre application a un code utilisable sur ce prix. Envoyez false pour le masquer, ou true pour toujours l'afficher. N'envoyez pas true avec discounts. Voir Organiser une vente avec des codes promotionnels.
  • discountsarray

    Une réduction à appliquer avant l'arrivée du client : une entrée avec coupon ou promotion_code, par identifiant, pas les deux. La page n'a alors pas de champ de code. Ne l'envoyez pas avec allow_promotion_codes: true. Une réduction inutilisable renvoie 422 avec le code coupon_invalid pour discounts.
  • customer_idstring

    Un client existant à facturer. La page d'abonnement affiche ses coordonnées en lecture seule. Ne l'envoyez pas avec customer.
  • customerobject

    Coordonnées à préremplir pour un nouveau client. La page d'abonnement affiche en lecture seule l'e-mail et le nom que vous envoyez, et le client remplit le reste. Ne l'envoyez pas avec customer_id.
    Afficher les paramètresMasquer les paramètres
    • emailstring

      Son adresse e-mail. Elle doit contenir @.
    • namestring

      Son nom.
    • phone_numberstring

      Son numéro de téléphone avec son indicatif pays, comme +237671234567. Facultatif. L'étape de paiement envoie la demande de paiement à ce numéro, et le client peut y choisir un autre numéro. Sans lui, l'étape de paiement demande le numéro.
  • success_urlstring

    Où envoyer le client une fois la session terminée. Abuna remplit ses jetons, ou ajoute les identifiants en paramètres de requête si elle n'en a aucun. Par défaut, l'URL de retour après paiement de votre application.
  • cancel_urlstring

    Où envoyer le client s'il part avant de payer. Par défaut, l'URL d'annulation de votre application.
  • metadataobject

    Vos propres clés et valeurs, renvoyées dans les événements de la session. L'abonnement que démarre la session les reçoit aussi. Jusqu'à 20 clés. Chaque clé fait de 1 à 40 caractères, et chaque valeur est une chaîne de 500 caractères maximum.
  • updates_channelstring

    La messagerie que la page d'abonnement propose en premier pour les rappels de paiement, une fois que le client a payé. L'e-mail part toujours. L'une des quatre valeurs ci-dessous. Par défaut, ask.
  • upgrade_timingstring

    Quand le changement de formule d'un client qui revient vers un prix supérieur du même produit prend effet. now, la valeur par défaut : il paie la différence maintenant et change de formule une fois le paiement fait. next_renewal : rien n'est débité maintenant, et il change de formule à son prochain renouvellement.

updates_channel

Quand votre application propose une messagerie, l'étape de paiement demande au client de connecter WhatsApp ou Telegram, et il ne peut payer qu'une fois l'une activée. Un essai gratuit demande après son début, sur son écran de fin, où l'e-mail seul est aussi proposé. L'e-mail part dans tous les cas. updates_channel définit la messagerie affichée en premier :

  • ask : les messageries de votre application dans l'ordre habituel : WhatsApp s'il est activé, puis Telegram. C'est la valeur par défaut.
  • telegram : Telegram s'affiche en premier.
  • whatsapp : WhatsApp s'affiche en premier.
  • email : e-mail seul. La page d'abonnement ne propose aucune messagerie et n'en demande pas.

Avec toute valeur sauf email, le client connecte une des messageries proposées par l'étape de paiement. Plus tard, il peut activer ou désactiver WhatsApp ou Telegram dans son espace client. Un client qui a déjà connecté une messagerie la garde, tout comme un client qui s'abonne avec des informations enregistrées qui en comprennent une : rien ne lui est redemandé. L'étape de paiement indique où vont ses rappels et lui permet de changer.

Si vous envoyez un canal que votre application ne propose pas, parce qu'elle est désactivée dans ses paramètres ou, pour WhatsApp, absent du forfait de votre équipe, la page d'abonnement s'ouvre quand même et fonctionne comme ask. Si votre application ne propose aucune messagerie, la page d'abonnement n'en propose aucune et le client paie avec des rappels par e-mail. Le updates_channel de la session indique ce qui s'applique maintenant.

Un client qui choisit WhatsApp confirme son numéro WhatsApp avec un code à 6 chiffres reçu sur WhatsApp. WhatsApp n'est pas activé tant qu'il ne l'a pas confirmé. Voir WhatsApp.

Un client qui choisit Telegram l'ouvre depuis l'étape de paiement, appuie sur Démarrer, puis paie. Une fois le paiement fait, il poursuit vers votre success_url. Certains ferment l'onglet avant d'y arriver, donc n'accordez pas l'accès depuis la page de retour. Utilisez plutôt les webhooks.

Clients qui reviennent

Un client peut revenir sur une page d'abonnement avec l'e-mail avec lequel il est déjà abonné dans votre application. Abuna reconnaît l'e-mail, sans tenir compte des majuscules ni des espaces autour. Le numéro de téléphone n'identifie jamais un client, car beaucoup paient depuis le numéro de quelqu'un d'autre. Le même numéro avec un autre e-mail est un nouveau client, et une session sans e-mail n'est jamais reconnue. Avec customer_id, c'est l'e-mail de ce client qui est comparé. Les liens d'abonnement fonctionnent de la même façon. Ce qui se passe dépend des abonnements du client au même produit qui n'ont pas pris fin :

  • Même prix, premier paiement pas encore fait : la page le ramène à ce paiement. Aucun abonnement, client ou facture n'est créé. Le subscription_id de la session est cet abonnement, et la session se termine quand il est payé, comme d'habitude. Cette page sert uniquement à payer. Elle n'affiche jamais les détails de l'abonnement, les factures ni les liens de gestion, même après le paiement. Abuna envoie au client son lien d'abonnement avec le reçu par e-mail.
  • Même prix, active ou past_due : la page d'abonnement est refusée avec 409 already_subscribed. La page lui indique qu'il est déjà abonné et lui propose de recevoir par e-mail les liens de son abonnement. Rien n'est créé ni débité, et la session reste ouverte.
  • Un autre prix du même produit, active ou past_due, dans la même devise : rien ne change sur la page d'abonnement. Abuna envoie au client par e-mail un lien pour passer cet abonnement au nouveau prix, et la page l'invite à consulter ses e-mails. Aucun deuxième abonnement n'est créé. Voir Changer de formule depuis la page d'abonnement.
  • Un autre prix du même produit, premier paiement pas encore fait : un nouvel abonnement démarre, comme d'habitude. L'abonnement impayé reste tel quel : le client peut encore le payer, et s'il ne le fait pas, il prend fin comme tout premier paiement jamais fait, avec subscription.canceled et la raison checkout_expired.
  • Un autre produit, ou un abonnement résilié ou terminé : un nouvel abonnement, comme d'habitude.

La création d'un abonnement avec POST /subscriptions n'est pas concernée.

Changer de formule depuis la page d'abonnement

N'importe qui peut saisir un e-mail sur une page d'abonnement : la page ne change donc jamais un abonnement à elle seule. Abuna envoie au client par e-mail un lien vers le changement, et la page l'invite à consulter ses e-mails. Elle dit la même chose que l'e-mail ait un abonnement ou non, et n'affiche aucun identifiant. Le lien est valable jusqu'à 7 jours, et jamais au-delà de la fin de la période payée en cours. Il ouvre une page avec la formule actuelle, la nouvelle, et ce que le changement coûte maintenant. Rien ne change tant que le client n'y a pas confirmé. Une demande plus récente remplace la proposition en attente, et seul le lien du dernier e-mail permet de la confirmer. Le même changement demandé à nouveau dans les 5 minutes conserve son lien et n'envoie pas de second e-mail. En mode Test, aucun e-mail n'est envoyé : l'e-mail, avec son lien, est enregistré comme événement notification.captured, dans la rubrique Événements du tableau de bord.

Le changement suit les règles de changement de formule :

  • Rétrogradation, vers un prix qui coûte autant ou moins : rien n'est débité maintenant. Le client garde la formule actuelle jusqu'à la fin de la période payée, puis renouvelle au nouveau prix.
  • Mise à niveau, avec upgrade_timing now, la valeur par défaut : le client paie maintenant le nouveau prix moins le temps non utilisé de la période en cours, et le changement s'applique une fois ce paiement réussi. S'il n'y a rien à payer, il s'applique à la confirmation.
  • Mise à niveau, avec upgrade_timing next_renewal : rien n'est débité maintenant. Le client garde la formule actuelle jusqu'à la fin de la période payée, puis renouvelle au nouveau prix.

Les liens d'abonnement utilisent toujours now. Abuna envoie plan_offer.created quand le changement est envoyé par e-mail, même si le client ne confirme jamais, et plan_offer.confirmed quand il confirme. subscription.updated suit, avec le changement downgrade_scheduled ou upgrade_scheduled pour un changement qui attend le renouvellement, puis price_changed quand le nouveau prix s'applique. Une mise à niveau avec quelque chose à payer envoie invoice.created et invoice.paid.

Le subscription_id de la session est l'abonnement existant, et son plan_offer_id est défini dès que le changement est envoyé par e-mail. Elle se termine quand le client confirme une rétrogradation, une mise à niveau au prochain renouvellement ou une mise à niveau sans rien à payer, ou quand il paie une mise à niveau. Ses données session.completed ont alors les champs du changement. Le client poursuit vers votre URL de retour après paiement comme d'habitude, avec l'identifiant de la session et celui de l'abonnement existant.

Dès qu'elle envoie un changement par e-mail, la session reste ouverte tant que la proposition l'est, au lieu de 24 heures : jusqu'à 7 jours après la proposition, et jamais au-delà de la fin de la période payée en cours. Son expires_at passe à la fin de la proposition. Elle expire aussi quand la proposition est remplacée ou retirée, ou quand une mise à niveau qu'elle a démarrée reste impayée et échoue. Une mise à niveau confirmée mais pas encore payée la garde ouverte jusqu'à son paiement ou son échec. Abuna envoie alors session.expired.

Renvoie la session avec le statut 201. Elle peut aussi renvoyer  :

  • 422 avec le code invalid quand un champ échoue. Chaque élément errors nomme le champ  : pas de price_id (required), un price_id ou customer_id que l'application n'a pas (not_found), customer envoyé avec customer_id (invalid), un updates_channel qui n'est pas l'une des quatre valeurs (invalid), un customer.email invalide (invalid) ou un customer.phone_number invalide (phone_invalid), un customer.phone_number d'un pays que votre prestataire de paiement ne peut pas débiter (phone_country_unsupported), une URL qui enfreint les règles d'URL (url_invalid), un upgrade_timing autre que now ou next_renewal (invalid), ou des metadata au-delà de leurs limites (invalid).
  • 410 avec le code price_archived quand le prix est archivé.
  • 422 avec le code not_accepting_payments quand une application en production ne peut pas encore encaisser de paiements.
  • 422 avec le code coupon_invalid quand une réduction de discounts ne peut pas être utilisée, ou 422 avec un élément errors pour discounts quand vous l'envoyez avec allow_promotion_codes: true.
  • 422 avec le code idempotency_key_reused ou 409 avec le code idempotency_in_progress. Voir Requêtes idempotentes.
POST /v1/apps/{appID}/sessions
curl https://api.abuna.app/v1/apps/8ddhXCDW/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2b9e-4d3a-4c8e-9a7f-2e5b8d1c0a43" \
  -d '{
    "type": "checkout",
    "price_id": "Zt6YbN3q",
    "customer": {"email": "ana@example.com"},
    "success_url": "https://example.com/welcome",
    "cancel_url": "https://example.com/pricing",
    "updates_channel": "telegram",
    "upgrade_timing": "next_renewal",
    "metadata": {"user_id": "42"}
  }'
Réponse
{
  "id": "A4kN1oSs",
  "type": "checkout",
  "status": "open",
  "url": "https://app.abuna.app/checkout/7f2c9e4a1b8d3f6e0c5a9d2b7e4f1a8c3d6b",
  "success_url": "https://example.com/welcome",
  "cancel_url": "https://example.com/pricing",
  "return_url": null,
  "metadata": {
    "user_id": "42"
  },
  "customer_id": null,
  "price_id": "Zt6YbN3q",
  "subscription_id": null,
  "invoice_id": null,
  "plan_offer_id": null,
  "at_period_end": null,
  "updates_channel": "telegram",
  "upgrade_timing": "next_renewal",
  "trial_days": null,
  "allow_promotion_codes": null,
  "discount": null,
  "amount_subtotal": 5000,
  "amount_discount": 0,
  "amount_total": 5000,
  "expires_at": 1727686400,
  "completed_at": null,
  "created_at": 1727600000
}

Créer une session de paiement

POST/v1/apps/{appID}/sessions

Accepte un en-tête Idempotency-Key.

Crée une session payment  : une page de paiement pour une facture ouverte. Rien n'est débité tant que le client n'a pas payé sur la page. Pour débiter depuis votre serveur le numéro de téléphone enregistré du client, utilisez Débiter une facture.

Trouvez les factures ouvertes avec Lister les factures et status=open, ou conservez l'invoice_id de l'événement invoice.created.

Paramètres du corps

  • typestringobligatoire

    payment.
  • invoice_idstringobligatoire

    La facture ouverte que paie le client.
  • success_urlstring

    Où envoyer le client une fois la session terminée. Abuna remplit ses jetons, ou ajoute les identifiants en paramètres de requête si elle n'en a aucun. Par défaut, l'URL de retour après paiement de votre application.
  • cancel_urlstring

    Où envoyer le client s'il part sans payer. Par défaut, l'URL d'annulation de votre application.
  • metadataobject

    Vos propres clés et valeurs, renvoyées dans les événements de la session. Jusqu'à 20 clés. Chaque clé fait de 1 à 40 caractères, et chaque valeur est une chaîne de 500 caractères maximum.

Renvoie la session avec le statut 201. Elle peut aussi renvoyer  :

  • 422 avec le code invalid quand un champ échoue  : pas d'invoice_id (required), un invoice_id que l'application n'a pas (not_found), une URL qui enfreint les règles d'URL (url_invalid), ou des metadata au-delà de leurs limites (invalid).
  • 409 avec le code already_paid quand la facture est déjà payée, ou 409 avec le code invoice_not_open quand elle est annulée, y compris la facture d'un abonnement résilié.
  • 422 avec le code not_accepting_payments quand une application en production ne peut pas encore encaisser de paiements.
  • 422 avec le code idempotency_key_reused ou 409 avec le code idempotency_in_progress. Voir Requêtes idempotentes.
POST /v1/apps/{appID}/sessions
curl https://api.abuna.app/v1/apps/8ddhXCDW/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "payment",
    "invoice_id": "V2nC8xEi",
    "success_url": "https://example.com/billing/paid",
    "cancel_url": "https://example.com/billing",
    "metadata": {"user_id": "42"}
  }'
Réponse
{
  "id": "z8TmY5Pq",
  "type": "payment",
  "status": "open",
  "url": "https://app.abuna.app/pay/3a8d1f6c9e2b5a7d0f4c8e1b6a9d3f7c2e5b",
  "success_url": "https://example.com/billing/paid",
  "cancel_url": "https://example.com/billing",
  "return_url": null,
  "metadata": {
    "user_id": "42"
  },
  "customer_id": "Cu5tM8rA",
  "price_id": null,
  "subscription_id": "x9QbL2sK",
  "invoice_id": "V2nC8xEi",
  "plan_offer_id": null,
  "at_period_end": null,
  "updates_channel": null,
  "upgrade_timing": null,
  "trial_days": null,
  "allow_promotion_codes": null,
  "discount": null,
  "amount_subtotal": null,
  "amount_discount": null,
  "amount_total": null,
  "expires_at": 1727686400,
  "completed_at": null,
  "created_at": 1727600000
}

Créer une session de changement de formule

POST/v1/apps/{appID}/sessions

Accepte un en-tête Idempotency-Key.

Crée une session plan_change  : une page où le client confirme le passage à un autre prix, et paie une mise à niveau. Rien ne change tant qu'il n'a pas confirmé. Abuna n'envoie ni e-mail ni message au client, envoyez-le vous-même vers l'url. Changer de formule explique les mises à niveau, les rétrogradations et leur coût.

Paramètres du corps

  • typestringobligatoire

    plan_change.
  • subscription_idstringobligatoire

    L'abonnement à déplacer. Il doit être active ou past_due.
  • price_idstringobligatoire

    Le nouveau prix. Il doit faire partie des options de formule de l'abonnement.
  • success_urlstring

    Où envoyer le client une fois la session terminée. Abuna remplit ses jetons, ou ajoute les identifiants en paramètres de requête si elle n'en a aucun. Par défaut, l'URL de retour après paiement de votre application.
  • cancel_urlstring

    Le lien « Retour » des étapes de confirmation et de paiement. Par défaut, l'URL d'annulation de votre application.
  • metadataobject

    Vos propres clés et valeurs, renvoyées dans les événements de la session. Jusqu'à 20 clés. Chaque clé fait de 1 à 40 caractères, et chaque valeur est une chaîne de 500 caractères maximum.

Renvoie la session avec le statut 201. Elle peut aussi renvoyer  :

  • 422 avec le code invalid quand un champ échoue  : pas de subscription_id ou price_id (required), un subscription_id que l'application n'a pas (not_found), une URL qui enfreint les règles d'URL (url_invalid), ou desmetadata au-delà de leurs limites (invalid).
  • 422 avec le code price_not_eligible quand le prix ne fait pas partie des options de formule.
  • 409 avec le code plan_change_unavailable quand l'abonnement n'est pas active ou past_due.
  • 422 avec le code idempotency_key_reused ou 409 avec le code idempotency_in_progress. Voir Requêtes idempotentes.
POST /v1/apps/{appID}/sessions
curl https://api.abuna.app/v1/apps/8ddhXCDW/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "plan_change",
    "subscription_id": "x9QbL2sK",
    "price_id": "Hc8LmV2s",
    "success_url": "https://example.com/plan/changed",
    "cancel_url": "https://example.com/plan",
    "metadata": {"user_id": "42"}
  }'
Réponse
{
  "id": "G2wP6hCs",
  "type": "plan_change",
  "status": "open",
  "url": "https://app.abuna.app/plan-change/5d2b8e1f4a7c0d3e6b9f2a5c8e1d4b7a0f3c",
  "success_url": "https://example.com/plan/changed",
  "cancel_url": "https://example.com/plan",
  "return_url": null,
  "metadata": {
    "user_id": "42"
  },
  "customer_id": "Cu5tM8rA",
  "price_id": "Hc8LmV2s",
  "subscription_id": "x9QbL2sK",
  "invoice_id": null,
  "plan_offer_id": "q2WkR5oF",
  "at_period_end": null,
  "updates_channel": null,
  "upgrade_timing": null,
  "trial_days": null,
  "allow_promotion_codes": null,
  "discount": null,
  "amount_subtotal": null,
  "amount_discount": null,
  "amount_total": null,
  "expires_at": 1728204800,
  "completed_at": null,
  "created_at": 1727600000
}

Créer une session de résiliation

POST/v1/apps/{appID}/sessions

Accepte un en-tête Idempotency-Key.

Crée une session cancel  : une page où le client confirme une résiliation. Rien ne change tant qu'il n'a pas confirmé. Pour résilier sans demander au client, utilisez Résilier un abonnement.

Paramètres du corps

  • typestringobligatoire

    cancel.
  • subscription_idstringobligatoire

    L'abonnement à résilier. Il doit être trialing, active ou past_due.
  • at_period_endboolean

    true met fin à l'abonnement à la fin de la période payée, et false y met fin immédiatement. Par défaut, le customer_cancel de votre application, lu à la création de la session.
  • success_urlstring

    Où envoyer le client une fois la session terminée. Abuna remplit ses jetons, ou ajoute les identifiants en paramètres de requête si elle n'en a aucun. Par défaut, l'URL de retour après paiement de votre application.
  • cancel_urlstring

    Le lien « Retour » de la page de confirmation. Par défaut, l'URL d'annulation de votre application.
  • metadataobject

    Vos propres clés et valeurs, renvoyées dans les événements de la session. Jusqu'à 20 clés. Chaque clé fait de 1 à 40 caractères, et chaque valeur est une chaîne de 500 caractères maximum.

Renvoie la session avec le statut 201. Elle peut aussi renvoyer  :

  • 422 avec le code invalid quand un champ échoue  : pas de subscription_id (required), un subscription_id que l'application n'a pas (not_found), une URL qui enfreint les règles d'URL (url_invalid), ou des metadata au-delà de leurs limites (invalid).
  • 409 avec le code subscription_canceled quand l'abonnement a pris fin, 409 avec le code subscription_not_active quand il est pending, sa première période n'étant pas encore payée, ou 409 avec le code cancel_already_scheduled quand une résiliation est déjà programmée.
  • 422 avec le code idempotency_key_reused ou 409 avec le code idempotency_in_progress. Voir Requêtes idempotentes.
POST /v1/apps/{appID}/sessions
curl https://api.abuna.app/v1/apps/8ddhXCDW/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "cancel",
    "subscription_id": "x9QbL2sK",
    "at_period_end": true,
    "success_url": "https://example.com/account/canceled",
    "cancel_url": "https://example.com/account",
    "metadata": {"user_id": "42"}
  }'
Réponse
{
  "id": "n9RcL3Xu",
  "type": "cancel",
  "status": "open",
  "url": "https://app.abuna.app/cancel/9e4b7a1d3f6c0e8b2d5a9f1c4e7b0d3a6f2c",
  "success_url": "https://example.com/account/canceled",
  "cancel_url": "https://example.com/account",
  "return_url": null,
  "metadata": {
    "user_id": "42"
  },
  "customer_id": "Cu5tM8rA",
  "price_id": null,
  "subscription_id": "x9QbL2sK",
  "invoice_id": null,
  "plan_offer_id": null,
  "at_period_end": true,
  "updates_channel": null,
  "upgrade_timing": null,
  "trial_days": null,
  "allow_promotion_codes": null,
  "discount": null,
  "amount_subtotal": null,
  "amount_discount": null,
  "amount_total": null,
  "expires_at": 1727686400,
  "completed_at": null,
  "created_at": 1727600000
}

Créer une session d'espace client

POST/v1/apps/{appID}/sessions

Accepte un en-tête Idempotency-Key.

Crée une session portal  : l'espace client d'un abonnement, avec un lien « Retour » vers votre application. L'abonnement peut avoir n'importe quel statut. Créez-en une nouvelle chaque fois que le client demande à gérer sa facturation.

Paramètres du corps

  • typestringobligatoire

    portal.
  • subscription_idstringobligatoire

    L'abonnement à gérer.
  • return_urlstringobligatoire

    Où mène le lien « Retour » de l'espace client.
  • metadataobject

    Vos propres clés et valeurs, renvoyées dans les événements de la session. Jusqu'à 20 clés. Chaque clé fait de 1 à 40 caractères, et chaque valeur est une chaîne de 500 caractères maximum.

Une session portal ne prend ni success_url ni cancel_url. Renvoie la session avec le statut 201. Elle peut aussi renvoyer  :

  • 422 avec le code invalid quand un champ échoue  : pas de subscription_id ou return_url (required), un subscription_id que l'application n'a pas (not_found), une return_url qui enfreint les règles d'URL (url_invalid), ou des metadata au-delà de leurs limites (invalid).
  • 422 avec le code idempotency_key_reused ou 409 avec le code idempotency_in_progress. Voir Requêtes idempotentes.
POST /v1/apps/{appID}/sessions
curl https://api.abuna.app/v1/apps/8ddhXCDW/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "portal",
    "subscription_id": "x9QbL2sK",
    "return_url": "https://example.com/account",
    "metadata": {"user_id": "42"}
  }'
Réponse
{
  "id": "D1vT7rQf",
  "type": "portal",
  "status": "open",
  "url": "https://app.abuna.app/portal/2c7f0a3d6b9e1c4f8a2d5b7e0c3f6a9d1b4e",
  "success_url": null,
  "cancel_url": null,
  "return_url": "https://example.com/account",
  "metadata": {
    "user_id": "42"
  },
  "customer_id": "Cu5tM8rA",
  "price_id": null,
  "subscription_id": "x9QbL2sK",
  "invoice_id": null,
  "plan_offer_id": null,
  "at_period_end": null,
  "updates_channel": null,
  "upgrade_timing": null,
  "trial_days": null,
  "allow_promotion_codes": null,
  "discount": null,
  "amount_subtotal": null,
  "amount_discount": null,
  "amount_total": null,
  "expires_at": 1727603600,
  "completed_at": null,
  "created_at": 1727600000
}

Lister les sessions

GET/v1/apps/{appID}/sessions

Liste les sessions de l'application, de la plus récente à la plus ancienne, une page à la fois. Tous les paramètres sont facultatifs, et un paramètre vide est ignoré.

Paramètres

  • typestring

    Uniquement les sessions de ce type  : checkout, payment, plan_change, cancel ou portal.
  • statusstring

    open, completed ou expired.
  • subscription_idstring

    Uniquement les sessions de cet abonnement.
  • limitinteger

    Combien de sessions renvoyer, de 1 à 100. Par défaut  : 50.
  • cursorstring

    La valeur next_cursor de la page précédente. Envoyez les mêmes filtres avec.

Attributs de la réponse

  • itemsarray

    Les sessions de la page. Vide quand rien ne correspond.
  • next_cursorstringnullable

    Passez-le en cursor pour obtenir la page suivante. Il vaut null sur la dernière page. Traitez-le comme opaque.

Renvoie 200. Une valeur non autorisée renvoie 422 avec le code invalid et le nom du paramètre dans errors.

GET /v1/apps/{appID}/sessions
curl "https://api.abuna.app/v1/apps/8ddhXCDW/sessions?status=completed&limit=50" \
  -H "Authorization: Bearer sk_test_..."
Réponse
{
  "items": [
    {
      "id": "A4kN1oSs",
      "type": "checkout",
      "status": "completed",
      "url": "https://app.abuna.app/checkout/7f2c9e4a1b8d3f6e0c5a9d2b7e4f1a8c3d6b",
      "success_url": "https://example.com/welcome",
      "cancel_url": "https://example.com/pricing",
      "return_url": null,
      "metadata": {
        "user_id": "42"
      },
      "customer_id": "Cu5tM8rA",
      "price_id": "Zt6YbN3q",
      "subscription_id": "x9QbL2sK",
      "invoice_id": null,
      "plan_offer_id": null,
      "at_period_end": null,
      "updates_channel": "telegram",
      "upgrade_timing": "next_renewal",
      "trial_days": null,
      "allow_promotion_codes": null,
      "discount": null,
      "amount_subtotal": 5000,
      "amount_discount": 0,
      "amount_total": 5000,
      "expires_at": 1727686400,
      "completed_at": 1727600600,
      "created_at": 1727600000
    }
  ],
  "next_cursor": null
}

Récupérer une session

GET/v1/apps/{appID}/sessions/{id}

Récupère une session.

Renvoie la session. Si l'application n'a aucune session avec cet identifiant, renvoie 404 avec le code not_found.

GET /v1/apps/{appID}/sessions/{id}
curl https://api.abuna.app/v1/apps/8ddhXCDW/sessions/A4kN1oSs \
  -H "Authorization: Bearer sk_test_..."
Réponse
{
  "id": "A4kN1oSs",
  "type": "checkout",
  "status": "completed",
  "url": "https://app.abuna.app/checkout/7f2c9e4a1b8d3f6e0c5a9d2b7e4f1a8c3d6b",
  "success_url": "https://example.com/welcome",
  "cancel_url": "https://example.com/pricing",
  "return_url": null,
  "metadata": {
    "user_id": "42"
  },
  "customer_id": "Cu5tM8rA",
  "price_id": "Zt6YbN3q",
  "subscription_id": "x9QbL2sK",
  "invoice_id": null,
  "plan_offer_id": null,
  "at_period_end": null,
  "updates_channel": "telegram",
  "upgrade_timing": "next_renewal",
  "trial_days": null,
  "allow_promotion_codes": null,
  "discount": null,
  "amount_subtotal": 5000,
  "amount_discount": 0,
  "amount_total": 5000,
  "expires_at": 1727686400,
  "completed_at": 1727600600,
  "created_at": 1727600000
}

Expirer une session

POST/v1/apps/{appID}/sessions/{id}/expire

Accepte un en-tête Idempotency-Key.

Met fin immédiatement à une session open, avant son expires_at. Sa page indique au client que la session a expiré, et Abuna envoie session.expired. Un abonnement qu'une session checkout a déjà démarré reste pending, comme décrit dans le guide Sessions. Expirer une session plan_change, ou une session checkout qui a proposé un changement de formule, retire aussi sa proposition de changement de formule, et Abuna envoie plan_offer.canceled.

Renvoie la session. Si elle est déjà completed ou expired, renvoie 409 avec le code session_not_open. Si l'application n'a aucune session avec cet identifiant, renvoie 404 avec le code not_found.

POST /v1/apps/{appID}/sessions/{id}/expire
curl -X POST https://api.abuna.app/v1/apps/8ddhXCDW/sessions/A4kN1oSs/expire \
  -H "Authorization: Bearer sk_test_..."
Réponse
{
  "id": "A4kN1oSs",
  "type": "checkout",
  "status": "expired",
  "url": "https://app.abuna.app/checkout/7f2c9e4a1b8d3f6e0c5a9d2b7e4f1a8c3d6b",
  "success_url": "https://example.com/welcome",
  "cancel_url": "https://example.com/pricing",
  "return_url": null,
  "metadata": {
    "user_id": "42"
  },
  "customer_id": null,
  "price_id": "Zt6YbN3q",
  "subscription_id": null,
  "invoice_id": null,
  "plan_offer_id": null,
  "at_period_end": null,
  "updates_channel": "telegram",
  "upgrade_timing": "next_renewal",
  "trial_days": null,
  "allow_promotion_codes": null,
  "discount": null,
  "amount_subtotal": 5000,
  "amount_discount": 0,
  "amount_total": 5000,
  "expires_at": 1727686400,
  "completed_at": null,
  "created_at": 1727600000
}

Types de session

Chaque type a sa propre page, sa propre règle de fin et ses propres données session.completed. Tous envoient session.expired avec les données de la référence des événements.

checkout

Pendant un essai gratuit, le client confirme ses coordonnées, ses rappels et son accord sans payer, puis saisit le code envoyé à son e-mail. La session se termine au démarrage de l'abonnement trialing, puis le client rejoint votre success_url, avec l'activation habituelle de la messagerie choisie.

Abuna envoie session.completed et subscription.created, pas subscription.paid. Leur abonnement inclut trial_ends_at en secondes Unix, ou null sans essai. Accordez l'accès à partir des webhooks, pas du retour du navigateur.

Créée par Créer une session checkout. L'url est une page d'abonnement pour price_id. La session se termine quand le premier paiement réussit et que l'abonnement devient active, ou au démarrage d'un essai gratuit. Elle expire 24 heures après sa création. Ses données session.completed contiennent session_id, type, subscription_id, customer_id, price_id, metadata, completed_at et les updates du client.

Pour un client qui revient, elle peut se terminer sur son abonnement existant. Quand la session a proposé un changement de formule, elle se termine une fois le changement confirmé, ou payé pour une mise à niveau, et elle dure aussi longtemps que la proposition. Ses données session.completed ont alors ces champs, les mêmes que ceux d'une session plan_change :

session.completed data pour un changement de formule

  • session_idstring

    La session.
  • typestring

    Toujours checkout.
  • subscription_idstring

    L'abonnement existant du client.
  • customer_idstring

    Son client.
  • metadataobject

    Les métadonnées transmises à la création de la session.
  • completed_attimestamp

    Quand la session s'est terminée.
  • plan_offer_idstring

    L'proposition de changement de formule faite par la page d'abonnement.
  • previous_price_idstring

    Le prix avant le changement.
  • price_idstring

    Le nouveau prix, celui que vend la session.
  • directionstring

    upgrade ou downgrade.
  • effective_attimestamp

    Quand le nouveau prix commence : au moment où la mise à niveau s'applique, ou à la fin de la période payée pour une rétrogradation ou une mise à niveau au prochain renouvellement.
session.completed data pour un changement de formule
{
  "session_id": "A4kN1oSs",
  "type": "checkout",
  "subscription_id": "x9QbL2sK",
  "customer_id": "Cu5tM8rA",
  "metadata": {
    "user_id": "42"
  },
  "completed_at": 1727600900,
  "plan_offer_id": "r7TnK4pW",
  "previous_price_id": "Hc8LmV2s",
  "price_id": "Zt6YbN3q",
  "direction": "upgrade",
  "effective_at": 1730192000,
  "subscription": {
    "id": "x9QbL2sK",
    "app_id": "8ddhXCDW",
    "customer_id": "Cu5tM8rA",
    "price_id": "Hc8LmV2s",
    "status": "active",
    "starts_at": 1727600000,
    "activated_at": 1727600100,
    "trial_ends_at": null,
    "canceled_at": null,
    "cancel_at": null,
    "cancel_at_period_end": false,
    "current_period_start": 1727600000,
    "current_period_end": 1730192000,
    "ended_reason": null,
    "metadata": {
      "user_id": "42"
    },
    "created_at": 1727600000,
    "manage_token": "8c1f4a7d2e9b3c6f0a5d8e1b4c7f2a9d3e6b",
    "discount": null
  }
}

payment

Créée par Créer une session de paiement. L'url est une page de paiement pour invoice_id. La session se termine quand cette facture est payée par son intermédiaire. Elle expire 24 heures après sa création, ou plus tôt dès que la facture ne peut plus être payée par ce biais  : payée autrement, annulée, ou son abonnement terminé. Une facture payée autrement expire la session, alors utilisez invoice.paid pour savoir qu'une facture est réglée. Les liens de paiement qu'Abuna envoie par e-mail, sur WhatsApp et sur Telegram continuent de fonctionner seuls.

session.completed data

  • session_idstring

    La session.
  • typestring

    Toujours payment.
  • invoice_idstring

    La facture payée par le client.
  • subscription_idstring

    Son abonnement.
  • customer_idstring

    Son client.
  • metadataobject

    Les métadonnées transmises à la création de la session.
  • completed_attimestamp

    Quand la session s'est terminée.
session.completed data
{
  "session_id": "z8TmY5Pq",
  "type": "payment",
  "invoice_id": "V2nC8xEi",
  "subscription_id": "x9QbL2sK",
  "customer_id": "Cu5tM8rA",
  "metadata": {
    "user_id": "42"
  },
  "completed_at": 1727600600,
  "subscription": {
    "id": "x9QbL2sK",
    "app_id": "8ddhXCDW",
    "customer_id": "Cu5tM8rA",
    "price_id": "Zt6YbN3q",
    "status": "active",
    "starts_at": 1727600000,
    "activated_at": 1727600100,
    "trial_ends_at": null,
    "canceled_at": null,
    "cancel_at": null,
    "cancel_at_period_end": false,
    "current_period_start": 1727600000,
    "current_period_end": 1730192000,
    "ended_reason": null,
    "metadata": {
      "user_id": "42"
    },
    "created_at": 1727600000,
    "manage_token": "8c1f4a7d2e9b3c6f0a5d8e1b4c7f2a9d3e6b",
    "discount": null
  }
}

plan_change

Créée par Créer une session de changement de formule. L'url est la page de confirmation du passage de subscription_id à price_id. Créer la session crée une proposition de changement de formule en arrière-plan et envoie plan_offer.created, mais Abuna n'envoie ni e-mail ni message au client. Elle remplace toute proposition ou session plan_change en attente, et la session plus ancienne reçoit session.expired.

La session se termine quand le changement est effectué  :

  • Une rétrogradation  : quand le client confirme. Elle est programmée pour la fin de la période payée.
  • Une mise à niveau  : quand son paiement réussit. Une mise à niveau qui coûte 0 s'applique, et se termine, à la confirmation.

Elle expire 7 jours après sa création, ou à la fin de la période en cours si elle arrive avant. Elle expire aussi quand sa proposition est remplacée, retirée ou expire, ou quand une mise à niveau qu'elle a démarrée reste impayée et échoue. Une mise à niveau confirmée en attente de paiement reste open jusqu'à son paiement ou son échec.

Les événements plan_offer.*, subscription.updated et invoice.* se déclenchent toujours comme pour tout changement de formule. Utilisez session.completed pour savoir que le client a terminé le parcours que vous avez démarré, et subscription.updated pour savoir que le prix a changé. Une rétrogradation change le prix à la fin de la période, après la fin de la session.

session.completed data

  • session_idstring

    La session.
  • typestring

    Toujours plan_change.
  • subscription_idstring

    L'abonnement.
  • customer_idstring

    Son client.
  • metadataobject

    Les métadonnées transmises à la création de la session.
  • completed_attimestamp

    Quand la session s'est terminée.
  • plan_offer_idstring

    L'proposition de changement de formule créée par la session.
  • previous_price_idstring

    Le prix avant le changement.
  • price_idstring

    Le nouveau prix.
  • directionstring

    upgrade ou downgrade.
  • effective_attimestamp

    Quand le nouveau prix commence  : au moment où la mise à niveau s'applique, ou à la fin de la période payée pour une rétrogradation.
session.completed data
{
  "session_id": "G2wP6hCs",
  "type": "plan_change",
  "subscription_id": "x9QbL2sK",
  "customer_id": "Cu5tM8rA",
  "metadata": {
    "user_id": "42"
  },
  "completed_at": 1727600900,
  "plan_offer_id": "q2WkR5oF",
  "previous_price_id": "Zt6YbN3q",
  "price_id": "Hc8LmV2s",
  "direction": "upgrade",
  "effective_at": 1727600900,
  "subscription": {
    "id": "x9QbL2sK",
    "app_id": "8ddhXCDW",
    "customer_id": "Cu5tM8rA",
    "price_id": "Hc8LmV2s",
    "status": "active",
    "starts_at": 1727600000,
    "activated_at": 1727600100,
    "trial_ends_at": null,
    "canceled_at": null,
    "cancel_at": null,
    "cancel_at_period_end": false,
    "current_period_start": 1727600900,
    "current_period_end": 1730192900,
    "ended_reason": null,
    "metadata": {
      "user_id": "42"
    },
    "created_at": 1727600000,
    "manage_token": "8c1f4a7d2e9b3c6f0a5d8e1b4c7f2a9d3e6b",
    "discount": null
  }
}

cancel

Pendant un essai, la résiliation demandée par le client est programmée à trial_ends_at. L'accès reste ouvert jusque-là, sans facture à payer. Pour retirer l'accès immédiatement depuis votre serveur, utilisez l'API de résiliation des abonnements.

Créée par Créer une session de résiliation. L'url est une page de confirmation pour résilier subscription_id. Elle montre ce qui se passe et la date de fin, avec un bouton de confirmation et un lien « Retour » vers cancel_url. L'abonnement doit être trialing, active ou past_due, sans résiliation déjà programmée. Vous ne pouvez pas en créer une pour un abonnement pending  : vous obtenez 409 avec le code subscription_not_active.

at_period_end est défini à la création de la session  : la valeur que vous avez envoyée, ou le réglage customer_cancel de l'application. La résiliation suit les règles de résiliation habituelles  :

  • À la fin de la période, l'abonnement reste active et le client garde l'accès jusqu'à la fin de la période payée.
  • Si la période en cours n'est pas payée, comme pendant que l'abonnement est past_due, ou est déjà terminée, l'abonnement prend fin immédiatement à la place. La page l'indique au client avant qu'il confirme.
  • Une résiliation immédiate annule les factures ouvertes de l'abonnement.

La session se termine quand le client confirme, que la résiliation soit programmée ou immédiate. Elle expire 24 heures après sa création sinon. subscription.updated (programmée) ou subscription.canceled (immédiate) se déclenchent toujours comme pour toute résiliation. Pour une résiliation programmée, subscription.canceled se déclenche plus tard, à cancel_at. Fiez-vous à ces événements pour changer l'accès.

session.completed data

  • session_idstring

    La session.
  • typestring

    Toujours cancel.
  • subscription_idstring

    L'abonnement.
  • customer_idstring

    Son client.
  • metadataobject

    Les métadonnées transmises à la création de la session.
  • completed_attimestamp

    Quand le client a confirmé.
  • cancel_attimestampnullable

    Quand l'abonnement prend fin. Null quand il a pris fin immédiatement.
  • immediateboolean

    true quand l'abonnement a pris fin immédiatement.
session.completed data
{
  "session_id": "n9RcL3Xu",
  "type": "cancel",
  "subscription_id": "x9QbL2sK",
  "customer_id": "Cu5tM8rA",
  "metadata": {
    "user_id": "42"
  },
  "completed_at": 1727600300,
  "cancel_at": 1730192000,
  "immediate": false,
  "subscription": {
    "id": "x9QbL2sK",
    "app_id": "8ddhXCDW",
    "customer_id": "Cu5tM8rA",
    "price_id": "Zt6YbN3q",
    "status": "active",
    "starts_at": 1727600000,
    "activated_at": 1727600100,
    "trial_ends_at": null,
    "canceled_at": null,
    "cancel_at": 1730192000,
    "cancel_at_period_end": true,
    "current_period_start": 1727600000,
    "current_period_end": 1730192000,
    "ended_reason": null,
    "metadata": {
      "user_id": "42"
    },
    "created_at": 1727600000,
    "manage_token": "8c1f4a7d2e9b3c6f0a5d8e1b4c7f2a9d3e6b",
    "discount": null
  }
}

portal

Créée par Créer une session d'espace client. L'url est l'espace client de subscription_id, avec un lien « Retour » vers return_url en haut. L'abonnement peut avoir n'importe quel statut. Le lien reste valable pendant que le client change de formule, paie, active les messages WhatsApp ou Telegram ou met à jour ses coordonnées. Sur la page de paiement, les liens de retour et de fin mènent à return_url, et « Gérer l'abonnement » revient à l'espace client. Chacun de ces liens est votre return_url exactement tel que vous l'avez envoyé. Abuna n'y ajoute aucun paramètre de requête ni identifiant.

Ce que l'espace client affiche dépend du statut de l'abonnement  :

  • trialing : la date de fin de l'essai et une résiliation qui conserve l'accès jusque-là, sans facture à payer.
  • pending  : la première facture avec sa date limite de paiement et un bouton Payer, ainsi qu'un bouton « Résilier l'abonnement » qui y met fin immédiatement. Il n'y a pas de changement de formule.
  • active ou past_due  : la formule, les factures, les coordonnées, un bouton « Résilier l'abonnement » et les prix vers lesquels le client peut changer, le cas échéant. Un abonnement past_due affiche aussi sa facture impayée avec un bouton Payer.
  • canceled  : la formule, la date de résiliation, les factures et les coordonnées du client, qu'il peut encore mettre à jour. Il n'y a rien à payer, ni changement de formule ni résiliation.

L'url doit être ouverte dans l'heure suivant sa création, sinon elle affiche un lien invalide. Une fois ouverte, elle continue de fonctionner comme l'espace client. Créez une nouvelle session chaque fois que le client demande à gérer sa facturation.

La session se termine quand le client l'ouvre pour la première fois. Cela ne signifie pas qu'il a changé quelque chose  : ce qu'il fait dans l'espace client envoie ses propres événements, comme subscription.updated, subscription.canceled, invoice.paid et customer.updated. Une session que personne n'ouvre expire au bout d'une heure. Le subscription_page_url de l'abonnement continue de fonctionner de son côté, sans lien de retour vers votre application.

session.completed data

  • session_idstring

    La session.
  • typestring

    Toujours portal.
  • subscription_idstring

    L'abonnement.
  • customer_idstring

    Son client.
  • metadataobject

    Les métadonnées transmises à la création de la session.
  • completed_attimestamp

    Quand le client a ouvert l'espace client pour la première fois.
session.completed data
{
  "session_id": "D1vT7rQf",
  "type": "portal",
  "subscription_id": "x9QbL2sK",
  "customer_id": "Cu5tM8rA",
  "metadata": {
    "user_id": "42"
  },
  "completed_at": 1727600020,
  "subscription": {
    "id": "x9QbL2sK",
    "app_id": "8ddhXCDW",
    "customer_id": "Cu5tM8rA",
    "price_id": "Zt6YbN3q",
    "status": "active",
    "starts_at": 1727600000,
    "activated_at": 1727600100,
    "trial_ends_at": null,
    "canceled_at": null,
    "cancel_at": null,
    "cancel_at_period_end": false,
    "current_period_start": 1727600000,
    "current_period_end": 1730192000,
    "ended_reason": null,
    "metadata": {
      "user_id": "42"
    },
    "created_at": 1727600000,
    "manage_token": "8c1f4a7d2e9b3c6f0a5d8e1b4c7f2a9d3e6b",
    "discount": null
  }
}

URL de redirection

success_url et cancel_url prennent par défaut l'URL de retour après paiement et l'URL d'annulation de votre application. Abuna les copie sur la session à sa création, donc modifier le réglage plus tard ne change pas les sessions existantes. Une session portal prend return_url à la place, et n'a ni l'une ni l'autre.

Chaque URL doit être une URL https absolue avec un hôte. En mode Test, http fonctionne aussi pour localhost, 127.0.0.1 et [::1]. Cela vaut pour l'URL de retour après paiement et l'URL d'annulation par défaut de l'application Test, pour chaque type de session. Toute autre URL renvoie 422 avec le code invalid et un élément errors avec le code url_invalid.

Jetons de l'URL de retour après paiement

Les sessions de résiliation et les changements de formule sans paiement dû envoient le client directement à success_url. Les sessions checkout, payment et les mises à niveau payantes affichent à la place un bouton « Retour ». Les deux utilisent success_url avec ces jetons remplis  :

  • {SESSION_ID}  : tous les types.
  • {SUBSCRIPTION_ID}  : tous les types.
  • {INVOICE_ID}  : payment uniquement.

Si l'URL n'a aucun jeton, Abuna ajoute les mêmes identifiants en paramètres de requête  : session_id, subscription_id, et pour payment, invoice_id. Elle conserve vos propres paramètres de requête et le fragment #. Rien n'est ajouté à cancel_url. Une session portal n'a pas de success_url. Son lien « Retour » mène à return_url.

Étapes suivantes