This version of Kill Bill is not supported anymore, please see our latest documentation

Introduction

This tutorial will help you put all of the pieces of the Subscription Billing and Payment features together, and work through a real-world scenario, so you understand how to integrate Kill Bill with your application.

Scenario

Let’s assume you want to build a site similar to Amazon Prime, i.e. an e-commerce website which offers a shopping cart and where paying subscribers have extra benefits (discounts, free shipping, etc.). You want to accept both credit cards and PayPal as means of payment.

Kill Bill will handle all subscriptions and payments as a separate service, and your application will communicate with Kill Bill over HTTP APIs.

Note that we won’t go into the details of building the actual website, we will assume you already have a front-end (Rails app, JSP webapp, etc.). You can also take a look at the following Stripe and PayPal demo websites, to help you with the front-end integration.

multi_gateways_overview

Requirements

We will assume:

  • You already went through the Getting started tutorial

  • You have MySQL installed and have created a killbill database

  • You have cURL installed. This is only to be able to run the examples from this tutorial. In practice, your application will use one of our client libraries

Setup

Payment gateways setup

To accept credit cards, we will integrate with Stripe: they offer free sandbox accounts and provide a nice dashboard to follow what’s going on. Choosing your payment processor is critical however, you need to make sure it offers the features you need (international payments, etc.) while minimizing your costs (see this blog post for more details on the topic). Luckily, there are thousands of vendors available and Kill Bill can integrate with pretty much any of them, so make sure to do your research.

Stripe

PayPal

  • Create a free account at paypal.com

  • Go to your Dashboard and click Create Account (You need both a Personal and a Business account). The Business account is for the merchant that will receive the money and the Personal account is for the customer that will purchase the subscription.

  • Login to the sandbox using the Personal account credentials and add some money

You then need to contact support so they can enable recurring payments on your sandbox:

  • Go to PayPal Technical Support

  • Create a ticket and ask to "Enable reference transactions for the Sandbox account XXXXX". Replace XXX with the API username of the Business test account you created (to see the username, click on Profile in the dashboard under the email address of the account, then click on the API credentials tab)

This process can take up to 48 hours. In the meantime, while you will be able to test one-time purchases, you won’t be able to test recurring transactions in PayPal.

MySQL

As stated in the requirements, we’re assuming you already have MySQL installed with a killbill database. You need to populate the database with the tables for the two plugins (Stripe and PayPal).

Assuming the server is located at 127.0.0.1 and the username/password to connect to it are killbill/killbill, run:

curl https://raw.githubusercontent.com/killbill/killbill-stripe-plugin/master/db/ddl.sql | mysql -h 127.0.0.1 -ukillbill -pkillbill killbill
curl https://raw.githubusercontent.com/killbill/killbill-paypal-express-plugin/master/db/ddl.sql | mysql -h 127.0.0.1 -ukillbill -pkillbill killbill

Plugins installation

Go to the Kaui plugins page and click the install button next to Stripe and PayPal. The process takes a few minutes to download and setup the binaries on the filesystem.

Plugins are installed under /var/tmp/bundles/plugins. You should see one sub-directory per plugin. If you work with Ruby, the directory structure should be familiar, as it is simply a gem cache. If you don’t, don’t worry. Just know that each plugin is independent and has all of its dependencies, hence the large number of files and directories.

Stripe setup

Go to your tenant configuration page and select the "Plugin Config" tab at the bottom. Enter stripe as the plugin name and the UI will prompt you for the secret key.

PayPal setup

Similarly, go to your tenant configuration page and select the "Plugin Config" tab at the bottom. Enter paypal as the plugin name and the UI will prompt you for the signature, login and password.

Shopping cart integration

In your website, we assume you have a shopping cart module: users can add items to their basket and when they are ready, go to the checkout page. This page will present various payment options (credit card form and PayPal button), as well as display their payment methods on file (previously used credit cards or linked PayPal accounts).

Creating accounts

We will assume that users going to your site have to create an account in your system. When they do, you will need to create a mirrored account in Kill Bill. This will let you do things like retrieve all payments for a given user, etc.

While your website will issue an API call to do it, let’s simply use Kaui in this tutorial to create the account manually.

Notes:

  • The externalKey should map to the unique id of the account in your system

  • There are many more fields you can store (phone number, address, etc.) — all of them are optional

Storing payment methods

At some point, the user will need to store his credit card information and/or his PayPal account. This can happen on a settings section of your website, or during the checkout flow.

This step is probably the most difficult one, as it is payment processor specific.

