spree_paypal_checkout 0.7.0 → 6.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef8dfb2e6f13c0334979a7af8f62d21882bdb0e2a717e36328aec335194d8767
-  data.tar.gz: d2f23cb259fb7f2c55b3c4af5fc98d48e9625f46ec239a351f9e6896f002302e
+  metadata.gz: b41da8ff17667c478aa2a55cc31033ba2e6478cde897ee20afa80f35aec99ae1
+  data.tar.gz: 25feabb516457d5699b497c8bdadff0a3221c66fd7643f871ad872de872ed0e8
 SHA512:
-  metadata.gz: 2bca77d66f83220e40a00cb7edbba2560948384c46a4033ac2b3e1dd92d7e08235f366f3f57c867e1a790539e3e48d521ca61fd1899f9283dd5ad9105c1ed4b2
-  data.tar.gz: ec63da1f24b8a6885f8da03d4a7fcbd212eb5cfba45d1f42922dffe167549fd84625b97ab2349820d8bc484c5cf97b5423b842044dc34e5819f6d5e2815cff0d
+  metadata.gz: a601b77f4a2f7cb3b0a78bc8d1dc619d048404ca706e150a1699f7fc78f8d5e25d20b75c4368c8d983f3611b9d6f3feab0ed43e25587450f40caf396b7899d45
+  data.tar.gz: 80cdce32765ca01bb72e1e50ccafdfae1d843e06a1b8c9f0a88b3d05750dc807744f7e9716366b273af4e9668625474c020b44ede67dc95b140c072364147a6f

data/LICENSE

@@ -1,9 +1,21 @@
 MIT License
 
-Copyright (c) 2026 Vendo Connect Inc.
+Copyright (c) 2026-present, Vendo Sp. z o.o., Vendo Connect Inc.
 
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -1,69 +1,51 @@
 # Spree PayPal Checkout
 
