<p align="center"><img src="logo.png"></p>
## Pay
### Payments engine for Ruby on Rails
[](https://travis-ci.org/excid3/pay)
Pay is a payments engine for Ruby on Rails 4.2 and higher.
**Current Payment Providers**
- Stripe (API version [2018-08-23](https://stripe.com/docs/upgrades#2018-08-23) or higher required)
- Braintree
Want to add a new payment provider? Contributions are welcome and the instructions [are here](https://github.com/jasoncharnes/pay/wiki/New-Payment-Provider).
## Installation
Add this line to your application's Gemfile:
```ruby
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:
```bash
$ bundle
```
Or install it yourself as:
```bash
$ gem install pay
```
## Setup
#### Migrations
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
#### The User Model
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`.
#### Non-User Model
If you need to use a model other than `User`, check out the [wiki page](https://github.com/jasoncharnes/pay/wiki/Model-Other-Than-User).
#### Run the Migrations
Finally, run the migrations with `$ rake db:migrate`
#### Getting NoMethodError?
`NoMethodError (undefined method 'stripe_customer' for #<User:0x00007fbc34b9bf20>)`
Fully restart your Rails application `bin/spring stop && rails s`
#### Stripe
You'll need to add your private Stripe API key to your Rails secrets `config/secrets.yml`, credentials `rails credentials:edit`
```yaml
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](https://github.com/jasoncharnes/pay/wiki/Using-Stripe-Elements-and-Devise).**
#### Background jobs
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](https://guides.rubyonrails.org/v4.2/active_job_basics.html#backends)
## Usage
Include the `Pay::Billable` module in the model you want to know about subscriptions.
```ruby
# 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.
## Configuration
Need to make some changes to how Pay is used? You can create an initializer `config/initializers/pay.rb`
```ruby
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 = "helpme@example.com"
config.send_emails = true
end
```
This allows you to create your own Charge class for instance, which could add receipt functionality:
```ruby
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
```
### Generators
#### Email Templates
If you want to modify the email templates, you can copy over the view files using:
```
$ bin/rails generate pay:email_views
```
## Emails
### Stripe
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
## User API
#### Trials
You can check if the user is on a trial by simply asking:
```ruby
user = User.find_by(email: 'michael@bluthcompany.co')
user.on_trial? #=> true or false
```
The `on_trial?` method has two optional arguments with default values.
```ruby
user = User.find_by(email: 'michael@bluthcompany.co')
user.on_trial?(name: 'default', plan: 'plan') #=> true or false
```
#### Generic Trials
For trials that don't require cards upfront:
```ruby
user = User.create(
email: 'michael@bluthcompany.co',
trial_ends_at: 30.days.from_now
)
user.on_generic_trial? #=> true
```
#### Creating a Charge
```ruby
user = User.find_by(email: 'michael@bluthcompany.co')
user.processor = 'stripe'
user.card_token = 'stripe-token'
user.charge(1500) # $15.00 USD
user = User.find_by(email: 'michael@bluthcompany.co')
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.
#### Creating a Subscription
```ruby
user = User.find_by(email: 'michael@bluthcompany.co')
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.
```ruby
def subscribe(name: 'default', plan: 'default', **options)
...
end
```
##### Name
Name is an internally used name for the subscription.
##### Plan
Plan is the plan ID from the payment processor.
##### Options
They do something?
#### Retrieving a Subscription from the Database
```ruby
user = User.find_by(email: 'gob@bluthcompany.co')
user.subscription
```
A subscription can be retrieved by name, too.
```ruby
user = User.find_by(email: 'gob@bluthcompany.co')
user.subscription(name: 'bananastand+')
```
#### Checking a User's Subscription Status
```ruby
user = User.find_by(email: 'george.senior@bluthcompany.co')
user.subscribed?
```
The `subscribed?` method has two optional arguments with default values.
```ruby
def subscribed?(name: 'default', plan: nil)
...
end
```
##### Name
Name is an internally used name for the subscription.
##### Plan
Plan is the plan ID from the payment processor.
#### Retrieving a Payment Processor Account
```ruby
user = User.find_by(email: 'george.michael@bluthcompany.co')
user.customer #> Stripe or Braintree customer account
```
#### Updating a Customer's Credit Card
```ruby
user = User.find_by(email: 'tobias@bluthcompany.co')
user.update_card('stripe-token')
```
#### Retrieving a Customer's Subscription from the Processor
```ruby
user = User.find_by(email: 'lucille@bluthcompany.co')
user.processor_subscription(subscription_id) #=> Stripe or Braintree Subscription
```
## Subscription API
#### Checking a Subscription's Trial Status
```ruby
user = User.find_by(email: 'lindsay@bluthcompany.co')
user.subscription.on_trial? #=> true or false
```
#### Checking a Subscription's Cancellation Status
```ruby
user = User.find_by(email: 'buster@bluthcompany.co')
user.subscription.cancelled? #=> true or false
```
#### Checking a Subscription's Grace Period Status
```ruby
user = User.find_by(email: 'her?@bluthcompany.co')
user.subscription.on_grace_period? #=> true or false
```
#### Checking to See If a Subscription Is Active
```ruby
user = User.find_by(email: 'carl.weathers@bluthcompany.co')
user.subscription.active? #=> true or false
```
#### Cancel a Subscription (At End of Billing Cycle)
```ruby
user = User.find_by(email: 'oscar@bluthcompany.co')
user.subscription.cancel
```
#### Cancel a Subscription Immediately
```ruby
user = User.find_by(email: 'annyong@bluthcompany.co')
user.subscription.cancel_now!
```
#### Swap a Subscription to another Plan
```ruby
user = User.find_by(email: 'steve.holt@bluthcompany.co')
user.subscription.swap("yearly")
```
#### Resume a Subscription on a Grace Period
```ruby
user = User.find_by(email: 'steve.holt@bluthcompany.co')
user.subscription.resume
```
#### Retrieving the Subscription from the Processor
```ruby
user = User.find_by(email: 'lucille2@bluthcompany.co')
user.subscription.processor_subscription
```
### Customizing Pay Models
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.
```ruby
# 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
```
```ruby
# 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
```
## Contributors
- [Jason Charnes](https://twitter.com/jmcharnes)
- [Chris Oliver](https://twitter.com/excid3)
## Contributing
👋 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`
## License
The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).