0.01
Repository is archived
No commit activity in last 3 years
No release in over 3 years
A subscription billing interface modeled after Laravel Cashier
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

~> 4.2.6
~> 1.11
>= 2.1.1, ~> 2.1
~> 5.8
~> 10.0

Runtime

~> 1.42.0
 Project Readme

This thing is ish.

For an updated, Rails-specific implementation checkout Pay.

Bank Teller

Gem Version Build Status Code Climate


Bank Teller is a Ruby on Rails interface for interacting with Stripe. It is an implementation of the Laravel library, Cashier. Major kudos to Taylor Otwell and all of the contributors to Cashier, it's amazing. Bank Teller has some minor API differences from Cashier, mostly to match the Ruby style. To quote the Cashier project: "It handles almost all of the boilerplate subscription billing code you are dreading writing... coupons, swapping subscription, subscription 'quantities', cancellation grace periods, and invoice PDFs (coming soon)."

This gem cannot be used as a stand-alone gem. It is very tightly integrated with ActiveSupport and ActiveRecord. This gem is best used in a Ruby on Rails application.

Still to Come

Contribute, if you'd like!

  • Finish Tests
  • Add Webhooks
  • Invoice PDFs
  • One Off Charges

Installation

Add this line to your application's Gemfile:

gem 'bank_teller'

And then execute:

$ bundle

Bank Teller comes with a couple of migrations:

  1. A migration to add fields to a users table. A users should already exist.
  2. A migration to create a subscriptions table.

To add these migrations to your application, run:

$ rails generate bank_teller:install
$ rake db:migrate

Usage

Setting It Up

Stripe requires a private API key. Once you have aquired your private key, you'll need to set the environment variable ENV["STRIPE_API_KEY"] equal to your API key. If you're not sure how to use environment variables, checkout Figaro or my favorite, dotenv.

Once you have your key in place, all you need to do is include the Billable module in your User class:

# app/models/user.rb
class User < ActiveRecord::Base
  include Billable
end

Make Some Money

Create a Subscription

user = User.find(1)
user.new_subscription('main', 'monthly').create(token)

#new_subscription is a method call on a User object that takes two arguments:

  1. The name of the plan, for internal use
  2. The ID of the plan you created with Stripe

#create takes one argument, the stripe credit card token. It sends the subscription to Stripe and creates the subscription record in the databse.

You can also send addtional fields for the user when creating a new subscription.

user.new_subscription('main', 'monthly').create(token, { email: 'john@johndoe.com' })

To see all the options, checkout the Stripe docs.

Coupons!
user.new_subscription('main', 'monthly', coupon: 'code').create(token)

Subscription Status

Active(ness)

See if a user has an active subscription:

user.subscribed?('main')

See if a user's subscription is still on a trial:

user.subscription('main').on_trial?

See if a user is subscribed to a specific plan:

user.subscribed_to_plan?('main', 'monthly')
Cancellations

See if a user has cancelled their subscription:

user.subscription('main').cancelled?

See if a user has cancelled their subscription, but still has a grace period:

user.subscription('main').on_grace_period?

Switch Plans

Swap between different Stripe plans:

user.subscription('main').swap('another-stripe-plan-id')

Quantity

Add 1 to the quantity of plans:

user.subscription('main').increment_quantity

Add n to the quantity of plans:

user.subscription('main').increment_quantity(10)

Remove 1 from the quantity of plans:

user.subscription('main').decrement_quantity

Remove n from the quantity of plans:

user.subscription('main').decrement_quantity(10)

Directly update the quantity of plans:

user.subscription('main').update_quantity(20)

Taxes

To charge tax for your plans, overwrite the tax_percentage method in your User class:

# app/models/user.rb
class User < ActiveRecord::Base
  def tax_percentage
    9.25
  end
end

Cancel Subscriptions

Cancel a subscription with a grace period (time remaining in the active plan):

user.subscription('main').cancel

Development

After checking out the repo, run bin/setup to install dependencies. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/jasoncharnes/bank_teller.