spree-paypal_merchant 5.2.0

data/app/presenters/spree/paypal_merchant/order_presenter.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require 'paypal_server_sdk'
+
+module Spree
+  module PaypalMerchant
+    ##
+    # Builds a PayPal Orders API create-order payload from a Spree order.
+    #
+    # The storefront owns the address: we send `purchase_units[].shipping`
+    # from `order.ship_address` and pin it with `SET_PROVIDED_ADDRESS` so
+    # PayPal does not re-collect it. The amount breakdown sends only
+    # `additional_tax_total` — sending full `tax_total` double-counts
+    # included VAT and trips PayPal `AMOUNT_MISMATCH`.
+    #
+    class OrderPresenter
+      PAYPAL_ITEM_NAME_MAX_LENGTH = 127
+
+      ##
+      # @param order [Spree::Order]
+      # @param amount [Numeric, NilClass] what PayPal should charge; defaults to
+      #   the order total. Less than the total when a gift card or store credit
+      #   pays part of the order.
+      #
+      def initialize(order, amount: nil)
+        @order = order
+        @amount = amount
+      end
+
+      attr_reader :order
+
+      ##
+      # @return [Hash] body ready for `client.orders.create_order`
+      #
+      def to_json(*_args)
+        {
+          'body' => PaypalServerSdk::OrderRequest.new(
+            intent: PaypalServerSdk::CheckoutPaymentIntent::CAPTURE,
+            purchase_units: [purchase_unit],
+            payment_source: payment_source
+          )
+        }
+      end
+
+      private
+
+      def purchase_unit
+        # A gift card or store credit pays part of the order, so the breakdown
+        # and items (which always sum to the full order total) can't describe
+        # what PayPal charges. PayPal accepts an amount on its own.
+        args =
+          if partial_charge?
+            { amount: PaypalServerSdk::AmountWithBreakdown.new(currency_code: order.currency.upcase,
+                                                               value: charge_amount.to_s) }
+          else
+            { amount: amount_with_breakdown, items: items }
+          end
+        args[:shipping] = shipping_details if shipping_details
+
+        PaypalServerSdk::PurchaseUnitRequest.new(**args)
+      end
+
+      def charge_amount
+        @amount.presence || order.total
+      end
+
+      def partial_charge?
+        charge_amount.to_d != order.total.to_d
+      end
+
+      # NOTE: the breakdown only sends additional (non-included) tax — sending
+      # the full tax_total double-counts VAT on tax-inclusive markets and
+      # trips AMOUNT_MISMATCH. Do not change to order.tax_total.
+      def amount_with_breakdown
+        PaypalServerSdk::AmountWithBreakdown.new(
+          currency_code: order.currency.upcase,
+          value: order.total.to_s,
+          breakdown: PaypalServerSdk::AmountBreakdown.new(
+            item_total: paypal_money(order.item_total),
+            shipping: paypal_money(order.ship_total),
+            tax_total: paypal_money(order.additional_tax_total),
+            discount: paypal_money((order.promo_total || 0).abs)
+          )
+        )
+      end
+
+      def paypal_money(amount)
+        PaypalServerSdk::Money.new(
+          currency_code: order.currency.upcase,
+          value: amount.to_s
+        )
+      end
+
+      def items
+        order.line_items.map do |line_item|
+          PaypalServerSdk::Item.new(
+            name: line_item.name.to_s[0...PAYPAL_ITEM_NAME_MAX_LENGTH],
+            unit_amount: paypal_money(line_item.price),
+            quantity: line_item.quantity.to_s,
+            sku: line_item.sku,
+            category: line_item.variant.digital? ? PaypalServerSdk::ItemCategory::DIGITAL_GOODS : PaypalServerSdk::ItemCategory::PHYSICAL_GOODS
+          )
+        end
+      end
+
+      def shipping_details
+        address = order.ship_address
+        return nil if address.blank?
+
+        PaypalServerSdk::ShippingDetails.new(
+          name: PaypalServerSdk::ShippingName.new(full_name: address.full_name),
+          address: PaypalServerSdk::Address.new(
+            country_code: address.country&.iso,
+            address_line_1: address.address1,
+            address_line_2: address.address2.presence,
+            admin_area_2: address.city,
+            admin_area_1: region_code(address),
+            postal_code: address.zipcode
+          )
+        )
+      end
+
+      def region_code(address)
+        address.state&.abbr.presence || address.state_name.presence
+      end
+
+      def payment_source
+        PaypalServerSdk::PaymentSource.new(
+          paypal: PaypalServerSdk::PaypalWallet.new(
+            experience_context: PaypalServerSdk::PaypalWalletExperienceContext.new(
+              brand_name: order.store&.name,
+              shipping_preference: shipping_preference,
+              user_action: PaypalServerSdk::PaypalExperienceUserAction::PAY_NOW
+            )
+          )
+        )
+      end
+
+      def shipping_preference
+        if order.ship_address.present?
+          PaypalServerSdk::PaypalWalletContextShippingPreference::SET_PROVIDED_ADDRESS
+        else
+          PaypalServerSdk::PaypalWalletContextShippingPreference::NO_SHIPPING
+        end
+      end
+    end
+  end
+end

data/app/serializers/spree/api/v3/payment_method_serializer_decorator.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Spree
+  module Api
+    module V3
+      ##
+      # Exposes non-secret payment-method preferences to the storefront.
+      #
+      module PaymentMethodSerializerDecorator
+        def self.prepended(base)
+          base.attribute :public_preferences, &:public_preferences
+        end
+      end
+    end
+  end
+end
+
+Spree::Api::V3::PaymentMethodSerializer.prepend(
+  Spree::Api::V3::PaymentMethodSerializerDecorator
+)

data/app/services/spree/paypal_merchant/capture_order.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Spree
+  module PaypalMerchant
+    ##
+    # Captures a legacy {Order} via the PayPal Orders API and completes
+    # the Spree checkout.
+    #
+    class CaptureOrder
+      ##
+      # @param paypal_order [Spree::PaypalMerchant::Order]
+      #
+      def initialize(paypal_order:)
+        @paypal_order = paypal_order
+        @order = paypal_order.order
+        @gateway = paypal_order.gateway
+        @amount = paypal_order.amount
+      end
+
+      attr_reader :paypal_order, :order, :gateway, :amount
+
+      ##
+      # @return [Spree::PaypalMerchant::Order]
+      #
+      def call
+        return paypal_order if order.completed? || order.canceled?
+
+        gateway_response = gateway.capture(
+          (amount.to_d * 100).to_i,
+          paypal_order.paypal_id,
+          { order_id: order.number }
+        )
+
+        order.with_lock do
+          paypal_order.update!(data: gateway_response.params)
+          paypal_order.create_payment!
+          Spree::Dependencies.checkout_complete_service.constantize.call(order: order)
+        end
+
+        paypal_order
+      end
+    end
+  end
+end

data/app/services/spree/paypal_merchant/create_payment.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Spree
+  module PaypalMerchant
+    ##
+    # Creates the Spree::Payment for a captured legacy PayPal order.
+    #
+    class CreatePayment
+      ##
+      # @param paypal_order [Spree::PaypalMerchant::Order]
+      # @param order [Spree::Order, NilClass]
+      # @param gateway [Spree::PaypalMerchant::Gateway, NilClass]
+      # @param amount [Numeric, NilClass]
+      #
+      def initialize(paypal_order:, order: nil, gateway: nil, amount: nil)
+        @paypal_order = paypal_order
+        @order = order || paypal_order.order
+        @gateway = gateway || paypal_order.gateway
+        @amount = amount || paypal_order.amount
+      end
+
+      ##
+      # @return [Spree::Payment]
+      #
+      def call
+        source = CreateSource.new(
+          paypal_payment_source: paypal_order.payment_source,
+          gateway: gateway,
+          order: order
+        ).call
+
+        payment = order.payments.find_or_initialize_by(
+          payment_method_id: gateway.id,
+          response_code: paypal_order.paypal_payment_id,
+          amount: amount
+        )
+
+        payment.source = source if source.present?
+        payment.state = 'completed'
+        payment.save!
+        payment
+      end
+
+      private
+
+      attr_reader :order, :gateway, :paypal_order, :amount
+    end
+  end
+end

data/app/services/spree/paypal_merchant/create_source.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Spree
+  module PaypalMerchant
+    ##
+    # Builds a {PaymentSources} record from a PayPal Orders `payment_source`.
+    #
+    # PayPal returns one of `paypal`, `apple_pay`, or `card` (Card Fields).
+    # Unknown keys raise so a new wallet is not silently dropped.
+    #
+    class CreateSource
+      ##
+      # @param paypal_payment_source [Hash]
+      # @param gateway [Spree::PaypalMerchant::Gateway]
+      # @param order [Spree::Order, NilClass]
+      # @param user [Spree::User, NilClass]
+      #
+      def initialize(paypal_payment_source:, gateway:, order: nil, user: nil)
+        @paypal_payment_source = paypal_payment_source.with_indifferent_access
+        @gateway = gateway
+        @user = user || order&.user
+        @order = order
+      end
+
+      ##
+      # @return [Spree::PaymentSource]
+      # @raise [ArgumentError] when the payload has no known wallet key
+      #
+      def call
+        if paypal_payment_source.key?(:paypal)
+          create_paypal_source
+        elsif paypal_payment_source[:apple_pay].present?
+          create_apple_pay_source
+        elsif paypal_payment_source[:card].present?
+          create_card_source
+        else
+          raise ArgumentError, "Unsupported PayPal payment source: #{paypal_payment_source.keys.join(', ')}"
+        end
+      end
+
+      private
+
+      attr_reader :gateway, :user, :paypal_payment_source, :order
+
+      def create_paypal_source
+        wallet = paypal_payment_source[:paypal] || {}
+        profile_id = wallet[:account_id].presence || "paypal-#{order&.number || 'guest'}"
+        source = PaymentSources::Paypal.find_or_initialize_by(
+          payment_method: gateway,
+          gateway_payment_profile_id: profile_id
+        )
+        source.update!(
+          user: user,
+          email: wallet[:email_address],
+          name: full_name(wallet[:name]),
+          account_id: wallet[:account_id],
+          account_status: wallet[:account_status]
+        )
+        source
+      end
+
+      def create_apple_pay_source
+        wallet = paypal_payment_source[:apple_pay]
+        card = wallet[:card] || {}
+        profile_id = wallet[:id].presence ||
+                     wallet[:token].presence ||
+                     ['applepay', card[:brand], card[:last_digits]].compact.join('-')
+
+        source = PaymentSources::ApplePay.find_or_initialize_by(
+          payment_method: gateway,
+          gateway_payment_profile_id: profile_id
+        )
+        source.update!(
+          user: user,
+          name: full_name(wallet[:name]).presence || wallet[:name],
+          email: wallet[:email_address],
+          card_brand: card[:brand],
+          last_digits: card[:last_digits],
+          card_type: card[:type]
+        )
+        source
+      end
+
+      def create_card_source
+        card = paypal_payment_source[:card]
+        profile_id = card[:id].presence || ['card', card[:brand], card[:last_digits]].compact.join('-')
+
+        source = PaymentSources::Card.find_or_initialize_by(
+          payment_method: gateway,
+          gateway_payment_profile_id: profile_id
+        )
+        source.update!(
+          user: user,
+          name: card[:name],
+          card_brand: card[:brand],
+          last_digits: card[:last_digits],
+          card_type: card[:type]
+        )
+        source
+      end
+
+      def full_name(name)
+        return name if name.is_a?(String)
+        return '' if name.blank?
+
+        "#{name[:given_name]} #{name[:surname]}".strip
+      end
+    end
+  end
+end

data/app/views/spree/admin/payment_methods/configuration_guides/_spree_paypal_merchant.html.erb

@@ -0,0 +1,17 @@
+<div class="alert alert-info">
+  <p class="mb-0">
+    To find your <strong>Client ID</strong> and <strong>Client Secret</strong>, go to the
+    <%= external_link_to 'PayPal Developer Dashboard', 'https://developer.paypal.com/dashboard/', class: 'alert-link' %>.
+    For more information, see the <%= external_link_to 'PayPal REST API documentation', 'https://developer.paypal.com/api/rest/', class: 'alert-link' %>.
+  </p>
+</div>
+
+<div class="alert alert-info mt-3">
+  <p class="mb-0">
+    <strong>Apple Pay</strong> is a funding source of this same PayPal method, not a second payment method.
+    Register every storefront domain that will show the Apple Pay button in the
+    <%= external_link_to 'PayPal Apple Pay domain registration', 'https://developer.paypal.com/docs/checkout/apm/apple-pay/', class: 'alert-link' %>
+    dashboard. Use the checkboxes below to offer Card Fields and Apple Pay
+    on the storefront. The Apple Pay button only renders in Safari over HTTPS.
+  </p>
+</div>

data/app/views/spree/admin/payment_methods/descriptions/_spree_paypal_merchant.html.erb

@@ -0,0 +1,10 @@
+<p class="mb-1">
+  PayPal Checkout: wallet, Pay Later, Apple Pay, and Card Fields on one payment method.
+</p>
+
+<div class="d-flex align-items-center">
+  <%= payment_method_icon_tag 'paypal', class: 'm-1' %>
+  <%= payment_method_icon_tag 'visa', class: 'm-1' %>
+  <%= payment_method_icon_tag 'master', class: 'm-1' %>
+  <%= payment_method_icon_tag 'apple_pay', class: 'm-1' %>
+</div>

data/app/views/spree/admin/payments/source_forms/_spree_paypal_merchant.html.erb

@@ -0,0 +1,7 @@
+<% if previous_cards.any? %>
+  <%= render 'spree/admin/payments/source_forms/previous_cards', previous_cards: previous_cards, f: f %>
+<% else %>
+  <span class="text-gray-600">
+    <%= Spree.t(:no_payment_sources_available, default: 'No saved PayPal accounts available.') %>
+  </span>
+<% end %>

data/app/views/spree/payment_sources/_paypal_merchant.html.erb

@@ -0,0 +1,17 @@
+<p class="mb-0">
+  <%= source.try(:display_payment_info) || source.class.try(:display_name) %>
+</p>
+<% if source.respond_to?(:email) && source.email.present? %>
+  <p class="mb-0">
+    <%= source.email %>
+  </p>
+<% end %>
+<% if source.respond_to?(:account_status) && source.account_status.present? %>
+  <p class="mb-0">
+    <% if source.account_status == 'VERIFIED' %>
+      <code class="text-success"><%= source.account_status %></code>
+    <% else %>
+      <code class="text-danger"><%= source.account_status %></code>
+    <% end %>
+  </p>
+<% end %>

data/config/initializers/spree.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Must be after_initialize: spree_core assigns (does not append to)
+# config.spree.payment_methods in its own after_initialize, and a
+# file-scope registration here would be silently clobbered.
+Rails.application.config.after_initialize do
+  Rails.application.config.spree.payment_methods << Spree::PaypalMerchant::Gateway
+end

data/db/migrate/20250528095719_create_spree_paypal_merchant_orders.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+class CreateSpreePaypalMerchantOrders < ActiveRecord::Migration[7.2]
+  def up
+    # A host upgrading from spree-paypal_platform already has the table under
+    # its old name; RenameSpreePaypalPlatformToPaypalMerchant moves it.
+    return if table_exists?(:spree_paypal_platform_orders) || table_exists?(:spree_paypal_merchant_orders)
+
+    create_table :spree_paypal_merchant_orders do |t|
+      t.references :order, null: false
+      t.references :payment_method, null: false
+      t.string :paypal_id, null: false
+      t.decimal :amount, null: false, precision: 10, scale: 2
+
+      if t.respond_to? :jsonb
+        t.jsonb :data
+      else
+        t.json :data
+      end
+
+      t.timestamps
+    end
+
+    add_index :spree_paypal_merchant_orders, %i[order_id paypal_id], unique: true
+    add_index :spree_paypal_merchant_orders, :paypal_id, unique: true
+  end
+
+  def down
+    drop_table :spree_paypal_merchant_orders, if_exists: true
+  end
+end

