pay 1.0.2 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2bde9d6a59e8bb2433c706309b09737bf46039ebc02f271b99923658ca3c3953
-  data.tar.gz: 0ef88d80eee2e59e4bcf6a52d8754cb602ea0aa54ba0818ac29361ac8cd3e06c
+  metadata.gz: 9665c51290c7d5fddc48d2c7a719f936907eb3a4c818c1bd886ddd0a01b3ac8f
+  data.tar.gz: 845efceadcd8e44a93228d30b82ec438e9d58842f683c16b97ebd44aef7b53bf
 SHA512:
-  metadata.gz: 73714b5b94113338beab99427ea82378b0f7de541f414662f15977e3470bc3cd3fe5069276e4fdbacf9617ffd189cd38a5eb6dc5a9d2668daa99eec964eb1936
-  data.tar.gz: 333b4d632b7cd1636928eabd29388542b92839ef6f9e2fedb2bd658536fd2ebc8a40a3ca7c41fb1a3974c2d3b9566f5e74da2a71a2106e36afce01b2ea8a83d9
+  metadata.gz: ff36eeb6ea85bb3d7d057b75534d3ce02fd0b193e3c6356d52d03c17f8108add95b961299849511a1b744df86d8c38f16fb47650a769721531f722b01682b823
+  data.tar.gz: 1cab7944c0c018079b5acb4f08e13c5ddaee3881a977a618f1e84730fc6bb24040b8f60ff2da924fd8957dea81ebc5208b8b0ef3cda7c9aa84c4a2819804b5be

data/README.md

@@ -4,27 +4,27 @@
 
 ### Payments engine for Ruby on Rails
 
