For an updated, Rails-specific implementation checkout Pay.
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.
- Finish Tests
- Add Webhooks
- Invoice PDFs
- One Off Charges
Add this line to your application's Gemfile:
gem 'bank_teller'
And then execute:
$ bundle
Bank Teller comes with a couple of migrations:
- A migration to add fields to a
users
table. Ausers
should already exist. - A migration to create a
subscriptions
table.
To add these migrations to your application, run:
$ rails generate bank_teller:install
$ rake db:migrate
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
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:
- The name of the plan, for internal use
- 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.
user.new_subscription('main', 'monthly', coupon: 'code').create(token)
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')
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?
Swap between different Stripe plans:
user.subscription('main').swap('another-stripe-plan-id')
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)
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 a subscription with a grace period (time remaining in the active plan):
user.subscription('main').cancel
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.
Bug reports and pull requests are welcome on GitHub at https://github.com/jasoncharnes/bank_teller.