data/db/migrate/20261003120000_rename_spree_paypal_platform_to_paypal_merchant.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# Upgrades a host from spree-paypal_platform. Renames the orders table (and
+# its default-named indexes) and rewrites stored STI class names, otherwise
+# PaymentMethod.all raises SubclassNotFound. A no-op on a fresh install.
+class RenameSpreePaypalPlatformToPaypalMerchant < ActiveRecord::Migration[7.2]
+  TYPES = {
+    spree_payment_methods: {
+      'Spree::PaypalPlatform::Gateway' => 'Spree::PaypalMerchant::Gateway'
+    },
+    spree_payment_sources: {
+      'Spree::PaypalPlatform::PaymentSources::Paypal' => 'Spree::PaypalMerchant::PaymentSources::Paypal',
+      'Spree::PaypalPlatform::PaymentSources::ApplePay' => 'Spree::PaypalMerchant::PaymentSources::ApplePay',
+      'Spree::PaypalPlatform::PaymentSources::Card' => 'Spree::PaypalMerchant::PaymentSources::Card'
+    },
+    spree_payment_sessions: {
+      'Spree::PaymentSessions::PaypalPlatform' => 'Spree::PaymentSessions::PaypalMerchant'
+    }
+  }.freeze
+
+  def up
+    if table_exists?(:spree_paypal_platform_orders) && !table_exists?(:spree_paypal_merchant_orders)
+      rename_table :spree_paypal_platform_orders, :spree_paypal_merchant_orders
+    end
+
+    TYPES.each { |table, mapping| rewrite(table, mapping) }
+  end
+
+  def down
+    if table_exists?(:spree_paypal_merchant_orders) && !table_exists?(:spree_paypal_platform_orders)
+      rename_table :spree_paypal_merchant_orders, :spree_paypal_platform_orders
+    end
+
+    TYPES.each { |table, mapping| rewrite(table, mapping.invert) }
+  end
+
+  private
+
+  def rewrite(table, mapping)
+    return unless table_exists?(table) && column_exists?(table, :type)
+
+    mapping.each do |from, to|
+      execute "UPDATE #{table} SET type = #{quote(to)} WHERE type = #{quote(from)}"
+    end
+  end
+end

data/lib/generators/spree/paypal_merchant/install/install_generator.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Spree
+  module PaypalMerchant
+    module Generators
+      ##
+      # Copies this gem's migrations into the host app and optionally runs them.
+      #
+      class InstallGenerator < Rails::Generators::Base
+        desc 'Copies Spree::PaypalMerchant migrations into the host application and runs them.'
+
+        class_option :auto_run_migrations,
+                     type: :boolean,
+                     default: false,
+                     desc: 'Run the copied migrations immediately instead of asking'
+
+        def copy_migrations
+          rake 'spree_paypal_merchant:install:migrations'
+        end
+
+        def run_migrations
+          if run_migrations?
+            rake 'db:migrate'
+          else
+            say_status :skip, 'db:migrate — remember to run it before using the gem', :yellow
+          end
+        end
+
+        private
+
+        def run_migrations?
+          return true if options[:auto_run_migrations]
+
+          ask('Run the migrations now? [Yn]').to_s.strip.casecmp('n') != 0
+        end
+      end
+    end
+  end
+end

