Pay is a payments engine for Ruby on Rails 4.2 and higher.
Current Payment Providers
- Stripe (API version 2018-08-23 or higher required)
- Braintree
Want to add a new payment provider? Contributions are welcome and the instructions are here.
Add this line to your application's Gemfile:
gem 'pay'
# To use Stripe, also include:
gem 'stripe', '< 5.0', '>= 2.8'
gem 'stripe_event', '~> 2.2'
# To use Braintree + PayPal, also include:
gem 'braintree', '< 3.0', '>= 2.92.0'
# To use Receipts
gem 'receipts', '~> 0.2.2'
And then execute:
$ bundle
Or install it yourself as:
$ gem install pay
This engine will create a subscription model and the neccessary migrations for the model you want to make "billable." The most common use case for the billable model is a User.
To add the migrations to your application, run the following migration:
$ bin/rails pay:install:migrations
This will install three migrations:
- db/migrate/create_subscriptions.pay.rb
- db/migrate/add_fields_to_users.pay.rb
- db/migrate/create_charges.pay.rb
If you have a User
model defined in app/models/user.rb
Pay will add the fields it needs to the users
table.
If you do not have a User
model defined, Pay will create a users
table and you will need to add app/models/user.rb
.
If you need to use a model other than User
, check out the wiki page.
Finally, run the migrations with $ rake db:migrate
NoMethodError (undefined method 'stripe_customer' for #<User:0x00007fbc34b9bf20>)
Fully restart your Rails application bin/spring stop && rails s
You'll need to add your private Stripe API key to your Rails secrets config/secrets.yml
, credentials rails credentials:edit
development:
stripe:
private_key: xxxx
public_key: yyyy
signing_secret: zzzz
You can also use the STRIPE_PRIVATE_KEY
and STRIPE_SIGNING_SECRET
environment variables.
To see how to use Stripe Elements JS & Devise, click here.
If a user's email is updated and they have a processor_id
set, Pay will enqueue a background job (EmailSyncJob) to sync the email with the payment processor.
It's important you set a queue_adapter for this to happen. If you don't, the code will be executed immediately upon user update. More information here
Include the Pay::Billable
module in the model you want to know about subscriptions.
# app/models/user.rb
class User < ActiveRecord::Base
include Pay::Billable
end
To sync over customer names, your Billable
model should respond to the first_name
and last_name
methods. Pay will sync these over to your Customer objects in Stripe and Braintree.
Need to make some changes to how Pay is used? You can create an initializer config/initializers/pay.rb
Pay.setup do |config|
config.billable_class = 'User'
config.billable_table = 'users'
config.chargeable_class = 'Pay::Charge'
config.chargeable_table = 'pay_charges'
# For use in the receipt/refund/renewal mailers
config.business_name = "Business Name"
config.business_address = "1600 Pennsylvania Avenue NW"
config.application_name = "My App"
config.support_email = "[email protected]"
config.send_emails = true
config.automount_webhook_routes = true
config.webhooks_path = "/webhooks" # Only when automount_webhook_routes is true
end
This allows you to create your own Charge class for instance, which could add receipt functionality:
class Charge < Pay::Charge
def receipts
# do some receipts stuff using the https://github.com/excid3/receipts gem
end
end
Pay.setup do |config|
config.chargeable_class = 'Charge'
end
If you want to modify the email templates, you can copy over the view files using:
$ bin/rails generate pay:email_views
Emails can be enabled/disabled using the send_emails
configuration option (enabled per default). When enabled, the following emails will be sent:
- When a charge succeeded
- When a charge was refunded
- When a subscription is about to renew
You can check if the user is on a trial by simply asking:
user = User.find_by(email: '[email protected]')
user.on_trial? #=> true or false
The on_trial?
method has two optional arguments with default values.
user = User.find_by(email: '[email protected]')
user.on_trial?(name: 'default', plan: 'plan') #=> true or false
For trials that don't require cards upfront:
user = User.create(
email: '[email protected]',
trial_ends_at: 30.days.from_now
)
user.on_generic_trial? #=> true
user = User.find_by(email: '[email protected]')
user.processor = 'stripe'
user.card_token = 'stripe-token'
user.charge(1500) # $15.00 USD
user = User.find_by(email: '[email protected]')
user.processor = 'braintree'
user.card_token = 'nonce'
user.charge(1500) # $15.00 USD
The charge
method takes the amount in cents as the primary argument.
You may pass optional arguments that will be directly passed on to either Stripe or Braintree. You can use these options to charge different currencies, etc.
user = User.find_by(email: '[email protected]')
user.processor = 'stripe'
user.card_token = 'stripe-token'
user.subscribe
A card_token
must be provided as an attribute.
The subscribe method has three optional arguments with default values.
def subscribe(name: 'default', plan: 'default', **options)
...
end
Name is an internally used name for the subscription.
Plan is the plan ID from the payment processor.
They do something?
user = User.find_by(email: '[email protected]')
user.subscription
A subscription can be retrieved by name, too.
user = User.find_by(email: '[email protected]')
user.subscription(name: 'bananastand+')
user = User.find_by(email: '[email protected]')
user.on_trial_or_subscribed?
The on_trial_or_subscribed?
method has two optional arguments with default values.
def on_trial_or_subscribed?(name: 'default', plan: nil)
...
end
user = User.find_by(email: '[email protected]')
user.subscribed?
The subscribed?
method has two optional arguments with default values.
def subscribed?(name: 'default', plan: nil)
...
end
Name is an internally used name for the subscription.
Plan is the plan ID from the payment processor.
user = User.find_by(email: '[email protected]')
user.customer #> Stripe or Braintree customer account
user = User.find_by(email: '[email protected]')
user.update_card('stripe-token')
user = User.find_by(email: '[email protected]')
user.processor_subscription(subscription_id) #=> Stripe or Braintree Subscription
user = User.find_by(email: '[email protected]')
user.subscription.on_trial? #=> true or false
user = User.find_by(email: '[email protected]')
user.subscription.cancelled? #=> true or false
user = User.find_by(email: '[email protected]')
user.subscription.on_grace_period? #=> true or false
user = User.find_by(email: '[email protected]')
user.subscription.active? #=> true or false
user = User.find_by(email: '[email protected]')
user.subscription.cancel
user = User.find_by(email: '[email protected]')
user.subscription.cancel_now!
user = User.find_by(email: '[email protected]')
user.subscription.swap("yearly")
user = User.find_by(email: '[email protected]')
user.subscription.resume
user = User.find_by(email: '[email protected]')
user.subscription.processor_subscription
Want to add methods to Pay::Subscription
or Pay::Charge
? You can
define a concern and simply include it in the model when Rails loads the
code.
Pay uses the to_prepare
method to allow concerns to be
included every time Rails reloads the models in development as well.
# app/models/concerns/subscription_extensions.rb
module SubscriptionExtensions
extend ActiveSupport::Concern
included do
# associations and other class level things go here
end
# instance methods and code go here
end
# config/initializers/subscription_extensions.rb
# Re-include the SubscriptionExtensions every time Rails reloads
Rails.application.config.to_prepare do
Pay.subscription_model.include SubscriptionExtensions
end
Webhooks are automatically mounted to /webhooks/{provider}
.
If you have a catch all route (for 404s etc) and need to control where/when the webhook endpoints mount, you will need to disable automatic mounting and mount the engine above your catch all route.
# config/initializers/pay.rb
config.automount_webhook_routes = false
# config/routes.rb
mount Pay::Engine, at: '/secret-webhook-path'
If you just want to modify where the engine mounts it's routes then you can change the path.
# config/initializers/pay.rb
config.webhooks_path = '/secret-webhook-path'
👋 Thanks for your interest in contributing. Feel free to fork this repo.
If you have an issue you'd like to submit, please do so using the issue tracker in GitHub. In order for us to help you in the best way possible, please be as detailed as you can.
If you'd like to open a PR please make sure the following things pass:
rake test
The gem is available as open source under the terms of the MIT License.