This version of Kill Bill is not supported anymore, please see our latest documentation

Overview

Kill Bill Platform

At its core, Kill Bill offers a flexible platform on which applications that require a high level of integrity, audit traces, and robustness can be developed. Currently there are two kind of applications that have been developed:

  • Billing Systems to manage recurring/usage based subscriptions

  • Payment systems that integrate with various payment gateways, payment processors, fraud detection systems, …​

The Billing System relies on the Payment System to make payments but the Payment System also offers raw payment apis and therefore can also be run as a standalone application.

Some of the features of the Kill Bill platform include:

  • Core Foundations

    • A plugin framework where custom plugins can be added to modify the behavior of the system, and or interact with third party systems,

    • A robust persistent event bus, that is used both internally and externally (events are visible to plugins)

    • An auditing framework that keeps track of all the changes that occurred (who?, when?, what?)

    • Authentication and RBAC support

  • Core services (account management, invoicing, entitlement, dunning, …​) which are built and packaged as independent jars, each of which with its own api; those core services post a well defined set of events on the persistent bus which are then consumed by other core services or plugins.

  • Plugins

pub?w=960&h=480

Contrary to most billing solutions, Kill Bill is not a batch oriented system, but instead, it is driven by events occurring in the system (for example, the creation of a new subscription will create a new event that the invoicing core service will process and as result a new invoice may be created along with a new event, which the payment code service will then process, …​)

Kill Bill is traditionally packaged as a war and is therefore executed within a web container (for example Tomcat). It offers REST APIs to manage all the state associated to accounts, subscriptions, invoices, payments, …​ It also provides lower level (java) APIs and can therefore be embedded as a library within a (java) user application.

Documentation

Our documentation is targeted for different types of audience:

  • Kill Bill Visitors: technical or non-technical folks interested to know more about what Kill Bill is about.

  • Kill Bill Users: technical folks that are interested to evaluate the solution or are ready to deploy it.

  • Kill Bill Developers: technical folks that are interested to contribute to the open-source project (often to enhance the platform to suit their own specific needs).

For the Kill Bill Visitors, we provide an overview of the product on our main web site, and also some more details about the features.

For the Kill Bill Users, we provide a set of:

  • user guides,

  • tutorials,

  • screencasts,

  • In addition to that, we also provide documentation for each specific plugin in the github plugin repository (via a Readme file). An example of such documentation can be seen for the Avatax plugin.

The user guides are split into 3 different pages:

For the Kill Bill Developers, we also provide additional pages on our github wiki.

Also, don’t forget to check our blog, which has interesting articles about some of Kill Bill internals, use cases, …​

Most of our documentation is hosted in a GitHub repository, so please either submit a PR when obvious things are missing or wrong, or let us know so we can improve it!

Where To Start?

This obviously depends on the type of audience, and also whether you are looking for a Billing System, or a Payment System.

If your goal is to get a sense of what Kill Bill provides, and assuming you are at least slightly technical, here is a good start:

  1. Read through the user guides

  2. Download Kill Bill and follow the 5' minutes tutorials from the both the Payment System User Guide and Billing System User Guide

  3. Gather your requirements and start the prototyping stage. You will need to have a local instance of Kill Bill and you have the following choices:

    • Use the released war (either self executable) or drop the war into your container

    • Use one of our already built Docker image

    • For mode advanced usage, you can also use the source code and rely on the start-server script

  4. Depending on your use case, you will need to configure your catalog, and develop/deploy plugins

Kill Bill Platform Features

Multi-Tenancy

Kill Bill supports multi-tenancy, meaning you can run multiple logical instances of Kill Bill with a single server and database. This is the default way to deploy Kill Bill. We posted a blog post which illustrates some of the use cases for running Kill Bill in a multi-tenant fashion.

When multi-tenancy is enabled, you first need to create a tenant:

curl -v \
     -X POST \
     -u admin:password \
     -H 'Content-Type: application/json' \
     -H 'X-Killbill-CreatedBy: admin' \
     -d '{"apiKey": "bob", "apiSecret": "lazar"}' \
     "http://127.0.0.1:8080/1.0/kb/tenants"

The call above will create the tenant and that tenant will be identified with its own tenantId. The supplied apiKey needs to be unique across all the tenants. The tenantId is immutable but the apiKey and apiSecret can be updated in the event they are compromised.

