How to integrate Kill Bill and Stripe end-to-end for a Monthly Subscription

Introduction

Creating a recurring billing solution can be difficult, and there are many challenges in the way. Customer management, automatic invoicing, secure payments, and failed transaction management are some common difficulties a business with a recurring subscription model may face.

In addition, many existing SaaS solutions force vendor lock-in on their customers, meaning that you don’t own the entirety of your data. You are also limited by the features the provider offers for your pricing schemes, as opposed to building your own.

Kill Bill solves these challenges by:

Operating from an entirely Open Source model — whether it runs locally or in the cloud, you own the subscription data, as opposed to being limited to the types of reports the SaaS solution provides
Integrating with providers like Stripe for payments, which will cover PCI complexity while you own the recurring billing logic

Tutorial

In this tutorial, we will guide you step-by-step on how to integrate Kill Bill and Stripe end-to-end for a monthly subscription model. We provide Docker as well as Non-Docker instructions as applicable.

Step 1: Install Kill Bill

Kill Bill can be installed via Docker or in a Tomcat server.

Using Docker

Ensure that you have Kill Bill, Kaui, and the database set up and running in Docker containers as explained in the Getting Started document.

You should be able to access the following:

Kaui UI

http://127.0.0.1:9090 (username/password: admin/password)

Kill Bill API

http://127.0.0.1:8080

Using Tomcat

Ensure that you have Kill Bill, Kaui, and the database set up in Tomcat as explained in the Getting Started document.

You should be able to access the following:

Kill Bill API

http://127.0.0.1:8080

Kaui UI

http://127.0.0.1:9090 (username/password: admin/password)

Step 2: Add a new tenant

Now, we need to add a new tenant.

At the top of the navigation panel, hover over the gear icon and select 'TENANTS.'
Select the '+' icon next to Kaui Tenants.

Enter the following information for the purpose of this tutorial:

Name: bob
API Key: bob
API Secret: lazar

Step 3: Create a new Sports product

After creating a new tenant, you should be brought to the following screen:

At the bottom of the screen, select the '+' icon next to Existing Plans to create a new product.

For the purpose of this tutorial, enter the following:

Click 'Save' and you should see the following:

Step 4: Create a Stripe account

Create an account at https://www.stripe.com. Once you have logged in, give your account a name by clicking on Add a name under the Unnamed account drop-down in the upper left-hand corner. A name is required for the Stripe integration.

Next, in the left panel, navigate to Developers > API Keys and click on Reveal test key token. You will need these keys once we configure the Stripe plugin for Kill Bill.

Step 5: Install the Stripe Plugin

In Kaui, hover over the plug icon at the top of the page and click on 'KPM (Kill Bill Plugin Manager).'

Select "Install New Plugin" in the upper-right corner.

In the list of plugins, find "stripe" and click on the cloud button to install.

After a few moments, refresh the /kpm page. You should see the stripe-plugin listed with a status of 'STOPPED.' Click the play button to start it. If you refresh again, you should find the stripe-plugin listed with a status of 'RUNNING.'

If you are not using Docker, you will also need to create the Stripe database tables by running this DDL in the Kill Bill database.

Step 6: Configure the Stripe Plugin with your API Keys

In Kaui, at the top of the screen, hover over the gear icon and select 'TENANTS.'

Click 'bob.'

At the bottom of the screen, navigate to the tab labeled 'Plugin Config.'

For Plugin name, select "stripe" from the drop-down menu.

In the configuration, enter the following and paste your publishable and secret keys you obtained from Stripe in Step 4.

org.killbill.billing.plugin.stripe.apiKey=sk_test_XXXX
org.killbill.billing.plugin.stripe.publicKey=pk_test_XXXX

Step 7: Install and run the Stripe Demo

The Stripe demo application can be installed via its Docker image or manually by cloning the code.

Using Docker

Open a command/terminal window and run the following command to pull the docker image for the Stripe demo application:

docker pull killbill/stripe-demo

Next, run the stripe-demo application using your Stripe publishable key as follows:

docker run -e PUBLISHABLE_KEY=pk_test_XXX -e KB_URL=http://host.docker.internal:8080 -ti -p4567:4567 killbill/stripe-demo

Manually by cloning the code

Open a terminal and clone the killbill-stripe demo:

$ git clone https://github.com/killbill/killbill-stripe-demo.git

Next, use RVM to install Ruby (Ruby 2.1+ or JRuby 1.7.20+ is recommended).

$ gpg --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3
\curl -sSL https://get.rvm.io | bash -s stable --ruby

On Windows machines, you can use RubyInstaller to install Ruby.

Once Ruby is installed, install the dependencies by running in the parent folder:

$ gem install bundler
$ bundle install

Next, run the stripe demo application using your Stripe publishable key as follows:

PUBLISHABLE_KEY=pk_test_XXX ruby app.rb

Step 8: Test the demo application

In your browser, navigate to http://localhost:4567/. This displays the following screen:

Enter dummy data (4242 4242 4242 4242 as the credit card number, any three digit CVC, any expiry date in the future, and any zip code) and click the Buy via Stripe Elements button. This displays the following confirmation screen:

Step 9: What just happened?

After we complete the checkout process with Stripe, the card has been tokenized, or intercepted and replaced with a surrogate token ID. If you visit to the Stripe Dashboard (https://dashboard.stripe.com), you should be able to navigate to the Payments page in the left-hand panel to see a succeeded Kill Bill charge for $10.

In Kaui, navigate to the /accounts page to see the newly created Kill Bill account, and select it:

You will see that a new payment method has been associated with this account by expanding 'Payment Methods' in the lower left-hand corner. A Customer object is also created in Stripe (see customer_id), so the token associated with this account can be re-used.

If you select 'Subscriptions' at the top of the page, you will see our newly creeated John Doe account now has a monthly subscription for our 'Sports' product, at a value of $10.00.

Navigating to the 'Payments' tab at the top of the page, you will also see that a payment was processed with an AUTH AMOUNT of $10.00.

Conclusion

Now, you should have a complete working setup of a monthly subscription model integrated with Kill Bill and Stripe.

Try playing around with the demo project to fit your needs, or check out the reference docs for more information:

API reference (https://killbill.github.io/slate/)
Production deployment (https://docs.killbill.io/latest/aws.html)
Community forum for help (https://groups.google.com/forum/#!forum/killbilling-users)