This is the reference guide to get started with Kill Bill Payments Platform.

Introduction

Kill Bill Payments Platform is designed to offer a single payment API for any type of payment gateway, processors, bank,…​ and to support any kind of payment flows. It is typically used to charge customers in eCommerce Shopping Cart type flows.

Requirements

We will assume:

  • You have gone through What is Kill Bill and are familiar with Kill Bill

  • You have gone through the Getting started tutorial and have Kill Bill, Kaui and the database setup and running

  • You have a tenant configured with API key bob and API secret lazar

  • You have cURL installed. This is only to be able to run the setup steps and examples from this documentation. In practice, your application will use one of our client libraries. If you are on Windows, we recommend that you use Git Bash to run the cURL commands.

Overview

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.

Terminology

Throughout this document, we will be using the following terminology:

E-commerce application/merchant website/client application - Application that integrates with Kill Bill.

End-user/customer - User that uses the e-commerce application.

Payment-related APIs - Kill Bill APIs that perform payment related operations.

Payment plugin - Piece of code that resides within Kill Bill and implements payment gateway specific APIs/interacts with the payment gateway.

Payment gateway/payment provider - Entity that processes the payment.

Account - A customer account in Kill Bill corresponding to an end-user.

Payment Method - A record of the details required for Kill Bill to trigger a payment. Payment Methods represent things like credit cards, debit cards, or PayPal accounts. An account can have multiple payment methods corresponding to different payment gateways.

Payment - A Kill Bill record that encapsulates charging an end-user against a payment method. It has a state that indicates the status of the underlying transaction.

How Payment Works

The following diagram provides a high level overview of the payment system in Kill Bill:

payment system overview

The Kill Bill payment system consists of Kill Bill’s payment related APIs and payment plugins. The Kill Bill APIs can be used by an external e-commerce application (to trigger one-off payments), by the Kill Bill core engine (to process recurring payments) and by Kill Bill Admin UI (Kaui)) (to process refunds, chargebacks, etc). The payment-related APIs then interact with the payment gateway via a payment plugin specific to the gateway.

Payment Methods Overview

As explained earlier, a payment method represents an abstraction corresponding to a payment scheme like a credit card, debit card, or PayPal. An account can have multiple payment methods corresponding to different payment gateways. For example, an account can have a credit card payment method as well as a Paypal payment method.

Each account also has a default payment method associated with it. When the account needs to be charged for recurring payments, the default payment method is used. Additionally, a client application can also override the payment method to use on a per payment call.

Payment Plugins Overview

As explained earlier, each payment gateway needs to have a gateway specific plugin within Kill Bill. Thus, at any time, there can be multiple payment plugins registered with Kill Bill, each of which interacts with a different payment gateway. When the Kill Bill system charges a customer against a particular payment method, the plugin associated with that payment method is used.

The figure below shows the relationship between a Kill Bill Account, its various PaymentMethods, each of which points to a Kill Bill plugin, which in turn interacts with a third party payment gateway.

payment plugin overview

Kill Bill provides many open-source payment plugins corresponding to different payment gateways. In addition, Kill Bill also has a Plugin API that can be used for developing a custom payment plugin corresponding to a specific payment gateway (as explained in the Plugin Development Guide).

By default, Kill Bill does not come configured with any payment plugins. So, if you would like to install an existing plugin or a custom plugin, you need to do this seprately as explained in the Plugin Installation Guide.

However, Kill Bill does have a built-in payment method called __EXTERNAL_PAYMENT__. This can be used to track payments that occur outside of Kill Bill. For example, a customer may be invoiced through Kill Bill and may later make a payment by check. The payment needs to be recorded into the system to mark the invoice as being paid and to bring its balance to zero. In such cases, the payment can be recorded against the __EXTERNAL_PAYMENT__ payment method.

Payment Methods

A payment method refers to the end-user’s payment details. When an end-user enters his/her payment details (like card information) into a merchant website, these payment details need to be saved in Kill Bill in order for Kill Bill to be able to process recurring payments. Additionally, the payment details may need to be saved within the payment gateway so that the end user does not have to enter their payment details each time.

