pay 2.2.0 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ba84d79847e4ef8659bcf7fce74b966c07bb93fa8e2f29f902a243c9d6e5c8bf
-  data.tar.gz: 78e829fc4d218aabee2544a969b184e29e2621bf0d965318d1b33e4e750ebae4
+  metadata.gz: 2166bd09d0f1dcafea1425635ec9346d4f7731c212fc695f46b0f2fedfa08d2e
+  data.tar.gz: b9a035ee4abda206db7e132e4ced798c5917829a5ecf94b1e89c587675a09cc3
 SHA512:
-  metadata.gz: 2c044f842d680969455c49a24124c48e2e80a1b06486db11782032ebdd0db810c1836151f97087bb1e06e083106524e9250520768a96462ff24fdc0723a4c5dd
-  data.tar.gz: 7dbe7db2d4c6161b9516f73a1496092b6ffb9ebf2c5471fe061ccfd79b1335bc0a3238c1e407f621e3717cbd0cf28496790153b884a8540557428b6cf33c665c
+  metadata.gz: f5689e3cc0f8eaa890a8a8483910a2ee96c2e893e7484195de2554f9931f650f23f5bb9c37e5ceeb8cbf2c07048d1b4e3b398dd7c3ce52eb2901bc08bbececb9
+  data.tar.gz: dc10f025e73b6e4e053f11ecdabfb954fc6178090a9e3e82533b9bc2a7d3fc867d7f4a94871427541997e551589f82a0943efb091d199a86e53c2b6ccbf48d2c

data/README.md

@@ -8,8 +8,9 @@ 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'
 ```
@@ -99,6 +103,9 @@ Pay.setup do |config|
 
   config.send_emails = true
 
+  config.default_product_name = "default"
+  config.default_plan_name = "default"
+
   config.automount_routes = true
   config.routes_path = "/pay" # Only when automount_routes is true
 end
@@ -133,10 +140,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
 
@@ -196,6 +208,8 @@ user.on_generic_trial? #=> true
 
 #### Creating a Charge
 
+##### Stripe and Braintree
+
 ```ruby
 user = User.find_by(email: 'michael@bluthcompany.co')
 
@@ -219,8 +233,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')
 
@@ -234,7 +263,7 @@ 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)
+def subscribe(name: Pay.default_product_name, plan: Pay.default_plan_name, **options)
   ...
 end
 ```
@@ -243,23 +272,56 @@ For example, you can pass the `quantity` option to subscribe to a plan with for
 
 ```ruby
 
-user.subscribe(name: "default", plan: "default", quantity: 3)
+user.subscribe(name: Pay.default_product_name, plan: Pay.default_plan_name, quantity: 3)
 ```
 
-##### Name
+###### Name
 
 Name is an internally used name for the subscription.
 
-##### Plan
+###### Plan
 
 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
@@ -316,26 +378,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
@@ -372,14 +453,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
@@ -388,6 +486,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
@@ -396,7 +504,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')
@@ -473,8 +591,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.
@@ -489,7 +607,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`
@@ -506,6 +639,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.
@@ -552,7 +699,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

@@ -4,6 +4,8 @@ rescue LoadError
   puts "You must `gem install bundler` and `bundle install` to run rake tasks"
 end
 
+require "bundler/gem_tasks"
+
 require "rdoc/task"
 
 RDoc::Task.new(:rdoc) do |rdoc|
@@ -19,10 +21,6 @@ load "rails/tasks/engine.rake"
 
 load "rails/tasks/statistics.rake"
 
-unless Rails.env.test?
-  require "bundler/gem_tasks"
-end
-
 require "rake/testtask"
 
 Rake::TestTask.new(:test) do |t|

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/braintree_controller.rb

@@ -33,7 +33,7 @@ module Pay
         charge = billable.save_braintree_transaction(subscription.transactions.first)
 
         if Pay.send_emails
-          Pay::UserMailer.receipt(billable, charge).deliver_later
+          Pay::UserMailer.with(billable: billable, charge: charge).receipt.deliver_later
         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

@@ -1,53 +1,32 @@
 module Pay
   class UserMailer < ApplicationMailer
-    def receipt(user, charge)
-      @user, @charge = user, charge
-
-      if charge.respond_to? :receipt
-        attachments[charge.filename] = charge.receipt
+    def receipt
+      if params[:charge].respond_to? :receipt
+        attachments[params[:charge].filename] = params[:charge].receipt
       end
 
-      mail(
-        to: to(user),
-        subject: Pay.email_receipt_subject
-      )
+      mail to: to
     end
 
-    def refund(user, charge)
-      @user, @charge = user, charge
-
-      mail(
-        to: to(user),
-        subject: Pay.email_refund_subject
-      )
+    def refund
+      mail to: to
     end
 
-    def subscription_renewing(user, subscription)
-      @user, @subscription = user, subscription
-
-      mail(
-        to: to(user),
-        subject: Pay.email_renewing_subject
-      )
+    def subscription_renewing
+      mail to: to
     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
-      )
+    def payment_action_required
+      mail to: to
     end
 
     private
 
-    def to(user)
-      if user.respond_to?(:customer_name)
-        "#{user.customer_name} <#{user.email}>"
+    def to
+      if params[:billable].respond_to?(:customer_name)
+        "#{params[:billable].customer_name} <#{params[:billable].email}>"
       else
-        user.email
+        params[:billable].email
       end
     end
   end