stripe integration cover photo

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 the entirety of data is not owned by you. You are also limited by the features offered by the provider 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

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.

Step 1: Install Docker

The recommended way of installing Docker and Docker Compose is via Docker’s repositories, for ease of installation and upgrade tasks.

Select the appropriate instructions for your preferred operating system.

Step 2: Install Docker Compose

Select the appropriate instructions for your preferred operating system.

Step 3: Create a docker-compose.yaml file

In a terminal, type the following:

$ mkdir killbill
$ cd killbill

With your favorite text editor, create a docker-compose.yaml file and reflect the following:

version: '3.7'
volumes:
  db:
services:
  killbill:
    image: killbill/killbill:0.22.2
    ports:
      - "8080:8080"
    environment:
      - KILLBILL_DAO_URL=jdbc:mysql://db:3306/killbill
      - KILLBILL_DAO_USER=root
      - KILLBILL_DAO_PASSWORD=killbill
  kaui:
    image: killbill/kaui:2.0.1
    ports:
      - "9090:8080"
    environment:
      - KAUI_CONFIG_DAO_URL=jdbc:mysql://db:3306/kaui
      - KAUI_CONFIG_DAO_USER=root
      - KAUI_CONFIG_DAO_PASSWORD=killbill
      - KAUI_KILLBILL_URL=http://killbill:8080
  db:
    image: killbill/mariadb:0.22
    volumes:
      - type: volume
        source: db
        target: /var/lib/mysql
    expose:
      - "3306"
    environment:
      - MYSQL_ROOT_PASSWORD=killbill

Note that you may have to change the version of the yaml file you create, according to which version of Docker you are using.

Save the file, and run:

$ docker-compose up

The startup sequence lasts a couple of minutes. You should see something like the following once it finishes:

stripe integration docker startup

If it takes a long time or if the container crashes, verify you have enough memory allocated to Docker. On a Mac for instance, go to Docker Desktop Preferences and set the Memory to 4GiB in the Advanced panel.

You may now access the following:

Kaui UI
Kill Bill API

Step 4: Add a new tenant

Now, we need to add a new tenant.

  1. At the top of the navigation panel, hover over the gear icon and select 'TENANTS.'

  2. 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 5: Create a new Sports product

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

stripe integration tenant

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:

stripe integration new product

Click 'Save' and you should see the following:

stripe integration existing plans

Step 6: 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 7: 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.'

stripe integration plugin running

Step 8: 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 5.

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

Step 9: Clone and Run the Demo

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

Afterwards, install the dependencies by running in the parent folder:

$ gem install bundler
$ bundle install

Obtain the IP address of your Kill Bill Docker container by running the following:

$ docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' <CONTAINER_ID>

Now, you can run the app using your Stripe publishable key:

$ KB_URL='http://<KILL_BILL_CONTAINER_IP>:8080' PUBLISHABLE_KEY=<YOUR_PUBLISHABLE_STRIPE_KEY> ruby app.rb

In your browser, navigate to http://localhost:4567/ and click the 'Buy' button.

Enter dummy data (4242 4242 4242 4242 as the credit card number, any three digit CVC and any expiry date in the future work) and complete the checkout process.

Step 10: 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.

stripe integration tokenization

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

stripe integration kbaccount

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.

stripe integration payment methods

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.

stripe integration subscription bundles

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.

stripe integration payments

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: