spree-paypal_platform 5.0.1

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

@@ -0,0 +1,309 @@
+# frozen_string_literal: true
+
+require 'net/http'
+
+module Spree
+  module PaypalCheckout
+    ##
+    # PayPal Checkout payment method.
+    #
+    # One method covers the PayPal wallet, Apple Pay, and Card Fields. Extra
+    # wallets are recorded as {PaymentSources} on the same gateway rather than
+    # as separate payment methods.
+    #
+    class Gateway < ::Spree::Gateway
+      include PaymentSessions
+
+      GatewayResponse = Struct.new(:success, :message, :params, :authorization) do
+        alias_method :success?, :success
+      end
+
+      preference :client_id, :string
+      preference :client_secret, :password
+      preference :webhook_secret, :string
+      preference :test_mode, :boolean, default: true
+      preference :enable_apple_pay, :boolean, default: true
+      preference :apple_pay_domain, :string
+
+      validates :preferred_client_id, :preferred_client_secret, presence: true
+
+      ##
+      # @return [Class]
+      #
+      def provider_class
+        self.class
+      end
+
+      ##
+      # Default source class for admin "previous cards" lookups. Actual
+      # captured payments may also be {PaymentSources::ApplePay} or
+      # {PaymentSources::Card}.
+      #
+      # @return [Class]
+      #
+      def payment_source_class
+        PaymentSources::Paypal
+      end
+
+      ##
+      # @return [TrueClass]
+      #
+      def payment_profiles_supported?
+        true
+      end
+
+      ##
+      # @return [String]
+      #
+      def default_name
+        'PayPal'
+      end
+
+      ##
+      # @return [String]
+      #
+      def method_type
+        'spree_paypal_checkout'
+      end
+
+      ##
+      # @return [String]
+      #
+      def payment_icon_name
+        'paypal'
+      end
+
+      ##
+      # @return [String]
+      #
+      def description_partial_name
+        'spree_paypal_checkout'
+      end
+
+      ##
+      # @return [String]
+      #
+      def configuration_guide_partial_name
+        'spree_paypal_checkout'
+      end
+
+      ##
+      # @return [String]
+      #
+      def source_partial_name
+        'paypal_checkout'
+      end
+
+      ##
+      # Whether the storefront should offer Apple Pay for this method.
+      #
+      # Domain registration with PayPal is still required; this flag only
+      # advertises the capability.
+      #
+      # @return [TrueClass, FalseClass]
+      #
+      def apple_pay_enabled?
+        preferred_enable_apple_pay
+      end
+
+      ##
+      # @return [String, NilClass]
+      #
+      def webhook_url
+        return nil unless store
+
+        "#{store.url_or_custom_domain}/api/v3/webhooks/payments/#{prefixed_id}"
+      end
+
+      ##
+      # Persist a gateway-customer profile for a signed-in buyer.
+      #
+      # @param payment [Spree::Payment]
+      # @return [Spree::GatewayCustomer, NilClass]
+      #
+      def create_profile(payment)
+        user = payment.order.user
+        return if user.blank?
+        return if payment.source.blank?
+        return unless payment.source.is_a?(PaymentSources::Paypal)
+
+        paypal_account_id = payment.source.account_id
+        return if paypal_account_id.blank?
+
+        payment.payment_method.gateway_customers.find_or_create_by(user: user, profile_id: paypal_account_id)
+      end
+
+      ##
+      # @return [PaypalServerSdk::Client]
+      #
+      def client
+        @client ||= PaypalServerSdk::Client.new(
+          client_credentials_auth_credentials: PaypalServerSdk::ClientCredentialsAuthCredentials.new(
+            o_auth_client_id: preferred_client_id,
+            o_auth_client_secret: preferred_client_secret
+          ),
+          environment: preferred_test_mode ? PaypalServerSdk::Environment::SANDBOX : PaypalServerSdk::Environment::PRODUCTION,
+          logging_configuration: PaypalServerSdk::LoggingConfiguration.new(
+            log_level: Logger::WARN,
+            request_logging_config: PaypalServerSdk::RequestLoggingConfiguration.new(
+              log_body: false
+            ),
+            response_logging_config: PaypalServerSdk::ResponseLoggingConfiguration.new(
+              log_headers: false
+            )
+          )
+        )
+      end
+
+      ##
+      # @raise [NotImplementedError] always — authorize-then-capture is unused
+      #
+      def authorize(_amount_in_cents, _payment_source, _gateway_options = {})
+        raise NotImplementedError, 'PayPal Checkout captures in one step; use #purchase'
+      end
+
+      ##
+      # Purchase is authorize + capture in one step.
+      #
+      # @param amount_in_cents [Integer]
+      # @param payment_source [#paypal_id]
+      # @param gateway_options [Hash]
+      # @return [GatewayResponse]
+      #
+      def purchase(amount_in_cents, payment_source, gateway_options = {})
+        capture(amount_in_cents, payment_source.paypal_id, gateway_options)
+      end
+
+      ##
+      # Capture a previously created PayPal order.
+      #
+      # @param amount_in_cents [Integer]
+      # @param paypal_id [String] PayPal order ID
+      # @param gateway_options [Hash]
+      # @return [GatewayResponse]
+      #
+      def capture(_amount_in_cents, paypal_id, gateway_options = {})
+        protect_from_error do
+          order = find_order(gateway_options[:order_id])
+          return failure('Order not found') unless order
+
+          response = client.orders.capture_order({
+                                                   'id' => paypal_id,
+                                                   'prefer' => 'return=representation'
+                                                 })
+
+          if response.data.status == 'COMPLETED'
+            success(response.data.id, response.data.as_json)
+          else
+            failure('Failed to capture PayPal payment', response.data)
+          end
+        end
+      end
+
+      ##
+      # Void a PayPal authorization.
+      #
+      # @param authorization [String]
+      # @param _source [Object]
+      # @param gateway_options [Hash]
+      # @return [GatewayResponse]
+      #
+      def void(authorization, _source, _gateway_options = {})
+        protect_from_error do
+          response = client.payments.void_payment({
+                                                    'authorization_id' => authorization,
+                                                    'prefer' => 'return=representation'
+                                                  })
+
+          success(authorization, response.data.as_json)
+        end
+      end
+
+      ##
+      # Refund a captured PayPal payment.
+      #
+      # @param amount_in_cents [Integer]
+      # @param _payment_source [Object]
+      # @param paypal_payment_id [String]
+      # @param gateway_options [Hash]
+      # @return [GatewayResponse]
+      #
+      def credit(amount_in_cents, _payment_source, paypal_payment_id, gateway_options = {})
+        refund_originator = gateway_options[:originator]
+        order = refund_originator.respond_to?(:order) ? refund_originator.order : refund_originator
+
+        return failure('Order not found') unless order
+
+        protect_from_error do
+          payload = {
+            capture_id: paypal_payment_id,
+            amount: {
+              value: (amount_in_cents / 100.0).to_s,
+              currency_code: order.currency.upcase
+            }
+          }.deep_stringify_keys
+
+          response = client.payments.refund_captured_payment(payload)
+
+          success(response.data.id, response.data.as_json)
+        end
+      end
+
+      ##
+      # Cancel a payment: refund if captured, otherwise void.
+      #
+      # @param authorization [String]
+      # @param payment [Spree::Payment, NilClass]
+      # @return [GatewayResponse]
+      #
+      def cancel(authorization, payment = nil)
+        protect_from_error do
+          if payment&.completed?
+            amount = payment.credit_allowed
+            return success(authorization, {}) if amount.zero?
+
+            refund = payment.refunds.create!(
+              amount: amount,
+              reason: Spree::RefundReason.order_canceled_reason,
+              refunder_id: payment.order.canceler_id
+            )
+
+            success(payment.response_code, refund.response.params)
+          else
+            response = client.payments.void_payment({
+                                                      'authorization_id' => authorization,
+                                                      'prefer' => 'return=representation'
+                                                    })
+
+            success(authorization, response.data.as_json)
+          end
+        end
+      end
+
+      private
+
+      def find_order(order_id)
+        return nil unless order_id
+
+        order_number, _payment_number = order_id.split('-')
+        Spree::Order.find_by(number: order_number)
+      end
+
+      def protect_from_error
+        yield
+      rescue PaypalServerSdk::APIException => e
+        raise Spree::Core::GatewayError, "PayPal API error: #{e.message}"
+      rescue Net::OpenTimeout, Net::ReadTimeout, SocketError, Errno::ECONNREFUSED => e
+        raise Spree::Core::GatewayError, "PayPal connection error: #{e.message}"
+      end
+
+      def success(authorization, response)
+        GatewayResponse.new(true, 'Transaction successful', response, authorization)
+      end
+
+      def failure(message, response = {})
+        GatewayResponse.new(false, message, response, nil)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Spree
+  module PaypalCheckout
+    ##
+    # A persisted PayPal Orders API response, used by the legacy
+    # `/api/v2/storefront/paypal_orders` flow.
+    #
+    # Payment-session hosts do not write this table; they keep the same
+    # payload on `Spree::PaymentSession#external_data`.
+    #
+    class Order < Base
+      class NotCapturedError < StandardError; end
+      class AlreadyCapturedError < StandardError; end
+
+      belongs_to :order, class_name: 'Spree::Order'
+      belongs_to :payment_method, class_name: 'Spree::PaymentMethod'
+      alias gateway payment_method
+
+      before_validation :set_amount_from_order, on: :create
+
+      validates :paypal_id, presence: true, uniqueness: true
+      validates :data, presence: true
+      validates :amount, numericality: { greater_than: 0 }, presence: true
+
+      store_accessor :data, :payer, :purchase_units, :payment_source, :status
+
+      ##
+      # Create a Spree::Payment for this captured PayPal order.
+      #
+      # @return [Spree::Payment]
+      # @raise [NotCapturedError] when the PayPal order is not COMPLETED
+      #
+      def create_payment!
+        raise NotCapturedError unless completed?
+
+        CreatePayment.new(
+          order: order,
+          paypal_order: self,
+          gateway: payment_method,
+          amount: amount
+        ).call
+      end
+
+      ##
+      # Capture the PayPal order via the Orders API.
+      #
+      # @return [Spree::PaypalCheckout::Order]
+      # @raise [AlreadyCapturedError] when already COMPLETED
+      #
+      def capture!
+        raise AlreadyCapturedError if completed?
+
+        CaptureOrder.new(paypal_order: self).call
+      end
+
+      ##
+      # Capture ID from the stored payload. Only present after capture.
+      #
+      # @return [String, NilClass]
+      #
+      def paypal_payment_id
+        @paypal_payment_id ||= data.dig('purchase_units', 0, 'payments', 'captures', 0, 'id')
+      end
+
+      ##
+      # Fresh PayPal order from the API.
+      #
+      # @return [PaypalServerSdk::ApiResponse]
+      #
+      def paypal_order
+        @paypal_order ||= gateway.client.orders.get_order({ 'id' => paypal_id })
+      end
+
+      ##
+      # @return [TrueClass, FalseClass]
+      #
+      def completed?
+        status == 'COMPLETED'
+      end
+
+      private
+
+      def set_amount_from_order
+        self.amount ||= order&.total
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Spree
+  module PaypalCheckout
+    ##
+    # Adds the legacy PayPal-order association onto {Spree::Order}.
+    #
+    module OrderDecorator
+      ##
+      # @param base [Class]
+      # @return [void]
+      #
+      def self.prepended(base)
+        base.store_accessor :private_metadata, :paypal_id
+        base.has_many :paypal_checkout_orders,
+                      class_name: 'Spree::PaypalCheckout::Order',
+                      dependent: :destroy,
+                      foreign_key: :order_id
+      end
+    end
+  end
+end
+
+Spree::Order.prepend(Spree::PaypalCheckout::OrderDecorator)

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Spree
+  module PaypalCheckout
+    ##
+    # Adds a paypal_checkout scope and predicate onto {Spree::PaymentMethod}.
+    #
+    module PaymentMethodDecorator
+      ##
+      # @param base [Class]
+      # @return [void]
+      #
+      def self.prepended(base)
+        base.scope :paypal_checkout, lambda {
+          where(type: Spree::PaypalCheckout.gateway_type_names)
+        }
+      end
+
+      ##
+      # @return [TrueClass, FalseClass]
+      #
+      def paypal_checkout?
+        Spree::PaypalCheckout.gateway_type_names.include?(type)
+      end
+    end
+  end
+end
+
+Spree::PaymentMethod.prepend(Spree::PaypalCheckout::PaymentMethodDecorator)

