What is a Kill Bill Plugin
Kill Bill Plugins are based on the OSGI Standard. They provide a way to write isolated code on top of the Kill Bill platform and interact with the system through different ways:
-
They can be called from the Kill Bill platform through Plugin APIs. This happens when a plugin that implements one of those APIs (or 'SPI' to be more precise) was correctly registered in the system.
-
They can receive bus events from the Kill Bill platform.
-
They can make API calls to Kill Bill.
Plugin Capabilities
Kill Bill Plugins have full power (and therefore need to be designed and tested carefully):
-
They have access to the database so as to maintain their own state. However they should not interact with the Kill Bill core tables directly but rely on APIs to retrieve and change state.
-
They have access to system properties.
-
They receive all events in the system.
-
They are isolated from the rest of the code and can use their own libraries (versions) without risk of conflict.
How You Can Use Plugins
Kill Bill Plugins can be used in a variety of ways:
-
Extend Kill Bill subsystem: Payment plugins are a good example of such plugins; they extend the core payment functionality by connecting to third party systems.
-
Provide additional business logic: Payment control plugins and invoice plugins allow to intercept the requests so as to modify it, abort it, or change state on the fly.
-
Listen to system events: Notification plugins listen to system events and take appropriate actions. For example, the analytics plugin can be used to build reports while the email notification plugin can be used to send emails.
-
Expose HTTP endpoints: Plugins can also export their own HTTP endpoints under a
/plugins/<pluginName>namespace. These can then be invoked via a REST client as required.
Types of Plugins
A Kill Bill plugin can either listen to Kill Bill bus events to be notified of changes and take appropriate actions and/or implement one (or several) plugin API(s). Thus, there are mainly two main types of plugins as follows:
-
Notification Plugin: A plugin registered to receive bus events. When a bus event is being delivered to the plugin, the plugin calls back Kill Bill through API calls to retrieve additional state for this event or to change the state in the system.
-
Plugin that is registered as an implementor of a specific Plugin API: These can be further classified as follows:
-
Payment Plugins - Implement the PaymentPluginApi. So, when a payment plugin registers itself as an implementor of the
PaymentPluginApi, the payment system invokes the plugin for issuing payment operations. The plugin has the ability to call back Kill Bill using APIs to retrieve more state or create/change state in the system. -
Payment Control Plugins - Implement the PaymentControlPluginApi.
-
Invoice Plugins: Implement the InvoicePluginApi.
-
Catalog Plugins: Implement the CatalogPluginApi.
-
Entitlement Plugins: Implement the EntitlementPluginApi.
-
Usage Plugins: Implement the UsagePluginApi.
-
It often makes sense to specialize plugins and have them implement only one of the plugin APIs, but this is a design choice, and there is nothing preventing a plugin from implementing multiple APIs. Although we don’t recommend it, a plugin could implement the PaymentPluginApi and the PaymentControlPluginApi, and that would qualify it as a 'payment and payment control plugin'.
List of Open-Source Plugins
The list below includes the most common open-source plugins. You can check the Kill Bill Github page for the complete list of plugins maintained by the Kill Bill team.
Analytics & Reporting
Use this plugin to generate reports and view them via Kaui. The plugin listens to all events in Kill Bill and maintains a set of reporting tables in real-time for business intelligence.
Work with the canned reports or create your own custom reports with the local database. You can also create reports against external databases.
The Analytics & Reporting plugin is a notification plugin type. You can read about notification plugins in Developing a Notification Plugin.
Coupons/Entitlement
This is a demo as opposed to a fully functional plugin. It uses the core entitlement subsystem to intercept subscription operations (i.e., subscription creation) so you can inject your own subscription business logic. Use cases include coupons management or price overrides. It can also use the catalog price override functionality to override the price on the fly.
For information about an entitlement type of plugin, see Developing an Entitlement Plugin.
Deposit
The deposit plugin enables you to distribute a single payment against multiple invoices. A couple of use cases that come to mind include:
-
Offline payment methods, such as wire transfers, in which finance personnel matches the details of the B2B customer’s wire (or ACH) deposit against the unpaid invoice. This is helpful for large organizations that settle in bulk several invoices with a single bank transfer.
-
Online payment methods, such as credit cards. In this situation, the B2B customer pays several unpaid invoices via a single credit card transaction. The deposit plugin can settle the unpaid invoices.
The Deposit plugin is a payment control plugin. You can learn more about that plugin type in Developing a Payment Control Plugin.
Email Notifications
The Email Notifications plugin listens to Kill Bill events, and when those events occur, it sends out an email. These events include:
-
Invoice creation
-
Payment failure
-
Payment (or refund) success
-
Subscription cancellation
Additionally, the plugin can send an email to your customer about upcoming invoices, the timing of which is adjustable. You can also configure the Email Notifications plugin to handle other types of events.
For more information about notification plugin types, see Developing a Notification Plugin.
Framework/Learning
Jump in and learn how to write Kill Bill plugins!
Hello World
The Hello World plugin shows how to do the following:
-
Build an OSGI plugin using Maven
-
Listen to Kill Bill events
-
Call Kill Bill APIs from the plugin
-
Register a custom HTTP servlet
This is a notification type of plugin. You can learn about notification plugins in Developing a Notification Plugin.
GoCardless Example
GoCardless enables customers to pay for products and services from their bank accounts. We call it an “example” because its operations include setting up a mandate for a first-time customer and processing payments, but it does not process credits or refunds.
To learn about payment plugins, see the Payment Plugin Overview.
For details about developing your own payment plugin, see the Payment Plugin Development Guide
Payment Gateways
Our current open-source payment plugins are for Adyen, Braintree, Qualpay, Stripe, and Hyperswitch.
Note: The Braintree and Adyen (Checkout) open-source plugins were developed by Wovenware, our development partner.
For more information about payment plugins, see the Payment Plugin Overview.
For details about developing your own payment plugin, see the Payment Plugin Development Guide
Taxes
We did not design Kill Bill to handle tax, deciding instead to defer tax logic to plugins. We have two open-source tax plugins that can communicate with third-party tax calculation vendors: Avalara Avatax and the Simple Tax plugin.
The tax plugins are considered a type of invoice control plugin. For more information on invoice control plugins, see Developing an Invoice Control Plugin.
Avalara Avatax
The Avatax plugin has two sets of APIs. One is for the full-featured Avalara AvaTax product. The other is for the Avalara TaxRates API. The TaxRates API is a free-to-use, no cost option for estimating sales tax rates.
You can request a free AvaTax account to use the TaxRates API. (Even after the trial period ends, you can still use it.)
Simple Tax
Developed by the Kill Bill community, you can use the Simple Tax plugin for fixed-rate taxes (for example, VAT).
Testing
Don’t worry - we’re not going to test you on your Kill Bill knowledge! Instead, we have a couple of plugins: one to test a catalog (assuming you are using a customized one) and another one to test payments.
Catalog Test
If you have decided to build your own catalog to work with Kill Bill’s subscription engine (along with the invoicing and payment logic), the Catalog Test plugin is a starting point. It loads a static json catalog and serves that catalog through the CatalogPluginApi.
To learn about catalog plugins, see Developing a Catalog Plugin.
Payment Test
You can use the Payment Test plugin to test the Kill Bill Payment plugin API by enabling certain failure modes (insufficient funds, payment gateway errors, runtime error, etc.) on a payment call.
For information about payment plugins, see the Payment Plugin Overview.
Further Reading
Plugin Development: