# Factures et paiements > Les périodes de facturation, leurs factures et les paiements associés. Listez et lisez les factures. Source : https://abuna.app/docs/api/invoices-and-payments?hl=fr Ces endpoints servent à lire les factures, à les débiter et à enregistrer les paiements reçus en dehors d'Abuna. Un abonnement facture une période à la fois : chaque période a une facture, et chaque tentative pour la payer est un paiement. Pour lire les trois d'un abonnement, [récupérez l'abonnement](https://abuna.app/docs/api/subscriptions.md?hl=fr#retrieve). Pour envoyer un client vers la page de paiement d'une facture ouverte, utilisez [Créer une session de paiement](https://abuna.app/docs/api/sessions.md?hl=fr#create-payment). ## L'objet billing period Créer un abonnement renvoie sa première période de facturation dans `period`. Abuna crée la suivante quand une période payée se termine, et émet sa facture. **Attributs** - `id` (string): Identifiant unique de la période de facturation. - `subscription_id` (string): L'abonnement auquel appartient la période. - `price_id` (string): Le prix facturé pour la période. - `pay_token` (string): Le jeton du lien de paiement de la période. - `starts_at` (timestamp): Quand la période commence, en secondes Unix. - `ends_at` (timestamp): Quand la période se termine, en secondes Unix. - `period_index` (integer): La position de la période dans l'abonnement, à partir de `0`. - `grace_period_ends_at` (timestamp): La date limite de paiement : le délai de paiement de l'application après le début de la période, mais jamais après sa fin. Si elle passe sans paiement, Abuna résilie l'abonnement. - `paid_at` (timestamp, nullable): Quand la période a été payée. - `paused_at` (timestamp, nullable): Réservé aux périodes en pause. Toujours null. - `in_force` (boolean): `false` pour la période d'une [mise à niveau](https://abuna.app/docs/api/subscriptions.md?hl=fr#upgrades) pendant qu'elle attend le paiement, et définitivement si la mise à niveau échoue. Une telle période ne compte pas parmi les périodes de l'abonnement, et la période suivante réutilise son `period_index`. - `created_at` (timestamp): Quand la période a été créée, en secondes Unix. **L'objet billing period** ```json { "id": "T6yVr3Dp", "subscription_id": "x9QbL2sK", "price_id": "Zt6YbN3q", "pay_token": "3a7e1c9f5b2d8a4e6c0f7b3d9a1e5c8f2b6d", "starts_at": 1727600000, "ends_at": 1730192000, "period_index": 0, "grace_period_ends_at": 1727686400, "paid_at": null, "paused_at": null, "in_force": true, "created_at": 1727600000 } ``` ## L'objet invoice Une facture conserve le montant, l'acheteur et le vendeur tels qu'ils étaient quand Abuna l'a émise. Les changements ultérieurs ne la modifient pas. Les numéros de facture se présentent par exemple `MYST-000124` : le préfixe [`invoice_prefix`](https://abuna.app/docs/api/apps.md?hl=fr#object) de l'application, puis le nombre de factures de l'application, complété à 6 chiffres et plus long au-delà de 999999. Chaque facture émise par l'application prend le numéro suivant, donc les numéros ne se répètent jamais et aucun n'est sauté. Le mode Production et le mode Test comptent séparément. Un numéro ne change jamais une fois émis, même si vous modifiez le préfixe. **Attributs** - `id` (string): Identifiant unique de la facture. - `app_id` (string): L'application qui a émis la facture. - `period_id` (string): La période de facturation facturée. - `subscription_id` (string): L'abonnement auquel appartient la facture. - `number` (string): Le numéro de facture, par exemple `MYST-000124`. Voir [numéros de facture](https://abuna.app/docs/api/invoices-and-payments.md?hl=fr#invoice-numbers). - `status` (string): `open` jusqu'au paiement, puis `paid`. `void` quand l'abonnement a été résilié avant le paiement, ou qu'un changement de formule l'a remplacée. Une facture annulée devient `paid` si un paiement que le client avait déjà approuvé passe après son annulation. Voir [Paiements qui arrivent en retard](https://abuna.app/docs/api/subscriptions.md?hl=fr#late-payments). - `kind` (string): `period` pour une période de facturation, ou `plan_change` pour la première période d'une mise à niveau. Voir [Mises à niveau](https://abuna.app/docs/api/subscriptions.md?hl=fr#upgrades). - `amount` (integer): Le montant dû, dans la plus petite unité de la devise. - `credit` (integer): Le temps inutilisé de la période précédente déduit du prix. `0` sauf si `kind` vaut `plan_change`. - `currency` (string): La devise du prix : `XAF`, `XOF` ou `USD`. - `item_label` (string): Le nom du prix. - `buyer_name` (string, nullable): Le nom du client. - `buyer_email` (string, nullable): L'adresse e-mail du client. - `seller_name` (string): Le nom de l'application. - `period_start` (timestamp): Quand la période facturée commence. - `period_end` (timestamp): Quand la période facturée se termine. - `due_at` (timestamp): La date limite de paiement. - `created_at` (timestamp): Quand la facture a été émise, en secondes Unix. - `paid_at` (timestamp, nullable): Quand la facture a été payée. - `voided_at` (timestamp, nullable): Quand la facture a été annulée. Null de nouveau dès qu'un paiement tardif la rend payée. - `discount` (integer): Ce que le coupon de la facture a retiré, dans la plus petite unité de la devise. `0` sans coupon. `amount` est déjà après cette réduction. - `coupon_id` (string, nullable): Le [coupon](https://abuna.app/docs/api/coupons.md?hl=fr#object) qui a accordé la réduction. Null sans coupon. - `promotion_code_id` (string, nullable): Le code promotionnel qui a apporté le coupon. Null quand vous avez appliqué le coupon directement, sans code. **L'objet invoice** ```json { "id": "V2nC8xEi", "app_id": "8ddhXCDW", "period_id": "T6yVr3Dp", "subscription_id": "x9QbL2sK", "number": "MYST-000124", "status": "open", "kind": "period", "amount": 5000, "credit": 0, "currency": "XAF", "item_label": "Monthly", "buyer_name": "Jane Doe", "buyer_email": "jane@example.com", "seller_name": "My store", "period_start": 1727600000, "period_end": 1730192000, "due_at": 1727686400, "created_at": 1727600000, "paid_at": null, "voided_at": null, "discount": 0, "coupon_id": null, "promotion_code_id": null } ``` ## L'objet payment Les clients paient par mobile money en FCFA. Quand la facture est dans une autre devise, le paiement enregistre la conversion : une facture de 10,00 $ payée avec un numéro camerounais est débitée de 6 039 FCFA, au taux du jour plus 2 %. Voir [Paiement en FCFA](https://abuna.app/docs/amounts-currencies-and-timestamps.md?hl=fr#paying-in-fcfa). **Attributs** - `id` (string): Identifiant unique du paiement. - `app_id` (string): L'application à laquelle appartient le paiement. - `period_id` (string): La période de facturation concernée par le paiement. - `driver` (string): Le prestataire de paiement, par exemple `pawapay`. `abuna` pour un paiement via [Paiements Abuna](https://abuna.app/docs/guides/payment-providers.md?hl=fr#abuna-payments), `sandbox` pour un paiement Test simulé, et `manual` pour un paiement que vous avez [marqué payé](https://abuna.app/docs/api/invoices-and-payments.md?hl=fr#mark-paid). - `provider` (string): Le réseau que le prestataire a débité, par exemple `MTN_MOMO_CMR`. `manual` pour un paiement que vous avez marqué payé. - `provider_reference` (string, nullable): L'identifiant propre au prestataire pour le débit. - `amount` (integer): Le montant débité, dans la plus petite unité de la devise. - `currency` (string): La devise débitée. Pour le mobile money, celle du réseau : `XAF` ou `XOF`. Pour un paiement que vous avez [marqué payé](https://abuna.app/docs/api/invoices-and-payments.md?hl=fr#mark-paid), la devise de la facture, sans conversion. - `original_amount` (integer, nullable): Le montant de la facture, dans la plus petite unité de sa devise. Null pour les paiements faits avant le 13 novembre 2026. - `original_currency` (string, nullable): La devise de la facture : `XAF`, `XOF` ou `USD`. Null pour les paiements faits avant le 13 novembre 2026. - `exchange_rate` (number, nullable): Les francs débités par unité de `original_currency` (par dollar pour l'USD), 2 % compris, par exemple `603.8094`. `1` entre XOF et XAF. Null quand la facture était déjà dans la devise débitée. - `exchange_margin_bps` (integer, nullable): La marge comprise dans `exchange_rate`, en centièmes de pour cent : `200` vaut 2 %. `0` entre XOF et XAF. Null quand la facture était déjà dans la devise débitée. - `exchange_rate_at` (timestamp, nullable): Quand le taux utilisé a été publié, en secondes Unix. Entre XOF et XAF, quand le paiement a commencé. Null quand la facture était déjà dans la devise débitée. - `status` (string): `pending`, `succeeded` ou `failed`. Un paiement `failed` dont le prestataire n'avait pas confirmé l'issue peut encore devenir `succeeded`, en général dans les 7 jours suivant son début ; voyez [`invoice.payment_failed`](https://abuna.app/docs/api/events.md?hl=fr#invoice-payment-failed). - `message` (string, nullable): Une courte note sur le paiement, à lire, par exemple la raison d'un échec. Ne l'analysez pas : sa formulation peut changer. Pour savoir pourquoi un paiement a échoué, lisez `failure` dans [`invoice.payment_failed`](https://abuna.app/docs/api/events.md?hl=fr#invoice-payment-failed). Null quand il n'y a pas de note. - `created_at` (timestamp): Quand le paiement a commencé, en secondes Unix. - `fee` (integer, nullable): Les frais du prestataire, dans la plus petite unité de la devise. En mode Production, ils valent null jusqu'à ce que le prestataire les communique. En mode Test, c'est une estimation. Pour un paiement via [Paiements Abuna](https://abuna.app/docs/guides/payment-providers.md?hl=fr#abuna-payments), ce sont plutôt les frais d'Abuna de 3,5 %, arrondis au franc inférieur, fixés une fois le paiement réussi. - `net` (integer, nullable): Pour un paiement via [Paiements Abuna](https://abuna.app/docs/guides/payment-providers.md?hl=fr#abuna-payments), ce que vous recevez : `amount` moins `fee`, fixé une fois le paiement réussi. Null pour tout autre paiement. - `session_id` (string, nullable): La session utilisée pour ce paiement, ou null pour un paiement effectué autrement. - `note` (string, nullable): Pour un paiement que vous avez marqué payé, la note que vous avez donnée sur la façon dont le client a payé. Les clients ne la voient jamais. Null sinon. - `marked_by_user_id` (string, nullable): Pour un paiement marqué payé depuis le tableau de bord, l'identifiant du membre de l'équipe qui l'a marqué. Null sinon. - `marked_by_api_key_id` (string, nullable): Pour un paiement marqué payé avec une clé secrète, l'identifiant de cette clé. Null sinon. - `method_label` (string): Le nom du réseau, en toutes lettres. `Paid outside Abuna` pour un paiement que vous avez marqué payé. **L'objet payment** ```json { "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" } ``` **Une facture de 10,00 $ payée en XAF** ```json { "amount": 6039, "app_id": "qhf83tDc", "created_at": 1794780106, "currency": "XAF", "driver": "sandbox", "exchange_margin_bps": 200, "exchange_rate": 603.8094, "exchange_rate_at": 1791100800, "fee": 120, "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": 1000, "original_currency": "USD", "period_id": "0kYPFwxJ", "provider": "test", "provider_reference": "test_ff6aaf0182bd3f1148bd", "session_id": null, "status": "succeeded" } ``` ## L'objet invoice summary Les endpoints de facture renvoient les factures sous cette forme. Elle ajoute le client et indique si la facture est impayée après sa date limite de paiement, et omet `app_id`, `period_id` et `seller_name`. **Attributs** - `id` (string): Identifiant unique de la facture. - `number` (string): Le numéro de facture, par exemple `MYST-000124`. Voir [numéros de facture](https://abuna.app/docs/api/invoices-and-payments.md?hl=fr#invoice-numbers). - `status` (string): `open` jusqu'au paiement, puis `paid`. `void` quand l'abonnement a été résilié avant le paiement, ou qu'un changement de formule l'a remplacée. Une facture annulée devient `paid` si un paiement que le client avait déjà approuvé passe après son annulation. Voir [Paiements qui arrivent en retard](https://abuna.app/docs/api/subscriptions.md?hl=fr#late-payments). - `overdue` (boolean): `true` quand la facture est `open` et que sa `due_at` est passée. La valeur est calculée à chaque requête. Ce n'est pas un statut. - `kind` (string): `period` ou `plan_change`, comme sur l'[objet invoice](https://abuna.app/docs/api/invoices-and-payments.md?hl=fr#invoice-object). - `amount` (integer): Le montant dû, dans la plus petite unité de la devise. - `credit` (integer): Le temps inutilisé déduit du prix, comme sur l'objet invoice. - `currency` (string): La devise du prix : `XAF`, `XOF` ou `USD`. - `item_label` (string): Le nom du prix. - `buyer_name` (string, nullable): Le nom du client. - `buyer_email` (string, nullable): L'adresse e-mail du client. - `subscription_id` (string): L'abonnement auquel appartient la facture. - `customer_id` (string): Le client de l'abonnement. - `period_start` (timestamp): Quand la période facturée commence. - `period_end` (timestamp): Quand la période facturée se termine. - `due_at` (timestamp): La date limite de paiement de la période de facturation (`grace_period_ends_at`), telle qu'elle est maintenant. Elle peut différer de la `due_at` de l'[objet invoice](https://abuna.app/docs/api/invoices-and-payments.md?hl=fr#invoice-object), qui est fixée à l'émission de la facture. - `created_at` (timestamp): Quand la facture a été émise, en secondes Unix. - `paid_at` (timestamp, nullable): Quand la facture a été payée. - `voided_at` (timestamp, nullable): Quand la facture a été annulée. Null de nouveau dès qu'un paiement tardif la rend payée. - `discount` (integer): Ce que le coupon de la facture a retiré, comme sur l'objet invoice. - `coupon_id` (string, nullable): Le coupon qui a accordé la réduction, comme sur l'objet invoice. - `promotion_code_id` (string, nullable): Le code promotionnel qui a apporté le coupon, comme sur l'objet invoice. **L'objet invoice summary** ```json { "id": "V2nC8xEi", "number": "MYST-000124", "status": "open", "overdue": false, "kind": "period", "amount": 5000, "credit": 0, "currency": "XAF", "item_label": "Monthly", "buyer_name": "Jane Doe", "buyer_email": "jane@example.com", "subscription_id": "x9QbL2sK", "customer_id": "Cu5tM8rA", "period_start": 1727600000, "period_end": 1730192000, "due_at": 1727686400, "created_at": 1727600000, "paid_at": null, "voided_at": null, "discount": 0, "coupon_id": null, "promotion_code_id": null } ``` ## Lister les factures `GET /v1/apps/{appID}/invoices` Liste les factures de l'application, de la plus récente à la plus ancienne, une page à la fois. Le mode Test et le mode Production ont des factures distinctes, donc une liste ne montre que le mode de l'application demandée. Tous les paramètres sont facultatifs, et un paramètre vide est ignoré. **Paramètres** - `status` (string): `open`, `paid`, `void` ou `overdue`. `open` inclut les factures dont la date limite de paiement est passée. `overdue` renvoie seulement les factures ouvertes dont la date limite de paiement est passée. - `search` (string): Une partie du numéro de facture, du nom de l'acheteur ou de son e-mail. Ignore la casse. - `from` (timestamp): Uniquement les factures émises à cette date ou après, en secondes Unix. - `to` (timestamp): Uniquement les factures émises avant cette date, en secondes Unix. - `customer_id` (string): Uniquement les factures de ce client. - `limit` (integer): Combien de factures 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 [factures](https://abuna.app/docs/api/invoices-and-payments.md?hl=fr#invoice-summary) 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}/invoices** cURL : ```bash curl "https://api.abuna.app/v1/apps/8ddhXCDW/invoices?status=overdue&limit=50" \ -H "Authorization: Bearer sk_test_..." ``` Node.js : ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/invoices?status=overdue&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/invoices?status=overdue&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/invoices?status=overdue&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": "V2nC8xEi", "number": "MYST-000124", "status": "open", "overdue": false, "kind": "period", "amount": 5000, "credit": 0, "currency": "XAF", "item_label": "Monthly", "buyer_name": "Jane Doe", "buyer_email": "jane@example.com", "subscription_id": "x9QbL2sK", "customer_id": "Cu5tM8rA", "period_start": 1727600000, "period_end": 1730192000, "due_at": 1727686400, "created_at": 1727600000, "paid_at": null, "voided_at": null, "discount": 0, "coupon_id": null, "promotion_code_id": null } ], "next_cursor": "MTcyNzYwMDAwMDAwMDAwMC4wMUo5WlE3VjFXMlgzWTRaNUE2QjdDOEQ5RQ" } ``` ## Récupérer une facture `GET /v1/apps/{appID}/invoices/{id}` Récupère une facture avec ses liens et son historique, depuis son émission jusqu'à son paiement ou son annulation. **Attributs de la réponse** - `invoice` (object): L'[objet invoice summary](https://abuna.app/docs/api/invoices-and-payments.md?hl=fr#invoice-summary). - `pay_url` (string, nullable): Le lien de paiement de la période de facturation. Il vaut null dès que la facture est payée ou annulée, ou quand l'abonnement est résilié. - `invoice_url` (string): Un lien vers la page de facture du client, qui affiche aussi les factures payées et annulées. Il expire au bout de 7 jours. - `timeline` (array): Ce qui est arrivé à la facture, du plus ancien au plus récent. Les événements de la même seconde arrivent dans l'ordre ci-dessous. - `type` (string): `issued` : Abuna a émis la facture.`reminder` : Abuna a programmé un rappel.`notice` : un message au client à propos de la facture.`payment` : une tentative de paiement, qu'elle ait réussi, échoué ou soit encore en attente.`paid` : la facture a été payée.`voided` : la facture a été annulée. - `at` (timestamp): Quand c'est arrivé, en secondes Unix. Pour un message, quand il a été envoyé, ou créé s'il n'est pas encore envoyé. - `notice` (object): Sur un événement `notice` : l'[objet notice](https://abuna.app/docs/api/notices.md?hl=fr#object). Son `recipient` est vide pour Telegram. - `payment` (object): Sur un événement `payment` : l'[objet payment](https://abuna.app/docs/api/invoices-and-payments.md?hl=fr#payment-object). Son `status` indique comment la tentative s'est terminée. - `reminder` (object): Sur un événement `reminder` : un objet avec `kind`, l'une des valeurs `renewal_upcoming`, `payment_overdue` ou `payment_final_notice`. > **Remarque :** En mode Production, un rappel apparaît sous la forme des messages qu'il a envoyés, et non comme un événement `reminder`. Les factures Test ne conservent aucun message, donc elles affichent des événements `reminder` à la place. Renvoie `200`. Si l'application n'a aucune facture avec cet identifiant, renvoie `404` avec le code `not_found`. **GET /v1/apps/{appID}/invoices/{id}** cURL : ```bash curl https://api.abuna.app/v1/apps/8ddhXCDW/invoices/V2nC8xEi \ -H "Authorization: Bearer sk_test_..." ``` Node.js : ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/invoices/V2nC8xEi", { headers: { Authorization: "Bearer sk_test_..." }, }); const detail = await response.json(); ``` Python : ```python import requests response = requests.get( "https://api.abuna.app/v1/apps/8ddhXCDW/invoices/V2nC8xEi", headers={"Authorization": "Bearer sk_test_..."}, ) detail = response.json() ``` PHP : ```php ["Authorization: Bearer sk_test_..."], CURLOPT_RETURNTRANSFER => true, ]); $detail = json_decode(curl_exec($ch), true); ``` Go : ```go req, _ := http.NewRequest("GET", "https://api.abuna.app/v1/apps/8ddhXCDW/invoices/V2nC8xEi", 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 detail map[string]any json.NewDecoder(res.Body).Decode(&detail) ``` **Réponse** ```json { "invoice": { "id": "V2nC8xEi", "number": "MYST-000124", "status": "open", "overdue": false, "kind": "period", "amount": 5000, "credit": 0, "currency": "XAF", "item_label": "Monthly", "buyer_name": "Jane Doe", "buyer_email": "jane@example.com", "subscription_id": "x9QbL2sK", "customer_id": "Cu5tM8rA", "period_start": 1727600000, "period_end": 1730192000, "due_at": 1727686400, "created_at": 1727600000, "paid_at": null, "voided_at": null, "discount": 0, "coupon_id": null, "promotion_code_id": null }, "pay_url": "https://app.abuna.app/pay/3a7e1c9f5b2d8a4e6c0f7b3d9a1e5c8f2b6d", "invoice_url": "https://app.abuna.app/invoice/V2nC8xEi?exp=1728204800&sig=b4e1c8f2a7d3960e5b1f8c4a2d7e3b9f6a0c5e8d1b4f7a2c9e6d3b0f8a5c1e7d", "timeline": [ { "type": "issued", "at": 1727600000 }, { "type": "notice", "at": 1727600002, "notice": { "id": "e7JpT4cN", "customer_id": "Cu5tM8rA", "subscription_id": "x9QbL2sK", "kind": "subscription_started", "channel": "email", "recipient": "jane@example.com", "subject": "Pay FCFA 5,000 to start your Pro · Monthly plan with My store", "status": "sent", "attempts": 1, "last_error": null, "next_attempt_at": 1727600000, "created_at": 1727600000, "sent_at": 1727600002 } }, { "type": "payment", "at": 1727600090, "payment": { "id": "m7Yw4NcJ", "app_id": "8ddhXCDW", "period_id": "T6yVr3Dp", "driver": "pawapay", "provider": "MTN_MOMO_CMR", "provider_reference": "9f3b7d1a-5c2e-8f4b-6d0a-3e7c1b5a9d2f", "amount": 5000, "currency": "XAF", "original_amount": 5000, "original_currency": "XAF", "exchange_rate": null, "exchange_margin_bps": null, "exchange_rate_at": null, "status": "failed", "message": "INSUFFICIENT_BALANCE: The payer's balance is too low", "created_at": 1727600090, "fee": 100, "net": null, "session_id": null, "note": null, "marked_by_user_id": null, "marked_by_api_key_id": null, "method_label": "MTN Mobile Money Cameroon" } }, { "type": "reminder", "at": 1727686400, "reminder": { "kind": "payment_overdue" } } ] } ``` ## Débiter une facture `POST /v1/apps/{appID}/invoices/{id}/charge` Débite le numéro de téléphone enregistré du client pour une facture ouverte. Le client approuve le paiement sur son téléphone. Le débit part vers le réseau du numéro, par exemple Orange Money pour un numéro camerounais commençant par 69. Quand le préfixe n'indique pas le réseau, il part vers le réseau avec lequel le client a payé en dernier. Avec le simulateur Abuna en Test, le débit réussit toujours. Pour que le client paie plutôt sur la page de paiement, utilisez [Créer une session de paiement](https://abuna.app/docs/api/sessions.md?hl=fr#create-payment). > **Remarque :** Cela fonctionne même quand l'application est en lecture seule, pour que les clients qui vous doivent puissent encore payer. **Attributs de la réponse** - `status` (string): `succeeded`, ou `pending` pendant que le client approuve le débit sur son téléphone. - `paid` (boolean): `true` quand `status` vaut `succeeded`. - `period` (object): La [période de facturation](https://abuna.app/docs/api/invoices-and-payments.md?hl=fr#period-object) de la facture. Renvoie `200`. Un débit refusé immédiatement renvoie `402` avec la raison comme code, comme `insufficient_funds` ou `payment_declined`. Ces cas échouent aussi : - `403` `plan_limit` : le premier paiement du client dépasserait la limite d'abonnés en production du forfait de votre équipe. - `404` `not_found` : l'application n'a aucune facture avec cet identifiant. - `409` `already_paid` : la facture est payée. - `409` `invoice_not_open` : la facture est annulée, parce que l'abonnement a été résilié. - `409` `payment_in_progress` : un autre paiement pour la facture est encore en attente. - `422` `not_accepting_payments` : une application en production ne peut pas encore encaisser de paiements. - `422` `payment_unavailable` : votre prestataire n'a aucun réseau capable de débiter le numéro du client. - `422` `phone_required`, sur le champ `phone_number` : le client n'a pas encore de numéro de téléphone. Ajoutez-en un avec [Mettre à jour un client](https://abuna.app/docs/api/customers.md?hl=fr#update), ou envoyez-lui une [session de paiement](https://abuna.app/docs/api/sessions.md?hl=fr#create-payment), qui le demande. - `503` `payment_paused` : aucun nouveau paiement n'a été lancé. Un paiement précédent sur la facture est peut-être encore en cours. Réessayez dans une minute environ. - `503` `exchange_rate_unavailable` : la facture est en USD et aucun taux de change récent n'est disponible. Rien n'a été débité. Réessayez plus tard. Un débit en `pending` peut encore échouer, par exemple si le client le refuse sur son téléphone ou si son solde est insuffisant. Vous recevez alors [`invoice.payment_failed`](https://abuna.app/docs/api/events.md?hl=fr#invoice-payment-failed). Son champ `failure` en donne la raison, avec les mêmes codes qu'un `402`, par exemple `insufficient_funds`. Un paiement échoué dont le prestataire n'avait pas confirmé l'issue peut encore aboutir plus tard, en général dans les 7 jours suivant son début : attendez [`invoice.paid`](https://abuna.app/docs/api/events.md?hl=fr#invoice-paid) avant de rembourser ou de résilier quoi que ce soit. **POST /v1/apps/{appID}/invoices/{id}/charge** cURL : ```bash curl -X POST https://api.abuna.app/v1/apps/8ddhXCDW/invoices/V2nC8xEi/charge \ -H "Authorization: Bearer sk_test_..." ``` Node.js : ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/invoices/V2nC8xEi/charge", { method: "POST", headers: { Authorization: "Bearer sk_test_..." }, }); const charge = await response.json(); ``` Python : ```python import requests response = requests.post( "https://api.abuna.app/v1/apps/8ddhXCDW/invoices/V2nC8xEi/charge", headers={"Authorization": "Bearer sk_test_..."}, ) charge = response.json() ``` PHP : ```php true, CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_..."], CURLOPT_POSTFIELDS => "", CURLOPT_RETURNTRANSFER => true, ]); $charge = json_decode(curl_exec($ch), true); ``` Go : ```go req, _ := http.NewRequest("POST", "https://api.abuna.app/v1/apps/8ddhXCDW/invoices/V2nC8xEi/charge", 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 charge map[string]any json.NewDecoder(res.Body).Decode(&charge) ``` **Réponse** ```json { "status": "succeeded", "paid": true, "period": { "id": "T6yVr3Dp", "subscription_id": "x9QbL2sK", "price_id": "Zt6YbN3q", "pay_token": "3a7e1c9f5b2d8a4e6c0f7b3d9a1e5c8f2b6d", "starts_at": 1727600000, "ends_at": 1730192000, "period_index": 0, "grace_period_ends_at": 1727686400, "paid_at": 1727600100, "paused_at": null, "in_force": true, "created_at": 1727600000 } } ``` ## Marquer une facture payée `POST /v1/apps/{appID}/invoices/{id}/mark-paid` Enregistre que le client a payé une facture ouverte en dehors d'Abuna, par exemple en espèces, par virement bancaire, ou directement sur votre propre numéro de mobile money. Abuna ne débite rien. La facture est alors payée comme n'importe quelle autre : l'abonnement démarre, se renouvelle ou n'est plus impayé (`past_due`), vous recevez `invoice.paid` et les événements d'abonnement qui suivent, et le client reçoit un reçu indiquant que vous avez enregistré son paiement. Un renouvellement marqué payé avant son démarrage conserve ses dates. > **Remarque :** Cela fonctionne même quand l'application est en lecture seule, pour que vous puissiez encore enregistrer ce que les clients vous ont payé. **Paramètres** - `note` (string, obligatoire): Comment le client a payé, pour vos propres archives, par exemple un reçu ou une référence de virement. De 1 à 500 caractères, les espaces étant retirés aux deux extrémités. Les clients ne la voient jamais. **Attributs de la réponse** - `status` (string): Toujours `succeeded`. - `paid` (boolean): Toujours `true`. - `period` (object): La [période de facturation](https://abuna.app/docs/api/invoices-and-payments.md?hl=fr#period-object) de la facture, désormais payée. - `payment` (object): Le [paiement](https://abuna.app/docs/api/invoices-and-payments.md?hl=fr#payment-object) enregistré : le montant de la facture et sa devise, sans conversion, `driver` et `provider` à `manual`, aucun frais, et votre note. Renvoie `200`. Ces cas échouent : - `403` `plan_limit` : le premier paiement du client dépasserait la limite d'abonnés en production du forfait de votre équipe. - `404` `not_found` : l'application n'a aucune facture avec cet identifiant. - `409` `already_paid` : la facture est payée. - `409` `invoice_not_open` : la facture est annulée, par exemple parce que l'abonnement a été résilié. - `409` `payment_in_progress` : un paiement par mobile money pour la facture attend l'approbation du client. Réessayez une fois qu'il a réussi ou échoué, avec une nouvelle `Idempotency-Key` si vous en avez envoyé une. - `422` `invalid` : la note est manquante ou vide (`required`) ou dépasse 500 caractères (`too_long`), dans `errors`. **POST /v1/apps/{appID}/invoices/{id}/mark-paid** cURL : ```bash curl https://api.abuna.app/v1/apps/8ddhXCDW/invoices/V2nC8xEi/mark-paid \ -H "Authorization: Bearer sk_test_..." \ -H "Content-Type: application/json" \ -H "Idempotency-Key: cash-V2nC8xEi" \ -d '{ "note": "Paid cash at the shop, receipt 0042" }' ``` Node.js : ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/invoices/V2nC8xEi/mark-paid", { method: "POST", headers: { Authorization: "Bearer sk_test_...", "Content-Type": "application/json", "Idempotency-Key": "cash-V2nC8xEi", }, body: JSON.stringify({ note: "Paid cash at the shop, receipt 0042", }), }); const marked = await response.json(); ``` Python : ```python import requests response = requests.post( "https://api.abuna.app/v1/apps/8ddhXCDW/invoices/V2nC8xEi/mark-paid", headers={"Authorization": "Bearer sk_test_...", "Idempotency-Key": "cash-V2nC8xEi"}, json={ "note": "Paid cash at the shop, receipt 0042", }, ) marked = response.json() ``` PHP : ```php true, CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_...", "Content-Type: application/json", "Idempotency-Key: cash-V2nC8xEi"], CURLOPT_POSTFIELDS => json_encode([ "note" => "Paid cash at the shop, receipt 0042", ]), CURLOPT_RETURNTRANSFER => true, ]); $marked = json_decode(curl_exec($ch), true); ``` Go : ```go body, _ := json.Marshal(map[string]any{ "note": "Paid cash at the shop, receipt 0042", }) req, _ := http.NewRequest("POST", "https://api.abuna.app/v1/apps/8ddhXCDW/invoices/V2nC8xEi/mark-paid", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer sk_test_...") req.Header.Set("Content-Type", "application/json") req.Header.Set("Idempotency-Key", "cash-V2nC8xEi") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var marked map[string]any json.NewDecoder(res.Body).Decode(&marked) ``` **Réponse** ```json { "status": "succeeded", "paid": true, "period": { "id": "T6yVr3Dp", "subscription_id": "x9QbL2sK", "price_id": "Zt6YbN3q", "pay_token": "3a7e1c9f5b2d8a4e6c0f7b3d9a1e5c8f2b6d", "starts_at": 1727600000, "ends_at": 1730192000, "period_index": 0, "grace_period_ends_at": 1727686400, "paid_at": 1727600100, "paused_at": null, "in_force": true, "created_at": 1727600000 }, "payment": { "amount": 5000, "app_id": "qhf83tDc", "created_at": 1794780106, "currency": "XAF", "driver": "manual", "exchange_margin_bps": null, "exchange_rate": null, "exchange_rate_at": null, "fee": null, "id": "tGfwt5dd", "marked_by_api_key_id": "01J9ZQ5K2M3N4P5Q6R7S8T9V0W", "marked_by_user_id": null, "message": null, "method_label": "Paid outside Abuna", "net": null, "note": "Paid cash at the shop, receipt 0042", "original_amount": 5000, "original_currency": "XAF", "period_id": "0kYPFwxJ", "provider": "manual", "provider_reference": null, "session_id": null, "status": "succeeded" } } ```