pay 2.2.2 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b0dc3430e6f89e4c1516a122bde97173ee5bdb1bfa835bb968b36083b633c4f
-  data.tar.gz: 0dbd1c62002fa67fbf9e78591f52199c9322e6d52868fb443e640f93dd2863d0
+  metadata.gz: cd6aa7121588fb74663d51c6fdb21d0a67b196cc1f125921ae208ad65758fb6c
+  data.tar.gz: f15391bc0601b3027f19ec2c5111103fd0d739b24a48366e2f3c67489c2b99c3
 SHA512:
-  metadata.gz: d6e108e2377cfabdd8da381f225094d4f8f2e0fb25ca28dbadf0cfbfaad1bbafbbb1f4613c92ac0bd8dc0d87c4de14b21d32004ab31ab572588bef4926746f92
-  data.tar.gz: 68ebaeed4f068419a51860d853bd914ba6c5076e590bac85005feb431a404bb7ea8c3fbbe113876e0f6ec56ad539d43e698504b99aa5951bc76894d18961f8c6
+  metadata.gz: 1539032c93fbcdf7a8ad83b51bff67451fcaac73553950ae916d2e67d78ad8257a34cc7729e51ed9243eb04270a25025e87286b2dbb65345fae5314b8dc370de
+  data.tar.gz: 73ba465dbf96a4af3f13091219ed4af9ad551ecb9f8a53b6a6b781720704b2f4aaf87474c526fca637023e576d6fc37e6c2c98d9c665550cda8691492a80f506

data/README.md

@@ -10,6 +10,7 @@ Pay is a payments engine for Ruby on Rails 4.2 and higher.
 
 - 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'
 ```
@@ -133,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
 
@@ -196,6 +205,8 @@ user.on_generic_trial? #=> true
 
 #### Creating a Charge
 
+##### Stripe and Braintree
+
 ```ruby
 user = User.find_by(email: 'michael@bluthcompany.co')
 
@@ -219,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')
 
@@ -246,20 +272,53 @@ For example, you can pass the `quantity` option to subscribe to a plan with for
 user.subscribe(name: "default", plan: "default", 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 +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
@@ -372,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
@@ -388,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
@@ -396,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')
@@ -473,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.
@@ -489,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`

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,5 +1,7 @@
 module Pay
   class PaymentsController < ApplicationController
+    layout "pay/application"
+
     def show
       @redirect_to = params[:back].presence || root_path
       @payment = Payment.from_id(params[:id])

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/models/pay/application_record.rb

@@ -1,5 +1,10 @@
 module Pay
-  class ApplicationRecord < ActiveRecord::Base
+  class ApplicationRecord < Pay.model_parent_class.constantize
     self.abstract_class = true
+
+    def self.json_column?(name)
+      return unless connected? && table_exists?
+      [:json, :jsonb].include?(attribute_types[name].type)
+    end
   end
 end

data/app/models/pay/charge.rb

@@ -2,6 +2,9 @@ module Pay
   class Charge < ApplicationRecord
     self.table_name = Pay.chargeable_table
 
+    # Only serialize for non-json columns
+    serialize :data unless json_column?("data")
+
     # Associations
     belongs_to :owner, polymorphic: true
 
@@ -39,5 +42,9 @@ module Pay
     def paypal?
       braintree? && card_type == "PayPal"
     end
+
+    def paddle?
+      processor == "paddle"
+    end
   end
 end

data/app/models/pay/subscription.rb

@@ -2,7 +2,10 @@ module Pay
   class Subscription < ApplicationRecord
     self.table_name = Pay.subscription_table
 
-    STATUSES = %w[incomplete incomplete_expired trialing active past_due canceled unpaid]
+    STATUSES = %w[incomplete incomplete_expired trialing active past_due canceled unpaid paused]
+
+    # Only serialize for non-json columns
+    serialize :data unless json_column?("data")
 
     # Associations
     belongs_to :owner, polymorphic: true
@@ -66,6 +69,15 @@ module Pay
       past_due? || incomplete?
     end
 
+    def paused?
+      status == "paused"
+    end
+
+    def pause
+      return unless paddle?
+      send("#{processor}_pause")
+    end
+
     def cancel
       send("#{processor}_cancel")
     end
@@ -76,8 +88,17 @@ module Pay
 
     def resume
       unless on_grace_period?
-        raise StandardError,
-          "You can only resume subscriptions within their grace period."
+        unless paddle?
+          raise StandardError,
+            "You can only resume subscriptions within their grace period."
+        end
+      end
+
+      unless paused?
+        if paddle?
+          raise StandardError,
+            "You can only resume paused subscriptions."
+        end
       end
 
       send("#{processor}_resume")

data/config/routes.rb

@@ -4,4 +4,5 @@ Pay::Engine.routes.draw do
   resources :payments, only: [:show], module: :pay
   post "webhooks/stripe", to: "stripe_event/webhook#event"
   post "webhooks/braintree", to: "pay/webhooks/braintree#create"
+  post "webhooks/paddle", to: "pay/webhooks/paddle#create"
 end

data/db/migrate/20200603134434_add_data_to_pay_models.rb

@@ -0,0 +1,17 @@
+class AddDataToPayModels < ActiveRecord::Migration[4.2]
+  def change
+    add_column :pay_subscriptions, :data, data_column_type
+    add_column :pay_charges, :data, data_column_type
+  end
+
+  def data_column_type
+    case ActiveRecord::Base.configurations.default_hash.dig("adapter")
+    when "mysql2"
+      :json
+    when "postgresql"
+      :jsonb
+    else
+      :text
+    end
+  end
+end