A Recurring Billing System with Stripe

Danny Whalen
  • June 2012
  • Ruby
  • RoR

These notes are meant to answer some basic questions about using Stripe for billing, and also to answer some questions about implementation which are not covered in the Stripe documentation and forums. This is not a comprehensive overview by any means. If you find errors, please let me know and I will fix them. The examples will use the stripe-ruby gem (v1.7.0). A list of basic operations can be found in Stripe's documentation.

Stripe recommends downloading the gem over SSL from the mirror at https://code.stripe.com.

sudo gem install --source https://code.stripe.com stripe

Here is a list of resources which I have found useful:

Creating Subscription Plans

Plans can be created through the Stripe Dashboard or the API. Since plans will not change often, it’s easy to create them through the Dashboard and retrieve them from the application via the API.

  :amount => 999,
  :interval => 'month',
  :name => 'My Basic Plan',
  :currency => 'usd',
  :id => 'basic'

Create Token with Stripe.js

Stripe provides a javascript library which sends encrypted credit card and cardholder data to Stripe’s servers from the browser. Card info is sent (along with the accounts public key) directly to Stripe and is never handled by host application.

// https://gist.github.com/1750368
  number: $('.card-number').val(),
  cvc: $('.card-cvc').val(),
  exp_month: $('.card-expiry-month').val(),
  exp_year: $('.card-expiry-year').val()
}, stripeResponseHandler);

The response includes the ID of the created card token if successful, and relevant error messages otherwise. The token represents a valid credit card stored by Stripe’s servers. Card tokens do not represent charges of any kind.

Token Object

A The host server can retrieve information about the card by retrieving the token referenced by the token ID. The response will contain basic card details including the last four digits of the card, instead of the entire number.


Create Customer

The card token ID can then be submitted to the host server. Card tokens can be used to create a one-time charge or to create a customer with a subscription. The relationship between a customer and a plan is described by a subscription. Subscriptions can be updated or canceled through the customer object.

  :description => "Customer for jim@example.com",
  :plan => "basic",
  :card => "tok_00000000000000" # obtained with Stripe.js

Many applications will offer a free plan. Stripe will allow plans to have an amount of 0 (zero). Customers can be subscribed to a free plan without providing credit card information. Subscribing free users to a free plan could make the upgrade process simpler, since a customer record will already exist. Providing a card token is optional when creating a customer with a subscription to a free account.