data/app/models/spree/paypal_checkout/payment_sources/apple_pay.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Spree
+  module PaypalCheckout
+    module PaymentSources
+      ##
+      # An Apple Pay wallet used through PayPal Checkout.
+      #
+      # PayPal returns `payment_source.apple_pay` on the captured order.
+      # The card brand / last digits (when present) are stored so admin
+      # can show "Apple Pay · Visa 4242" rather than a bare wallet name.
+      #
+      class ApplePay < ::Spree::PaymentSource
+        store_accessor :private_metadata,
+                       :card_brand,
+                       :last_digits,
+                       :card_type,
+                       :name,
+                       :email
+
+        ##
+        # @return [Array<String>]
+        #
+        def actions
+          %w[credit void]
+        end
+
+        ##
+        # @return [String]
+        #
+        def self.display_name
+          'Apple Pay'
+        end
+
+        ##
+        # Human-readable wallet line for admin and order emails.
+        #
+        # @return [String]
+        #
+        def display_payment_info
+          parts = ['Apple Pay']
+          parts << card_brand.to_s.titleize if card_brand.present?
+          parts << last_digits if last_digits.present?
+          parts.join(' · ')
+        end
+      end
+    end
+  end
+end

data/app/models/spree/paypal_checkout/payment_sources/card.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Spree
+  module PaypalCheckout
+    module PaymentSources
+      ##
+      # An Advanced Credit and Debit Card (Card Fields) payment.
+      #
+      class Card < ::Spree::PaymentSource
+        store_accessor :private_metadata,
+                       :card_brand,
+                       :last_digits,
+                       :card_type,
+                       :name
+
+        ##
+        # @return [Array<String>]
+        #
+        def actions
+          %w[credit void]
+        end
+
+        ##
+        # @return [String]
+        #
+        def self.display_name
+          'Card'
+        end
+
+        ##
+        # Human-readable card line for admin and order emails.
+        #
+        # @return [String]
+        #
+        def display_payment_info
+          parts = [card_brand.to_s.titleize.presence, last_digits].compact
+          parts.join(' · ').presence || 'Card'
+        end
+      end
+    end
+  end
+end

data/app/models/spree/paypal_checkout/payment_sources/paypal.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Spree
+  module PaypalCheckout
+    module PaymentSources
+      ##
+      # A PayPal wallet account captured as a Spree payment source.
+      #
+      class Paypal < ::Spree::PaymentSource
+        store_accessor :private_metadata, :email, :name, :account_status, :account_id
+
+        ##
+        # @return [Array<String>]
+        #
+        def actions
+          %w[credit void]
+        end
+
+        ##
+        # @return [String]
+        #
+        def self.display_name
+          'PayPal'
+        end
+
+        ##
+        # Human-readable wallet line for admin and order emails.
+        #
+        # @return [String]
+        #
+        def display_payment_info
+          ['PayPal', account_id].compact.join(' · ')
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Spree
+  module PaypalCheckout
+    ##
+    # Looks up the store's active PayPal Checkout gateway.
+    #
+    module StoreDecorator
+      ##
+      # @return [Spree::PaypalCheckout::Gateway, NilClass]
+      #
+      def paypal_checkout_gateway
+        @paypal_checkout_gateway ||= payment_methods.paypal_checkout.active.last
+      end
+    end
+  end
+end
+
+Spree::Store.prepend(Spree::PaypalCheckout::StoreDecorator)