spree-paypal_merchant 5.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ab60916880d1d5bea9ba2921266c7780011afe124111ced6ec568ea290749f3c
+  data.tar.gz: 05320b99c8cc4f7f077d9e99761618a05a61ef4a730f412094b4fd705f055469
+SHA512:
+  metadata.gz: dd1331f42e0599a7ab58d7271a9f7d85b3d37375c3e5e8b7e5004a72953cff2b6f34ff4c7373c9479d06b442659acc2857c80858479fa21ad6491ad5ed4da2eb
+  data.tar.gz: 38b28e6801bdb7e982cd286a547739a8b44605f6a1a1e524f8680df647a7cf2f955c7b34d247cb11e81b0ccc78d03fcac2cf89091cd5024e51defb660e51f18c

data/CHANGELOG.md

@@ -0,0 +1,67 @@
+# Changelog
+
+## 5.2.0
+
+Renamed from `spree-paypal_platform`. Same code, new name.
+
+| | Before | After |
+|---|---|---|
+| Gem | `spree-paypal_platform` | `spree-paypal_merchant` |
+| Require | `spree/paypal_platform` | `spree/paypal_merchant` |
+| Constant | `Spree::PaypalPlatform` | `Spree::PaypalMerchant` |
+| Table | `spree_paypal_platform_orders` | `spree_paypal_merchant_orders` |
+| Store API type | `paypal_platform` | `paypal_merchant` |
+| Generator | `spree:paypal_platform:install` | `spree:paypal_merchant:install` |
+
+To upgrade, swap the gem in the Gemfile and run
+`bin/rails g spree:paypal_merchant:install`. It copies
+`RenameSpreePaypalPlatformToPaypalMerchant`, which renames the table and
+rewrites stored STI class names (payment methods, payment sources, payment
+sessions). Map the `paypal_merchant` Store API type in the storefront
+*before* deploying the backend.
+
+Entries below use the old name.
+
+## 5.1.5
+
+- Gift cards and store credit: the PayPal order is created for the amount
+  due (`total_minus_store_credits`), not the full order total. Before, PayPal
+  charged the full total while Spree recorded the gift card as paying part
+  of it, so the customer paid twice for that part. A partial charge is sent
+  as a plain amount, without the breakdown and items that sum to the full
+  total.
+- Completing a session refuses to capture when the PayPal order amount no
+  longer matches the amount due (e.g. a gift card was applied, or the cart
+  changed, after the PayPal order was created). The session fails and the
+  storefront creates a new one.
+
+## 5.1.4
+
+- `enable_card_fields` preference (checkbox, default on).
+- Storefront sees `enable_apple_pay` and `enable_card_fields` on the payment
+  method (`public_preferences`) and on the payment session `external_data`.
+- Client token is not requested when Card Fields are disabled.
+
+## 5.1.3
+
+Remove the unused `apple_pay_domain` preference. Domain registration is
+in the PayPal dashboard, not this field.
+
+## 5.1.2
+
+- Completing a session GETs the PayPal order first and skips capture when
+  it is already `COMPLETED` (Apple Pay `confirmOrder`).
+- `CreateSource` accepts an empty `payment_source.paypal` hash from the
+  create-order echo so checkout can finish after PayPal has taken payment.
+
+## 5.1.1
+
+First release.
+
+- `Spree::PaypalPlatform::Gateway` for Spree 5.6+
+- PayPal wallet, Apple Pay, and Card Fields on one payment method
+- Store API v3 payment sessions
+- `SET_PROVIDED_ADDRESS` so the storefront owns shipping
+- VAT-safe amount breakdown (`additional_tax_total` only)
+- Official `paypal-server-sdk` `~> 2.3`
+- One migration: create `spree_paypal_platform_orders`

data/LICENSE

@@ -0,0 +1,10 @@
+MIT License
+
+Copyright (c) 2025 Vendo Connect Inc.
+Copyright (c) 2026 Aypex
+
+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 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

@@ -0,0 +1,84 @@
+# spree-paypal_merchant
+
+PayPal Checkout for Spree 5.6+, as a single payment method covering the PayPal
+wallet, Apple Pay, and Card Fields.
+
+Published gem: **`spree-paypal_merchant`**  
+Require: **`spree/paypal_merchant`**  
+Constant: **`Spree::PaypalMerchant`**
+
+This is not the official `spree_paypal_checkout` gem. It started from that
+extension (VAT `AMOUNT_MISMATCH` guard, storefront-owned address) and adds
+Apple Pay as a funding source of the same gateway.
+
+## What it is
+
+- One `Spree::PaypalMerchant::Gateway` payment method.
+- Checkout goes through Spree's **Store API v3 payment sessions**
+  (`POST /api/v3/store/carts/:id/payment_sessions` → complete).
+- The storefront owns the address. The gem pins it with
+  `SET_PROVIDED_ADDRESS` so PayPal does not re-collect it.
+- Amount breakdown sends **only `additional_tax_total`**. Sending full
+  `tax_total` double-counts included VAT and trips PayPal `AMOUNT_MISMATCH`.
+- Talks to PayPal via the official
+  [`paypal-server-sdk`](https://github.com/paypal/PayPal-Ruby-Server-SDK) gem
+  (`~> 2.3`).
+
+Apple Pay is not a second payment method and not a Spree Integration. It is
+a `payment_source.apple_pay` on the same Checkout order.
+
+## Installation
+
+```ruby
+gem 'spree-paypal_merchant'
+```
+
+```bash
+bundle install
+bin/rails g spree:paypal_merchant:install
+```
+
+The generator copies the migrations. Pass `--auto-run-migrations` to skip the
+prompt.
+
+Then add a **PayPal** payment method in admin and set:
+
+| Preference | Purpose |
+|---|---|
+| `client_id` / `client_secret` | REST app credentials from the PayPal Developer Dashboard |
+| `webhook_secret` | PayPal webhook ID (used as the verify-webhook `webhook_id`) |
+| `test_mode` | Sandbox vs live |
+| `enable_apple_pay` | Offer Apple Pay on the storefront (default on) |
+| `enable_card_fields` | Offer Card Fields on the storefront (default on) |
+
+Webhook URL is the standard Spree v3 payments webhook:
+
+```text
+https://<store>/api/v3/webhooks/payments/<prefixed-payment-method-id>
+```
+
+## Apple Pay
+
+1. Enable Apple Pay on the PayPal business account.
+2. Register every storefront domain (and subdomain) that will show the button
+   in the [PayPal Apple Pay domain
+   registration](https://developer.paypal.com/docs/checkout/apm/apple-pay/)
+   dashboard.
+3. Headless storefronts load the PayPal JS SDK with `components=applepay`
+   and render Apple's `ApplePaySession`. The gem records
+   `payment_source.apple_pay` as
+   `Spree::PaypalMerchant::PaymentSources::ApplePay`.
+4. Safari + HTTPS only.
+
+## Developing
+
+```bash
+bundle install
+bundle exec rake test_app
+bundle exec rspec
+```
+
+## License
+
+MIT. Derived from [spree/spree_paypal_checkout](https://github.com/spree/spree_paypal_checkout)
+(Vendo Connect Inc.), re-namespaced and extended by Aypex.

data/Rakefile

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+require 'spree/testing_support/extension_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
+
+desc 'Generates a dummy app for testing'
+task :test_app do
+  # Must be the require path, not the gem name: spree_core's common:test_app
+  # does a literal `require ENV['LIB_NAME']` and constantizes
+  # "#{LIB_NAME.camelize}::Generators::InstallGenerator".
+  ENV['LIB_NAME'] = 'spree/paypal_merchant'
+  ENV['DB'] ||= 'postgres'
+  Rake::Task['extension:test_app'].execute(install_storefront: true, install_admin: true)
+end

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

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Spree
+  class PaymentSessions::PaypalMerchant < PaymentSession
+    ##
+    # @return [String]
+    #
+    def paypal_order_id
+      external_id
+    end
+
+    ##
+    # @return [String, NilClass]
+    #
+    def paypal_capture_id
+      external_data&.dig('purchase_units', 0, 'payments', 'captures', 0, 'id')
+    end
+
+    ##
+    # @return [Hash, NilClass]
+    #
+    def paypal_payer
+      external_data&.dig('payer')
+    end
+
+    ##
+    # @return [Hash, NilClass]
+    #
+    def paypal_payment_source
+      external_data&.dig('payment_source')
+    end
+
+    ##
+    # @return [TrueClass, FalseClass]
+    #
+    def accepted?
+      external_data&.dig('status') == 'COMPLETED'
+    end
+
+    ##
+    # @return [TrueClass, FalseClass]
+    #
+    def successful?
+      accepted?
+    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).
+    #
+    # @param metadata [Hash]
+    # @return [Spree::Payment, NilClass]
+    #
+    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
+    end
+
+    private
+
+    def create_payment_source!
+      return nil if paypal_payment_source.blank?
+
+      Spree::PaypalMerchant::CreateSource.new(
+        paypal_payment_source: paypal_payment_source,
+        gateway: payment_method,
+        order: order
+      ).call
+    end
+  end
+end

data/app/models/spree/paypal_merchant/base.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Spree
+  module PaypalMerchant
+    ##
+    # Abstract ActiveRecord base for this gem's persisted models.
+    #
+    # Table names resolve through {Spree::PaypalMerchant.table_name_prefix}.
+    #
+    class Base < ::Spree.base_class
+      self.abstract_class = true
+    end
+  end
+end

data/app/models/spree/paypal_merchant/gateway/payment_sessions.rb

@@ -0,0 +1,308 @@
+# frozen_string_literal: true
+
+require 'net/http'
+
+module Spree
+  module PaypalMerchant
+    class Gateway < ::Spree::Gateway
+      ##
+      # Payment-session lifecycle used by Spree 5 storefronts.
+      #
+      module PaymentSessions
+        extend ActiveSupport::Concern
+
+        ##
+        # @return [TrueClass, FalseClass]
+        #
+        def session_required?
+          true
+        end
+
+        ##
+        # @return [Class]
+        #
+        def payment_session_class
+          Spree::PaymentSessions::PaypalMerchant
+        end
+
+        ##
+        # Creates a PayPal order and persists a payment session.
+        #
+        # Also requests a Card Fields client token. Failure is non-fatal —
+        # the wallet / Apple Pay buttons still work without it.
+        #
+        # @param order [Spree::Order]
+        # @param amount [Numeric, NilClass]
+        # @param external_data [Hash]
+        # @return [Spree::PaymentSessions::PaypalMerchant, NilClass]
+        #
+        def create_payment_session(order:, amount: nil, **_unused)
+          total = amount.presence || order.total_minus_store_credits
+
+          return nil if total.zero?
+
+          protect_from_error do
+            order_presenter = OrderPresenter.new(order, amount: total)
+            paypal_response = client.orders.create_order(order_presenter.to_json)
+
+            session_data = paypal_response.data.as_json
+
+            session_data['enable_apple_pay'] = apple_pay_enabled?
+            session_data['enable_card_fields'] = card_fields_enabled?
+
+            if card_fields_enabled?
+              client_token = generate_client_token
+              session_data['client_token'] = client_token if client_token.present?
+            end
+
+            payment_session_class.create!(
+              order: order,
+              payment_method: self,
+              amount: total,
+              currency: order.currency,
+              status: 'pending',
+              external_id: paypal_response.data.id,
+              customer: order.user,
+              external_data: session_data
+            )
+          end
+        end
+
+        ##
+        # @param payment_session [Spree::PaymentSessions::PaypalMerchant]
+        # @param amount [Numeric, NilClass]
+        # @param external_data [Hash]
+        # @return [TrueClass, FalseClass, NilClass]
+        #
+        def update_payment_session(payment_session:, amount: nil, external_data: {})
+          attrs = {}
+          attrs[:amount] = amount if amount.present?
+
+          attrs[:external_data] = (payment_session.external_data || {}).merge(external_data.stringify_keys) if external_data.present?
+
+          payment_session.update!(attrs) if attrs.any?
+        end
+
+        ##
+        # Captures the PayPal order and creates the Spree payment.
+        #
+        # Does not complete the order — that is handled by Carts::Complete.
+        #
+        # @param payment_session [Spree::PaymentSessions::PaypalMerchant]
+        # @param params [Hash]
+        # @return [void]
+        #
+        def complete_payment_session(payment_session:, **_unused)
+          paypal_order_id = payment_session.external_id
+          lookup = { 'id' => paypal_order_id, 'prefer' => 'return=representation' }
+
+          fetched = client.orders.get_order(lookup)
+          response =
+            if fetched.data.status == 'COMPLETED'
+              fetched
+            else
+              ensure_amount_matches!(payment_session, fetched)
+              client.orders.capture_order(lookup)
+            end
+
+          payment_session.update!(external_data: response.data.as_json)
+
+          payment_session.order.with_lock do
+            if response.data.status == 'COMPLETED'
+              payment_session.process if payment_session.can_process?
+
+              payment = payment_session.find_or_create_payment!
+
+              if payment.present? && !payment.completed?
+                payment.started_processing! if payment.checkout?
+                payment.complete! if payment.can_complete?
+              end
+
+              create_profile(payment) if payment&.source.present?
+
+              payment_session.complete unless payment_session.completed?
+            elsif payment_session.can_fail?
+              payment_session.fail
+            end
+          end
+        rescue PaypalServerSdk::APIException => e
+          payment_session.fail if payment_session.can_fail?
+          raise Spree::Core::GatewayError, "PayPal API error: #{e.message}"
+        end
+
+        ##
+        # Parses an incoming PayPal webhook into a payment-session action.
+        #
+        # @param raw_body [String]
+        # @param headers [Hash]
+        # @return [Hash, NilClass]
+        #
+        def parse_webhook_event(raw_body, headers)
+          verify_webhook_signature!(raw_body, headers)
+
+          event = JSON.parse(raw_body).with_indifferent_access
+          event_type = event[:event_type]
+          resource = event[:resource] || {}
+
+          paypal_order_id = extract_order_id_from_webhook(event_type, resource)
+          return nil unless paypal_order_id
+
+          payment_session = Spree::PaymentSessions::PaypalMerchant.find_by(
+            payment_method: self,
+            external_id: paypal_order_id
+          )
+          return nil unless payment_session
+
+          case event_type
+          when 'CHECKOUT.ORDER.APPROVED'
+            { action: :authorized, payment_session: payment_session, metadata: { paypal_event: event } }
+          when 'PAYMENT.CAPTURE.COMPLETED'
+            { action: :captured, payment_session: payment_session, metadata: { paypal_event: event } }
+          when 'PAYMENT.CAPTURE.DENIED', 'PAYMENT.CAPTURE.DECLINED'
+            { action: :failed, payment_session: payment_session, metadata: { paypal_event: event } }
+          when 'PAYMENT.CAPTURE.REVERSED', 'PAYMENT.CAPTURE.REFUNDED'
+            { action: :canceled, payment_session: payment_session, metadata: { paypal_event: event } }
+          end
+        end
+
+        private
+
+        ##
+        # Refuses to capture a PayPal order whose amount no longer matches what
+        # is due — e.g. a gift card was applied, or the cart changed, after the
+        # PayPal order was created. Capturing would take the stale amount; the
+        # storefront recreates the session instead.
+        #
+        # @raise [Spree::Core::GatewayError]
+        #
+        def ensure_amount_matches!(payment_session, fetched)
+          value = fetched.data.as_json.dig('purchase_units', 0, 'amount', 'value')
+          return if value.blank?
+
+          due = payment_session.order.total_minus_store_credits
+          return if value.to_d == due.to_d
+
+          payment_session.fail if payment_session.can_fail?
+          raise Spree::Core::GatewayError,
+                "PayPal order amount #{value} does not match the amount due #{due}"
+        end
+
+        def extract_order_id_from_webhook(event_type, resource)
+          case event_type
+          when /\ACHECKOUT\.ORDER\./
+            resource['id']
+          when /\APAYMENT\.CAPTURE\./
+            resource.dig('supplementary_data', 'related_ids', 'order_id')
+          end
+        end
+
+        def verify_webhook_signature!(raw_body, headers)
+          if preferred_webhook_secret.blank?
+            return if Rails.env.local?
+
+            raise Spree::PaymentMethod::WebhookSignatureError,
+                  'PayPal webhook_secret is not configured'
+          end
+
+          transmission_id = headers['HTTP_PAYPAL_TRANSMISSION_ID'] || headers['PAYPAL-TRANSMISSION-ID']
+          transmission_time = headers['HTTP_PAYPAL_TRANSMISSION_TIME'] || headers['PAYPAL-TRANSMISSION-TIME']
+          cert_url = headers['HTTP_PAYPAL_CERT_URL'] || headers['PAYPAL-CERT-URL']
+          auth_algo = headers['HTTP_PAYPAL_AUTH_ALGO'] || headers['PAYPAL-AUTH-ALGO']
+          transmission_sig = headers['HTTP_PAYPAL_TRANSMISSION_SIG'] || headers['PAYPAL-TRANSMISSION-SIG']
+
+          raise Spree::PaymentMethod::WebhookSignatureError, 'Missing PayPal webhook headers' unless transmission_id && transmission_sig
+
+          token = obtain_access_token
+
+          uri = URI("#{api_base}/v1/notifications/verify-webhook-signature")
+
+          payload = {
+            auth_algo: auth_algo,
+            cert_url: cert_url,
+            transmission_id: transmission_id,
+            transmission_sig: transmission_sig,
+            transmission_time: transmission_time,
+            webhook_id: preferred_webhook_secret,
+            webhook_event: JSON.parse(raw_body)
+          }
+
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = true
+          http.open_timeout = 5
+          http.read_timeout = 10
+          request = Net::HTTP::Post.new(uri.path, {
+                                          'Content-Type' => 'application/json',
+                                          'Authorization' => "Bearer #{token}"
+                                        })
+          request.body = payload.to_json
+
+          response = http.request(request)
+          raise Spree::PaymentMethod::WebhookSignatureError, "Webhook verification failed: HTTP #{response.code}" unless http_success?(response)
+
+          result = JSON.parse(response.body)
+
+          raise Spree::PaymentMethod::WebhookSignatureError, 'Invalid webhook signature' unless result['verification_status'] == 'SUCCESS'
+        rescue Spree::PaymentMethod::WebhookSignatureError
+          raise
+        rescue Net::OpenTimeout, Net::ReadTimeout, SocketError, JSON::ParserError, Errno::ECONNREFUSED => e
+          raise Spree::PaymentMethod::WebhookSignatureError, "Webhook verification failed: #{e.message}"
+        end
+
+        def obtain_access_token
+          uri = URI("#{api_base}/v1/oauth2/token")
+
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = true
+          http.open_timeout = 5
+          http.read_timeout = 10
+          request = Net::HTTP::Post.new(uri.path, { 'Content-Type' => 'application/x-www-form-urlencoded' })
+          request.basic_auth(preferred_client_id, preferred_client_secret)
+          request.body = 'grant_type=client_credentials'
+
+          response = http.request(request)
+          return nil unless http_success?(response)
+
+          JSON.parse(response.body)['access_token']
+        end
+
+        ##
+        # Short-lived client token for Card Fields. Returns nil on failure.
+        #
+        # @return [String, NilClass]
+        #
+        def generate_client_token
+          token = obtain_access_token
+          return nil if token.blank?
+
+          uri = URI("#{api_base}/v1/identity/generate-token")
+
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = true
+          http.open_timeout = 5
+          http.read_timeout = 10
+          request = Net::HTTP::Post.new(uri.path, {
+                                          'Content-Type' => 'application/json',
+                                          'Accept-Language' => 'en_US',
+                                          'Authorization' => "Bearer #{token}"
+                                        })
+
+          response = http.request(request)
+          return nil unless http_success?(response)
+
+          JSON.parse(response.body)['client_token']
+        rescue Net::OpenTimeout, Net::ReadTimeout, SocketError, JSON::ParserError, Errno::ECONNREFUSED => e
+          Rails.logger.warn("[spree-paypal_merchant] client token generation failed: #{e.message}")
+          nil
+        end
+
+        def api_base
+          preferred_test_mode ? 'https://api-m.sandbox.paypal.com' : 'https://api-m.paypal.com'
+        end
+
+        def http_success?(response)
+          response.code.to_i.between?(200, 299)
+        end
+      end
+    end
+  end
+end