# 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. Source : https://abuna.app/docs/api/sessions?hl=fr 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](https://abuna.app/docs/guides/sessions.md?hl=fr) 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`](https://abuna.app/docs/api/sessions.md?hl=fr#create-checkout) : une page d'abonnement qui vend un prix. Envoyez `price_id`. - [`payment`](https://abuna.app/docs/api/sessions.md?hl=fr#create-payment) : une page de paiement pour une facture ouverte. Envoyez `invoice_id`. - [`plan_change`](https://abuna.app/docs/api/sessions.md?hl=fr#create-plan-change) : le client confirme le passage à un autre prix. Envoyez `subscription_id` et `price_id`. - [`cancel`](https://abuna.app/docs/api/sessions.md?hl=fr#create-cancel) : le client confirme la résiliation. Envoyez `subscription_id`. - [`portal`](https://abuna.app/docs/api/sessions.md?hl=fr#create-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** - `id` (string): Identifiant unique de la session. - `type` (string): Ce à quoi sert la session : `checkout`, `payment`, `plan_change`, `cancel` ou `portal`, tel que vous l'avez envoyé à la création. - `status` (string): `open` jusqu'à sa fin. `completed` dès que le client termine, selon la définition de chaque [type](https://abuna.app/docs/api/sessions.md?hl=fr#types), ou `expired` lorsqu'elle expire ou que vous l'expirez. Une session terminée ne change plus jamais. - `url` (string): La page vers laquelle envoyer le client. Elle appartient à ce client, ne la partagez pas. - `success_url` (string, nullable): 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](https://abuna.app/docs/api/sessions.md?hl=fr#placeholders). - `cancel_url` (string, nullable): 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_url` (string, nullable): Pour `portal`, où mène le lien « Retour » de l'espace client. Null pour les autres types. - `metadata` (object): Vos propres clés et valeurs, telles que vous les avez envoyées. `{}` quand vous n'en avez pas envoyé. - `customer_id` (string, nullable): 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_id` (string, nullable): Pour `checkout`, le prix que vend la session. Pour `plan_change`, le nouveau prix. Null pour les autres types. - `subscription_id` (string, nullable): 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](https://abuna.app/docs/api/sessions.md?hl=fr#returning-customers)). Pour les autres types, l'abonnement sur lequel agit la session. Null tant qu'il est inconnu. - `invoice_id` (string, nullable): Pour `payment`, la facture que paie le client. Null pour les autres types. - `plan_offer_id` (string, nullable): 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](https://abuna.app/docs/api/sessions.md?hl=fr#checkout-switch), ou null. Null pour les autres types. - `at_period_end` (boolean, nullable): 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`](https://abuna.app/docs/api/apps.md?hl=fr#object) de l'application. Null pour les autres types. - `updates_channel` (string, nullable): 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](https://abuna.app/docs/api/sessions.md?hl=fr#create-checkout). Null pour les autres types. - `upgrade_timing` (string, nullable): Pour `checkout`, quand le [changement de formule](https://abuna.app/docs/api/sessions.md?hl=fr#checkout-switch) 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_at` (timestamp): 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](https://abuna.app/docs/api/sessions.md?hl=fr#checkout-switch) prend la fin de la proposition à la place. - `trial_days` (integer, nullable): 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_codes` (boolean, nullable): 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. - `discount` (object, nullable): Pour `checkout`, la réduction de la session : `coupon`, le [coupon](https://abuna.app/docs/api/coupons.md?hl=fr#object), 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_subtotal` (integer, nullable): Pour `checkout`, le montant du prix avant réduction, dans la plus petite unité de la devise. Null pour les autres types. - `amount_discount` (integer, nullable): 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_total` (integer, nullable): 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_at` (timestamp, nullable): Quand la session s'est terminée. - `created_at` (timestamp): Quand la session a été créée, en secondes Unix. **L'objet session** ```json { "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` Crée une session [`checkout`](https://abuna.app/docs/api/sessions.md?hl=fr#type-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](https://abuna.app/docs/api/subscriptions.md?hl=fr#create). **Paramètres du corps** - `type` (string, obligatoire): `checkout`. - `price_id` (string, obligatoire): Le prix à vendre. Il ne doit pas être archivé. - `trial_days` (integer): 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](https://abuna.app/docs/guides/trials.md?hl=fr). - `allow_promotion_codes` (boolean): 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](https://abuna.app/docs/guides/promotion-codes.md?hl=fr#checkout). - `discounts` (array): 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_id` (string): Un client existant à facturer. La page d'abonnement affiche ses coordonnées en lecture seule. Ne l'envoyez pas avec `customer`. - `customer` (object): 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`. - `email` (string): Son adresse e-mail. Elle doit contenir `@`. - `name` (string): Son nom. - `phone_number` (string): 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_url` (string): Où envoyer le client une fois la session terminée. Abuna remplit ses [jetons](https://abuna.app/docs/api/sessions.md?hl=fr#placeholders), 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_url` (string): Où envoyer le client s'il part avant de payer. Par défaut, l'URL d'annulation de votre application. - `metadata` (object): 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_channel` (string): 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_timing` (string): Quand le [changement de formule](https://abuna.app/docs/api/sessions.md?hl=fr#checkout-switch) 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](https://abuna.app/docs/guides/customer-notifications.md?hl=fr#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](https://abuna.app/docs/guides/customer-notifications.md?hl=fr#grant-access). ### 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](https://abuna.app/docs/api/sessions.md?hl=fr#checkout-switch). - **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`](https://abuna.app/docs/api/events.md?hl=fr#notification-captured), dans la rubrique **Événements** du tableau de bord. Le changement suit les [règles de changement de formule](https://abuna.app/docs/api/subscriptions.md?hl=fr#changing-plan) : - **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](https://abuna.app/docs/api/sessions.md?hl=fr#type-checkout). 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](https://abuna.app/docs/api/sessions.md?hl=fr#urls) (`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](https://abuna.app/docs/errors.md?hl=fr#idempotency). **POST /v1/apps/{appID}/sessions** cURL : ```bash 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"} }' ``` Node.js : ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/sessions", { method: "POST", headers: { Authorization: "Bearer sk_test_...", "Content-Type": "application/json", "Idempotency-Key": "6f1c2b9e-4d3a-4c8e-9a7f-2e5b8d1c0a43", }, body: JSON.stringify({ 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" }, }), }); const session = await response.json(); ``` Python : ```python import requests response = requests.post( "https://api.abuna.app/v1/apps/8ddhXCDW/sessions", headers={"Authorization": "Bearer sk_test_...", "Idempotency-Key": "6f1c2b9e-4d3a-4c8e-9a7f-2e5b8d1c0a43"}, json={ "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"}, }, ) session = response.json() ``` PHP : ```php true, CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_...", "Content-Type: application/json", "Idempotency-Key: 6f1c2b9e-4d3a-4c8e-9a7f-2e5b8d1c0a43"], CURLOPT_POSTFIELDS => json_encode([ "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"], ]), CURLOPT_RETURNTRANSFER => true, ]); $session = json_decode(curl_exec($ch), true); ``` Go : ```go body, _ := json.Marshal(map[string]any{ "type": "checkout", "price_id": "Zt6YbN3q", "customer": map[string]any{"email": "ana@example.com"}, "success_url": "https://example.com/welcome", "cancel_url": "https://example.com/pricing", "updates_channel": "telegram", "upgrade_timing": "next_renewal", "metadata": map[string]any{"user_id": "42"}, }) req, _ := http.NewRequest("POST", "https://api.abuna.app/v1/apps/8ddhXCDW/sessions", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer sk_test_...") req.Header.Set("Content-Type", "application/json") req.Header.Set("Idempotency-Key", "6f1c2b9e-4d3a-4c8e-9a7f-2e5b8d1c0a43") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var session map[string]any json.NewDecoder(res.Body).Decode(&session) ``` **Réponse** ```json { "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` Crée une session [`payment`](https://abuna.app/docs/api/sessions.md?hl=fr#type-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](https://abuna.app/docs/api/invoices-and-payments.md?hl=fr#charge). Trouvez les factures ouvertes avec [Lister les factures](https://abuna.app/docs/api/invoices-and-payments.md?hl=fr#list) et `status=open`, ou conservez l'`invoice_id` de l'événement [`invoice.created`](https://abuna.app/docs/api/events.md?hl=fr#invoice-created). **Paramètres du corps** - `type` (string, obligatoire): `payment`. - `invoice_id` (string, obligatoire): La facture ouverte que paie le client. - `success_url` (string): Où envoyer le client une fois la session terminée. Abuna remplit ses [jetons](https://abuna.app/docs/api/sessions.md?hl=fr#placeholders), 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_url` (string): Où envoyer le client s'il part sans payer. Par défaut, l'URL d'annulation de votre application. - `metadata` (object): 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](https://abuna.app/docs/api/sessions.md?hl=fr#urls) (`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](https://abuna.app/docs/errors.md?hl=fr#idempotency). **POST /v1/apps/{appID}/sessions** cURL : ```bash 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"} }' ``` Node.js : ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/sessions", { method: "POST", headers: { Authorization: "Bearer sk_test_...", "Content-Type": "application/json" }, body: JSON.stringify({ type: "payment", invoice_id: "V2nC8xEi", success_url: "https://example.com/billing/paid", cancel_url: "https://example.com/billing", metadata: { user_id: "42" }, }), }); const session = await response.json(); ``` Python : ```python import requests response = requests.post( "https://api.abuna.app/v1/apps/8ddhXCDW/sessions", headers={"Authorization": "Bearer sk_test_..."}, json={ "type": "payment", "invoice_id": "V2nC8xEi", "success_url": "https://example.com/billing/paid", "cancel_url": "https://example.com/billing", "metadata": {"user_id": "42"}, }, ) session = response.json() ``` PHP : ```php true, CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_...", "Content-Type: application/json"], CURLOPT_POSTFIELDS => json_encode([ "type" => "payment", "invoice_id" => "V2nC8xEi", "success_url" => "https://example.com/billing/paid", "cancel_url" => "https://example.com/billing", "metadata" => ["user_id" => "42"], ]), CURLOPT_RETURNTRANSFER => true, ]); $session = json_decode(curl_exec($ch), true); ``` Go : ```go body, _ := json.Marshal(map[string]any{ "type": "payment", "invoice_id": "V2nC8xEi", "success_url": "https://example.com/billing/paid", "cancel_url": "https://example.com/billing", "metadata": map[string]any{"user_id": "42"}, }) req, _ := http.NewRequest("POST", "https://api.abuna.app/v1/apps/8ddhXCDW/sessions", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer sk_test_...") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var session map[string]any json.NewDecoder(res.Body).Decode(&session) ``` **Réponse** ```json { "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` Crée une session [`plan_change`](https://abuna.app/docs/api/sessions.md?hl=fr#type-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](https://abuna.app/docs/api/subscriptions.md?hl=fr#changing-plan) explique les mises à niveau, les rétrogradations et leur coût. **Paramètres du corps** - `type` (string, obligatoire): `plan_change`. - `subscription_id` (string, obligatoire): L'abonnement à déplacer. Il doit être `active` ou `past_due`. - `price_id` (string, obligatoire): Le nouveau prix. Il doit faire partie des [options de formule](https://abuna.app/docs/api/subscriptions.md?hl=fr#list-plan-options) de l'abonnement. - `success_url` (string): Où envoyer le client une fois la session terminée. Abuna remplit ses [jetons](https://abuna.app/docs/api/sessions.md?hl=fr#placeholders), 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_url` (string): Le lien « Retour » des étapes de confirmation et de paiement. Par défaut, l'URL d'annulation de votre application. - `metadata` (object): 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](https://abuna.app/docs/api/sessions.md?hl=fr#urls) (`url_invalid`), ou des`metadata` 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](https://abuna.app/docs/errors.md?hl=fr#idempotency). **POST /v1/apps/{appID}/sessions** cURL : ```bash 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"} }' ``` Node.js : ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/sessions", { method: "POST", headers: { Authorization: "Bearer sk_test_...", "Content-Type": "application/json" }, body: JSON.stringify({ 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" }, }), }); const session = await response.json(); ``` Python : ```python import requests response = requests.post( "https://api.abuna.app/v1/apps/8ddhXCDW/sessions", headers={"Authorization": "Bearer sk_test_..."}, json={ "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"}, }, ) session = response.json() ``` PHP : ```php true, CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_...", "Content-Type: application/json"], CURLOPT_POSTFIELDS => json_encode([ "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"], ]), CURLOPT_RETURNTRANSFER => true, ]); $session = json_decode(curl_exec($ch), true); ``` Go : ```go body, _ := json.Marshal(map[string]any{ "type": "plan_change", "subscription_id": "x9QbL2sK", "price_id": "Hc8LmV2s", "success_url": "https://example.com/plan/changed", "cancel_url": "https://example.com/plan", "metadata": map[string]any{"user_id": "42"}, }) req, _ := http.NewRequest("POST", "https://api.abuna.app/v1/apps/8ddhXCDW/sessions", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer sk_test_...") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var session map[string]any json.NewDecoder(res.Body).Decode(&session) ``` **Réponse** ```json { "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` Crée une session [`cancel`](https://abuna.app/docs/api/sessions.md?hl=fr#type-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](https://abuna.app/docs/api/subscriptions.md?hl=fr#cancel). **Paramètres du corps** - `type` (string, obligatoire): `cancel`. - `subscription_id` (string, obligatoire): L'abonnement à résilier. Il doit être `trialing`, `active` ou `past_due`. - `at_period_end` (boolean): `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`](https://abuna.app/docs/api/apps.md?hl=fr#object) de votre application, lu à la création de la session. - `success_url` (string): Où envoyer le client une fois la session terminée. Abuna remplit ses [jetons](https://abuna.app/docs/api/sessions.md?hl=fr#placeholders), 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_url` (string): Le lien « Retour » de la page de confirmation. Par défaut, l'URL d'annulation de votre application. - `metadata` (object): 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](https://abuna.app/docs/api/sessions.md?hl=fr#urls) (`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](https://abuna.app/docs/errors.md?hl=fr#idempotency). **POST /v1/apps/{appID}/sessions** cURL : ```bash 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"} }' ``` Node.js : ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/sessions", { method: "POST", headers: { Authorization: "Bearer sk_test_...", "Content-Type": "application/json" }, body: JSON.stringify({ 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" }, }), }); const session = await response.json(); ``` Python : ```python import requests response = requests.post( "https://api.abuna.app/v1/apps/8ddhXCDW/sessions", headers={"Authorization": "Bearer sk_test_..."}, json={ "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"}, }, ) session = response.json() ``` PHP : ```php true, CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_...", "Content-Type: application/json"], CURLOPT_POSTFIELDS => json_encode([ "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"], ]), CURLOPT_RETURNTRANSFER => true, ]); $session = json_decode(curl_exec($ch), true); ``` Go : ```go body, _ := json.Marshal(map[string]any{ "type": "cancel", "subscription_id": "x9QbL2sK", "at_period_end": true, "success_url": "https://example.com/account/canceled", "cancel_url": "https://example.com/account", "metadata": map[string]any{"user_id": "42"}, }) req, _ := http.NewRequest("POST", "https://api.abuna.app/v1/apps/8ddhXCDW/sessions", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer sk_test_...") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var session map[string]any json.NewDecoder(res.Body).Decode(&session) ``` **Réponse** ```json { "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` Crée une session [`portal`](https://abuna.app/docs/api/sessions.md?hl=fr#type-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** - `type` (string, obligatoire): `portal`. - `subscription_id` (string, obligatoire): L'abonnement à gérer. - `return_url` (string, obligatoire): Où mène le lien « Retour » de l'espace client. - `metadata` (object): 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](https://abuna.app/docs/api/sessions.md?hl=fr#urls) (`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](https://abuna.app/docs/errors.md?hl=fr#idempotency). **POST /v1/apps/{appID}/sessions** cURL : ```bash 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"} }' ``` Node.js : ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/sessions", { method: "POST", headers: { Authorization: "Bearer sk_test_...", "Content-Type": "application/json" }, body: JSON.stringify({ type: "portal", subscription_id: "x9QbL2sK", return_url: "https://example.com/account", metadata: { user_id: "42" }, }), }); const session = await response.json(); ``` Python : ```python import requests response = requests.post( "https://api.abuna.app/v1/apps/8ddhXCDW/sessions", headers={"Authorization": "Bearer sk_test_..."}, json={ "type": "portal", "subscription_id": "x9QbL2sK", "return_url": "https://example.com/account", "metadata": {"user_id": "42"}, }, ) session = response.json() ``` PHP : ```php true, CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_...", "Content-Type: application/json"], CURLOPT_POSTFIELDS => json_encode([ "type" => "portal", "subscription_id" => "x9QbL2sK", "return_url" => "https://example.com/account", "metadata" => ["user_id" => "42"], ]), CURLOPT_RETURNTRANSFER => true, ]); $session = json_decode(curl_exec($ch), true); ``` Go : ```go body, _ := json.Marshal(map[string]any{ "type": "portal", "subscription_id": "x9QbL2sK", "return_url": "https://example.com/account", "metadata": map[string]any{"user_id": "42"}, }) req, _ := http.NewRequest("POST", "https://api.abuna.app/v1/apps/8ddhXCDW/sessions", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer sk_test_...") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var session map[string]any json.NewDecoder(res.Body).Decode(&session) ``` **Réponse** ```json { "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** - `type` (string): Uniquement les sessions de ce type : `checkout`, `payment`, `plan_change`, `cancel` ou `portal`. - `status` (string): `open`, `completed` ou `expired`. - `subscription_id` (string): Uniquement les sessions de cet abonnement. - `limit` (integer): Combien de sessions renvoyer, de 1 à 100. Par défaut : 50. - `cursor` (string): La valeur `next_cursor` de la page précédente. Envoyez les mêmes filtres avec. **Attributs de la réponse** - `items` (array): Les [sessions](https://abuna.app/docs/api/sessions.md?hl=fr#object) de la page. Vide quand rien ne correspond. - `next_cursor` (string, nullable): 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 : ```bash curl "https://api.abuna.app/v1/apps/8ddhXCDW/sessions?status=completed&limit=50" \ -H "Authorization: Bearer sk_test_..." ``` Node.js : ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/sessions?status=completed&limit=50", { headers: { Authorization: "Bearer sk_test_..." }, }); const page = await response.json(); ``` Python : ```python import requests response = requests.get( "https://api.abuna.app/v1/apps/8ddhXCDW/sessions?status=completed&limit=50", headers={"Authorization": "Bearer sk_test_..."}, ) page = response.json() ``` PHP : ```php ["Authorization: Bearer sk_test_..."], CURLOPT_RETURNTRANSFER => true, ]); $page = json_decode(curl_exec($ch), true); ``` Go : ```go req, _ := http.NewRequest("GET", "https://api.abuna.app/v1/apps/8ddhXCDW/sessions?status=completed&limit=50", nil) req.Header.Set("Authorization", "Bearer sk_test_...") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var page map[string]any json.NewDecoder(res.Body).Decode(&page) ``` **Réponse** ```json { "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 : ```bash curl https://api.abuna.app/v1/apps/8ddhXCDW/sessions/A4kN1oSs \ -H "Authorization: Bearer sk_test_..." ``` Node.js : ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/sessions/A4kN1oSs", { headers: { Authorization: "Bearer sk_test_..." }, }); const session = await response.json(); ``` Python : ```python import requests response = requests.get( "https://api.abuna.app/v1/apps/8ddhXCDW/sessions/A4kN1oSs", headers={"Authorization": "Bearer sk_test_..."}, ) session = response.json() ``` PHP : ```php ["Authorization: Bearer sk_test_..."], CURLOPT_RETURNTRANSFER => true, ]); $session = json_decode(curl_exec($ch), true); ``` Go : ```go req, _ := http.NewRequest("GET", "https://api.abuna.app/v1/apps/8ddhXCDW/sessions/A4kN1oSs", nil) req.Header.Set("Authorization", "Bearer sk_test_...") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var session map[string]any json.NewDecoder(res.Body).Decode(&session) ``` **Réponse** ```json { "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` 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](https://abuna.app/docs/guides/sessions.md?hl=fr#expired-session-subscription). 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 : ```bash curl -X POST https://api.abuna.app/v1/apps/8ddhXCDW/sessions/A4kN1oSs/expire \ -H "Authorization: Bearer sk_test_..." ``` Node.js : ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/sessions/A4kN1oSs/expire", { method: "POST", headers: { Authorization: "Bearer sk_test_..." }, }); const session = await response.json(); ``` Python : ```python import requests response = requests.post( "https://api.abuna.app/v1/apps/8ddhXCDW/sessions/A4kN1oSs/expire", headers={"Authorization": "Bearer sk_test_..."}, ) session = response.json() ``` PHP : ```php true, CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_..."], CURLOPT_POSTFIELDS => "", CURLOPT_RETURNTRANSFER => true, ]); $session = json_decode(curl_exec($ch), true); ``` Go : ```go req, _ := http.NewRequest("POST", "https://api.abuna.app/v1/apps/8ddhXCDW/sessions/A4kN1oSs/expire", nil) req.Header.Set("Authorization", "Bearer sk_test_...") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var session map[string]any json.NewDecoder(res.Body).Decode(&session) ``` **Réponse** ```json { "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](https://abuna.app/docs/api/events.md?hl=fr#session-expired). ### 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](https://abuna.app/docs/api/sessions.md?hl=fr#create-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`](https://abuna.app/docs/api/customers.md?hl=fr#object) du client. Pour un [client qui revient](https://abuna.app/docs/api/sessions.md?hl=fr#returning-customers), elle peut se terminer sur son abonnement existant. Quand la session a proposé un [changement de formule](https://abuna.app/docs/api/sessions.md?hl=fr#checkout-switch), 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`](https://abuna.app/docs/api/sessions.md?hl=fr#type-plan-change) : **session.completed data pour un changement de formule** - `session_id` (string): La session. - `type` (string): Toujours `checkout`. - `subscription_id` (string): L'abonnement existant du client. - `customer_id` (string): Son client. - `metadata` (object): Les métadonnées transmises à la création de la session. - `completed_at` (timestamp): Quand la session s'est terminée. - `plan_offer_id` (string): L'proposition de changement de formule faite par la page d'abonnement. - `previous_price_id` (string): Le prix avant le changement. - `price_id` (string): Le nouveau prix, celui que vend la session. - `direction` (string): `upgrade` ou `downgrade`. - `effective_at` (timestamp): 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** ```json { "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](https://abuna.app/docs/api/sessions.md?hl=fr#create-payment). 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_id` (string): La session. - `type` (string): Toujours `payment`. - `invoice_id` (string): La facture payée par le client. - `subscription_id` (string): Son abonnement. - `customer_id` (string): Son client. - `metadata` (object): Les métadonnées transmises à la création de la session. - `completed_at` (timestamp): Quand la session s'est terminée. **session.completed data** ```json { "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](https://abuna.app/docs/api/sessions.md?hl=fr#create-plan-change). 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](https://abuna.app/docs/api/subscriptions.md?hl=fr#changing-plan). 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_id` (string): La session. - `type` (string): Toujours `plan_change`. - `subscription_id` (string): L'abonnement. - `customer_id` (string): Son client. - `metadata` (object): Les métadonnées transmises à la création de la session. - `completed_at` (timestamp): Quand la session s'est terminée. - `plan_offer_id` (string): L'proposition de changement de formule créée par la session. - `previous_price_id` (string): Le prix avant le changement. - `price_id` (string): Le nouveau prix. - `direction` (string): `upgrade` ou `downgrade`. - `effective_at` (timestamp): 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** ```json { "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](https://abuna.app/docs/api/subscriptions.md?hl=fr#cancel). Créée par [Créer une session de résiliation](https://abuna.app/docs/api/sessions.md?hl=fr#create-cancel). 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](https://abuna.app/docs/api/subscriptions.md?hl=fr#canceling) 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_id` (string): La session. - `type` (string): Toujours `cancel`. - `subscription_id` (string): L'abonnement. - `customer_id` (string): Son client. - `metadata` (object): Les métadonnées transmises à la création de la session. - `completed_at` (timestamp): Quand le client a confirmé. - `cancel_at` (timestamp, nullable): Quand l'abonnement prend fin. Null quand il a pris fin immédiatement. - `immediate` (boolean): `true` quand l'abonnement a pris fin immédiatement. **session.completed data** ```json { "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](https://abuna.app/docs/api/sessions.md?hl=fr#create-portal). 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_id` (string): La session. - `type` (string): Toujours `portal`. - `subscription_id` (string): L'abonnement. - `customer_id` (string): Son client. - `metadata` (object): Les métadonnées transmises à la création de la session. - `completed_at` (timestamp): Quand le client a ouvert l'espace client pour la première fois. **session.completed data** ```json { "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`.