by Pierre-Alexandre Meyer | Jul 25, 2016 | System Integration
One of our most popular blog posts is Having fun with Docker, Stripe and Kill Bill, where we showed how easy it is to leverage the powerful subscription engine offered by Kill Bill while delegating payments to Stripe. A lot has happened over the past 18 months: tools like docker-machine and docker-compose have become better and recent releases of Kill Bill have removed the need to edit various configuration files post-installation. Let’s take a look at how simpler the installation process has become. I assume you already have Docker installed and created a Stripe account. The first step is to create a machine to run your containers. On a mac, you would typically use the virtualbox driver: docker-machine create -d virtualbox killbill eval $(docker-machine env killbill) Note that to deploy Kill Bill to the cloud, the steps are similar (simply replace the driver with your provider’s, such as Microsoft Azure for example). Next, create a docker-compose file similar to the one below: and run: docker-compose up 3 containers will start: one for MariaDB (shared database), one for Kill Bill itself and one for Kaui (Kill Bill admin UI). You can then explore Kill Bill APIs by going to http://192.168.99.100:8080/api.html or log-in to Kaui by going to http://192.168.99.100:9090 (username: admin, password: password) to create your tenant. Note: make sure to replace 192.168.99.100 with the IP of your machine which you can retrieve via docker-machine ip killbill The final step is to configure your Stripe credentials. Create a configuration file stripe.yml: :stripe: :api_secret_key: 'sk_test_aaaabbbbccccdddd' and upload it via Kaui at http://192.168.99.100:9090/admin_tenants/1: That’s it! To test your installation, you can run our sample Sinatra app,...
by Pierre-Alexandre Meyer | Jul 18, 2016 | System Integration
The Kill Bill team loves data and measuring things. As part of our performance work last year, we did a pass at cleaning up all of our metrics. As a result, we now export over 600 metrics all over the stack, from latency of low-level database queries to overall rates of HTTP requests. These can be easily integrated with InfluxDB and Grafana: that’s how Groupon monitors its payment infrastructure. Maintaining a monitoring system is no easy task however, especially at scale. It’s no surprise that even companies like Stripe are outsourcing (some of) this work to Datadog. In this post, I’ll show you how to export Kill Bill metrics with Datadog’s standard agent, and some of the metrics you want to keep an eye on in production. I assume you already have Kill Bill running using our Docker image and that you have a Datadog API key. The first step is to enable JMX, by adding the following System Properties to your kpm.yml: ~ > docker exec -ti killbill /bin/bash [email protected]:/var/lib/tomcat7$ export TERM=xterm [email protected]:/var/lib/tomcat7$ vi /etc/killbill/kpm.yml # Add the following to the jvm: line # -Dcom.sun.management.jmxremote=true # -Dcom.sun.management.jmxremote.authenticate=false # -Dcom.sun.management.jmxremote.port=8000 # -Dcom.sun.management.jmxremote.ssl=false [email protected]:/var/lib/tomcat7$ exit ~ > docker restart killbill Then, install the Ubuntu Datadog agent (when prompted, the sudo password is tomcat7): ~ > docker exec -ti killbill /bin/bash [email protected]:/var/lib/tomcat7$ cd /var/tmp [email protected]:/var/lib/tomcat7$ DD_API_KEY=REPLACE_ME bash -c "$(curl -L https://raw.githubusercontent.com/DataDog/dd-agent/master/packaging/datadog-agent/source/install_agent.sh)" [email protected]:/var/lib/tomcat7$ sudo /etc/init.d/datadog-agent start Note that the final installation step, when the agent tries to register with your account, may fail. Starting the agent manually afterwards fixes the issue. Go now to you Datadog account and enable the JMX integration. The final step is...
by Pierre-Alexandre Meyer | Jul 9, 2016 | Analytics
Running a successful subscription business requires careful monitoring of a variety of metrics: MRR, Churn, LTV, CAC, etc. It’s no surprise that our first plugin was the Analytics plugin, which computes in realtime these metrics and provides tools to build your own dashboards. Understanding, tweaking and validating these KPIs for your own business requires careful thinking and is typically owned by an experienced Business Intelligence team working closely with the executive team on a daily basis. For those who simply can’t afford the overhead, ChartMogul comes to the rescue. Their SaaS platform builds these metrics for you and lets you explore your data through cohorts, custom segments and geo-mapping tools. We’re pleased to announce today a new Kill Bill plugin for ChartMogul. This integration is in fact very similar to the Analytics plugin, i.e. it listens in real-time to events that Kill Bill produces, and mirrors the data in ChartMogul: The plugin is available in beta at https://github.com/killbill/killbill-chartmogul-plugin. For help or feedback, feel free to reach-out on the...
by Pierre-Alexandre Meyer | Jul 3, 2016 | System Integration
The open-source Kill Bill platform provides advanced subscription management as well as payment APIs. Businesses of any size, from the 2-person startup to public companies, rely on it for their e-commerce recurring billing and shopping cart payment needs. Lots of SaaS companies have similar offerings. Choosing the right partner from the get go is critical however, as migrations are error-prone and difficult. If you are a young startup, you probably want something simple, cheap and low-maintenance, which can adapt to your needs as you grow. Kill Bill combined with Microsoft Azure BizSpark for startups gives you just that, which probably explains the uptick of requests we’ve had recently regarding integration with Microsoft Azure. Thanks to our Docker images, this is quite easy – this tutorial will show you how to deploy Kill Bill integrated with Stripe in a few commands. Pre-requisites Create a Microsoft Azure account Write down your subscription id: log-in to https://portal.azure.com, click on the account dropdown, then “My permissions” Install the latest version of docker-machine VM setup Create the VM using docker-machine: docker-machine create -d azure \ --azure-ssh-user ops \ --azure-subscription-id AZURE_SUBSCRIPTION_ID \ --azure-open-port 8080 \ --azure-open-port 3000 \ azure You should see it running at https://portal.azure.com/#blade/HubsExtension/BrowseAllResourcesBlade. Write down the IP of the machine by running docker-machine ip azure Configure your shell for the rest of the tutorial: eval $(docker-machine env azure) Database setup For this tutorial, we will simply run a MySQL database in a Docker container on the same host: docker run -tid \ --name db \ -p 3306:3306 \ -e MYSQL_ROOT_PASSWORD=root \ -e MYSQL_DATABASE=killbill \ mariadb Modify the database to make sure it...
by Stéphane Brossier | Jun 16, 2016 | Billing Systems, Kill Bill Internals
Until now, Kill Bill only allowed to configure the Bill Cycle Day (BCD) attached to each subscription through the use of billing alignment catalog rules. As a reminder, the BCD defines the day when a specific subscription gets billed. For instance assuming customers get billed in advance, then creating a monthly subscription on 6/1/2016 with a BCD=1 would generate a first invoice on the 6/1/2016 for the month of June, and then a next invoice on July 1st for the month of July, etc… In the current scheme, there are 3 different possible billing alignment policies, that are configured using special catalog rules: ACCOUNT: All subscriptions whose Plan is defined with an ACCOUNT alignment will use the same account level BCD. This allows to group all subscriptions for an account on the same invoice. The BCD is either set using api, or if not set, the system will infer that BCD when the first subscription on the account is created (by looking at the first Phase in the Plan whose recurring price is not 0). SUBSCRIPTION: The BCD is based on the subscription startDate and by also looking at the first Phase in the Plan whose recurring price is not 0. BUNDLE: This is similar to the SUBSCRIPTION case but the system will use the start date of the base subscription to compute the BCD. With the existing mechanism, the administrator configures once the various policies in the catalog and then everything happens automatically. This approach is convenient but rather static (does not allow to change a BCD for an existing subscription). In order to provide a more dynamic...
by Pierre-Alexandre Meyer | Apr 25, 2016 | Payments
A typical integration with a payment gateway such as Stripe looks like this: In the error handling block, you may decide to email the customer, block his access to your website, etc. Hopefully, you also keep track of these errors and generate a daily report on how many transactions fail: after all, these directly impact your bottom line. Good enough? Unfortunately, as we will see below, this approach is often too simplistic. In this particular example, the exception caught is only one of several possibilities. Looking at Stripe’s documentation specifically, CardError is thrown only for 402 – Request Failed. Other exceptions can occur, such as RateLimitError, when 429 – Too Many Requests is returned: in this case, you went over your API quota and you will want such requests to be re-submitted later. Let’s now assume we fix our code above to look like: Errors like InvalidRequestError, AuthenticationError or APIError should be closely monitored after each deployment, as they may be triggered by a recent code or configuration change. What about the black box of CardError? Let’s take a look at how we can categorize further such payment failures. On one hand, some transactions may be blocked by your payment gateway, depending on your configuration settings. Braintree for instance refers to them as Gateway Rejections. A typical example is CVV rejections: when triggering an authorization, the issuing bank will tell the gateway if the supplied CVV matches. If it doesn’t, most gateways can be configured to automatically void the transaction to prevent fraud. Another typical scenario is when your provider offers fraud detection tools: if it determines that the...
by Pierre-Alexandre Meyer | Apr 6, 2016 | System Integration
We consider Kill Bill as a platform first, upon which you can build your billing and payment infrastructure. As such, we are working hard to make sure (almost) every aspect of the system is accessible through APIs (subscriptions, invoices and payments management, but also system configuration, plugins management, etc.). As we’re approaching 200 Kill Bill APIs, interacting with the system can be intimidating. I personally have entire folders full of cURL recipes, for Kill Bill itself but also for our various plugins. We publish our documentation using Swagger (available at runtime at http://127.0.0.1:8080/api.html), which is incredibly useful for discovering APIs and one-off requests, less so for keeping a library of snippets. Enter Postman, a free Chrome and Mac App which helps you construct, send and store HTTP requests. Once you have it installed, just import the Kill Bill Postman Collection. Select a request template, modify the query parameters and/or JSON body and click “Send”. Voilà! Postman sends the request to Kill Bill and automatically pretty-prints the response. You can even generate the equivalent cURL command (useful to share it on a bug report). You can also create your own private Collections, for example one for common requests you make in your development environment (trigger a payment, restart a plugin, etc.) and one for requests to help debugging your production environment (e.g. retrieve details for a specific account or payment). I’ve just started using it, mainly as a fancy repository of cURL snippets, but it offers lots of advanced features like requests scripting, a test runner and team collaboration tools. Go give it a...
by Stéphane Brossier | Feb 10, 2016 | Billing Systems
In this blog, we will explore the power behind the BlockingState abstraction inside Kill Bill. Overview: The BlockingState events were introduced in version 0.6.x, so while they are certainly not new, they were mostly used for internal purpose inside Kill Bill. We recently enriched our apis to make them fully available to plugins. Let’s take a simple use case where a user subscribes to a monthly recurring Plan on January 1st 2016 (and catalog was configured to bill in advance). Each 1st of the month, the invoicing system takes as an input the subscription state (subscription events) and the user is billed for a full month. This works quite well, but how can we address the following questions: Entitlement: The ability to separate what the user is billed for and the service that she receives (e.g if user cancels mid month, we may want to terminate the service right away and keep the billing until the end of the month) Overdue: The user does not pay its bills. We want to allow to introduce some states that will define a gradual degrade of the service until the user pays Pause/Resume: Ability to arbitrarily pause the billing (and/or its associated entitlement) for a period of time. The BlockingState events allow to introduce arbitrary states associated to subscriptions, and allow to modify the behavior of the system to block billing or entitlement periods, solving the original use cases we had and more… Internals: Before looking at their usage, let’s review what they contain: stateName : A string that is to be interpreted by the service inserting such event blockingStateType : An...
by Stéphane Brossier | Jan 29, 2016 | The Kill Bill Story
We are excited to announce our new release Kill Bill 0.16.x (and we just released 0.16.1 to make it even better)! This is the result of 6 months of hard work and a lot has happened… so let’s review: Performance Improvement This has been a very long effort that started already in release 0.14.x and that we have continued forward. We have already posted some notes about the work and some results. Obviously performance is a never ending task because as the system evolves, it becomes necessary to verify there is no performance regression, but we now have a stable and performant system and all the tools to continue the work (tests, perf framework and baseline to compare numbers). Full Payment Stack One of the main focus of that release was around the payment subsystem. Kill Bill now offers a full payment subsystem (unrelated to the subscription/invoicing engine), with standalone payment apis (auth, capture, refund, …). The payment subsystem has been implemented on top of state machines that enforce correct transitions for payment transactions and offers 2 flexible payment plugin apis to extend the core payment system: The payment plugin api allows to extend the core payment system to interact with third party payment gateways or processors. We already have 16 such payment plugins (for Stripe, CyberSource, Adyen, PayPal, Braintree, …) The payment control plugin api allows to intercept payment operations in real time to customize the system. There are many use cases for this api (integration with fraud systems, payment routing, retry strategies, disbursement, currency conversion, …) We believe we can support any payment flows and integrate with...
by Pierre-Alexandre Meyer | Dec 9, 2015 | System Integration
Kill Bill’s plugin architecture has grown significantly over the past couple of years. We already have about 50 open-source plugins extending Kill Bill with new features and offering tight integrations with payment gateways, fraud detection solutions, etc. (and we have first-hand knowledge of well over a dozen closed-source plugins, developed by companies we have advised). Not all plugins are created equal though. Some can be very simple (e.g. send an email when an invoice is generated), others — very complex (e.g. the Adyen plugin, which provides more than 250 payment methods worldwide). For some of these more advanced ones, that integrate with third-party solutions, we recently started formal review and certification processes. The goal of the process is twofolds. First, it gives us direct access to the vendor technical team, which helps us make sure the connector is optimized for that particular integration. Second, it gives us an opportunity to educate the partner on Kill Bill and on the very unique open-source nature of the project. Today, we are pleased to announce that we have added Avalara to the list of such certified integrations. To give you a peek of the work that happened behind the scenes, we had our initial introduction meeting on April 15th (surprisingly enough!) of this year and finalized the certification last week. During this time, we made sure the Avatax™ plugin passed all the required integration tests and verified that the data from Kill Bill is mapped correctly to the generated tax documents. The Avalara team also educated us on some of the more advanced sales topics that we need to keep in mind...
![[Updated] Having fun with Docker, Stripe and Kill Bill](http://killbill.io/wp-content/uploads/2014/11/docker1.png)