Each subsequent (REST) api call will require the following two headers (for Kill Bill to identity which tenant that call is targeted to, and verify the user has the right to access that tenant):

  • X-Killbill-ApiKey

  • X-Killbill-ApiSecret

RBAC

Kill Bill’s authentication and authorization relies on Apache Shiro. In a nutshell, Shiro allows you to configure a set of Users, where each User is associated with a set of Roles, and each Role contains a set of Permissions.

Kill Bill (through Shiro) supports the following types of configuration:

  • File based configuration (shiro.ini). This is the default configuration embedded in Kill Bill, which provides you with one admin user having all the rights.

  • Database configuration: Kill Bill offers a set of endpoints to add users, roles, and permissions

  • LDAP: Kill Bill also offers to interact with LDAP to retrieve all the users, roles, permissions. The configuration happens though system properties.

Note that all those 3 mechanisms can coexist, and often need to coexist to solve the chicken and egg problem of having permissions to add new users, roles, …​ through APIs.

The following blog post gives an overview of how our admin UI interacts with Kill Bill and takes advantage of the RBAC features.

Plugins

Overview

Kill Bill supports a powerful plugin framework based on the OSGI standard. The purpose of OSGI based plugins is to ensure that they are isolated from each other and from the core platform, allowing Kill Bill users to extend the system with minimal knowledge about the system. Kill Bill supports writing plugins in various languages to address a wider audience of developers, and also leverage existing libraries in other languages than java. In theory, plugins could be written in all JVM based languages. In practice, Kill Bill currently supports:

  • Java based plugins (pure OSGI plugins)

  • Ruby plugins. They rely on a built-in framework on top of OSGI to make sure ruby code will be fully isolated. In addition to that, each ruby plugin is based on a ruby skeleton whose code is partially automatically generated and whose purpose is to allow developers to write pure ruby code.

  • Scala (a prototype has been been built showing the feasibility of such plugins)

The purpose of the plugins is multiple:

  • Provide hooks to third party systems (for e.g: payment gateways, tax systems, fraud detection systems, CRM, proprietary systems, …​)

  • Modify the behavior of the core Kill Bill system to address specific needs (for example intercept ongoing payments to route them differently, intercept ongoing invoices to customize them, perform on the fly currency conversion, …​)

  • Add specific business logic when certain types of events occur (notify customers of upcoming invoices, perform automatic action for dunning, …​)

In order to achieve those goals, Kill Bill supports a mechanism for the plugin to register for any type of events occurring in the system. In addition to that, plugins can also implement certain types of plugin apis, and register/unregister in the system during the start/stop sequence.

The following set of plugin APIs is currently supported:

  • Payment plugin api: Those APIs are used by plugins interacting with third party payment gateways or payment processors.

  • Currency plugin api: By implementing this API, the plugin would provide the business logic for currency conversion, which is then available to payment plugins for real time currency conversion.

  • Invoice plugin api: Plugins implementing this API would be called during invoice generation when Kill Bill’s invoicing code computes the items but prior the invoice is persisted, to provide the ability for the plugin to modify the items (for example to add extra tax items).

  • Payment routing plugin api: The purpose of this API is to intercept payments and as a result abort them (fraud use case) or reroute them to a different payment plugin (payment gateway downtime, or cost optimization scenario).

Note that some of these APIs are still a work in progress as we understand better the requirements; we are also working on additional plugin APIs to provide access to other parts of the system.

Lifecycle and Layout Internals

Kill Bill Plugins will be started and stopped during the Kill Bill lifecycle initialization stages. Each plugin will need to provide an activator with a start and stop method. During initialization and when all the foundation and core services have started, Kill Bill will automatically discover the existing plugins (based on the filesystem layout described below) and it will invoke the start method to initialize the plugins. During shutdown sequence, each plugin will first be stopped and then the rest of the foundation and core services will be stopped.

Kill Bill looks for all plugins in a bundle directory, by default /var/tmp/bundles (you can override it via the system property org.killbill.osgi.bundle.install.dir). The expected layout is the following:

bundles/
  platform/
  plugins/
    ruby/
      ruby-plugin-a/
        ruby-plugin-a-version/
          boot.rb
          killbill.properties
      ruby-plugin-b/
        ruby-plugin-b-version/
          boot.rb
          killbill.properties
    java/
      java-plugin-a/
        java-plugin-a-version/
          plugin-a.jar
      java-plugin-b/
        java-plugin-b-version/
          plugin-b.jar

