Kill Bill payment guide

Download the latest jetty-console.war from Maven Central (download the jetty-console.war artifact).

To start Kill Bill, either double click on the war file, or run the following in a terminal (recommended to check logs):

This will start Kill Bill with an embedded H2 database (data is persisted in a local killbill.h2.db file, so changes are preserved across restarts).

After the system has started, you can experiment by following the simple scenario below. Note that each call creating an object in the system returns its URI, and so the curls below are using the UUID that was returned at the time the demo was created. You would need to replace the UUID with the one returned in each call if you were to follow that demo.

If you get an error like the following at startup:

you may have an invalid hostname set. To work around it, add the following line in /etc/hosts:

and restart Kill Bill.

Kill Bill has a payment subsystem which offers several APIs:

The former set of APIs is used by the core billing engine to charge for subscriptions, and by Kaui (the Kill Bill Admin UI) to handle refunds, chargebacks, adjustments, etc. for invoices and payments associated with such subscriptions.

The latter set can be used to trigger payments (auth, capture, credit, refund, etc.) by your e-commerce application (e.g. shopping cart). It also offers helpers to create payment forms and redirect URLs in case of hosted payment pages. It is independent of any subscriptions or invoices and is used solely to make payments.

Kill Bill is a generic platform to build billing and payment infrastructures and as such, it is agnostic of payment gateways. However, it provides a framework to register payment plugins, which in turn implement gateway specific APIs. Those payment plugins must be OSGI compliant plugins. They can be written either in:

The main reason to provide a way to write ruby payment plugins is to be able to reuse the Active Merchant gem. We even have a generator to help you generate a payment plugin from an Active Merchant implementation.

Check the wiki page Payment Plugins for a community-supported list of already written payment plugins.

The Kill Bill payment code will detect all the payment plugins registered in the system and decide which plugin to use when a charge, refund, …​ operation needs to happen. The dispatching is based on the payment methods associated with each account. By default, the model is to attach a default payment method to each account: that payment method will have a link that points to a specific plugin to use. For instance, one account could have a Paypal payment method that would point to the Paypal plugin. Additionally, you can also override the payment method to use on a per payment call. The figure below shows the relashionship between a Kill Bill Account, its various PaymentMethods, each of which points to a given Kill Bill plugin, which itself is in charge to interact with a third party payment gateway.

By default Kill Bill does not come configured with any payment plugins except for the built-in EXTERNAL_PAYMENT, which is used to track payments which occurred outside of Kill Bill. A typical example would be for when a customer pays by check and we want to make sure the invoice balance is set to 0 after receiving the check. A user, represented in Kill Bill as an account can add as many payment methods as required, and each of those will identify a specific plugin that Kill Bill will use when making payments.

Initially a client of the api can make either an authorization, a purchase, or a credit call (all other operations such as refund would require an initial payment to have already existed). That initial operation will create a Payment and an initial PaymentTransaction. The user can then submit additional requests for the same payment (capture, refund, …​) and each of those calls will result in additional PaymentTransaction attached to the same payment. The payments have a state which will drive the set of possible subsequent operations available. For instance, it is possible to make a capture call against a payment in a state AUTH_SUCCESS but it is not possible to make such an operation against a payment in an AUTH_ERRORED state. The set of payment state transitions are configured in an xml file and the Kill Bill payment subsystem is in charge to enforce the transitions. The following diagram below shows all the possible transitions:

In addition to the payment state transitions, each PaymentTransaction has a status to reflect the result of the operation. The PaymentTransaction status depends on the plugin result and it can be summarized below:

Note that the first 3 cases are normal cases but the last 2 are errors that are unrelated to the user being able to make the payment operation:

If a payment is aborted by a control plugin, a payment attempt row is recorded with a state of ABORTED (no payment nor payment transaction is created). Kill Bill will return a 422 HTTP code.

Kill Bill supports two main payment flows, referred to as Hosted Payment Pages (or HPP) and as Gateway integration:

For a concrete example on how the two flows can be implemented, take a look at our Adyen demo.

In the flow diagrams below, we consider the following actors:

During an HPP flow, the customer enters his payment method information (either on the main Merchants Site or a third-party site) and then submits a form containing that information to make the payment. The information required to present the user with a payment form (specific form fields or URL where the form is hosted) is obtained by calling the buildFormDescriptor API.

The result of the API call will depend on the type of HPP integration:

Note that after calling buildFormDescriptor, the payment may or may not exist in Kill Bill: this will depend on the plugin. If it does however, it will be most likely in a PENDING state.

Here are a few common scenarii:

The conceptual flow below shows a 3D-Secure variation of the previous flows. The main difference is that prior redirecting the browser to the landing page, it is first redirected to the access control server where the user can enter custom information.

For gateway integrations, the entry point for any payment is either the createAuthorization (to authorize a credit card), createPurchase (to charge a payment method, for example authorizing and capturing a credit card, to initiate an ACH transfer, to withdraw money from a Bitcoin wallet, etc.) or createCredit (to deposit money on a payment method, without any reference to a previous payment) APIs. The payment state will be in *_INIT state before calling the plugin.

Usually, transactions end up in a terminal state right away as most gateways provide synchronous APIs. However, depending on the payment method, the plugin can choose to set the status to PENDING. For example, this is the case for 3D-Secure transactions (until the payment is verified by the issuer after redirecting the user), for direct debit transfers (e.g. ACH, which take usually a couple of days to be acknowledged), or for Bitcoin transfers (until the transaction is confirmed by the blockchain). Additionally, some gateways don’t always provide synchronous responses (e.g. when capturing funds using Adyen), in which case the plugin has to rely on asynchronous notifications to transition the payment into a terminal state.

Before any payment operation can occur, the user must first enter his payment information. In Kill Bill, this translates into creating a PaymentMethod. When dealing with credit card information specifically, merchants have to keep the data into a PCI compliant environment (often handled by the gateway): this process requires tokenization of the PAN, so that the payment system only handles the token, which is stored at the plugin level and passed to Kill Bill as a plugin property. Take a look at our Stripe demo for a concrete example.

Note that the creation of the Kill Bill payment method is not represented in the flows below: it can happen either in a prior step or during the payment using one of our combo payment call. Usually, the user is prompted with a form to enter his payment method information, and then the payment is initiated using one of the createAuthorization or createPurchase APIs. Kill Bill will connect to its payment plugin which in turn will contact the gateway to perform the required operation. Upon success/failure, the user is redirected to a landing page.

If 3D-Secure is enabled, the payment (e.g. authorization) is split into two phases:

In the sections below, we are presenting APIs to manage payment methods and payments operations. Those APIs have been built to be as generic as possible. Because each plugin/gateway has its own specificities, you can pass extra data by using plugin properties:

This mechanism allows to pass information from the client of the API to the plugin, while being opaque to Kill Bill; for instance, in order to specify the following two plugin properties:

One would have to add the following query parameters (note that this needs to be URL encoded):

The mechanism also works for receiving information back from the plugin; the plugin can return a piece of json that will be embedded in the json response; for instance, the plugin could return a specific key:

A payment object is associated with a set of transactions (authorization, multiple captures, etc.). You can retrieve that object via:

The calls below describe how to create payments. For each call, you can specify in the body a transactionExternalKey string to tag your payments (it represents a unique identifier in an external system).