data/lib/spree/paypal_merchant/engine.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Spree
+  module PaypalMerchant
+    ##
+    # Rails engine for the PayPal Checkout payment method.
+    #
+    class Engine < ::Rails::Engine
+      require 'spree/core'
+      isolate_namespace Spree
+
+      # Decorators reopen existing constants, so Zeitwerk must not autoload them.
+      initializer 'spree_paypal_merchant.ignore_decorators_from_zeitwerk', before: :setup_main_autoloader do
+        Rails.autoloaders.main.ignore(
+          File.join(File.dirname(__FILE__), '../../../app/**/*_decorator*.rb')
+        )
+      end
+
+      # engine_name generates route-helper prefixes and must be a valid Ruby
+      # identifier, so it cannot contain a dash.
+      engine_name 'spree_paypal_merchant'
+
+      config.generators do |g|
+        g.test_framework :rspec
+      end
+
+      ##
+      # Loads the gem's decorators. Called on every reload in development.
+      #
+      # @return [void]
+      #
+      def self.activate
+        Dir.glob(File.join(File.dirname(__FILE__), '../../../app/**/*_decorator*.rb')).each do |c|
+          Rails.configuration.cache_classes ? require(c) : load(c)
+        end
+      end
+
+      config.to_prepare(&method(:activate).to_proc)
+    end
+  end
+end

data/lib/spree/paypal_merchant/factories.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+FactoryBot.define do
+  factory :paypal_merchant_gateway, class: 'Spree::PaypalMerchant::Gateway' do
+    name { 'PayPal Checkout' }
+    association :store, factory: :store
+    preferences do
+      {
+        client_id: ENV.fetch('PAYPAL_CLIENT_ID', 'client_id_test'),
+        client_secret: ENV.fetch('PAYPAL_CLIENT_SECRET', 'client_secret_test'),
+        test_mode: true,
+        enable_apple_pay: true,
+        enable_card_fields: true
+      }
+    end
+  end
+
+  factory :paypal_merchant_payment_source, class: 'Spree::PaypalMerchant::PaymentSources::Paypal' do
+    association :payment_method, factory: :paypal_merchant_gateway
+    gateway_payment_profile_id { 'PAY-CUSTOMER-ID' }
+  end
+
+  factory :paypal_merchant_apple_pay_source, class: 'Spree::PaypalMerchant::PaymentSources::ApplePay' do
+    association :payment_method, factory: :paypal_merchant_gateway
+    gateway_payment_profile_id { 'APPLEPAY-TOKEN-1' }
+    card_brand { 'VISA' }
+    last_digits { '4242' }
+  end
+
+  factory :paypal_merchant_payment_session, class: 'Spree::PaymentSessions::PaypalMerchant' do
+    association :order, factory: :order
+    association :payment_method, factory: :paypal_merchant_gateway
+    amount { order.total }
+    currency { order.currency }
+    status { 'pending' }
+    external_id { "PAYPAL-ORDER-#{SecureRandom.hex(8).upcase}" }
+    external_data do
+      JSON.parse(File.read(Spree::PaypalMerchant::Engine.root.join('spec/fixtures/paypal_order.json')))
+    end
+
+    factory :completed_paypal_merchant_payment_session do
+      status { 'completed' }
+      external_data do
+        JSON.parse(File.read(Spree::PaypalMerchant::Engine.root.join('spec/fixtures/captured_paypal_order.json')))
+      end
+    end
+  end
+
+  factory :paypal_merchant_order, class: 'Spree::PaypalMerchant::Order' do
+    paypal_id { 'PAY-ORDER-ID' }
+    order { create(:order) }
+    payment_method { create(:paypal_merchant_gateway) }
+    amount { order.total }
+    data { JSON.parse(File.read(Spree::PaypalMerchant::Engine.root.join('spec/fixtures/paypal_order.json'))) }
+
+    factory :captured_paypal_merchant_order do
+      data { JSON.parse(File.read(Spree::PaypalMerchant::Engine.root.join('spec/fixtures/captured_paypal_order.json'))) }
+    end
+  end
+end

data/lib/spree/paypal_merchant/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Spree
+  module PaypalMerchant
+    # Major version tracks Spree's major version: 5.x supports Spree 5.x.
+    VERSION = '5.2.0'
+  end
+end