The bundles/platform directory is used for non Kill Bill specific OSGI plugins. For example, you can drop in it the Apache Felix Web Console jar, and Kill Bill will automatically start it during its initialization sequence. Here is a recommended set of convenience plugins to run. Note that in the case of Ruby plugins (see below), you need to copy the correct version of the org.kill-bill.billing:killbill-platform-osgi-bundles-jruby artifact and name it as bundles/platform/jruby.jar.

Also, in the case of java based plugins, it is enough to just copy the jar under the correct directory entry, but in the case of the ruby plugins, the layout is a bit more complex: it expects a top level killbill.properties file describing the type of plugin and special libraries to load, as well as a gems directory containing all the dependencies. Fortunately, if you are using one of the official Ruby plugins, you don’t need to worry about this. You can download tar.gz packages with the correct layout. Simply unpack them and restart Kill Bill.

If you want to develop your own ruby plugin, check our instructions here and here.

We also provide hello world skeleton of plugins in java and ruby to get started.

Deployment

Overview

Kill Bill (whether used as a Billing System or Payment System) is fundamentally a backend system and so the following consideration should apply:

  • Don’t make the system visible to the outside world, you should have a front end system, or a reverse proxy in front of it; if you need to handle some IPN (Internal Payment Notification), we also developed an app for that specific purpose.

  • Always deploy at least 2 instances (for reliability purpose) in front of a load balancer.

  • Setup your database with a master and a slave instances (or more exotic setup if required), and configure it to take regular snapshot

  • Aggregate your logs (for example using LogStash, GrayLog2, …​) and take a look at our logback recipes

  • Look at the all the existing Kill Bill JMX metrics (using VisualVM, jconsole, …​) and set some alerts (for instance by using the following script)

  • Configure your system properly, especially when it comes to the settings of the bus and notification queue.

When deploying Kill Bill, the following pieces will need to be deployed in addition to your OS, VM, or container (Docker,…​):

  • A web container (jetty, tomcat, …​)

  • The killbill war

  • The plugins

  • The configuration files and system properties

  • The database along with the various schemas: The Kill Bill schema is available from our download page and each stateful plugin will/should expose such a schema (for example, here is the schema for the Adyen plugin)

In order to ease the deployment we first created KPM, the Kill Bill Package Manager. KPM will allow to fetch existing (signed) artifacts for the main killbill war and also for each of the plugins, and deploy them at the right place. KPM will not take care of deploying the web container and the various configuration files or properties.

So, in addition to KPM, we also provide Docker images. Those images internally rely on KPM for fetching the various artifacts and install them at the right location on the image. The docker run command allows to override existing Kill Bill system properties and mount volumes where configuration files can be accessed.

Note that one can decide to only use KPM for fetching and installing artifacts, and bypass docker to deploy on VMs or bare metal. Or alternatively one can use other tools, manual steps to fetch those artifacts from Maven Central, or by using our convenient download page.

The following sections below will give manual instructions on how to deploy on various containers.

Installation in Jetty

Download the Jetty container

If you don’t have it yet, you can download the Jetty container here. If you’re unsure which version to use, we recommend 8.1.7.v20120910. Make sure you can unpack and start Jetty as described here.

Jetty ships with examples you can safely remove:

  • contexts/javadoc.xml

  • contexts/test.d/override-web.xml

  • contexts/test.xml

  • webapps/spdy.war

  • webapps/test.war

Deploy Kill Bill in Jetty

Place the downloaded Kill Bill war under webapps/root.war in the Jetty folder.

Update the start.ini file with Kill Bill specific configuration. Here is a working example (make sure to adapt the jdbc properties):

# Kill Bill properties
-Dorg.killbill.dao.url=jdbc:mysql://127.0.0.1:3306/killbill
-Dorg.killbill.dao.user=killbill
-Dorg.killbill.dao.password=killbill

# Start classpath OPTIONS
OPTIONS=Server,resources,ext,plus,annotations

# Configuration files
etc/jetty.xml
etc/jetty-annotations.xml
etc/jetty-deploy.xml
etc/jetty-webapps.xml

