How to integrate Kill Bill and Stripe end-to-end for a Monthly Subscription
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.
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. 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.
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:
http://127.0.0.1:9090 (username/password: admin/password)
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:
http://127.0.0.1:8080/kaui (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.
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.
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.'
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.
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.
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.
Now, you should have a complete working setup of a monthly subscription model integrated with Kill Bill and Stripe.
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)