Stripe

Handling credit card information is regulated by the PCI-DSS standard. Fortunately, Stripe lets your work around these requirements by providing a special form. Users will use this form to securely store their card into Stripe servers, while Stripe will give you a token you will use to charge these cards.

For more details on the integration, checkout the stripe.js documentation.

When the Javascript call returns from Stripe, it will contain the token that needs to be stored in Kill Bill:

curl -v \
     -X POST \
     -u admin:password \
     -H 'Content-Type: application/json' \
     -H 'X-Killbill-ApiKey:bob' \
     -H 'X-Killbill-ApiSecret:lazar' \
     -H 'X-Killbill-CreatedBy: creator' \
     --data-binary '{
       "pluginName": "killbill-stripe",
       "pluginInfo": {
         "properties": [
           {
             "key": "token",
             "value": "t3GER3BP3JHLASZe"
           }
         ]
       }
     }' \
     "http://127.0.0.1:8080/1.0/kb/accounts/<ACCOUNT_ID>/paymentMethods?isDefault=true"

This will create a new payment method and set is as the default for the account. If you load the account page in Kaui, you should now see the payment method.

A demo of that integration is available here.

PayPal

The PayPal flow is a bit different. You first need to tell PayPal you are going to create a token:

curl -v \
     -X POST \
     -u admin:password \
     -H 'Content-Type: application/json' \
     -H 'X-Killbill-ApiKey:bob' \
     -H 'X-Killbill-ApiSecret:lazar' \
     -H 'X-Killbill-CreatedBy: creator' \
     --data-binary '{
       "kb_account_id": "<ACCOUNT_ID>",
       "currency": "USD",
       "options": {
         "return_url": "http://www.google.com/?q=SUCCESS",
         "cancel_return_url": "http://www.google.com/?q=FAILURE",
         "billing_agreement": {
           "description": "Your subscription"
         }
       }
     }' \
     "http://127.0.0.1:8080/plugins/killbill-paypal-express/1.0/setup-checkout"

Kill Bill will return a 302 Found on success. The customer should be redirected to the url specified in the Location header, e.g. https://www.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=EC-20G53990M6953444J.

Follow the link to log to the paypal site: on the PayPal site, the user will be guided through the approval process to create a token for your website.

Once that step is completed, the customer comes back from the PayPal flow, you can now create the payment method in Kill Bill by specifyfing the token that was returned in the setup-checkout step (e.g. EC-20G53990M6953444J). Note that this token is now associated to the customer who was redirected to Paypal and accepted the agreement.

curl -v \
     -X POST \
     -u admin:password \
     -H 'Content-Type: application/json' \
     -H 'X-Killbill-ApiKey:bob' \
     -H 'X-Killbill-ApiSecret:lazar' \
     -H 'X-Killbill-CreatedBy: creator' \
     --data-binary '{
       "pluginName": "killbill-paypal-express",
       "pluginInfo": {
         "properties": [
           {
             "key": "token",
             "value": "EC-20G53990M6953444J"
           }
         ]
       }
     }' \
     "http://127.0.0.1:8080/1.0/kb/accounts/<ACCOUNT_ID>/paymentMethods?isDefault=true"

If you load the account page in Kaui, you should now see the two payment methods.

A demo of that integration is available here.

Processing payments

While storing a payment method is payment processor specific, triggering payments isn’t (Kill Bill is hiding the complexity for you). When the user clicks "buy" on your checkout page, perform the following call (update the amount accordingly):

curl -v \
     -u admin:password \
     -H "X-Killbill-ApiKey: bob" \
     -H "X-Killbill-ApiSecret: lazar" \
     -H "Content-Type: application/json" \
     -H "X-Killbill-CreatedBy: demo" \
     --data-binary '{"transactionType":"PURCHASE","amount":"10","currency":"USD"}' \
     "http://127.0.0.1:8080/1.0/kb/accounts/<ACCOUNT_ID>/payments"

That’s it! The call will synchronously go to Stripe or PayPal, depending on the default payment method on the account, and perform the payment.

If you want to display payment methods information on the checkout page, you can retrieve them via:

curl -v \
     -u admin:password \
     -H "X-Killbill-ApiKey: bob" \
     -H "X-Killbill-ApiSecret: lazar" \
     -H "Content-Type: application/json" \
     "http://127.0.0.1:8080/1.0/kb/accounts/<ACCOUNT_ID>/paymentMethods?pluginInfo=true"

