pay 2.1.2 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b8ee10da017b8876cf39df8679d26cf1c18de43201809065693d1c59a4d687f
-  data.tar.gz: e522b86563b6d6f1770d589f9d3f608168869b9dfc4adc499bb8b6c997669683
+  metadata.gz: cd6aa7121588fb74663d51c6fdb21d0a67b196cc1f125921ae208ad65758fb6c
+  data.tar.gz: f15391bc0601b3027f19ec2c5111103fd0d739b24a48366e2f3c67489c2b99c3
 SHA512:
-  metadata.gz: d775f1b342f3202c2a11c17372e4602fb186bf0c4556ee5e3eae11be4fcd293e5dd719a540a1c3c6f310cc00df9c5802c321b0e503aa4fc102d613562012fee8
-  data.tar.gz: 8d8bcc8b121760e323dc11ad79db0ac344f07324d157159bb30a6e0b5bf0b55fe6a8c5f5960820031b6808cec411e50ee3abc0d6c4460ccc0c9b7372c99ae250
+  metadata.gz: 1539032c93fbcdf7a8ad83b51bff67451fcaac73553950ae916d2e67d78ad8257a34cc7729e51ed9243eb04270a25025e87286b2dbb65345fae5314b8dc370de
+  data.tar.gz: 73ba465dbf96a4af3f13091219ed4af9ad551ecb9f8a53b6a6b781720704b2f4aaf87474c526fca637023e576d6fc37e6c2c98d9c665550cda8691492a80f506

data/README.md

@@ -2,14 +2,15 @@
 
 ## Pay - Payments engine for Ruby on Rails
 
-[![Build Status](https://github.com/pay-rails/pay/workflows/Tests/badge.svg)](https://github.com/pay-rails/pay/actions)
+[![Build Status](https://github.com/pay-rails/pay/workflows/Tests/badge.svg)](https://github.com/pay-rails/pay/actions) [![Gem Version](https://badge.fury.io/rb/pay.svg)](https://badge.fury.io/rb/pay)
 
 Pay is a payments engine for Ruby on Rails 4.2 and higher.
 
 **Current Payment Providers**
 
-- 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)
+- Stripe ([supports SCA](https://stripe.com/docs/strong-customer-authentication) using API version `2020-08-27`)
 - Braintree
+- Paddle
 
 Want to add a new payment provider? Contributions are welcome and the instructions [are here](https://github.com/jasoncharnes/pay/wiki/New-Payment-Provider).
 
@@ -35,6 +36,9 @@ gem 'stripe_event', '~> 2.3'
 # To use Braintree + PayPal, also include:
 gem 'braintree', '< 3.0', '>= 2.92.0'
 
+# To use Paddle, also include:
+gem 'paddle_pay', '~> 0.0.1'
+
 # To use Receipts
 gem 'receipts', '~> 1.0.0'
 ```
@@ -78,6 +82,8 @@ class User < ActiveRecord::Base
 end
 ```
 
+An `email` attribute or method on your `Billable` model is required.
+
 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
@@ -131,10 +137,15 @@ development:
     public_key: yyyy
     merchant_id: aaaa
     environment: sandbox
+  paddle:
+    vendor_id: xxxx
+    vendor_auth_code: yyyy
+    public_key_base64: MII...==
 ```
 
 For Stripe, you can also use the `STRIPE_PUBLIC_KEY`, `STRIPE_PRIVATE_KEY` and `STRIPE_SIGNING_SECRET` environment variables.
 For Braintree, you can also use `BRAINTREE_MERCHANT_ID`, `BRAINTREE_PUBLIC_KEY`, `BRAINTREE_PRIVATE_KEY`, and `BRAINTREE_ENVIRONMENT` environment variables.
+For Paddle, you can also use `PADDLE_VENDOR_ID`, `PADDLE_VENDOR_AUTH_CODE` and `PADDLE_PUBLIC_KEY_BASE64` environment variables.
 
 ### Generators
 
@@ -194,6 +205,8 @@ user.on_generic_trial? #=> true
 
 #### Creating a Charge
 
+##### Stripe and Braintree
+
 ```ruby
 user = User.find_by(email: 'michael@bluthcompany.co')
 
@@ -217,8 +230,23 @@ different currencies, etc.
 On failure, a `Pay::Error` will be raised with details about the payment
 failure.
 
+##### Paddle
+It is only possible to create immediate one-time charges on top of an existing subscription.
+
+```ruby
+user = User.find_by(email: 'michael@bluthcompany.co')
+
+user.processor = 'paddle'
+user.charge(1500, {charge_name: "Test"}) # $15.00 USD
+
+```
+
+An existing subscription and a charge name are required.
+
 #### Creating a Subscription
 
+##### Stripe and Braintree
+
 ```ruby
 user = User.find_by(email: 'michael@bluthcompany.co')
 
@@ -237,20 +265,60 @@ def subscribe(name: 'default', plan: 'default', **options)
 end
 ```
 
-##### Name
+For example, you can pass the `quantity` option to subscribe to a plan with for per-seat pricing.
+
+```ruby
+
+user.subscribe(name: "default", plan: "default", quantity: 3)
+```
+
+###### Name
 
 Name is an internally used name for the subscription.
 
-##### Plan
+###### Plan
 
-Plan is the plan ID from the payment processor.
+Plan is the plan ID or price ID from the payment processor. For example: `plan_xxxxx` or `price_xxxxx`
 
-##### Options
+###### Options
 
 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.
 
+##### Paddle
+It is currently not possible to create a subscription through the API. Instead the subscription in Pay is created by the Paddle Subscription Webhook. In order to be able to assign the subcription to the correct owner, the Paddle [passthrough parameter](https://developer.paddle.com/guides/how-tos/checkout/pass-parameters) has to be used for checkout.
+
+To ensure that the owner cannot be tampered with, Pay uses a Signed Global ID with a purpose. The purpose string consists of "paddle_" and the subscription plan id (or product id respectively).
+
+Javascript Checkout:
+```javascript
+Paddle.Checkout.open({
+	product: 12345,
+	passthrough: "<%= Pay::Paddle.passthrough(owner: current_user) %>"
+});
+```
+
+Paddle Button Checkout:
+```html
+<a href="#!" class="paddle_button" data-product="12345" data-email="<%= current_user.email %>" data-passthrough="<%= Pay::Paddle.passthrough(owner: current_user) %>"
+```
+
+###### Passthrough
+
+Pay providers a helper method for generating the passthrough JSON object to associate the purchase with the correct Rails model.
+
+```ruby
+Pay::Paddle.passthrough(owner: current_user, foo: :bar)
+#=> { owner_sgid: "xxxxxxxx", foo: "bar" }
+
+# To generate manually without the helper
+#=> { owner_sgid: current_user.to_sgid.to_s, foo: "bar" }.to_json
+```
+
+Pay parses the passthrough JSON string and verifies the `owner_sgid` hash to match the webhook with the correct billable record.
+The passthrough parameter `owner_sgid` is only required for creating a subscription.
+
 #### Retrieving a Subscription from the Database
 
 ```ruby
@@ -307,26 +375,45 @@ Plan is the plan ID from the payment processor.
 
 #### Retrieving a Payment Processor Account
 
+##### Stripe and Braintree
+
 ```ruby
 user = User.find_by(email: 'george.michael@bluthcompany.co')
 
 user.customer #> Stripe or Braintree customer account
 ```
 
+##### Paddle
+
+It is currently not possible to retrieve a payment processor account through the API.
+
 #### Updating a Customer's Credit Card
 
+##### Stripe and Braintree
+
 ```ruby
 user = User.find_by(email: 'tobias@bluthcompany.co')
 
 user.update_card('payment_method_id')
 ```
 
+##### Paddle
+
+Paddle provides a unique [Update URL](https://developer.paddle.com/guides/how-tos/subscriptions/update-payment-details) for each user, which allows them to update the payment method.
+```ruby
+user = User.find_by(email: 'tobias@bluthcompany.co')
+
+user.subscription.paddle_update_url
+```
+
+
+
 #### 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
+user.processor_subscription(subscription_id) #=> Stripe, Braintree or Paddle Subscription
 ```
 
 ## Subscription API
@@ -363,14 +450,31 @@ user = User.find_by(email: 'carl.weathers@bluthcompany.co')
 user.subscription.active? #=> true or false
 ```
 
+#### Checking to See If a Subscription Is Paused
+
+```ruby
+user = User.find_by(email: 'carl.weathers@bluthcompany.co')
+
+user.subscription.paused? #=> true or false
+```
+
 #### Cancel a Subscription (At End of Billing Cycle)
 
+##### Stripe, Braintree and Paddle
+
 ```ruby
 user = User.find_by(email: 'oscar@bluthcompany.co')
 
 user.subscription.cancel
 ```
 
+##### Paddle
+In addition to the API, Paddle provides a subscription [Cancel URL](https://developer.paddle.com/guides/how-tos/subscriptions/cancel-and-pause) that you can redirect customers to cancel their subscription.
+
+```ruby
+user.subscription.paddle_cancel_url
+```
+
 #### Cancel a Subscription Immediately
 
 ```ruby
@@ -379,6 +483,16 @@ user = User.find_by(email: 'annyong@bluthcompany.co')
 user.subscription.cancel_now!
 ```
 
+#### Pause a Subscription
+
+##### Paddle
+
+```ruby
+user = User.find_by(email: 'oscar@bluthcompany.co')
+
+user.subscription.pause
+```
+
 #### Swap a Subscription to another Plan
 
 ```ruby
@@ -387,7 +501,17 @@ user = User.find_by(email: 'steve.holt@bluthcompany.co')
 user.subscription.swap("yearly")
 ```
 
-#### Resume a Subscription on a Grace Period
+#### Resume a Subscription
+
+##### Stripe or Braintree Subscription (on Grace Period)
+
+```ruby
+user = User.find_by(email: 'steve.holt@bluthcompany.co')
+
+user.subscription.resume
+```
+
+##### Paddle (Paused)
 
 ```ruby
 user = User.find_by(email: 'steve.holt@bluthcompany.co')
@@ -464,8 +588,8 @@ config.routes_path = '/secret-webhook-path'
 
 ## 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
+We support Stripe, Braintree and Paddle and make our best attempt to
+standardize the three. 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.
@@ -480,7 +604,22 @@ development:
     merchant_id: zzzz
     environment: sandbox
 ```
+#### Paddle
 
+```yaml
+  paddle:
+    vendor_id: xxxx
+    vendor_auth_code: yyyy
+    public_key_base64: MII...==
+```
+
+Paddle receipts can be retrieved by a charge receipt URL.
+```ruby
+user = User.find_by(email: 'annyong@bluthcompany.co')
+
+charge = user.charges.first
+charge.paddle_receipt_url
+```
 #### Stripe
 
 You'll need to add your private Stripe API key to your Rails secrets `config/secrets.yml`, credentials `rails credentials:edit`
@@ -497,6 +636,20 @@ 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).**
 
+You need the following event types to trigger the webhook:
+
+```
+customer.subscription.updated
+customer.subscription.deleted
+customer.subscription.created
+payment_method.updated
+invoice.payment_action_required
+customer.updated
+customer.deleted
+charge.succeeded
+charge.refunded
+```
+
 ##### 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.
@@ -511,9 +664,7 @@ correctly for SCA payments.
 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).
-
-The Javascript will now need to use createPaymentMethod instead of createToken. https://stripe.com/docs/js/payment_intents/create_payment_method
+You should use `stripe.confirmCardSetup` 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.confirmCardPayment` if you'd like to charge the customer immediately (think checking out of a shopping cart).
 
 The Javascript also needs to have a PaymentIntent or SetupIntent created server-side and the ID passed into the Javascript to do this. That way it knows how to safely handle the card tokenization if it meets the SCA requirements.
 
@@ -545,7 +696,10 @@ If you have an issue you'd like to submit, please do so using the issue tracker
 
 If you'd like to open a PR please make sure the following things pass:
 
-- `rake test`
+```ruby
+bin/rails db:test:prepare
+bin/rails test
+```
 
 ## License
 

data/Rakefile

@@ -1,33 +1,31 @@
 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 "bundler/gem_tasks"
+
+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", __dir__)
-load 'rails/tasks/engine.rake'
-
-load 'rails/tasks/statistics.rake'
+load "rails/tasks/engine.rake"
 
-unless Rails.env.test?
-  require "bundler/gem_tasks"
-end
+load "rails/tasks/statistics.rake"
 
-require 'rake/testtask'
+require "rake/testtask"
 
 Rake::TestTask.new(:test) do |t|
-  t.libs << 'test'
-  t.pattern = 'test/**/*_test.rb'
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
   t.verbose = false
 end
 

data/app/controllers/pay/payments_controller.rb

@@ -1,6 +1,9 @@
 module Pay
   class PaymentsController < ApplicationController
+    layout "pay/application"
+
     def show
+      @redirect_to = params[:back].presence || root_path
       @payment = Payment.from_id(params[:id])
     end
   end

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

@@ -0,0 +1,36 @@
+module Pay
+  module Webhooks
+    class PaddleController < Pay::ApplicationController
+      if Rails.application.config.action_controller.default_protect_from_forgery
+        skip_before_action :verify_authenticity_token
+      end
+
+      def create
+        verifier = Pay::Paddle::Webhooks::SignatureVerifier.new(check_params.as_json)
+        if verifier.verify
+          case params["alert_name"]
+          when "subscription_created"
+            Pay::Paddle::Webhooks::SubscriptionCreated.new(check_params.as_json)
+          when "subscription_updated"
+            Pay::Paddle::Webhooks::SubscriptionUpdated.new(check_params.as_json)
+          when "subscription_cancelled"
+            Pay::Paddle::Webhooks::SubscriptionCancelled.new(check_params.as_json)
+          when "subscription_payment_succeeded"
+            Pay::Paddle::Webhooks::SubscriptionPaymentSucceeded.new(check_params.as_json)
+          when "subscription_payment_refunded"
+            Pay::Paddle::Webhooks::SubscriptionPaymentRefunded.new(check_params.as_json)
+          end
+          render json: {success: true}, status: :ok
+        else
+          head :ok
+        end
+      end
+
+      private
+
+      def check_params
+        params.except(:action, :controller).permit!
+      end
+    end
+  end
+end

data/app/mailers/pay/user_mailer.rb

@@ -44,8 +44,8 @@ module Pay
     private
 
     def to(user)
-      if user.respond_to?(:name)
-        "#{user.name} <#{user.email}>"
+      if user.respond_to?(:customer_name)
+        "#{user.customer_name} <#{user.email}>"
       else
         user.email
       end