Payment bridge plugin to connect to Kill Bill (payment) system
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Bridge plugin

Release builds are available on Maven Central with coordinates

Kill Bill compatibility

Plugin version Kill Bill version
0.0.y 0.19.z
0.1.y 0.20.z


The killbill-bridge-plugin, or in short bridge, is intended to bridge two deployments of Kill Bill, one used as a subscription/invoice engine (KB Subscription or in short KB-S) , and the other one used as an internal payment gateway (KB Payment or in short KB-P):

alt text

The bridge really plays two different functions, one of which is to offer a payment control layer, by implementing the Kill Bill payment control plugin api, and the other is the payment plugin itself by implementing the Kill Bill payment plugin api. The payment control layer is used to modify incoming payment requests prior it reaches the payment plugin operation itself (e.g authorization).

The KB-S system will provide all the normal functionality, including payment operations, but those will be delegated to KB-P. There are numerous reasons why a company would want to adopt this model:

  • Keeping invoice/subscription engine separate from payment system fits well in a micro-services architecture model
  • Related to previous micro-services architecture point, this also allows to decouple the responsabilties -- different teams, deployment schedule,...
  • Allow to fully leverage the internal payment gateway to implement more advanced things like payment routing, payment optimization, ... while keeping all this aspect hidden from core subscription/invoice engine
  • Different compliance scopes (SOX, PII, PCI, ...)


There are two main models that we can identify, called respectively proxy and proxy-routing models:

  1. proxy model: The KB-P is used as a simple internal payment gateway but does not do any dynamic payment routing: In this model, each paymentMethod associated with an Account in KB-S reflects the plugin that should be used (e.g stripe) on the KB-P side -- that is, the pluginName associated to each paymentMethod will correctly show killbill-stripe in this example. The KB-P is completely transparent and really works as a proxy. NOTE This has only been partially impletemented **

  2. proxy-routing model: In this second model, the KB-P is used as a dynamic payment gateway. It can route payments based on rules such as latency, errors, BIN-level optimization, business-level rules -- mimimum volume to meet contract terms, ... In this case, creating a paymentMethod associated with an Account in the KB-S will not create a matching paymentMethod on the KB-P side; instead, the bridge will initiate all the payment requests with a null paymentMethodId and rely on the control payment layer on the KB-P side to automatically do the payment routing.


This plugin implements the Kill Bill payment plugin api and is intended to connect as a bridge between a Kill Bill system operating for handling billing components (Subscriptions, Invoices, ...) and another Kill Bill system operating for handling payments.

The plugin will need to have the default configuration parameter to connect to the remote Kill Bill (payment) system. In addition for each tenant, the details of the api_key and api_secret will be required.

Here's a configuration example:

  username: admin
  password: password
  apiKey: bob
  apiSecret: lazar
  # All other properties are optional
  proxyModel: proxy
  # Defaults to internalPaymentMethodId

In case you have a multi-regions deployment:

local: !!org.killbill.billing.plugin.bridge.BridgeConfig
    username: admin
    password: password
    apiKey: bob
    apiSecret: lazar

eu-central-1: !!org.killbill.billing.plugin.bridge.BridgeConfig
    <<: *killbillClientConfigDefault
    <<: *paymentConfigDefault

ap-northeast-2: !!org.killbill.billing.plugin.bridge.BridgeConfig
    <<: *killbillClientConfigDefault
    serverUrl: http://kb.apac:8080
    <<: *paymentConfigDefault


ID Mappings

Each KB system, KB-S and KB-P manages different objects entities (e.g Account) and those will have different ids on the different systems. Therefore in the most generic use case, the bridge will be responsible to make the id translation (e.g mapping a KB-S Account id with its counterpart KB-P Account id). In order to avoid keeping state in the plugin (id mapping table), we will use the externalKey associated with each object to keep this mapping:

The externalKey for each object (Account, PaymentMethod, Payment, PaymentTransaction) will be the same on both system. Because the PaymentPluginApi uses ids to refer all these objects, we need some mapping function for all objects. A typical mapping function wwill be (e.g accountId): KB-S (accountId) -> KB-S (Account) -> accountExternalKey -> KB-P (Account) -> KB-P (accountId).