spree-paypal_platform 5.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a661dd4e40e71d2cba0a11105489d4eecce8bbc75936fc8213ce3508903ea8b2
+  data.tar.gz: 3323ef46afcd1734d213c672f743ee6d1f7e4eb7580a6d5facfb034bb252001d
+SHA512:
+  metadata.gz: f050fe6366417de127b12e0d3f1ef4cce790b79a985d1fb16ff7d27486dfb3fbdb97badb6fee18caa0ccf022dc8d54b51c5e1a6bc959fb981dc3558acf4ee933
+  data.tar.gz: 81552556697e34abd82667c5ca6950a147d674f47a0c3ce96b698788ebee690624a8941130a1586adda3c34cc434825f71e05e5cbff31e4e9f38667db860d067

data/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## 5.0.1
+
+Published name is **`spree-paypal_platform`**. RubyGems rejected
+`spree-paypal_checkout` as too similar to the official
+`spree_paypal_checkout`. Require path and constants are unchanged
+(`spree/paypal_checkout` → `Spree::PaypalCheckout`).
+
+## 5.0.0
+
+First Aypex release. Intended published name `spree-paypal_checkout` was
+never accepted by RubyGems; see 5.0.1.
+
+### Audit follow-up
+
+- Do not log PayPal request bodies; client logging is WARN without bodies/headers.
+- Webhook verify now checks HTTP status and is specced for signed and unsigned paths.
+- `#authorize` raises `NotImplementedError`.
+- `#void` / `#credit` / `#cancel` specs restored; `CaptureOrder` no longer uses the `money` gem.
+- Unique index on `spree_paypal_checkout_orders.paypal_id`.
+- Payment sources share `#display_payment_info`; OAuth/token HTTP responses must be 2xx.
+
+- Port of the `aypex-io/spree_paypal_checkout` `tongkat-fitness` fork into
+  `Spree::PaypalCheckout`, published as `spree-paypal_checkout`.
+- Store API v3 payment sessions only. No `/api/v2/storefront/paypal_orders`.
+- Official `paypal-server-sdk` `~> 2.3`.
+- Apple Pay and Card Fields recorded as payment sources on the same gateway.
+- Keeps the VAT `AMOUNT_MISMATCH` guard (additional tax only) and
+  `SET_PROVIDED_ADDRESS` storefront-owned shipping.
+- STI alias + rewrite migration for hosts coming from
+  `SpreePaypalCheckout::Gateway`.

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,117 @@
+# spree-paypal_platform
+
+PayPal Checkout for Spree 5.6+, as a single payment method covering the PayPal
+wallet, Apple Pay, and Card Fields.
+
+This is Aypex's own gem, **published as `spree-paypal_platform`**. It is **not**
+the official `spree_paypal_checkout` gem. RubyGems treats `-` and `_` as the
+same name, so `spree-paypal_checkout` was rejected as too similar. The GitHub
+repo is `aypex-io/spree-paypal_platform`; `require "spree/paypal_checkout"`
+and `Spree::PaypalCheckout` are unchanged.
+
+It started from that official extension (including the VAT `AMOUNT_MISMATCH`
+fix and storefront-owned address) and adds Apple Pay as a funding source of
+the same gateway.
+
+## What it is
+
+- One `Spree::PaypalCheckout::Gateway` payment method.
+- Checkout goes through Spree's **Store API v3 payment sessions**
+  (`POST /api/v3/store/carts/:id/payment_sessions` → complete). There is no
+  legacy `/api/v2/storefront/paypal_orders` controller.
+- 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. Extra PayPal
+wallets (Venmo, Google Pay, …) should follow the same pattern.
+
+## Installation
+
+```ruby
+gem 'spree-paypal_platform'
+```
+
+```bash
+bundle install
+bin/rails g spree:paypal_checkout: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` | Advertise Apple Pay to headless storefronts (default on) |
+| `apple_pay_domain` | Domain registered with PayPal for Apple Pay |
+
+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. Unregistered domains are rejected by Apple.
+3. Headless storefronts load the PayPal JS SDK with `components=applepay`
+   (or `buttons,applepay,card-fields`) and render Apple's `ApplePaySession`.
+   The gem records the captured `payment_source.apple_pay` as
+   `Spree::PaypalCheckout::PaymentSources::ApplePay`.
+4. Safari + HTTPS only. `localhost` will not work; use a public HTTPS tunnel
+   for local testing.
+
+This gem does not ship a Next.js / Stimulus Apple Pay button. The TKF
+storefront already owns the wallet and Card Fields UI; Apple Pay belongs
+there, next to `FUNDING.PAYPAL`.
+
+## Coming from `spree_paypal_checkout`
+
+Existing `spree_payment_methods.type` rows store
+`SpreePaypalCheckout::Gateway`. This gem aliases that constant, so checkout
+keeps working before you migrate. The install generator also copies a
+rewrite migration that updates those STI strings to
+`Spree::PaypalCheckout::Gateway`.
+
+Replace the GitHub pin:
+
+```ruby
+# before
+gem 'spree_paypal_checkout', github: 'aypex-io/spree_paypal_checkout', branch: 'tongkat-fitness'
+
+# after
+gem 'spree-paypal_platform'
+```
+
+Then run the install generator and bump the storefront's
+`resolveGatewayId` map if it still keys on `paypal_checkout` /
+`SpreePaypalCheckout::Gateway` — both still resolve if you keep the old
+keys, because the gateway's `api_type` becomes `paypal_checkout` either way
+(`Spree::PaypalCheckout::Gateway` → `paypal_checkout`).
+
+## 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_checkout'
+  ENV['DB'] ||= 'postgres'
+  Rake::Task['extension:test_app'].execute(install_storefront: true, install_admin: true)
+end

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

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Spree
+  class PaymentSessions::PaypalCheckout < 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::PaypalCheckout::CreateSource.new(
+        paypal_payment_source: paypal_payment_source,
+        gateway: payment_method,
+        order: order
+      ).call
+    end
+  end
+end

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

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

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

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+
+require 'net/http'
+
+module Spree
+  module PaypalCheckout
+    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::PaypalCheckout
+        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::PaypalCheckout, 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)
+            paypal_response = client.orders.create_order(order_presenter.to_json)
+
+            session_data = paypal_response.data.as_json
+
+            client_token = generate_client_token
+            session_data['client_token'] = client_token if client_token.present?
+
+            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::PaypalCheckout]
+        # @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::PaypalCheckout]
+        # @param params [Hash]
+        # @return [void]
+        #
+        def complete_payment_session(payment_session:, **_unused)
+          paypal_order_id = payment_session.external_id
+
+          response = client.orders.capture_order({
+                                                   'id' => paypal_order_id,
+                                                   'prefer' => 'return=representation'
+                                                 })
+
+          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::PaypalCheckout.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
+
+        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_platform] 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