This is useful if you want to let the user override the payment method to use during checkout. In that case, you can pass the query parameter paymentMethodId to the purchase call above.

Subscriptions integration

Now that your users are able to purchase their products, we want to offer a buy-up subscription option, and offer free shipping to subscribed users. For simplicity, we will assume that we offer a single Standard plan, at $24.95 per month.

Creating the catalog

Plans are defined in an XML configuration file. This file is really powerful and offers various options for handling trials, add-ons, upgrades/downgrades, etc. For more details on its features, read the Subscription Billing user guide.

For simplicity, Kaui lets you configure simple plans through the UI, so you don’t have to generate the catalog manually. This is available on your tenant configuration page.

For this tutorial, create 2 plans: standard-free (free plan) and standard-monthly (premium plan), associated with a single Standard product (the product category is BASE). We could have just defined standard-monthly, but that way you could make free users subscribe to the free plan. This is useful for reporting for example (to track how long it took to upsell them, etc.)

Note that we haven’t defined any trial period.

multi_gateways_standard-free_kaui multi_gateways_standard-monthly_kaui multi_gateways_catalog_kaui

Creating and retrieving subscriptions

Let’s now try to subscribe a user to the Standard plan. This is the call that will need to be triggered from the website, when the user chooses the premium plan on the subscription checkout page (we assume the user has already an account and payment method on file, see the previous section):

curl -v \
     -u admin:password \
     -H "X-Killbill-ApiKey: bob" \
     -H "X-Killbill-ApiSecret: lazar" \
     -H "Content-Type: application/json" \
     -H "X-Killbill-CreatedBy: demo" \
     -X POST \
     --data-binary '{"accountId":"<ACCOUNT_ID>","planName":"standard-monthly"}' \
     "http://127.0.0.1:8080/1.0/kb/subscriptions"

Because there is no trial period and billing is performed in advance, Kill Bill will have automatically billed the user for the first month.

To view the invoice:

curl -v \
     -u admin:password \
     -H "X-Killbill-ApiKey: bob" \
     -H "X-Killbill-ApiSecret: lazar" \
     -H "Content-Type: application/json" \
     "http://127.0.0.1:8080/1.0/kb/accounts/<ACCOUNT_ID>/invoices?withItems=true"

To view the payment:

curl -v \
     -u admin:password \
     -H "X-Killbill-ApiKey: bob" \
     -H "X-Killbill-ApiSecret: lazar" \
     -H "Content-Type: application/json" \
     "http://127.0.0.1:8080/1.0/kb/accounts/<ACCOUNT_ID>/payments"

Kill Bill will now automatically charge the user on a monthly basis. You can estimate the amount which will be billed at a future date (replace the targetDate parameter with a date in the future):

curl -v \
     -u admin:password \
     -H "X-Killbill-ApiKey: bob" \
     -H "X-Killbill-ApiSecret: lazar" \
     -H "Content-Type: application/json" \
     -H "X-Killbill-CreatedBy: demo" \
     -X POST \
     "http://127.0.0.1:8080/1.0/kb/invoices/dryRun?accountId=<ACCOUNT_ID>&targetDate=2017-12-21"

Premium feature example: applying 10% discount at checkout

We are able to charge customers on a one-time basis, and subscribe them to the premium plan. We now need to bring it together: as an example, we will apply a 10% discount in the shopping cart, when users are premium subscribers.

In the basket view, retrieve the list of subscription bundles the user is subscribed to:

curl -v \
     -u admin:password \
     -H "X-Killbill-ApiKey: bob" \
     -H "X-Killbill-ApiSecret: lazar" \
     -H "Content-Type: application/json" \
     "http://127.0.0.1:8080/1.0/kb/accounts/<ACCOUNT_ID>/bundles"

The subscriptions list will show the cancellation status (see cancelledDate). If it’s null or in the future, the subscriber is still a paying customer, in which case you can apply the 10% discount.

Conclusion

In this tutorial, we’ve shown you how to leverage the basic features of the Kill Bill platform, how to provide recurring and one-off billing, as well as integrate with various payment processors. Kill Bill has many more features to offer, make sure to read the full user guide.

Next steps: exercises for the reader

If you want to continue the tutorial, here are some next steps:

  • Configure the overdue system. What happens when premium subscribers don’t pay?

  • Setup the Analytics plugin to create revenue dashboards and monitor your MRR.

  • Defer authorize and capture: if you are shipping physical goods, you are required to defer capture only when the product ships.

  • Add a second plan, with a discounted yearly pricing and try to upgrade/downgrade users between plans.