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

Introduction

Scenario

Let’s assume you want to build an e-commerce website and 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, Drupal, etc.). You can also take a look at the following Stripe and PayPal demo websites, to help you with the front-end integration.

Requirements

We will assume:

  • You already went through the Getting started tutorial and have MySQL, Kill Bill and Kaui setup and running in Docker containers

  • You went through our documentation and are familiar with the concept of accounts, payment methods, subscriptions, invoices and payments in the Kill Bill environment

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

Setup

Payment gateways setup

In this tutorial, we will integrate with Stripe for credit card processing and with PayPal.

Choosing your payment processor is critical, you need to make sure it offers the features you need (e.g. international payments) while minimizing your costs (see this blog post for more details on the topic). Luckily, there are hundreds 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 Sandbox→Accounts. Create 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(s). Make sure to set a PayPal balance so that accounts have some money available

  • Once the accounts are created, click on the business account in the list, then Profile. In the modal, click on the API Credentials tab and write down the Username, Password and Signature.

Plugins installation

Go to the Kaui KPM plugins page (/kpm/plugins, accessible through the plug icon on the top menu) 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.

Stripe setup

Go to your tenant configuration page (accessible by clicking on your tenant name on the top menu) and select the "Plugin Config" tab at the bottom. Select Stripe as the plugin name and the UI will prompt you for the secret key.

PayPal setup

Similarly, select PayPal as the plugin name and the UI will prompt you for the signature, login (i.e. username) and password.

Setup review

At this point, Kill Bill is ready and configured to create subscriptions and trigger payments (i.e. charge credit cards and PayPal accounts).

The next step is to integrate it with your e-commerce website.

Storing payment methods for recurring billing

At some point, the user will need to submit his credit card information and/or his PayPal account, so that Kill Bill can subsequently charge it on a recurring basis (e.g. every month). This could happen in a Profile section of your website, or maybe even during the checkout flow.

This integration 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 secure form (Stripe.js). 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 (t3GER3BP3JHLASZe in this example) that needs to be stored in Kill Bill. For this tutorial, you can store that token manually using Kaui. From the main account page, click the + next to Payment Methods. In the form, populate:

  • Plugin name: killbill-stripe

  • Property:

    • Name: token

    • Value: t3GER3BP3JHLASZe

  • Select the Default payment method checkbox

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.

The equivalent API call that your website would issue is:

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: eCommerce' \
     --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"

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: eCommerce' \
     --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"

Replace return_url (used on success) and cancel_return_url (used on failure) with landing pages custom to your website.

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 where the user will be guided through the approval process to create a token specific to your website. For testing, log-in with the Personal account you had created (not the Business one).

Once that step is completed, the customer comes back from PayPal, 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).

For this tutorial, you can store that token manually using Kaui. From the main account page, click the + next to Payment Methods. In the form, populate:

  • Plugin name: killbill-paypal-express

  • Property:

    • Name: token

    • Value: EC-20G53990M6953444J

This token is now associated to the customer who was redirected to Paypal and accepted the billing agreement. If you load the account page in Kaui, you should now see the two payment methods. The credit card on Stripe is the default payment method for recurring subscriptions (click on the Star icon to change this). Note that an account should always have a default payment method, even if only one payment method type is created in the system.

The equivalent API call that your website would issue is:

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"

A demo of that integration is available here.

Conclusion

In this tutorial, we’ve shown you how to integrate with various payment processors and store payment methods on file. At this point, most of the Kill Bill features (subscriptions, invoicing, dunning and even payment APIs) are payment processor agnostic.