The PaymentApi#addPaymentMethod is the entry point for saving a payment method in Kill Bill. Thus, a merchant website needs to invoke this method in order to save the payment details as a payment method in Kill Bill.

Payment Method Flows Overview

Payment method flows describe how a payment method gets created in Kill Bill.

Kill Bill supports three main payment method flows as follows:

  • Client-Side Tokenization - In this case, the end user’s payment method details are converted into a token which is sent to Kill Bill.

  • Hosted Payment Page - In this case, the merchant website redirects the end-user to a page on the payment gateway, which collects the payment method details. Kill Bill then fetches a gateway-specific token from the payment gateway.

  • Server-Side Tokenization - In this case, the end-user’s payment details are sent to Kill Bill, which then sends these to the payment gateway to perform tokenization.

The flow diagrams below explain these payment method flows. We consider the following actors:

  • Browser: The end-user sitting behind a browser and initiating the payment method flow

  • Merchant Site: customer facing web site which receives the order

  • Kill Bill - The Kill Bill system

  • Checkout Servlet - Plugin servlet that initiates setting up the payment method.

  • Payment Plugin: Kill Bill plugin corresponding to the payment gateway.

  • Payment Gateway: Entity that processes the payment.

Client-side Tokenization Payment Method Flow

In this case, the merchant website collects the end-user’s payment details. These are then converted into a token (either via a payment gateway specific Javascript or iFrame). This token is sent to Kill Bill. Kill Bill then saves it in the Kill Bill database and uses it to charge the customer.

The following diagram explains this payment method flow:

clientside tokenization payment method flow

  1. The end user enters payment details on the merchant website.

  2. The merchant website converts it into a token and invokes the addPaymentMethod in Kill Bill with this token. This saves the token in the Kill Bill database.

  3. Some payment gateways require the token to be saved within the gateway so as to be able to process recurring payments. In such cases, Kill Bill invokes the addPaymentMethod in the payment plugin corresponding to the payment gateway.

  4. The payment plugin then makes a gateway specific call to save the payment token within the gateway.

Hosted Payment Page Payment Method Flow

Sometimes, a merchant site may not provide a payment form/may not want to collect payment data and tokenize it. The hosted payment page flow is useful in such situations. In such cases, the merchant site needs to perform a two-step process. In the first step, it needs to invoke Kill Bill to obtain the URL to redirect the user and redirect the user to this page. Once the end-user enters his/her payment details on this page, the merchant site needs to invoke Kill Bill to add the payment method. Kill Bill then retrieves the payment details from the payment gateway and saves them in the Kill Bill database. This information is then used by Kill Bill to charge the customer.

The following diagram explains this payment method flow:

hpp payment method flow

  1. The end user initiates the checkout process.

  2. The merchant website invokes a checkout servlet in Kill Bill.

  3. The checkout servlet invokes the PaymentPluginApi#buildFormDescriptor method in the payment plugin.

  4. The PaymentPlugin#buildFormDescriptor method makes a gateway-specific call and obtains a redirect URL.

  5. The merchant website redirects the end user to this URL.

  6. The end user enters payment details on this page.

  7. If successful, the payment gateway redirects the user to a success URL on the merchant site.

  8. The merchant site then invokes the KillBill#addPaymentMethod

  9. Kill Bill in turn invokes the PaymentPlugin#addPaymentMethod.

  10. The PaymentPlugin#addPaymentMethod performs a gateway specific call and obtains a gateway specific payment method id. This is then saved in the Kill Bill database.

Server-side Tokenization Payment Method Flow

Sometimes, a merchant site may collect the card details from the end-user and send them to Kill Bill. In this case, Kill Bill makes a call to the payment gateway to tokenize the card information. However, this approach is used very rarely as this requires a merchant website to be PCI Level 1 compliant. To know what it takes to be PCI Level 1 compliant, you can read this article.

The following diagram explains this payment method flow: