Référence de l'API
Événements
Le journal de tout ce qui s'est passé dans une application, et chaque type d'événement.
Lisez les événements survenus dans votre application, comme une facture payée, pour garder vos données à jour avec Abuna. Abuna enregistre chaque événement, et l'envoie aussi à l'URL du webhook si vous en avez défini une.
L'objet event
Un événement a la même forme ici et dans un corps de webhook. Un webhook pour l'événement porte le même id.
Attributs
idstringIdentifiant unique de l'événement. Les ID d'événement se trient dans l'ordre où les événements ont eu lieu. Voir Ordre des événements.typestringLe type de l'événement.environmentstringtestoulive.created_attimestampQuand l'événement a eu lieu, en secondes Unix.dataobjectLes données de l'événement. Leurs champs dépendent du type.
{
"created_at": 1794780106,
"data": {
"amount": 5000,
"coupon_id": null,
"credit": 0,
"currency": "XAF",
"discount": 0,
"invoice_id": "OG3ZsOC7",
"invoice_number": "ACME-000001",
"kind": "period",
"metadata": {
"user_id": "42"
},
"paid_at": 1794780106,
"payment": {
"amount": 5000,
"app_id": "qhf83tDc",
"created_at": 1794780106,
"currency": "XAF",
"driver": "sandbox",
"exchange_margin_bps": null,
"exchange_rate": null,
"exchange_rate_at": null,
"fee": 100,
"id": "tGfwt5dd",
"marked_by_api_key_id": null,
"marked_by_user_id": null,
"message": null,
"method_label": "Successful payment (test)",
"net": null,
"note": null,
"original_amount": 5000,
"original_currency": "XAF",
"period_id": "0kYPFwxJ",
"provider": "test",
"provider_reference": "test_ff6aaf0182bd3f1148bd",
"session_id": null,
"status": "succeeded"
},
"period_end": 1797372106,
"period_id": "0kYPFwxJ",
"period_start": 1794780106,
"promotion_code_id": null,
"subscription": {
"activated_at": 1794780106,
"app_id": "qhf83tDc",
"cancel_at": null,
"cancel_at_period_end": false,
"canceled_at": null,
"created_at": 1794780106,
"current_period_end": 1797372106,
"current_period_start": 1794780106,
"customer_id": "GzeUZeSV",
"discount": null,
"ended_reason": null,
"id": "wTiODxvH",
"manage_token": "ac78d36db5c13e5f1bcbb67ece2ee29137a0",
"metadata": {
"user_id": "42"
},
"price_id": "IaFQHLTL",
"starts_at": 1794780106,
"status": "active",
"trial_ends_at": null
},
"subscription_id": "wTiODxvH"
},
"environment": "test",
"id": "01M7GKP458FZEMMQQ7VM7J4QK4",
"type": "invoice.paid"
}Lister les événements
GET/v1/apps/{appID}/events
Liste les événements de l'application, du plus récent au plus ancien, une page à la fois. Chaque page continue avec des événements plus anciens. Voir Listes et filtres.
Paramètres de requête
typestringUniquement les événements de ce type, commeinvoice.paid.limitintegerCombien d'événements renvoyer, de 1 à 100. Par défaut : 50.cursorstringLa valeurnext_cursorde la page précédente. Envoyez les mêmes filtres avec.
Attributs de la réponse
itemsarrayLes événements de la page, du plus récent au plus ancien. Vide quand rien ne correspond.next_cursorstringnullablePassez-le comme cursor pour obtenir la page suivante, plus ancienne. Il vaut null sur la dernière page. Traitez-le comme opaque.
Renvoie 200. Un limit en dehors de 1 à 100 renvoie 422 avec le code invalid et un élément errors pour limit.
curl "https://api.abuna.app/v1/apps/8ddhXCDW/events?type=invoice.paid" \
-H "Authorization: Bearer sk_test_..."{
"items": [
{
"created_at": 1794780106,
"data": {
"amount": 5000,
"coupon_id": null,
"credit": 0,
"currency": "XAF",
"discount": 0,
"invoice_id": "OG3ZsOC7",
"invoice_number": "ACME-000001",
"kind": "period",
"metadata": {
"user_id": "42"
},
"paid_at": 1794780106,
"payment": {
"amount": 5000,
"app_id": "qhf83tDc",
"created_at": 1794780106,
"currency": "XAF",
"driver": "sandbox",
"exchange_margin_bps": null,
"exchange_rate": null,
"exchange_rate_at": null,
"fee": 100,
"id": "tGfwt5dd",
"marked_by_api_key_id": null,
"marked_by_user_id": null,
"message": null,
"method_label": "Successful payment (test)",
"net": null,
"note": null,
"original_amount": 5000,
"original_currency": "XAF",
"period_id": "0kYPFwxJ",
"provider": "test",
"provider_reference": "test_ff6aaf0182bd3f1148bd",
"session_id": null,
"status": "succeeded"
},
"period_end": 1797372106,
"period_id": "0kYPFwxJ",
"period_start": 1794780106,
"promotion_code_id": null,
"subscription": {
"activated_at": 1794780106,
"app_id": "qhf83tDc",
"cancel_at": null,
"cancel_at_period_end": false,
"canceled_at": null,
"created_at": 1794780106,
"current_period_end": 1797372106,
"current_period_start": 1794780106,
"customer_id": "GzeUZeSV",
"discount": null,
"ended_reason": null,
"id": "wTiODxvH",
"manage_token": "ac78d36db5c13e5f1bcbb67ece2ee29137a0",
"metadata": {
"user_id": "42"
},
"price_id": "IaFQHLTL",
"starts_at": 1794780106,
"status": "active",
"trial_ends_at": null
},
"subscription_id": "wTiODxvH"
},
"environment": "test",
"id": "01M7GKP458FZEMMQQ7VM7J4QK4",
"type": "invoice.paid"
}
],
"next_cursor": "MDFKOVpROEUxRjJHM0g0SjVLNk03TjhQOVE"
}Récupérer un événement
GET/v1/apps/{appID}/events/{id}
Récupère un événement, dans la même forme que le corps de son webhook. Utilisez-le pour récupérer à nouveau un événement par l'id qu'un webhook vous a donné.
Renvoie l'événement. Si l'application n'a aucun événement avec cet ID, renvoie 404 avec le code not_found.
curl https://api.abuna.app/v1/apps/8ddhXCDW/events/01M7GKP458FZEMMQQ7VM7J4QK4 \
-H "Authorization: Bearer sk_test_..."{
"created_at": 1794780106,
"data": {
"amount": 5000,
"coupon_id": null,
"credit": 0,
"currency": "XAF",
"discount": 0,
"invoice_id": "OG3ZsOC7",
"invoice_number": "ACME-000001",
"kind": "period",
"metadata": {
"user_id": "42"
},
"paid_at": 1794780106,
"payment": {
"amount": 5000,
"app_id": "qhf83tDc",
"created_at": 1794780106,
"currency": "XAF",
"driver": "sandbox",
"exchange_margin_bps": null,
"exchange_rate": null,
"exchange_rate_at": null,
"fee": 100,
"id": "tGfwt5dd",
"marked_by_api_key_id": null,
"marked_by_user_id": null,
"message": null,
"method_label": "Successful payment (test)",
"net": null,
"note": null,
"original_amount": 5000,
"original_currency": "XAF",
"period_id": "0kYPFwxJ",
"provider": "test",
"provider_reference": "test_ff6aaf0182bd3f1148bd",
"session_id": null,
"status": "succeeded"
},
"period_end": 1797372106,
"period_id": "0kYPFwxJ",
"period_start": 1794780106,
"promotion_code_id": null,
"subscription": {
"activated_at": 1794780106,
"app_id": "qhf83tDc",
"cancel_at": null,
"cancel_at_period_end": false,
"canceled_at": null,
"created_at": 1794780106,
"current_period_end": 1797372106,
"current_period_start": 1794780106,
"customer_id": "GzeUZeSV",
"discount": null,
"ended_reason": null,
"id": "wTiODxvH",
"manage_token": "ac78d36db5c13e5f1bcbb67ece2ee29137a0",
"metadata": {
"user_id": "42"
},
"price_id": "IaFQHLTL",
"starts_at": 1794780106,
"status": "active",
"trial_ends_at": null
},
"subscription_id": "wTiODxvH"
},
"environment": "test",
"id": "01M7GKP458FZEMMQQ7VM7J4QK4",
"type": "invoice.paid"
}Ordre des événements
Les ID d'événement se trient dans l'ordre où les événements ont eu lieu. Comparez-les comme de simples chaînes : l'ID d'un événement plus tardif se trie après celui d'un événement plus ancien. created_at est en secondes entières, donc les événements d'un même changement le partagent souvent. Ordonnez les événements par id, pas par created_at.
Un même changement enregistre plusieurs événements à la fois. Ils arrivent dans cet ordre :
- Nouvel abonnement sans essai :
subscription.created, puisinvoice.created. - Renouvellement :
subscription.updatedsi un passage à une formule moins chère programmé commence avec la nouvelle période,subscription.renewed,subscription.past_duesi la nouvelle période a déjà commencé, puisinvoice.created. Un renouvellement émis avant la fin de la période payée envoiesubscription.past_duede son côté plus tard, à la fin de la période payée, s'il est encore impayé à ce moment-là. - Paiement :
customer.updateds'il donne au client son premier numéro de téléphone,subscription.updateds'il paie une montée de formule,session.completeds'il a été payé via une sessionpaymentou termine une sessionplan_change,invoice.paid, puis au premier paiementsubscription.paidet lesession.completeddu checkout, et enfinsubscription.recoveredsi l'abonnement étaitpast_due. - Suppression d'un client :
subscription.canceledpour chaque abonnement que la suppression a terminé, puiscustomer.deleted.
Rattraper les événements manqués
Si votre serveur a manqué des webhooks, listez les événements que vous n'avez pas traités et traitez-les maintenant. Commencez sans cursor, puis passez le next_cursor de chaque page jusqu'à ce qu'il soit null, ou jusqu'à atteindre des événements créés 5 minutes avant le plus récent que vous avez traité. Un événement peut être listé quelques secondes après un plus récent, donc ignorez ceux que vous avez déjà traités par id plutôt que de vous arrêter au premier. Traitez ce que vous avez collecté du plus ancien au plus récent.
const base = "https://api.abuna.app/v1/apps/8ddhXCDW/events?limit=100";
const headers = { Authorization: "Bearer sk_test_..." };
const newestHandledAt = 1727600600; // created_at of the newest event you handled
const stopAt = newestHandledAt - 5 * 60;
const missed = [];
let cursor = null;
let done = false;
while (!done) {
const url = base + (cursor ? "&cursor=" + encodeURIComponent(cursor) : "");
const page = await (await fetch(url, { headers })).json();
for (const event of page.items) {
if (event.created_at < stopAt) {
done = true;
break;
}
if (!(await alreadyHandled(event.id))) missed.push(event);
}
cursor = page.next_cursor;
if (!cursor) done = true;
}
// Oldest first, in the order the events happened.
for (const event of missed.reverse()) {
await handle(event);
}Types d'événement
Chaque type ci-dessous liste les champs de son data. Les ID sont des chaînes, les montants sont des entiers dans la plus petite unité de la devise, et les heures sont en secondes Unix.
Chaque événement dont le data contient un subscription_id contient aussi subscription : l'objet subscription complet, tel que Récupérer un abonnement le renvoie sous subscription, tel qu'il est juste après le changement que l'événement signale. Un événement de session dont le subscription_id est null n'a pas de subscription. Les listes ci-dessous omettent subscription.
L'abonnement inclut trial_ends_at : la fin de l'essai en secondes Unix, ou null sans essai. Son statut est trialing pendant un essai gratuit.
Les événements d'abonnement, de facture et d'offre de formule portent les métadonnées de l'abonnement au moment où l'événement est enregistré. Les événements de session portent lemetadata propre à la session, pas celui de l'abonnement. Passez du metadata à chaque session que vous créez. Sans cela, les événements de session portent {}. Les listes ci-dessous omettent le metadata sauf indication contraire.
session.completed
Une session s'est terminée. Une session se termine au plus une fois, et une session expirée ne se termine jamais. Le data dépend du type de la session. Chaque type a session_id, type, subscription_id, customer_id, metadata (le metadata que vous avez passé à la création de la session) et completed_at.
checkout(Créer une session checkout) : sans essai, le premier paiement a réussi et l'abonnement est maintenantactive. Pour un essai gratuit, la session se termine à son démarrage, avecstatus: trialinget sans paiement. Sans essai,subscription.paidest enregistré au même moment. Ajouteprice_id, le prix de l'abonnement, etupdates, lesupdatesdu client. Quand la page d'abonnement a plutôt changé la formule d'un client qui revient, la session s'est terminée une fois le changement confirmé, ou payé pour une montée de formule.subscription_idest son abonnement existant, et les données ajoutent les champsplan_changeci-dessous au lieu deupdates.payment(Créer une session de paiement) : la facture a été payée via la session.invoice.paidest aussi envoyé. Ajouteinvoice_id.plan_change(Créer une session de changement de formule) : le client a confirmé le changement, et l'a payé s'il s'agissait d'une montée de formule avec quelque chose à payer. Ajoute les champs ci-dessous.cancel(Créer une session de résiliation) : le client a confirmé la résiliation, programmée ou immédiate.subscription.updated(programmée) ousubscription.canceled(immédiate) est aussi envoyé. Ajoute les champs ci-dessous.portal(Créer une session d'espace client) : le client a ouvert son espace client pour la première fois. Cela ne signifie pas qu'il a changé quelque chose. Ce qu'il y fait envoie ses propres événements, commesubscription.updated,subscription.canceled,invoice.paidetcustomer.updated. N'ajoute rien.
plan_change data, et le changement de formule d'une checkout, ajoutés
plan_offer_idstringL'offre de formule derrière la session.previous_price_idstringLe prix avant le changement.price_idstringLe nouveau prix.directionstringupgradeoudowngrade.effective_attimestampQuand le nouveau prix commence. Pour un passage à une formule moins chère, ou une montée de formule au prochain renouvellement, la fin de la période payée :subscription.updatedse déclenche alors avec le changement de prix.
cancel data ajoutés
cancel_attimestampnullableQuand l'abonnement prend fin.subscription.canceledse déclenche alors. Null quand il a pris fin tout de suite.immediatebooleantruequand l'abonnement a pris fin tout de suite.
session.expired
Une session ouverte a expiré à son expires_at, ou vous l'avez fait expirer. Abuna ne fait pas expirer une session checkout de lui-même pendant que son paiement est en attente. Un abonnement pending démarré par une session checkout reste, et prend fin avec checkout_expired s'il n'est pas payé à temps.
Une session payment expire aussi quand sa facture est payée autrement, annulée, ou quand son abonnement prend fin. Une session plan_change expire aussi quand son offre est remplacée, annulée ou expirée, ou quand une montée de formule qu'elle a démarrée expire faute de paiement. Une session checkout qui a proposé un changement de formule expire de la même façon, au lieu de 24 heures après. Une session cancel expire 24 heures après sa création si le client ne confirme pas, et une session portal 1 heure après sa création si personne ne l'ouvre. Voir Types de session.
data
session_idstringLa session.typestringLe type de la session :checkout,payment,plan_change,cancelouportal.subscription_idstringnullableL'abonnement que la session a démarré ou sur lequel elle agit. Pour checkout, null si le client n'est pas allé jusque-là.customer_idstringnullableLe client que vous avez passé, ou celui créé à partir des coordonnées du client. Null si aucun des deux.price_idstringnullableLe prix de la session, ou null pour les sessions payment, cancel et portal.invoice_idstringnullableLa facture de la session payment, ou null pour les autres types.plan_offer_idstringnullableL'offre d'une session plan_change, ou d'une session checkout qui a proposé un changement de formule. Null sinon.metadataobjectLe metadata que vous avez passé à la création de la session.expired_attimestampQuand la session a expiré.
{
"customer_id": "GzeUZeSV",
"expired_at": 1794780106,
"invoice_id": null,
"metadata": {
"user_id": "42"
},
"plan_offer_id": null,
"price_id": null,
"session_id": "XYKz5u9G",
"subscription": {
"activated_at": 1794780106,
"app_id": "qhf83tDc",
"cancel_at": null,
"cancel_at_period_end": false,
"canceled_at": null,
"created_at": 1794780106,
"current_period_end": 1797372106,
"current_period_start": 1794780106,
"customer_id": "GzeUZeSV",
"discount": null,
"ended_reason": null,
"id": "wTiODxvH",
"manage_token": "ac78d36db5c13e5f1bcbb67ece2ee29137a0",
"metadata": {
"user_id": "42"
},
"price_id": "IaFQHLTL",
"starts_at": 1794780106,
"status": "active",
"trial_ends_at": null
},
"subscription_id": "wTiODxvH",
"type": "cancel"
}subscription.created
Un abonnement a été créé, via l'API, une session checkout ou un lien d'abonnement. Il est trialing si un essai gratuit s'applique, ou pending sans essai.
data
subscription_idstringLe nouvel abonnement.customer_idstringSon client.price_idstringSon prix.period_idstringSa période d'essai gratuit, ou sa première période de facturation sans essai.
subscription.paid
La première période a été payée et l'abonnement est maintenant active. Après un essai gratuit, c'est le paiement de la première facture, quel que soit le moment où le client la paie. Le début d'un essai ne l'envoie pas. Les paiements suivants envoient invoice.paid, et subscription.recovered quand ils ramènent un abonnement past_due à active.
data
subscription_idstringL'abonnement.customer_idstringSon client.price_idstringSon prix.period_idstringLa première période payée.activated_attimestampQuand l'abonnement a commencé : le début de l'essai, ou le premier paiement sans essai.
subscription.trial_ending
Un essai gratuit se termine bientôt. Abuna émet cet événement selon le délai habituel des rappels de renouvellement de votre application. La date de fin est data.subscription.trial_ends_at, en secondes Unix. L'événement contient l'abonnement et ses métadonnées, comme décrit plus haut. Voir Essais gratuits.
Une URL de webhook ajoutée à partir de maintenant reçoit cet événement par défaut. Une URL configurée avant l'arrivée des essais gratuits ne le reçoit pas tant que vous ne l'activez pas : un propriétaire d'équipe ouvre Webhooks dans le tableau de bord, modifie les Événements et le coche.
subscription.renewed
Après un essai, la première période payante commence à trial_ends_at, même si le client paie en avance.
Abuna a émis la période de facturation suivante et sa facture. Cela se produit avant la fin de la période payée ou de l'essai, d'autant de jours à l'avance que l'indique renewal_lead_days de l'application (3 par défaut), ou quand elle se termine avec 0. La nouvelle période commence quand la période payée se termine, et le client peut la payer dès maintenant. Si elle est encore impayée à la fin de la période payée, subscription.past_due suit alors.
data
subscription_idstringL'abonnement.period_idstringLa nouvelle période de facturation.amountintegerLe montant dû pour la nouvelle période.currencystringXAF,XOFouUSD.
subscription.past_due
La période payée ou l'essai a pris fin et la période suivante n'est pas payée, donc l'abonnement est maintenant impayé (past_due). Un renouvellement payé avant la période payée ne l'envoie jamais. Gardez l'accès du client tant qu'il est past_due. Si la période n'est pas payée à sa date limite de paiement, subscription.canceled suit avec la raison non_payment.
data
subscription_idstringL'abonnement.metadataobjectLes métadonnées de l'abonnement.
subscription.recovered
La facture d'un abonnement past_due a été payée, donc il est de nouveau active. Il vient juste après invoice.paid. Il vient aussi quand un paiement qui arrive après une résiliation pour non-paiement ramène l'abonnement ; voir Paiements qui arrivent en retard. Le data est le même que celui de subscription.past_due.
subscription.updated
Un abonnement en cours, y compris un essai, a changé. Cet événement est émis quand une résiliation à la fin de la période payée ou de l'essai est programmée ou retirée, quand le prix change (une montée de formule prend effet, ou un passage à une formule moins chère programmé commence), quand un passage à une formule moins chère, ou une montée de formule au prochain renouvellement, est programmé ou retiré, quand une montée de formule en attente de paiement expire, et quand un nouveau changement en efface un précédent. Pour une résiliation programmée, subscription.canceled suit quand elle prend fin. Voir Changer de formule.
data
subscription_idstringL'abonnement.price_idstringLe prix sur lequel l'abonnement est actuellement.cancel_attimestampnullableQuand l'abonnement prendra fin, si une résiliation est programmée. Null sinon.cancel_at_period_endbooleantruetant qu'une résiliation est programmée pour la fin de la période payée,falsesinon.scheduled_price_changeobjectnullableLe passage à une formule moins chère, ou la montée de formule au prochain renouvellement, programmé pour la fin de la période payée. Null quand il n'y en a pas.Afficher les attributsMasquer les attributs
price_idstringLe prix vers lequel l'abonnement passe.effective_attimestampQuand il passe.
changeobjectCe qui est arrivé au prix. Présent uniquement quand le prix a changé, ou qu'un passage à une formule moins chère ou une montée de formule au prochain renouvellement a été programmé ou retiré. Une montée de formule expirée, une résiliation à la fin de la période, et une montée de formule qui commence à attendre un paiement n'en ont pas.Afficher les attributsMasquer les attributs
typestringprice_changed,downgrade_scheduled,downgrade_undone,upgrade_scheduledouupgrade_undone.old_price_idstringLe prix avant.new_price_idstringLe nouveau prix, ou celui programmé.effective_attimestampQuand le changement a pris effet, ou quand le changement programmé le fera.
updated_bystringmerchantquand vous l'avez changé, oucustomerquand le client l'a changé dans son espace client ou a changé de formule sur une page d'abonnement. Quand un changement de formule est exécuté plus tard (une montée de formule payée, un passage à une formule moins chère qui commence, une montée de formule qui expire), c'est celui qui l'a demandé :customerdepuis l'espace client ou une page d'abonnement, oumerchantquand il a confirmé un changement vers lequel vous l'avez envoyé.
subscription.canceled
L'abonnement a pris fin. Il se déclenche quand l'abonnement prend vraiment fin : tout de suite pour une résiliation immédiate, ou à la fin de la période payée pour une résiliation programmée. Programmer une résiliation envoie subscription.updated à la place. Le subscription dans le data a ended_reason unpaid pour non_payment et checkout_expired, et canceled pour les autres.
data
subscription_idstringL'abonnement.reasonstringPourquoi il a pris fin :merchant(vous l'avez résilié),customer(le client l'a résilié dans son espace client),non_payment(un renouvellement a dépassé sa date limite de paiement), oucheckout_expired(la première période n'a jamais été payée). Une résiliation programmée qui prend fin garde qui l'a programmée,merchantoucustomer.
plan_offer.created
Une session de changement de formule a créé une offre de formule, une page d'abonnement a proposé à un client qui revient de changer de formule, ou vous avez proposé un changement depuis le tableau de bord et Abuna a envoyé le lien au client. Une session de changement de formule n'envoie pas d'e-mail ; un changement demandé au paiement envoie son lien de confirmation uniquement par e-mail. Renvoyer le lien depuis le tableau de bord ne le déclenche pas à nouveau. Les quatre plan_offer événements partagent le même data.
data
offer_idstringL'offre.subscription_idstringL'abonnement.price_idstringLe prix proposé.expires_attimestampQuand l'offre cesse de fonctionner.
plan_offer.confirmed
Le client a accepté l'offre. Un passage à une formule moins chère, ou une montée de formule au prochain renouvellement, est maintenant programmé, ou une montée de formule est appliquée ou en attente de paiement. subscription.updated se déclenche quand le prix change ou que le changement est programmé.
plan_offer.canceled
L'offre a cessé avant que le client l'accepte. Le data ajoute reason : merchant quand vous l'avez annulée, ou replaced quand une nouvelle offre ou le propre changement de formule du client a pris sa place, ou que l'abonnement a été résilié. Une résiliation enregistre plan_offer.canceled juste avant subscription.canceled, qui a donc l'id d'événement le plus grand.
plan_offer.expired
L'offre a atteint son expires_at sans être acceptée.
invoice.created
Abuna a émis une facture pour une nouvelle période de facturation, ou pour une montée de formule. Une montée de formule en attente de paiement reçoit les dates de sa période quand elle est payée, et invoice.paid les porte.
data
invoice_idstringLa facture.invoice_numberstringSon numéro.subscription_idstringSon abonnement.period_idstringLa période de facturation qu'elle facture.kindstringperiodpour une période de facturation, ouplan_changepour la première période d'une montée de formule.amountintegerLe montant dû.creditintegerLe temps inutilisé de la période en cours déduit du nouveau prix.0sur une factureperiod.discountintegerCe que le coupon de la facture a retiré.0sans coupon.amountest déjà après cette réduction. Voir l'objet invoice.coupon_idstringnullableLe coupon qui a accordé la réduction. Null sans coupon.promotion_code_idstringnullableLe code promotionnel qui a apporté le coupon. Null quand vous avez appliqué le coupon directement, sans code.currencystringXAF,XOFouUSD.period_starttimestampQuand la période commence.period_endtimestampQuand la période se termine.
invoice.paid
Une facture a été payée. Un renouvellement payé avant le début de sa période est tout de même pour cette période : period_start ne bouge pas. Une facture qui a été annulée peut aussi devenir payée, quand un paiement que le client a approuvé avant son annulation aboutit ; voir Paiements qui arrivent en retard. Le data a tous les champs de invoice.created, plus deux. Ses amount et currency restent ceux de la facture, dans la devise du prix.
data
paid_attimestampQuand elle a été payée.paymentobjectLe paiement qui a réglé la facture, sous la forme de l'objet payment. Sesamountetcurrencysont ce que le client a payé, en FCFA pour le mobile money. Quand la facture était dans une autre devise,original_amount,original_currencyetexchange_ratemontrent la conversion.
invoice.payment_failed
Un paiement sur une facture a échoué. La facture reste ouverte, donc le client peut réessayer avant la date limite de paiement.
Certains paiements sont signalés comme échoués avant que le prestataire ait confirmé leur issue, par exemple quand il ne répond pas à temps. Un tel paiement peut encore aboutir plus tard, en général dans les 7 jours suivant son début. Un paiement échoué pour une raison précise, comme insufficient_funds, reste échoué, sauf si le prestataire indique ensuite qu'il a été payé. Dès qu'un paiement échoué est payé, vous recevez invoice.paid, et la facture est paid. Considérez invoice.paid comme la réponse définitive : ne remboursez pas le client et ne coupez pas son accès sur la seule base de invoice.payment_failed.
data
subscription_idstringL'abonnement.period_idstringLa période de facturation.invoice_idstringLa facture.invoice_numberstringSon numéro.provider_referencestringL'ID du prestataire pour le débit. Vide s'il n'en a donné aucun.failurestringLa raison de l'échec, avec les mêmes codes qu'un débit refusé en402, commeinsufficient_funds. Vautpayment_declinedsi le prestataire n'a donné aucune raison.messagestringUne courte note sur l'échec, à lire. Ne l'analysez pas, car sa formulation peut changer. Branchez surfailure. Vide quand il n'y a pas de note.paymentobjectLe paiement qui a échoué, sous la forme de l'objet payment, avec le montant qu'il a tenté de débiter.
customer.updated
Le nom, l'e-mail, le numéro de téléphone ou les métadonnées d'un client ont changé. Il est aussi envoyé quand un client sans numéro de téléphone paie pour la première fois : son phone_number est maintenant le numéro qui a payé, et updated_by vaut customer.
data
customer_idstringLe client.namestringnullableSon nom maintenant.emailstringSon adresse e-mail maintenant.phone_numberstringnullableSon numéro de téléphone maintenant. Null jusqu'à son premier paiement s'il est venu par la page d'abonnement.metadataobjectLes métadonnées du client.updated_bystringmerchantquand vous l'avez changé, oucustomerquand le client l'a changé dans son espace client ou que son premier paiement lui a donné un numéro de téléphone.updatesobjectLesupdatesdu client maintenant.
customer.updates_changed
Le statut Telegram ou WhatsApp d'un client a changé. Cela arrive quand le client s'abonne sur une page d'abonnement, connecte une messagerie à l'étape de paiement de la page d'abonnement ou dans son espace client, l'active (dans Telegram, ou en confirmant son numéro WhatsApp avec un code), l'arrête en envoyant « arrêt » dans la discussion, le désactive dans son espace client, ou, pour WhatsApp, a un numéro qui ne peut pas recevoir de messages. Un changement que vous faites aux paramètres de messagerie de votre application ne l'envoie pas. Chaque changement envoie un événement, et un statut qui reste le même n'en envoie aucun.
data
customer_idstringLe client.channelstringLa messagerie dont le statut a changé :telegramouwhatsapp.statusstringLe statut maintenant :off,active,stopped, ou, pour Telegram,pending, et, pour WhatsApp,failed.previous_statusstringLe statut avant.updatesobjectLesupdatesdu client maintenant.
{
"customer_id": "Cu5tM8rA",
"channel": "telegram",
"status": "active",
"previous_status": "pending",
"updates": {
"channel": "telegram",
"email": {
"status": "active"
},
"telegram": {
"status": "active",
"connected_at": 1727600300,
"connect_url": null
},
"whatsapp": {
"status": "off",
"connected_at": null,
"connect_url": null
}
}
}Listez ces événements pour voir combien de clients ont activé une messagerie :
curl "https://api.abuna.app/v1/apps/8ddhXCDW/events?type=customer.updates_changed" \
-H "Authorization: Bearer sk_test_..."customer.deleted
Vous avez supprimé un client. Ses abonnements ont pris fin et ses données personnelles sont effacées, donc l'événement n'en contient aucune. Quand vous le recevez, supprimez votre propre copie des données du client. Il arrive après les événements subscription.canceled de cette suppression. Supprimer de nouveau le même client n'envoie rien.
data
customer_idstringLe client.deleted_bystringmerchant: vous avez supprimé le client, avec votre clé secrète ou dans le tableau de bord. C'est la seule valeur aujourd'hui.
{
"customer_id": "Cu5tM8rA",
"deleted_by": "merchant"
}price_change.scheduled
Vous avez programmé un nouveau montant pour un prix, ou remplacé celui qui était en attente. Les trois price_change événements partagent le même data.
data
price_change_idstringLe changement.price_idstringLe prix.amountintegerLe nouveau montant.previous_amountintegerLe montant avant le changement.currencystringXAF,XOFouUSD.effective_attimestampMinuit au début du jour à partir duquel le nouveau montant s'applique, dans timezone.timezonestringLe fuseau horaire de votre application, commeAfrica/Douala. C'est letimezonede l'application.keep_current_subscribersbooleantruequand toutes les personnes abonnées ce jour-là gardent l'ancien montant.
price_change.canceled
Un changement en attente s'est arrêté avant son jour. Le data ajoute reason : merchant quand vous l'avez annulé, ou replaced quand vous avez programmé un nouveau changement à sa place. Un remplacement envoie aussi price_change.scheduled.
price_change.applied
Le montant du prix est passé au nouveau à son effective_at. L'événement arrive dans environ une minute après ce moment. À partir de là, les checkouts et les nouveaux abonnements le paient. Les abonnés actuels y passent à leur prochain renouvellement, sauf si keep_current_subscribers est true.
notification.captured
Mode Test uniquement. Abuna a rédigé un message pour un client Test et en a conservé une copie ici. La plupart des messages Test ne sont pas envoyés ; sent indique lesquels l'ont été. Cet événement ne va jamais vers l'URL du webhook.
data
customer_idstringLe client. Absent pourprofile_code, car la personne n'est peut-être pas encore cliente.kindstringCe sur quoi porte le message. Voir types de messages aux clients. Un type de plus n'apparaît qu'ici :profile_code, le code des informations enregistrées d'un client sur la page d'abonnement.channelstringemail,telegramouwhatsapp.recipientstringL'adresse e-mail, le numéro WhatsApp ou la conversation Telegram auxquels il est allé, ou serait allé.subjectstringLa ligne d'objet. Pour un code par e-mail, elle contient le code.textstringLe message, en texte brut.sentbooleantruepour les trois codes par e-mail que le mode Test envoie comme en production :trial_email_code,email_codeetprofile_code.falsepour tous les autres messages, qui n'ont pas été envoyés.