You should now be all set! Kill Bill can be started via the command

java -jar start.jar

Enable SSL

The following command generates a key pair and certificate directly into a keystore:

keytool -keystore keystore -alias jetty -genkey -keyalg RSA

Save the keystore file under the etc/ directory of the Jetty distribution.

In your start.ini file, add the etc/jetty-ssl.xml configuration file and edit this file to update the KeyStorePassword, KeyManagerPassword and TrustStorePassword directives with the passwords you specified when you ran the keytool command.

Kill Bill should now be available over SSL. For more details, see the Jetty guide here.

Installation in Tomcat

Download the Tomcat container

If you don’t have it yet, you can download the Tomcat container here. You can then untar the archive and at this point you need to tweak the configuration before starting it. The setup suggested below is a quick setup used for demo, it may not be not best way to deploy your Kill Bill war into tomcat especially if you plan to have multiple wars within the same container.

Deploy Kill Bill in Tomcat

Assuming you installed tomcat in a directory called CATALINA_HOME, then there are two things that need to happen:

The Kill Bill system properties need to be added at the end of the CATALINA_HOME/conf/catalina.properties. The minimal set of system properties that need to added are the one for the jdbc parameters:

# Kill Bill properties
org.killbill.dao.url=jdbc:mysql://127.0.0.1:3306/killbill
org.killbill.dao.user=killbill
org.killbill.dao.password=killbil
ANTLR_USE_DIRECT_CLASS_LOADING=true

A new entry must be added to let tomcat know about the location of the Kill Bill war. That file is called Root.xml and it must located under CATALINA_HOME/conf/Catalina/localhost (create the directories if they don’t exist). Its content must be:

<Context docBase="path_to_killbill-server.war">
</Context>

Once this is setup, you can start the tomcat container using the script CATALINA_HOME/bin/startup.sh. The server will be started in the background but logs can be followed at CATALINA_HOME/logs/catalina.out.

Installation in Glassfish

Download the GlassFish container

If you don’t have it yet, you can download the GlassFish container here.

Deploy Kill Bill in GlassFish

Configure GlassFish with your Kill Bill specific configuration in domains/domain1/config/domain.xml (make sure to adapt the jdbc properties):

<jvm-options>-Dorg.killbill.dao.url=jdbc:mysql://127.0.0.1:3306/killbill</jvm-options>
<jvm-options>-Dorg.killbill.dao.user=killbill</jvm-options>
<jvm-options>-Dorg.killbill.dao.password=killbill</jvm-options>

In the glassfish directory of the unzipped GlasshFish distribution, run the following command to deploy Kill Bill:

./bin/asadmin start-domain ; ./bin/asadmin deploy --contextroot "/" /path/to/killbill.war

Configuration

System properties

Overview

Kill Bill configuration is done principally via Java System Properties. These can be set on the command line (e.g. java -Dkey1=value1 -Dkey2=value2 -jar killbill-server-jetty-console.war) or in Java Properties files (via -Dorg.killbill.server.properties=file:///path/to/killbill.properties or start.ini if you are using Jetty). Some containers use custom formats (for example, System Properties in GlassFish would be placed in domains/domain1/config/domain.xml), so please refer to your container documentation for more information.

The system properties are global to the system, and therefore will apply to all tenants. Those properties will also be accessible to the various plugins through a special interface. Some parts of the system also rely on additional xml configuration. Currently, only the caching layer which is based on EhCache requires such xml configuration. The location of the xml itself is specified via a system property org.killbill.cache.config.location.

In addition to these global settings, the following is also available on a per tenant basis:

  • Catalog configuration

  • Overdue configuration

  • Invoice templates, and language translation resources

System Properties

Kill Bill relies on config-magic to define, initialize, and make accessible through function calls all its system properties.

Some core services in Kill Bill export some properties, whose name is fairly explanatory:

The properties to configure the database are split between the core Kill Bill services and the plugins to allow plugins to use a different database or configuration (pooling, …​):

The properties to configure the persistent buses and notification queue are shown below. Those properties are built to be used across multiple instances (we have two persistent buses) which explains the substitution parameter instanceName. For more detail on the configuration of the bus and notification queue, check here.

Finally some high level properties to configure OSGI (where to find the plugins, …​), and some Kill Bill web app configuration (multi-tenancy on/off, …​):