-This is the official PayPal Checkout extension for [Spree Commerce](https://spreecommerce.org).
+Official [PayPal](https://www.paypal.com) payment gateway for
+[Spree Commerce](https://spreecommerce.org), built on Spree's payment session
+API.
 
-This PayPal Checkout integration is bundled in the [Spree Starter](https://github.com/spree/spree_starter/) for your development convenience.
-
-Or you could follow the [installation instructions](https://spreecommerce.org/docs/integrations/payments/paypal).
-
-If you like what you see, consider giving this repo a GitHub star :star:
-
-Thank you for supporting Spree open-source :heart:
+Supports PayPal, Pay Later, Venmo, and card payments that buyers without a
+PayPal account make in PayPal's own window. Honors the store's capture setting:
+payments are captured at checkout, or authorized and captured later.
 
 ## Installation
 
-1. Add this extension to your Gemfile with this line:
-
-    ```ruby
-    bundle add spree_paypal_checkout
-    ```
-
-2. Run the install generator
-
-    ```ruby
-    bundle exec rails g spree_paypal_checkout:install
-    ```
-
-3. Restart your server
-
-  If your server was running, restart it so that it can find the assets properly.
+```bash
+spree add paypal
+```
 
-## Developing
+Without the Spree CLI, add `gem 'spree_paypal_checkout'` to the `Gemfile` with
+the same version requirement as your `spree` gem and run `bundle install`. The
+gateway registers itself — there is nothing to generate and no migrations to
+run.
 
-1. Create a dummy app
+## Configuration
 
-    ```bash
-    bundle update
-    bundle exec rake test_app
-    ```
+Create a PayPal payment method in the admin dashboard and enter the client id
+and secret of your PayPal REST app. Leave Test mode on for sandbox credentials
+and turn it off for live ones. Saving queues a job that registers the webhook
+with PayPal; until it has run, PayPal's notifications are refused, so if none
+arrive, check the job queue for a failed `SpreePaypalCheckout::RegisterWebhookJob`.
 
-2. Add your new code
-3. Run tests
+Set `PAYPAL_LOG_LEVEL` (for example `debug`) to change how much the PayPal
+client logs. Request and response bodies are never logged.
 
-    ```bash
-    bundle exec rspec
-    ```
+## Upgrading from spree_paypal_checkout 0.x
 
-When testing your applications integration with this extension you may use it's factories.
-Simply add this require statement to your spec_helper:
+See the PayPal section of the Spree 5.6 → 6.0 upgrade guide. Two upgrade
+steps, `migrate_paypal_payments` and `register_paypal_webhooks`, carry existing
+payments and webhooks over; run them before dropping the old
+`spree_paypal_checkout_orders` table.
 
-```ruby
-require 'spree_paypal_checkout/factories'
-```
+## Testing
 
-## Releasing a new version
+The suite runs offline against recorded VCR cassettes:
 
-```shell
-bundle exec gem bump -p -t
-bundle exec gem release
+```bash
+bundle exec rake test_app   # once
+bundle exec rspec
 ```
 
-For more options please see [gem-release README](https://github.com/svenfuchs/gem-release)
-
-## Contributing
-
-If you'd like to contribute, please take a look at the
-[instructions](CONTRIBUTING.md) for installing dependencies and crafting a good
-pull request.
-
-Copyright (c) 2025 Vendo Connect Inc, released under the AGPL-3.0 license
+Record cassettes against the PayPal sandbox by adding `RECORD_VCR=1`,
+`PAYPAL_CLIENT_ID` and `PAYPAL_CLIENT_SECRET` to the environment and running the
+`vcr`-tagged examples.

data/Rakefile

@@ -1,25 +1,15 @@
-require 'bundler'
-Bundler::GemHelper.install_tasks
-
+require 'rubygems'
+require 'rake'
+require 'rake/testtask'
 require 'rspec/core/rake_task'
-require 'spree/testing_support/extension_rake'
+require 'spree/testing_support/common_rake'
 
 RSpec::Core::RakeTask.new
 
-task :default do
-  if Dir['spec/dummy'].empty?
-    Rake::Task[:test_app].invoke
-    Dir.chdir('../../')
-  end
-  Rake::Task[:spec].invoke
-end
+task default: :spec
 
-desc 'Generates a dummy app for testing'
+desc "Generates a dummy app for testing"
 task :test_app do
   ENV['LIB_NAME'] = 'spree_paypal_checkout'
-  Rake::Task['extension:test_app'].execute(
-    install_storefront: true,
-    install_admin: true
-  )
-  system({ 'BUNDLE_GEMFILE' => File.expand_path('Gemfile', __dir__) }, 'rails g spree_legacy_api_v2:install')
+  Rake::Task['common:test_app'].invoke
 end

data/app/jobs/spree_paypal_checkout/base_job.rb

@@ -0,0 +1,5 @@
+module SpreePaypalCheckout
+  class BaseJob < Spree::BaseJob
+    queue_as { SpreePaypalCheckout.queue }
+  end
+end

data/app/jobs/spree_paypal_checkout/register_webhook_job.rb

@@ -0,0 +1,20 @@
+module SpreePaypalCheckout
+  class RegisterWebhookJob < BaseJob
+    # Safe to replay: registration finds the webhook for the URL before
+    # creating one.
+    retry_on StandardError, wait: :polynomially_longer, attempts: 5
+    # Must come after `retry_on StandardError` so DeserializationError lands in discard.
+    discard_on ActiveJob::DeserializationError
+
+    def perform(payment_method_id)
+      # Locked on load: two saves in a row queue two jobs, and both would
+      # otherwise create a webhook for the same URL.
+      Spree::PaymentMethod.transaction do
+        payment_method = Spree::PaymentMethod.lock.find_by(id: payment_method_id)
+        next unless payment_method.is_a?(SpreePaypalCheckout::Gateway)
+
+        payment_method.register_webhook
+      end
+    end
+  end
+end

data/app/maintenance_tasks/spree_paypal_checkout/maintenance_tasks/migrate_payments.rb

@@ -0,0 +1,100 @@
+module SpreePaypalCheckout
+  module MaintenanceTasks
+    # Gives PayPal payments taken under the 5.x gem the 6.0 shape: the PayPal
+    # order id as the response code, the key core links a session to its
+    # payment by, and the capture id the 5.x gem stored there moved to
+    # metadata['paypal_capture_id'], where refunds and the dashboard link read
+    # it.
+    #
+    # The order id is found two ways, both from the 5.x gem's own records: the
+    # session that took the payment holds the capture in its external data, and
+    # a payment from the older non-session flow is matched through
+    # spree_paypal_checkout_orders, which must therefore not be dropped first.
+    # A payment matched by neither is logged and left as it was.
+    class MigratePayments < Spree::MaintenanceTask
+      LEGACY_ORDERS_TABLE = 'spree_paypal_checkout_orders'.freeze
+
+      supports_dry_run
+
+      def collection
+        gateway_ids = Spree::PaymentMethod.unscoped.where(type: 'SpreePaypalCheckout::Gateway').select(:id)
+        Spree::Payment.unscoped.where(payment_method_id: gateway_ids).where.not(response_code: [nil, '']).order(:id)
+      end
+
+      def process(payment)
+        # Payments taken in 6.0, and those an earlier run converted, already
+        # carry what PayPal issued.
+        if payment.metadata['paypal_capture_id'].present? || payment.metadata['paypal_authorization_id'].present?
+          return tally(:already_converted)
+        end
+
+        paypal_order_id = paypal_order_id_for(payment)
+        if paypal_order_id.nil?
+          Rails.logger.warn("[spree_paypal_checkout] migrate_paypal_payments: no PayPal order found for payment #{payment.id}")
+          return tally(:unmatched)
+        end
+        return tally(:would_convert) if dry_run?
+
+        payment.update_columns(
+          response_code: paypal_order_id,
+          metadata: payment.metadata.merge('paypal_capture_id' => payment.response_code),
+          updated_at: Time.current
+        )
+        tally(:converted)
+      rescue ActiveRecord::RecordNotUnique
+        # Another payment of the same order already carries this PayPal order.
+        Rails.logger.warn("[spree_paypal_checkout] migrate_paypal_payments: payment #{payment.id} duplicates another payment's PayPal order")
+        tally(:unmatched)
+      end
+
+      private
+
+      def paypal_order_id_for(payment)
+        capture_id = payment.response_code
+        session_order_id(payment, capture_id) || legacy_order_id(payment, capture_id)
+      end
+
+      # The 5.x session stored PayPal's whole capture response as its external
+      # data, the order id as its external id.
+      # Looked up within the payment's own order or cart, so each payment reads
+      # a handful of rows.
+      def session_order_id(payment, capture_id)
+        owner = payment.order_id ? { order_id: payment.order_id } : { cart_id: payment.cart_id }
+        return if owner.values.first.nil?
+
+        sessions = Spree::PaymentSessions::PaypalCheckout.unscoped.where(payment_method_id: payment.payment_method_id, **owner)
+        sessions.find { |session| capture_id_in(session.external_data) == capture_id }&.external_id
+      end
+
+      # The older flow only ever paid for orders.
+      def legacy_order_id(payment, capture_id)
+        return if payment.order_id.nil? || !legacy_orders_table?
+
+        rows = legacy_order_model.where(payment_method_id: payment.payment_method_id, order_id: payment.order_id)
+        rows.find { |row| capture_id_in(row.data) == capture_id }&.paypal_id
+      end
+
+      def capture_id_in(data)
+        data = JSON.parse(data) if data.is_a?(String)
+        return unless data.is_a?(Hash)
+
+        data.dig('purchase_units', 0, 'payments', 'captures', 0, 'id')
+      rescue JSON::ParserError
+        nil
+      end
+
+      def legacy_orders_table?
+        @legacy_orders_table = ActiveRecord::Base.connection.table_exists?(LEGACY_ORDERS_TABLE) if @legacy_orders_table.nil?
+        @legacy_orders_table
+      end
+
+      # The 5.x model is gone, so the table is read through a throwaway one.
+      def legacy_order_model
+        @legacy_order_model ||= Class.new(ActiveRecord::Base) do
+          self.table_name = LEGACY_ORDERS_TABLE
+          self.inheritance_column = nil
+        end
+      end
+    end
+  end
+end

data/app/models/spree/payment_sessions/paypal_checkout.rb

@@ -1,76 +1,58 @@
 module Spree
+  # Stored under this name in `type` columns since 5.x, so it is kept.
   class PaymentSessions::PaypalCheckout < PaymentSession
-    def paypal_order_id
-      external_id
-    end
+    # The order read at completion, or by prepare_for_settlement! on the
+    # webhook path, so settlement inside the lock does no PayPal I/O.
+    attr_writer :paypal_order
 
-    def paypal_capture_id
-      external_data&.dig('purchase_units', 0, 'payments', 'captures', 0, 'id')
+    def intent
+      external_data&.dig('intent')
     end
 
-    def paypal_payer
-      external_data&.dig('payer')
+    # Moves only after a recoverable decline, so a buyer's next try reaches
+    # PayPal as a new request rather than a replay of the declined one.
+    #
+    # @return [Integer]
+    def attempt
+      (external_data&.dig('attempt') || 1).to_i
     end
 
-    def paypal_payment_source
-      external_data&.dig('payment_source')
+    # Whether Complete ever asked PayPal to move money for this session.
+    def complete_attempted?
+      external_data.present? && (external_data.key?('attempt') || external_data.key?('paypal_result'))
     end
 
-    def accepted?
-      external_data&.dig('status') == 'COMPLETED'
+    # @return [Hash]
+    def paypal_order
+      @paypal_order ||= payment_method.paypal_order(external_id)
     end
 
-    def successful?
-      accepted?
+    # Settlement reads the order only to create the payment, so a session that
+    # already has one needs no PayPal call.
+    def prepare_for_settlement!
+      paypal_order if payment.nil?
+      self
     end
 
-    # Creates or finds the Spree::Payment for this session.
-    # Defers creation until paypal_capture_id is present so response_code
-    # is always the capture ID (required for refunds via Gateway#credit).
-    def find_or_create_payment!(metadata = {})
-      return unless persisted?
-      return payment if payment.present?
-      return unless paypal_capture_id
-
-      order.with_lock do
-        existing_payment = order.payments.where(
-          payment_method: payment_method,
-          response_code: paypal_capture_id
-        ).first
-
-        return existing_payment if existing_payment.present?
-
-        source = create_payment_source!
-
-        order.payments.create!(
-          payment_method: payment_method,
-          amount: amount,
-          response_code: paypal_capture_id,
-          source: source,
-          skip_source_requirement: true,
-          private_metadata: metadata
-        )
-      end
+    # @return [SpreePaypalCheckout::PaymentSources::Paypal, nil]
+    def payment_source_for_settlement
+      SpreePaypalCheckout::PaymentSources::Paypal.for_payment_source(
+        paypal_order['payment_source'],
+        payment_method: payment_method,
+        customer: owner&.customer,
+        paypal_order_id: external_id
+      )
     end
 
-    private
-
-    def create_payment_source!
-      paypal_data = paypal_payment_source&.dig('paypal')
-      return nil unless paypal_data
+    # Records what PayPal issued against the order, which refunds and the
+    # dashboard link cannot read from the order id alone.
+    def apply_settlement_metadata(payment, metadata)
+      super
 
-      source = SpreePaypalCheckout::PaymentSources::Paypal.find_or_initialize_by(
-        payment_method: payment_method,
-        gateway_payment_profile_id: paypal_data['account_id']
-      )
-      source.update!(
-        user: order.user,
-        email: paypal_data['email_address'],
-        name: "#{paypal_data.dig('name', 'given_name')} #{paypal_data.dig('name', 'surname')}".strip,
-        account_id: paypal_data['account_id'],
-        account_status: paypal_data['account_status']
-      )
-      source
+      capture = payment_method.captures(paypal_order).first
+      authorization = payment_method.authorizations(paypal_order).first
+      payment.metadata['paypal_capture_id'] = capture['id'] if capture
+      payment.metadata['paypal_authorization_id'] = authorization['id'] if authorization
     end
   end
 end

data/app/models/spree_paypal_checkout/amounts.rb

@@ -0,0 +1,55 @@
+module SpreePaypalCheckout
+  # PayPal's decimal-string amounts (https://developer.paypal.com/reference/currency-codes/).
+  # Written in the currency's ISO exponent, except that PayPal takes HUF, JPY
+  # and TWD only in whole units. An amount PayPal would refuse raises here,
+  # naming the rule, rather than being rounded to a sum Spree did not record.
+  module Amounts
+    module_function
+
+    SUPPORTED_CURRENCIES = %w[
+      AUD BRL CAD CHF CNY CZK DKK EUR GBP HKD HUF ILS JPY MXN MYR NOK NZD PHP PLN SEK SGD THB TWD USD
+    ].freeze
+    WHOLE_UNITS = %w[HUF JPY TWD].freeze
+
+    class UnsupportedAmount < Spree::Core::GatewayError; end
+
+    # @param currency [String]
+    # @return [Boolean]
+    def supported_currency?(currency)
+      SUPPORTED_CURRENCIES.include?(currency.to_s.upcase)
+    end
+
+    # @return [Boolean] whether PayPal takes this amount in this currency
+    def payable?(amount, currency)
+      to_paypal(amount, currency)
+      true
+    rescue UnsupportedAmount
+      false
+    end
+
+    # @param amount [BigDecimal, Spree::Money]
+    # @param currency [String]
+    # @return [String] e.g. "19.99", or "2000" for yen
+    # @raise [UnsupportedAmount] when PayPal would refuse the amount
+    def to_paypal(amount, currency)
+      amount = amount.to_d if amount.respond_to?(:to_d)
+      code = currency.to_s.upcase
+      raise UnsupportedAmount, "PayPal does not take #{code}" unless supported_currency?(code)
+
+      places = WHOLE_UNITS.include?(code) ? 0 : Spree::Money::Rounding.precision(code)
+      quantized = Spree::Money::Rounding.quantize(amount, places)
+      if quantized != amount
+        rule = places.zero? ? 'only in whole units' : "only to #{places} decimal places"
+        raise UnsupportedAmount, "PayPal takes #{code} #{rule}, got #{amount.to_s('F')}"
+      end
+      return quantized.to_i.to_s if places.zero?
+
+      Spree::Money::Rounding.format(quantized, code)
+    end
+
+    # @return [PaypalServerSdk::Money]
+    def to_paypal_money(amount, currency)
+      PaypalServerSdk::Money.new(currency_code: currency.to_s.upcase, value: to_paypal(amount, currency))
+    end
+  end
+end