---
title: "Kill Bill : la facturation open source que vous hébergez vous-même"
description: "Comment fonctionne Kill Bill, la plateforme open source de facturation et de paiements auto-hébergée : catalogue, abonnements, factures, plugins de paiement, installation avec Docker, premier abonnement via l'API, et quand elle surpasse Stripe Billing."
date: 2026-09-15
tags: ["facturation", "paiements", "open source", "backend", "mode d'emploi"]
language: fr
canonical: https://aissamirhir.com/fr/blog/kill-bill-open-source-billing
source: aissamirhir.com
---
Tout produit qui encaisse de l'argent finit par construire la même chose : des offres, des périodes d'essai, des changements de formule, des factures, des relances de cartes refusées, des remboursements. La plupart des équipes louent cette couche à Stripe Billing, Chargebee ou Recurly et paient un pourcentage du chiffre d'affaires. [Kill Bill](https://killbill.io/) prend l'autre chemin : c'est une plateforme open source de facturation et de paiements que vous déployez sur votre propre infrastructure, publiée sous licence Apache 2.0.

Cette note explique ce qu'est Kill Bill, comment il fonctionne en interne, comment le lancer en local et créer votre premier abonnement, et quand c'est (ou non) le bon choix.

| Élément | Détails |
| --- | --- |
| Quoi | Serveur de facturation d'abonnements et de paiements auto-hébergé |
| Licence | Apache 2.0, libre d'utilisation et de modification |
| Stack | Serveur Java, MySQL, MariaDB ou PostgreSQL, API REST |
| Interface d'admin | Kaui, une application back-office pour la finance et le support |
| Passerelles | Stripe, Adyen, PayPal, Braintree, GoCardless et d'autres via des plugins |
| Historique | Plus de 15 ans en production |
| Liens | [Site](https://killbill.io/) · [Documentation](https://docs.killbill.io/) · [GitHub](https://github.com/killbill/killbill) · [Référence API](https://apidocs.killbill.io/) |

## Le problème qu'il résout

Les outils de facturation hébergés permettent de démarrer vite, mais ils ont trois coûts qui augmentent avec le temps :

- **Des frais proportionnels au chiffre d'affaires.** Un pourcentage de chaque facture ne coûte rien à 10 k par mois et fait mal à 10 M.
- **L'enfermement.** Vos abonnements, factures et jetons de paiement vivent dans le système d'un autre, selon son modèle de données.
- **Une logique limitée.** Si vous avez besoin d'une passerelle de paiement locale, d'un autre outil anti-fraude, de règles de relance sur mesure ou de factures modifiées à la volée, vous attendez la feuille de route du fournisseur.

Kill Bill répond aux trois en étant une infrastructure qui vous appartient. Vous payez des serveurs, pas un pourcentage du chiffre d'affaires, les données sont dans votre base, et vous modifiez le comportement avec des plugins.

La contrepartie est claire : vous faites désormais tourner un serveur de facturation. Cela implique une base de données, des mises à jour, de la supervision et des développeurs qui comprennent le modèle.

## Vue d'ensemble

Kill Bill n'est ni une page de paiement ni un portail client. C'est le moteur de facturation derrière votre produit. Votre application appelle son API REST quand quelque chose se produit (un client s'inscrit, change de formule, résilie), et Kill Bill gère tout ce qui suit.

```flow
{
  "direction": "LR",
  "height": 520,
  "nodes": [
    { "id": "app", "label": "Votre application", "sub": "paiement, portail, backend", "kind": "client" },
    { "id": "kaui", "label": "Kaui", "sub": "admin pour la finance", "kind": "client" },
    { "id": "kb", "label": "Serveur Kill Bill", "sub": "API REST, multi-tenant", "kind": "api" },
    { "id": "db", "label": "Base de données", "sub": "MySQL, MariaDB, PostgreSQL", "kind": "store" },
    { "id": "events", "label": "Événements", "sub": "notifications push", "kind": "queue" },
    { "id": "plugins", "label": "Plugins", "sub": "paiement, taxe, facture, catalogue", "kind": "worker" },
    { "id": "gateway", "label": "Passerelles de paiement", "sub": "Stripe, Adyen, PayPal", "kind": "provider" },
    { "id": "tax", "label": "Moteurs de taxes", "sub": "Avalara, Vertex", "kind": "provider" }
  ],
  "edges": [
    { "from": "app", "to": "kb", "label": "appels REST" },
    { "from": "kaui", "to": "kb", "label": "appels REST" },
    { "from": "kb", "to": "db", "label": "tout l'état" },
    { "from": "kb", "to": "plugins", "label": "points d'extension", "animated": true },
    { "from": "plugins", "to": "gateway", "label": "débit, remboursement" },
    { "from": "plugins", "to": "tax", "label": "taux de taxe" },
    { "from": "kb", "to": "events", "label": "facture, paiement" },
    { "from": "events", "to": "app", "label": "webhooks", "dashed": true }
  ]
}
```

- **Serveur Kill Bill.** Une application Java qui expose l'API REST et exécute la logique de facturation. Une seule installation peut héberger plusieurs tenants, chacun avec ses propres données, son catalogue et sa configuration.
- **Base de données.** Chaque compte, abonnement, facture, paiement et journal d'audit est stocké dans votre base. Rien ne vit uniquement en mémoire.
- **Kaui.** L'interface d'administration, pour que la finance et le support consultent les clients, ajustent des factures ou émettent des remboursements sans toucher à l'API.
- **Plugins.** Des points d'extension chargés à l'exécution (bundles OSGi) qui connectent passerelles et moteurs de taxes, ou modifient le comportement des factures, des paiements et du catalogue.
- **Événements.** Kill Bill notifie votre application quand quelque chose change, par exemple une facture créée ou un paiement échoué, pour que vous puissiez ouvrir un accès ou envoyer un e-mail.
- **Bibliothèques clientes.** Des clients officiels existent pour Java, Ruby, PHP, Node.js, Python et Go.

## Les concepts clés

| Concept | Signification |
| --- | --- |
| Tenant | Un espace isolé avec sa propre clé et son secret d'API. Utile pour les environnements ou les plateformes en marque blanche |
| Compte | Un client : nom, e-mail, devise, fuseau horaire, moyens de paiement |
| Catalogue | Votre modèle tarifaire : produits, offres, prix, périodes de facturation et phases |
| Phase d'offre | Une étape d'une offre, par exemple un `TRIAL` de 14 jours suivi d'une phase payante `EVERGREEN` |
| Abonnement | Le contrat entre un compte et une offre ; il passe d'une phase à l'autre automatiquement |
| Bundle | Un groupe d'abonnements, par exemple une offre de base et ses options |
| Facture | Générée à chaque cycle, avec des lignes récurrentes, fixes, d'usage, de crédit et de prorata |
| Paiement | La tentative d'encaisser une facture via un moyen de paiement et son plugin |
| Overdue | Les règles de relance qui changent l'état d'un compte (avertissement, bloqué) quand des factures restent impayées |

Le catalogue mérite une précision. C'est en général un fichier XML (validé par un schéma publié), et c'est là que Kill Bill est le plus puissant : essais, phases promotionnelles, options, règles de montée et de descente de gamme, devises multiples et listes de prix y sont définis. Pour expérimenter, vous pouvez éviter le XML et créer des offres simples via l'API ou dans Kaui.

## La vie d'un abonnement

Prenons un client qui s'abonne à une offre « Pro » avec 14 jours d'essai, à 29 USD par mois.

```flow
{
  "direction": "TB",
  "height": 760,
  "nodes": [
    { "id": "signup", "label": "Le client s'inscrit", "sub": "votre app appelle l'API", "kind": "client" },
    { "id": "sub", "label": "Abonnement créé", "sub": "offre pro-monthly", "kind": "api" },
    { "id": "trial", "label": "Phase TRIAL", "sub": "14 jours, facture à 0 USD", "kind": "note" },
    { "id": "evergreen", "label": "Phase EVERGREEN", "sub": "29 USD chaque mois", "kind": "note" },
    { "id": "invoice", "label": "Facture générée", "sub": "à chaque cycle", "kind": "store" },
    { "id": "payment", "label": "Tentative de paiement", "sub": "moyen de paiement par défaut", "kind": "worker" },
    { "id": "gateway", "label": "Plugin de passerelle", "sub": "Stripe, Adyen, ...", "kind": "provider" },
    { "id": "overdue", "label": "Règles overdue", "sub": "relance, alerte, blocage", "kind": "queue" }
  ],
  "edges": [
    { "from": "signup", "to": "sub" },
    { "from": "sub", "to": "trial" },
    { "from": "trial", "to": "evergreen", "label": "changement de phase" },
    { "from": "evergreen", "to": "invoice" },
    { "from": "invoice", "to": "payment", "animated": true },
    { "from": "payment", "to": "gateway", "label": "débit" },
    { "from": "gateway", "to": "overdue", "label": "si refusé", "dashed": true },
    { "from": "overdue", "to": "payment", "label": "nouvel essai", "dashed": true }
  ]
}
```

1. **Inscription.** Votre application crée un compte, y associe un moyen de paiement et crée un abonnement à `pro-monthly`.
2. **Essai.** Kill Bill démarre la phase `TRIAL` et produit une facture à zéro. Rien n'est débité.
3. **Changement de phase.** Au 15e jour, l'abonnement passe tout seul en phase `EVERGREEN`. Aucune tâche cron de votre côté.
4. **Facture.** À chaque cycle, Kill Bill construit la facture, avec le prorata si le client a changé de formule en cours de cycle, les crédits et les frais d'usage.
5. **Paiement.** La facture déclenche un paiement sur le moyen de paiement par défaut, via le plugin de passerelle.
6. **Gestion des échecs.** Si la carte est refusée, les relances et les règles overdue prennent le relais, et peuvent faire passer le compte en état d'avertissement ou de blocage que votre application lit pour restreindre l'accès.
7. **Événements.** À chaque étape, votre application reçoit des notifications sur lesquelles elle peut agir.

## Le lancer en local avec Docker

L'installation la plus rapide utilise Docker Compose avec trois conteneurs : Kill Bill, Kaui et une base MariaDB partagée. Enregistrez ceci sous `docker-compose.yml` (ce sont les versions d'images du guide officiel ; vérifiez Docker Hub pour des tags plus récents) :

```yaml
version: '3.2'
volumes:
  db:
services:
  killbill:
    image: killbill/killbill:0.24.16
    ports:
      - "8080:8080"
    environment:
      - KILLBILL_DAO_URL=jdbc:mysql://db:3306/killbill
      - KILLBILL_DAO_USER=root
      - KILLBILL_DAO_PASSWORD=killbill
      - KILLBILL_CATALOG_URI=SpyCarAdvanced.xml
  kaui:
    image: killbill/kaui:4.0.4
    ports:
      - "9090:8080"
    environment:
      - KAUI_CONFIG_DAO_URL=jdbc:mysql://db:3306/kaui
      - KAUI_CONFIG_DAO_USER=root
      - KAUI_CONFIG_DAO_PASSWORD=killbill
      - KAUI_KILLBILL_URL=http://killbill:8080
  db:
    image: killbill/mariadb:0.24
    volumes:
      - type: volume
        source: db
        target: /var/lib/mysql
    expose:
      - "3306"
    environment:
      - MYSQL_ROOT_PASSWORD=killbill
```

Puis démarrez le tout :

```bash
docker compose up
```

- Le démarrage prend quelques minutes. Si un conteneur plante, allouez au moins 4 Go de mémoire à Docker.
- Kaui est accessible sur `http://127.0.0.1:9090` avec l'identifiant par défaut `admin` / `password`.
- L'explorateur d'API est sur `http://127.0.0.1:8080/api.html`.
- Ces identifiants servent uniquement aux tests en local. Changez-les avant que quoi que ce soit ne quitte votre machine.

## Votre premier abonnement avec l'API

Une fois la stack lancée, ces appels créent un tenant, une offre simple, un client et un abonnement. Chaque requête après la création du tenant utilise sa clé et son secret d'API en en-têtes.

```bash
KB=http://127.0.0.1:8080
AUTH=(-u admin:password -H "X-Killbill-ApiKey: bob" -H "X-Killbill-ApiSecret: lazar")
JSON=(-H "Content-Type: application/json" -H "X-Killbill-CreatedBy: demo")

# 1. Créer un tenant (espace isolé avec sa clé et son secret)
curl -X POST -u admin:password "${JSON[@]}" \
  -d '{"apiKey": "bob", "apiSecret": "lazar"}' \
  "$KB/1.0/kb/tenants"

# 2. Créer une offre simple : Pro, 29 USD par mois, 14 jours d'essai
curl -X POST "${AUTH[@]}" "${JSON[@]}" \
  -d '{"planId": "pro-monthly", "productName": "Pro", "productCategory": "BASE",
       "currency": "USD", "amount": 29, "billingPeriod": "MONTHLY",
       "trialLength": 14, "trialTimeUnit": "DAYS"}' \
  "$KB/1.0/kb/catalog/simplePlan"

# 3. Créer un compte client (l'id est dans l'en-tête Location)
curl -i -X POST "${AUTH[@]}" "${JSON[@]}" \
  -d '{"name": "Jane Doe", "email": "jane@example.com", "currency": "USD"}' \
  "$KB/1.0/kb/accounts"

ACCOUNT_ID=collez-l-id-ici

# 4. Ajouter un moyen de paiement par défaut (paiement externe, pour les tests)
curl -X POST "${AUTH[@]}" "${JSON[@]}" \
  -d '{"pluginName": "__EXTERNAL_PAYMENT__"}' \
  "$KB/1.0/kb/accounts/$ACCOUNT_ID/paymentMethods?isDefault=true"

# 5. Abonner le compte à l'offre
curl -X POST "${AUTH[@]}" "${JSON[@]}" \
  -d "{\"accountId\": \"$ACCOUNT_ID\", \"planName\": \"pro-monthly\"}" \
  "$KB/1.0/kb/subscriptions"

# 6. Voir la facture générée par Kill Bill
curl "${AUTH[@]}" "$KB/1.0/kb/accounts/$ACCOUNT_ID/invoices"
```

Vous devriez voir une facture d'essai à zéro. Ouvrez le même compte dans Kaui pour voir l'abonnement, les factures et la chronologie. En production, votre backend fait ces appels via une bibliothèque cliente plutôt qu'avec `curl`, et un vrai plugin de passerelle remplace le paiement externe.

## Les plugins : là où réside la flexibilité

La vraie force de Kill Bill, c'est de construire votre propre logique au-dessus du cœur. Il existe plusieurs types de plugins :

| Type de plugin | Ce qu'il permet |
| --- | --- |
| Paiement | Connecter une passerelle ou un processeur (Stripe, Adyen, PayPal, Braintree, GoCardless, ou le vôtre) |
| Contrôle de paiement | Exécuter du code avant et après un paiement : routage, anti-fraude, règles de relance, annulation d'un débit |
| Facture | Ajouter ou modifier des lignes de facture à la volée, comme des taxes ou des frais spécifiques |
| Catalogue | Charger les tarifs depuis votre propre système au lieu du XML |
| Usage | Transmettre des données d'usage pour la facturation à terme échu ou à la consommation |
| Entitlement | Intercepter les changements d'abonnement, par exemple pour valider une montée de gamme |
| Notification | Réagir aux événements de Kill Bill et les pousser vers d'autres systèmes |

Des plugins open source couvrent déjà les besoins courants, comme les fournisseurs de taxes (AvaTax), les notifications par e-mail ou l'analytique, et servent aussi d'exemples pour écrire les vôtres. Les plugins s'installent avec KPM, le gestionnaire de paquets de Kill Bill, ou depuis Kaui.

## Open source ou Aviate ?

Les deux reposent sur le même cœur open source.

| | Open source | Aviate |
| --- | --- | --- |
| Prix | Gratuit | Prix fixe, pas un pourcentage du chiffre d'affaires |
| Hébergement | Vous l'exploitez (Docker, Kubernetes, AWS, Tomcat) | Cloud géré avec mise à l'échelle automatique et supervision |
| En plus | Facturation, paiements, Kaui, plugins | API de catalogue, métrage, portefeuille et crédits, coupons, taxes |
| Support | Communauté (Google Group) | Support commercial |

Certaines fonctions d'Aviate, comme le métrage d'usage et les portefeuilles prépayés, visent la facturation à l'usage et par jetons pour l'IA. Comme le cœur reste open source, le projet insiste sur le fait que vous pouvez partir sans perdre vos données.

## Quand Kill Bill est le bon choix

**Bon choix :**

- Votre volume de facturation rend les frais au pourcentage coûteux.
- Vous avez besoin de passerelles, d'outils anti-fraude ou de fournisseurs de taxes que les outils hébergés ne gèrent pas, ce qui est fréquent hors des États-Unis et de l'Europe.
- Vous avez besoin d'une logique sur mesure : montants dynamiques, routage des paiements, politiques de relance particulières.
- Les données de facturation doivent rester sur votre infrastructure pour des raisons de conformité ou de souveraineté.
- Vous exploitez une plateforme qui facture pour le compte de nombreux tenants.

**Mauvais choix :**

- Vous n'avez pas encore lancé et il vous faut une facturation opérationnelle cette semaine. Stripe Billing, Paddle ou Lemon Squeezy iront plus vite.
- Votre modèle se limite à des abonnements simples sur une seule passerelle.
- Personne dans l'équipe ne peut prendre en charge un service Java, une base de données et leurs mises à jour.
- Vous voulez une page de paiement et un portail client clés en main. Avec Kill Bill, c'est à vous de les construire.

## Mon avis

Kill Bill, c'est la facturation vue comme une infrastructure plutôt que comme une fonctionnalité. Le modèle est explicite (catalogue, phases, bundles, factures, états overdue), chaque changement d'état est audité, et le système de plugins permet de modifier le comportement sans forker. Le coût est opérationnel : vous héritez d'un vrai serveur avec un vrai modèle de données, et le catalogue demande un temps d'apprentissage.

Ma règle : commencez avec un outil hébergé tant que vos tarifs changent tous les mois, et concevez votre code pour que la facturation soit derrière une interface. Quand les frais, la couverture des passerelles ou les règles métier commencent à coincer, Kill Bill fait partie des très rares options open source matures vers lesquelles migrer.

## FAQ

```faq
{
  "items": [
    { "q": "Kill Bill est-il vraiment gratuit ?", "a": "Oui. Le cœur est open source sous licence Apache 2.0. Vous ne payez que votre infrastructure, ou Aviate si vous voulez la version gérée et les fonctions supplémentaires." },
    { "q": "Kill Bill remplace-t-il Stripe ?", "a": "Non. Kill Bill remplace la couche de facturation (offres, abonnements, factures, relances). Les paiements passent toujours par une passerelle comme Stripe, Adyen ou PayPal, connectée via un plugin." },
    { "q": "Avec quels langages peut-on l'intégrer ?", "a": "Tout langage capable d'appeler une API REST. Des bibliothèques clientes officielles existent pour Java, Ruby, PHP, Node.js, Python et Go." },
    { "q": "Quelles bases de données sont prises en charge ?", "a": "L'équipe principale utilise MySQL et teste aussi MariaDB et PostgreSQL. L'installation Docker est fournie avec MariaDB." },
    { "q": "Gère-t-il la facturation à l'usage ou par jetons IA ?", "a": "Oui. Le cœur open source gère l'usage et la facturation à terme échu, et Aviate ajoute le métrage, les portefeuilles prépayés et les crédits pensés pour les produits à l'usage et l'IA." },
    { "q": "Kill Bill inclut-il une page de paiement ou un portail client ?", "a": "Non. C'est un moteur back-end avec une interface d'admin (Kaui). Votre application fournit les pages de paiement et de compte côté client et appelle l'API." }
  ]
}
```

## Liens

- Site : [killbill.io](https://killbill.io/)
- Documentation : [docs.killbill.io](https://docs.killbill.io/)
- Prise en main : [docs.killbill.io/latest/getting_started](https://docs.killbill.io/latest/getting_started.html)
- Référence API : [apidocs.killbill.io](https://apidocs.killbill.io/)
- Code source : [github.com/killbill/killbill](https://github.com/killbill/killbill)
- Communauté : [Google Group des utilisateurs de Kill Bill](https://groups.google.com/g/killbilling-users)