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'And then execute:
$ bundleOr install it yourself as:
$ gem install payThis 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 two migrations:
- db/migrate/create_subscriptions.rb
- db/migrate/add_fields_to_users.rb
If you need to use a model other than User, check out the wiki page.
Finally, run the migrations with $ rake db:migrate
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: zzzzYou can also use the STRIPE_PRIVATE_KEY and STRIPE_SIGNING_SECRET
environment variables.
If a users email is updated and they have a processor_id set, we'll 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
endTo see how to use Stripe Elements JS & Devise, click here.
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 = '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
endThis 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'
endIf 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 falseTrials that don't require cards upfront simply
user = User.create(
email: '[email protected]',
trial_ends_at: 30.days.from_now
)
user.on_generic_trial?
#=> trueuser = 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 USDThe 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.subscribeA card_token must be provided as an attribute.
The subscribe method has three optional arguments with default values.
def subscribe(name: 'default', plan: 'default')
...
endName 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.subscriptionuser = User.find_by(email: '[email protected]')
user.subscribed?The subscribed? method has two optional arguments with default values.
def subscribed?(name: 'default', plan: nil)
...
endName is an internally used name for the subscription.
Plan is the plan ID from the payment processor.
Processor is the string value of the payment processor subscription. Pay currently only supports Stripe, but other implementations are welcome.
user = User.find_by(email: '[email protected]')
user.customeruser = User.find_by(email: '[email protected]')
user.update_card('stripe-token')user = User.find_by(email: '[email protected]')
user.processor_subscription(subscription_id)user = User.find_by(email: '[email protected]')
user.subscription.on_trial?user = User.find_by(email: '[email protected]')
user.subscription.cancelled?user = User.find_by(email: '[email protected]')
user.subscription.on_grace_period?user = User.find_by(email: '[email protected]')
user.subscription.active?user = User.find_by(email: '[email protected]')
user.subscription.canceluser = 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.resumeuser = User.find_by(email: '[email protected]')
user.subscription.processor_subscription👋 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 testrubocop
These will need to be passing in order for a Pull Request to be accepted.
The gem is available as open source under the terms of the MIT License.