-[![Build Status](https://travis-ci.org/excid3/pay.svg?branch=master)](https://travis-ci.org/excid3/pay)
+[![Build Status](https://github.com/excid3/pay/workflows/Tests/badge.svg)](https://github.com/excid3/pay/actions)
 
 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)
+- Stripe ([supports SCA](https://stripe.com/docs/strong-customer-authentication), API version [2019-03-14](https://stripe.com/docs/upgrades#2019-03-14) 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:
+Add these lines to your application's Gemfile:
 
 ```ruby
 gem 'pay'
 
 # To use Stripe, also include:
-gem 'stripe', '< 5.0', '>= 2.8'
-gem 'stripe_event', '~> 2.2'
+gem 'stripe', '< 6.0', '>= 2.8'
+gem 'stripe_event', '~> 2.3'
 
 # To use Braintree + PayPal, also include:
 gem 'braintree', '< 3.0', '>= 2.92.0'
@@ -36,18 +36,18 @@ gem 'receipts', '~> 0.2.2'
 And then execute:
 
 ```bash
-$ bundle
+bundle
 ```
 
 Or install it yourself as:
 
 ```bash
-$ gem install pay
+gem install pay
 ```
 
 ## Setup
 
-#### Migrations
+### 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.
 
@@ -55,32 +55,51 @@ To add the migrations to your application, run the following migration:
 
 `$ bin/rails pay:install:migrations`
 
-This will install three migrations:
+This will install four migrations:
 
 - db/migrate/create_subscriptions.pay.rb
 - db/migrate/add_fields_to_users.pay.rb
 - db/migrate/create_charges.pay.rb
+- db/migrate/add_status_to_subscriptions.pay.rb
 
-#### The User Model
+### The Billable Module
 
-If you have a `User` model defined in `app/models/user.rb` Pay will add the fields it needs to the `users` table.
+To enable payments for a model, you simply include the `Pay::Billable`
+module in it. By default, we assume this is `User`.
 
-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'd like to use a different model, you can configure it in an
+initializer:
 
-#### Non-User Model
+```ruby
+Pay.setup do |config|
+  # Make the billable class the same name as your ActiveRecord model
+  config.billable_class = "Team"
 
-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).
+  # Make the billable table the same name as your ActiveRecord table name for the model
+  # This is optional.
+  # Once you update the billable class, the table name will use the ActiveRecord inflected table name
+  config.billable_table = "teams"
+end
+```
 
 #### Run the Migrations
 
 Finally, run the migrations with `$ rake db:migrate`
 
-#### Getting NoMethodError?
+####  Getting NoMethodError?
 
 `NoMethodError (undefined method 'stripe_customer' for #<User:0x00007fbc34b9bf20>)`
 
 Fully restart your Rails application `bin/spring stop && rails s`
 
+## Payment Providers
+
+We support both Stripe and Braintree and make our best attempt to
+standardize the two. They function differently so keep that in mind if
+you plan on doing more complex payments. It would be best to stick with
+a single payment provider in that case so you don't run into
+discrepancies.
+
 #### Stripe
 
 You'll need to add your private Stripe API key to your Rails secrets `config/secrets.yml`, credentials `rails credentials:edit`
@@ -97,6 +116,30 @@ You can also use the `STRIPE_PRIVATE_KEY` and `STRIPE_SIGNING_SECRET` environmen
 
 **To see how to use Stripe Elements JS & Devise, [click here](https://github.com/jasoncharnes/pay/wiki/Using-Stripe-Elements-and-Devise).**
 
+##### Strong Customer Authentication (SCA)
+
+Our Stripe integration **requires** the use of Payment Method objects to correctly support Strong Customer Authentication with Stripe. If you've previously been using card tokens, you'll need to upgrade your Javascript integration.
+
+Subscriptions that require SCA are marked as `incomplete` by default.
+Once payment is authenticated, Stripe will send a webhook updating the
+status of the subscription. You'll need to use the [Stripe CLI](https://github.com/stripe/stripe-cli) to forward
+webhooks to your application to make sure your subscriptions work
+correctly for SCA payments.
+
+```bash
+stripe listen --forward-to localhost:3000/pay/webhooks/stripe
+```
+
+You should use `stripe.handleCardSetup` on the client to collect card information anytime you want to save the card and charge them later (adding a card, then charging them on the next page for example). Use `stripe.handleCardPayment` if you'd like to charge the customer immediately (think checking out of a shopping cart).
+
+**Payment Confirmations**
+
+Sometimes you'll have a payment that requires extra authentication. In this case, Pay provides a webhook and action for handling these payments. It will automatically email the customer and provide a link with the PaymentIntent ID in the url where the customer will be asked to fill out their name and card number to confirm the payment. Once done, they'll be redirected back to your application.
+
+If you'd like to change the views of the payment confirmation page, you can install the views using the generator and modify the template.
+
+[<img src="https://d1jfzjx68gj8xs.cloudfront.net/items/2s3Z0J3Z3b1J1v2K2O1a/Screen%20Shot%202019-10-10%20at%2012.56.32%20PM.png?X-CloudApp-Visitor-Id=51470" alt="Stripe SCA Payment Confirmation" style="zoom: 25%;" />](https://d1jfzjx68gj8xs.cloudfront.net/items/2s3Z0J3Z3b1J1v2K2O1a/Screen%20Shot%202019-10-10%20at%2012.56.32%20PM.png)
+
 #### 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.
@@ -137,7 +180,7 @@ Pay.setup do |config|
   config.send_emails = true
 
   config.automount_webhook_routes = true
-  config.webhooks_path = "/webhooks" # Only when automount_webhook_routes is true
+  config.routes_path = "/pay" # Only when automount_webhook_routes is true
 end
 ```
 
@@ -155,19 +198,38 @@ Pay.setup do |config|
 end
 ```
 
+### Credentials
+
+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
+  braintree:
+    private_key: xxxx
+    public_key: yyyy
+```
+
+You can also use the `STRIPE_PUBLIC_KEY`, `STRIPE_PRIVATE_KEY` and `STRIPE_SIGNING_SECRET` environment variables.
+
 ### Generators
 
-#### Email Templates
+If you want to modify the Stripe SCA template or any other views, you can copy over the view files using:
+
+```bash
+bin/rails generate pay:views
+```
 
 If you want to modify the email templates, you can copy over the view files using:
 
+```bash
+bin/rails generate pay:email_views
 ```
-$ bin/rails generate pay:email_views
-```
-
-## Emails
 
-### Stripe
+### Emails
 
 Emails can be enabled/disabled using the `send_emails` configuration option (enabled per default). When enabled, the following emails will be sent:
 
@@ -175,7 +237,7 @@ Emails can be enabled/disabled using the `send_emails` configuration option (ena
 - When a charge was refunded
 - When a subscription is about to renew
 
-## User API
+## Billable API
 
 #### Trials
 
@@ -214,7 +276,7 @@ user.on_generic_trial? #=> true
 user = User.find_by(email: 'michael@bluthcompany.co')
 
 user.processor = 'stripe'
-user.card_token = 'stripe-token'
+user.card_token = 'payment_method_id'
 user.charge(1500) # $15.00 USD
 
 user = User.find_by(email: 'michael@bluthcompany.co')
@@ -236,7 +298,7 @@ different currencies, etc.
 user = User.find_by(email: 'michael@bluthcompany.co')
 
 user.processor = 'stripe'
-user.card_token = 'stripe-token'
+user.card_token = 'payment_method_id'
 user.subscribe
 ```
 
@@ -260,7 +322,9 @@ Plan is the plan ID from the payment processor.
 
 ##### Options
 
-They do something?
+By default, the trial specified on the subscription will be used.
+
+`trial_period_days: 30` can be set to override and a trial to the subscription. This works the same for Braintree and Stripe.
 
 #### Retrieving a Subscription from the Database
 
@@ -329,7 +393,7 @@ user.customer #> Stripe or Braintree customer account
 ```ruby
 user = User.find_by(email: 'tobias@bluthcompany.co')
 
-user.update_card('stripe-token')
+user.update_card('payment_method_id')
 ```
 
 #### Retrieving a Customer's Subscription from the Processor
@@ -445,9 +509,13 @@ Rails.application.config.to_prepare do
 end
 ```
 
-## Webhooks
+## Routes & Webhooks
+
+Routes are automatically mounted to `/pay` by default.
+
+We provide a route for confirming SCA payments at `/pay/payments/:payment_intent_id`
 
-Webhooks are automatically mounted to `/webhooks/{provider}`.
+Webhooks are automatically mounted at `/pay/webhooks/{provider}`
 
 #### Customizing webhook mount path
 
@@ -455,7 +523,7 @@ If you have a catch all route (for 404s etc) and need to control where/when the
 
 ```ruby
 # config/initializers/pay.rb
-config.automount_webhook_routes = false
+config.automount_routes = false
 
 # config/routes.rb
 mount Pay::Engine, at: '/secret-webhook-path'
@@ -466,7 +534,7 @@ If you just want to modify where the engine mounts it's routes then you can chan
 ```ruby
 # config/initializers/pay.rb
 
-config.webhooks_path = '/secret-webhook-path'
+config.routes_path = '/secret-webhook-path'
 ```
 
 ## Contributors

data/Rakefile

@@ -1,40 +1,40 @@
 begin
-  require 'bundler/setup'
+  require "bundler/setup"
 rescue LoadError
-  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+  puts "You must `gem install bundler` and `bundle install` to run rake tasks"
 end
 
-require 'rdoc/task'
+require "rdoc/task"
 
 RDoc::Task.new(:rdoc) do |rdoc|
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title    = 'Pay'
-  rdoc.options << '--line-numbers'
-  rdoc.rdoc_files.include('README.md')
-  rdoc.rdoc_files.include('lib/**/*.rb')
+  rdoc.rdoc_dir = "rdoc"
+  rdoc.title = "Pay"
+  rdoc.options << "--line-numbers"
+  rdoc.rdoc_files.include("README.md")
+  rdoc.rdoc_files.include("lib/**/*.rb")
 end
 
-APP_RAKEFILE = File.expand_path('../test/dummy/Rakefile', __FILE__)
+APP_RAKEFILE = File.expand_path("../test/dummy/Rakefile", __FILE__)
 
-load 'rails/tasks/engine.rake'
-load 'rails/tasks/statistics.rake'
+load "rails/tasks/engine.rake"
+load "rails/tasks/statistics.rake"
 
-require 'bundler/gem_tasks'
-require 'rake/testtask'
+require "bundler/gem_tasks"
+require "rake/testtask"
 
 Rake::TestTask.new(:test) do |t|
-  t.libs << 'lib'
-  t.libs << 'test'
-  t.pattern = 'test/**/*_test.rb'
+  t.libs << "lib"
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
   t.verbose = false
 end
 
 task default: :test
 
 task :console do
-  require 'irb'
-  require 'irb/completion'
-  require 'pay'
+  require "irb"
+  require "irb/completion"
+  require "pay"
   ARGV.clear
   IRB.start
 end

data/app/controllers/pay/payments_controller.rb

@@ -0,0 +1,7 @@
+module Pay
+  class PaymentsController < ApplicationController
+    def show
+      @payment = Payment.from_id(params[:id])
+    end
+  end
+end

data/app/controllers/pay/webhooks/braintree_controller.rb

@@ -7,13 +7,15 @@ module Pay
 
       def create
         case webhook_notification.kind
-        when 'subscription_charged_successfully'
+        when "subscription_charged_successfully"
           subscription_charged_successfully(webhook_notification)
-        when 'subscription_canceled'
+        when "subscription_canceled"
           subscription_canceled(webhook_notification)
+        when "subscription_trial_ended"
+          subscription_trial_ended(webhook_notification)
         end
 
-        render json: { success: true }, status: :ok
+        render json: {success: true}, status: :ok
       rescue ::Braintree::InvalidSignature => e
         head :ok
       end
@@ -24,9 +26,10 @@ module Pay
         subscription = event.subscription
         return if subscription.nil?
 
-        user = Pay.user_model.find_by(processor: :braintree, processor_id: subscription.id)
-        return unless user.present?
+        pay_subscription = Pay.subscription_model.find_by(processor: :braintree, processor_id: subscription.id)
+        return unless pay_subscription.present?
 
+        user = pay_subscription.owner
         charge = user.save_braintree_transaction(subscription.transactions.first)
 
         if Pay.send_emails
@@ -45,8 +48,18 @@ module Pay
         user.update(braintree_subscription_id: nil)
       end
 
+      def subscription_trial_ended(event)
+        subscription = event.subscription
+        return if subscription.nil?
+
+        pay_subscription = Pay.subscription_model.find_by(processor: :braintree, processor_id: subscription.id)
+        return unless pay_subscription.present?
+
+        pay_subscription.update(trial_ends_at: Time.zone.now)
+      end
+
       def webhook_notification
-        @webhook_notification ||= ::Braintree::WebhookNotification.parse(
+        @webhook_notification ||= Pay.braintree_gateway.webhook_notification.parse(
           params[:bt_signature],
           params[:bt_payload]
         )

data/app/mailers/pay/application_mailer.rb

@@ -1,6 +1,6 @@
 module Pay
   class ApplicationMailer < ActionMailer::Base
-    default from: 'from@example.com'
-    layout 'mailer'
+    default from: Pay.support_email
+    layout "mailer"
   end
 end

data/app/mailers/pay/user_mailer.rb

@@ -23,12 +23,24 @@ module Pay
     end
 
     def subscription_renewing(user, subscription)
+      @user, @subscription = user, subscription
+
       mail(
         to: to(user),
         subject: Pay.email_renewing_subject,
       )
     end
 
+    def payment_action_required(user, payment_intent_id, subscription)
+      payment = Payment.from_id(payment_intent_id)
+      @user, @payment, @subscription = user, payment, subscription
+
+      mail(
+        to: to(user),
+        subject: Pay.payment_action_required_subject
+      )
+    end
+
     private
 
     def to(user)

data/app/models/pay/subscription.rb

@@ -2,6 +2,8 @@ module Pay
   class Subscription < ApplicationRecord
     self.table_name = Pay.subscription_table
 
+    STATUSES = %w[incomplete incomplete_expired trialing active past_due canceled unpaid]
+
     # Associations
     belongs_to :owner, class_name: Pay.billable_class, foreign_key: :owner_id
 
@@ -11,13 +13,16 @@ module Pay
     validates :processor_id, presence: true
     validates :processor_plan, presence: true
     validates :quantity, presence: true
+    validates :status, presence: true
 
     # Scopes
     scope :for_name, ->(name) { where(name: name) }
-    scope :on_trial, ->{ where.not(trial_ends_at: nil).where("? < trial_ends_at", Time.zone.now) }
-    scope :cancelled, ->{ where.not(ends_at: nil) }
-    scope :on_grace_period, ->{ cancelled.where("? < ends_at", Time.zone.now) }
-    scope :active, ->{ where(ends_at: nil).or(on_grace_period).or(on_trial) }
+    scope :on_trial, -> { where.not(trial_ends_at: nil).where("trial_ends_at > ?", Time.zone.now) }
+    scope :cancelled, -> { where.not(ends_at: nil) }
+    scope :on_grace_period, -> { cancelled.where("ends_at > ?", Time.zone.now) }
+    scope :active, -> { where(ends_at: nil).or(on_grace_period).or(on_trial) }
+    scope :incomplete, -> { where(status: :incomplete) }
+    scope :past_due, -> { where(status: :past_due) }
 
     attribute :prorate, :boolean, default: true
 
@@ -33,16 +38,32 @@ module Pay
       trial_ends_at? && Time.zone.now < trial_ends_at
     end
 
-    def cancelled?
+    def canceled?
       ends_at?
     end
 
+    def cancelled?
+      canceled?
+    end
+
     def on_grace_period?
-      cancelled? && Time.zone.now < ends_at
+      canceled? && Time.zone.now < ends_at
     end
 
     def active?
-      ends_at.nil? || on_grace_period? || on_trial?
+      ["trialing", "active"].include?(status) && (ends_at.nil? || on_grace_period? || on_trial?)
+    end
+
+    def past_due?
+      status == "past_due"
+    end
+
+    def incomplete?
+      status == "incomplete"
+    end
+
+    def has_incomplete_payment?
+      past_due? || incomplete?
     end
 
     def cancel
@@ -56,7 +77,7 @@ module Pay
     def resume
       unless on_grace_period?
         raise StandardError,
-              'You can only resume subscriptions within their grace period.'
+          "You can only resume subscriptions within their grace period."
       end
 
       send("#{processor}_resume")
@@ -70,8 +91,18 @@ module Pay
       update(processor_plan: plan, ends_at: nil)
     end
 
-    def processor_subscription
-      owner.processor_subscription(processor_id)
+    def swap_and_invoice(plan)
+      swap(plan)
+      owner.invoice!(subscription_id: processor_id)
+    end
+
+    def processor_subscription(options = {})
+      owner.processor_subscription(processor_id, options)
+    end
+
+    def latest_payment
+      return unless stripe?
+      processor_subscription(expand: ["latest_invoice.payment_intent"]).latest_invoice.payment_intent
     end
   end
 end

data/app/views/layouts/pay/application.html.erb

@@ -1,12 +1,18 @@
 <!DOCTYPE html>
 <html>
-<head>
-  <title>Pay</title>
-  <%= stylesheet_link_tag    "pay/application", media: "all" %>
-  <%= javascript_include_tag "pay/application" %>
+<head class="h-full">
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Payment Confirmation - <%= Pay.business_name %></title>
+  <%#= stylesheet_link_tag    "pay/application", media: "all" %>
+  <%#= javascript_include_tag "pay/application" %>
   <%= csrf_meta_tags %>
+
+  <link href="https://unpkg.com/tailwindcss@^1.0/dist/tailwind.min.css" rel="stylesheet">
+  <script src="https://cdn.jsdelivr.net/npm/vue@2.6.10/dist/vue.min.js"></script>
+  <script src="https://js.stripe.com/v3"></script>
 </head>
-<body>
+<body class="font-sans text-gray-600 bg-gray-200 leading-normal p-4 h-full">
 
 <%= yield %>