spree_stripe 1.8.2 → 6.0.0.beta1

data/app/models/spree_stripe/gateway/payment_sessions.rb

@@ -1,12 +1,19 @@
 module SpreeStripe
   class Gateway < ::Spree::Gateway
+    # A Stripe payment session is a Stripe payment intent: creating the session
+    # creates the intent, and the session stores its id as the external id.
+    # Intents are Stripe-side API objects — there is no intent record in Spree.
     module PaymentSessions
       extend ActiveSupport::Concern
 
-      # Intent states where nothing has been confirmed yet, so the intent can
-      # safely be handed to another checkout window. Anything further along
-      # means money is already moving and a second intent would double-charge.
-      REUSABLE_INTENT_STATUSES = %w[requires_payment_method requires_confirmation].freeze
+      # Banks confirm these asynchronously, so `processing` is as good as accepted.
+      DELAYED_NOTIFICATION_PAYMENT_METHOD_TYPES = %w[sepa_debit us_bank_account].freeze
+      # Funds arrive out of band, leaving the intent in `requires_action`.
+      BANK_PAYMENT_METHOD_TYPES = %w[customer_balance us_bank_account].freeze
+      # next_action.type Stripe sets while an ACH debit awaits verification.
+      MICRODEPOSIT_VERIFICATION_ACTION = 'verify_with_microdeposits'.freeze
+      MANUAL_CAPTURE_METHOD = 'manual'.freeze
+      SETUP_FUTURE_USAGE = 'off_session'.freeze
 
       def session_required?
         true
@@ -16,45 +23,38 @@ module SpreeStripe
         Spree::PaymentSessions::Stripe
       end
 
-      # Returns the order's reusable pending session (its amount and payment
-      # method brought up to date) or creates a new one. An order gets at most
-      # one unconfirmed Stripe intent at a time: a second checkout window
-      # confirms the same intent — which Stripe rejects once the first one
-      # succeeds — instead of charging a second one.
+      # @param order [Spree::Cart, Spree::Order]
+      # @return [Spree::PaymentSessions::Stripe]
       def create_payment_session(order:, amount: nil, external_data: {})
         total = amount.presence || order.total_minus_store_credits
         amount_in_cents = Spree::Money.new(total, currency: order.currency).cents
 
-        raise Spree::Core::GatewayError, I18n.t('spree.stripe.payment_session_errors.zero_amount') if amount_in_cents.zero?
+        raise Spree::Core::GatewayError, Spree.t('stripe.payment_session_errors.zero_amount') if amount_in_cents.zero?
 
-        reused_session = reuse_payment_session(order, total, external_data)
-        return reused_session if reused_session.present?
-
-        customer = fetch_or_create_customer(order: order)
-        stripe_pm_id = external_data[:stripe_payment_method_id] || external_data['stripe_payment_method_id']
+        gateway_customer = fetch_or_create_customer(order: order)
+        stripe_payment_method_id = external_data[:stripe_payment_method_id] || external_data['stripe_payment_method_id']
 
         response = create_payment_intent(
           amount_in_cents, order,
-          payment_method_id: stripe_pm_id,
-          customer_profile_id: customer&.profile_id
+          payment_method_id: stripe_payment_method_id,
+          customer_profile_id: gateway_customer&.profile_id
         )
 
-        ephemeral_key_response = create_ephemeral_key(customer.profile_id) if customer.present?
-        ephemeral_key_secret = ephemeral_key_response&.params&.dig('secret')
+        ephemeral_key_response = create_ephemeral_key(gateway_customer.profile_id) if gateway_customer.present?
 
         payment_session_class.create!(
-          order: order,
+          owner: order,
           payment_method: self,
           amount: total,
           currency: order.currency,
           status: 'pending',
           external_id: response.authorization,
-          customer: order.user,
-          customer_external_id: customer&.profile_id,
+          customer: order.customer,
+          customer_external_id: gateway_customer&.profile_id,
           external_data: {
             'client_secret' => response.params['client_secret'],
-            'ephemeral_key_secret' => ephemeral_key_secret,
-            'stripe_payment_method_id' => stripe_pm_id
+            'ephemeral_key_secret' => ephemeral_key_response&.params&.dig('secret'),
+            'stripe_payment_method_id' => stripe_payment_method_id
           }.compact
         )
       end
@@ -68,145 +68,258 @@ module SpreeStripe
           amount_in_cents = Spree::Money.new(amount, currency: payment_session.currency).cents
         end
 
-        stripe_pm_id = external_data[:stripe_payment_method_id] || external_data['stripe_payment_method_id']
+        stripe_payment_method_id = external_data[:stripe_payment_method_id] || external_data['stripe_payment_method_id']
 
         update_payment_intent(
           payment_session.external_id,
           amount_in_cents || payment_session.amount_in_cents,
-          payment_session.order,
-          stripe_pm_id
+          payment_session.owner,
+          stripe_payment_method_id
         )
 
-        if external_data.present?
-          attrs[:external_data] = (payment_session.external_data || {}).merge(external_data.stringify_keys)
-        end
+        attrs[:external_data] = (payment_session.external_data || {}).merge(external_data.stringify_keys) if external_data.present?
 
         payment_session.update!(attrs) if attrs.any?
       end
 
-      # Completes a payment session by verifying with Stripe, creating the
-      # Payment record, and patching wallet address data.
+      # Verifies the intent with Stripe, creates the Payment record and patches
+      # wallet address data.
       #
-      # Does NOT complete the order — that is handled by Carts::Complete
-      # (called by the storefront or by the webhook handler).
+      # Does NOT complete the order — Carts::Complete owns that.
       def complete_payment_session(payment_session:, params: {})
-        stripe_pi = retrieve_payment_intent(payment_session.external_id)
+        stripe_payment_intent = retrieve_payment_intent(payment_session.external_id)
+
+        unless payment_intent_accepted?(stripe_payment_intent)
+          payment_session.fail if payment_session.can_fail?
+          return payment_session
+        end
 
-        if payment_intent_accepted?(stripe_pi)
-          payment_session.process if payment_session.can_process?
+        payment_session.process if payment_session.can_process?
 
-          charge = payment_session.stripe_charge
+        charge = payment_session.stripe_charge
+        patch_wallet_address(payment_session.owner, charge) if charge.present?
 
-          # Patch wallet billing address (Apple Pay, Google Pay)
-          patch_wallet_address(payment_session.order, charge) if charge.present?
+        # `succeeded` is the only status where funds have moved. The other
+        # accepted statuses — requires_capture (manual capture), processing
+        # (delayed-notification banks), requires_action (bank transfer awaiting
+        # funds) — settle as authorization-only, completed later by webhook or
+        # explicit capture.
+        payment_session.settle_payment!(captured: payment_intent_successful?(stripe_payment_intent))
 
-          # Create the Payment record
-          payment_session.find_or_create_payment!
+        payment_session.complete unless payment_session.completed?
+        payment_session
+      end
 
-          # `else` covers requires_capture (manual capture), processing (delayed-notification
-          # banks), and requires_action (bank transfer awaiting funds) — all auth-only states.
-          payment = payment_session.payment
-          if payment.present? && !payment.completed?
-            if payment_intent_successful?(stripe_pi)
-              payment.process!
-            else
-              payment.authorize!
-            end
-          end
+      def retrieve_payment_intent(payment_intent_id)
+        send_request { |opts| Stripe::PaymentIntent.retrieve({ id: payment_intent_id, expand: ['payment_method'] }, opts) }
+      end
 
-          payment_session.complete unless payment_session.completed?
-        else
-          payment_session.fail if payment_session.can_fail?
-        end
+      def confirm_payment_intent(payment_intent_id)
+        send_request { |opts| Stripe::PaymentIntent.confirm(payment_intent_id, {}, opts) }
       end
 
-      private
+      def capture_payment_intent(payment_intent_id, amount_in_cents)
+        send_request { |opts| Stripe::PaymentIntent.capture(payment_intent_id, { amount_to_capture: amount_in_cents }, opts) }
+      end
+
+      def cancel_payment_intent(payment_intent_id)
+        send_request { |opts| Stripe::PaymentIntent.cancel(payment_intent_id, {}, opts) }
+      end
+
+      # Whether the intent has progressed far enough to record a payment. The
+      # acceptable statuses depend on how the money moves: manual capture stops
+      # at `requires_capture`, delayed-notification banks sit in `processing`,
+      # and bank transfers wait for funds in `requires_action`.
+      def payment_intent_accepted?(payment_intent)
+        statuses = %w[succeeded]
+        statuses << 'requires_capture' if payment_intent_manual_capture?(payment_intent)
+        statuses << 'processing' if payment_intent_type_in?(payment_intent, DELAYED_NOTIFICATION_PAYMENT_METHOD_TYPES)
+        statuses << 'requires_action' if payment_intent_charge_not_required?(payment_intent) &&
+                                         !payment_intent_awaiting_microdeposits?(payment_intent)
+
+        payment_intent.status.in?(statuses)
+      end
 
-      def reuse_payment_session(order, amount, external_data)
-        session = order.payment_sessions.where(payment_method: self, status: 'pending').not_expired.order(:created_at).last
-        return if session.blank?
+      def payment_intent_successful?(payment_intent)
+        payment_intent.status == 'succeeded'
+      end
+
+      def payment_intent_requires_capture?(payment_intent)
+        payment_intent.status == 'requires_capture'
+      end
+
+      # Bank transfers settle without a charge object, so the payment source has
+      # to be built from the intent instead.
+      def payment_intent_charge_not_required?(payment_intent)
+        payment_intent_type_in?(payment_intent, BANK_PAYMENT_METHOD_TYPES)
+      end
 
-        intent = retrieve_payment_intent(session.external_id)
+      # ACH debits sit in requires_action until the customer confirms the two
+      # microdeposit amounts. Funds are not on their way yet, so the session
+      # must not settle — Stripe reports the eventual outcome by webhook.
+      def payment_intent_awaiting_microdeposits?(payment_intent)
+        next_action = payment_intent.try(:next_action)
+        return false unless next_action.respond_to?(:type)
 
-        if intent.status == 'canceled'
-          session.cancel if session.can_cancel?
-          return
+        next_action.type.to_s == MICRODEPOSIT_VERIFICATION_ACTION
+      end
+
+      def payment_intent_manual_capture?(payment_intent)
+        payment_intent.respond_to?(:capture_method) && payment_intent.capture_method == MANUAL_CAPTURE_METHOD
+      end
+
+      private
+
+      # @param order [Spree::Cart, Spree::Order]
+      # @return [Spree::PaymentResponse]
+      def create_payment_intent(amount_in_cents, order, payment_method_id: nil, customer_profile_id: nil)
+        payload = {
+          amount: amount_in_cents,
+          currency: order.currency,
+          customer: customer_profile_id,
+          payment_method: payment_method_id,
+          # Stripe knows only "charge now" or "authorize now, capture later",
+          # so both on_dispatch and manual map to its manual capture.
+          capture_method: (MANUAL_CAPTURE_METHOD unless capture_at_checkout?),
+          statement_descriptor_suffix: statement_descriptor_suffix_for(order),
+          automatic_payment_methods: { enabled: true },
+          transfer_group: order.number,
+          metadata: { spree_order_id: order.id },
+          shipping: shipping_payload(order.ship_address)
+        }.compact
+
+        # A saved payment method is already tokenized; a new one is stored so it
+        # can be charged off-session later.
+        payload[:payment_method_options] = {
+          card: { setup_future_usage: SETUP_FUTURE_USAGE },
+          sepa_debit: { setup_future_usage: SETUP_FUTURE_USAGE }
+        } if payment_method_id.blank?
+
+        protect_from_error do
+          response = send_request { |opts| Stripe::PaymentIntent.create(payload, opts) }
+
+          success(response.id, response)
         end
+      end
+
+      # Only the fields that can legitimately change while a session is pending.
+      def update_payment_intent(payment_intent_id, amount_in_cents, order, payment_method_id = nil)
+        protect_from_error do
+          payload = {
+            amount: amount_in_cents,
+            currency: order.currency,
+            customer: fetch_or_create_customer(order: order)&.profile_id,
+            payment_method: payment_method_id,
+            shipping: shipping_payload(order.ship_address)
+          }.compact
 
-        unless intent.status.in?(REUSABLE_INTENT_STATUSES)
-          raise Spree::Core::GatewayError, I18n.t('spree.stripe.payment_session_errors.payment_in_progress')
+          response = send_request { |opts| Stripe::PaymentIntent.update(payment_intent_id, payload, opts) }
+
+          success(response.id, response)
         end
+      end
 
-        update_payment_session(payment_session: session, amount: amount, external_data: external_data)
+      # Stripe requires address1 on a shipping address; Spree does not always
+      # demand one, so an incomplete address is omitted rather than rejected.
+      #
+      # @return [Hash, nil]
+      def shipping_payload(ship_address)
+        return if ship_address.blank?
+
+        # Validated on a duplicate: `invalid?` populates errors on the record,
+        # and clearing them afterwards would still stomp whatever the caller
+        # had collected on the live address.
+        return if ship_address.address1.blank? || ship_address.dup.invalid?
+
+        {
+          address: {
+            city: ship_address.city,
+            country: ship_address.country_code,
+            line1: ship_address.address1,
+            line2: ship_address.address2,
+            postal_code: ship_address.postal_code,
+            state: ship_address.state_code
+          },
+          name: ship_address.full_name
+        }
+      end
 
-        session
+      def statement_descriptor_suffix_for(order)
+        SpreeStripe::StatementDescriptorSuffixPresenter.new(order_description: order.number).call
       end
 
-      def payment_intent_successful?(stripe_pi)
-        stripe_pi.status == 'succeeded'
+      def payment_intent_type_in?(payment_intent, types)
+        payment_method = payment_intent.payment_method
+        return false unless payment_method.respond_to?(:type)
+
+        payment_method.type.in?(types)
       end
 
-      # Patches the order's billing address with data from the Stripe charge.
-      # Needed for quick checkout (Apple Pay/Google Pay) where the storefront
-      # doesn't have the billing address before payment confirmation.
-      def patch_wallet_address(order, charge)
+      # Quick checkout (Apple Pay / Google Pay) confirms payment before the
+      # storefront has a billing address, so it arrives on the Stripe charge.
+      #
+      # @param owner [Spree::Cart, Spree::Order]
+      def patch_wallet_address(owner, charge)
         return if charge.blank?
 
         billing_details = charge.billing_details
         address = billing_details.address
 
-        order.email ||= billing_details.email
-        order.save! if order.email_changed?
+        owner.email ||= billing_details.email
+        owner.save! if owner.email_changed?
 
-        # Skip if billing address is already valid
-        return if order.bill_address.present? && order.bill_address.valid?
+        return if owner.bill_address.present? && owner.bill_address.valid?
 
-        country_iso = address.country
-        country = (country_iso.present? && Spree::Country.by_iso(country_iso)) ||
-                  order.store.default_market&.default_country ||
+        country = (address.country.presence && Spree::Country.by_iso(address.country)) ||
+                  owner.store.default_market&.default_country ||
                   Spree::Country.by_iso('US')
 
-        order.bill_address ||= Spree::Address.new(country: country, user: order.user)
-        order.bill_address.quick_checkout = true
-
-        first_name = billing_details.name&.split(' ')&.first || order.ship_address&.first_name || order.user&.first_name
-        last_name = billing_details.name&.split(' ')&.last || order.ship_address&.last_name || order.user&.last_name
-
-        order.bill_address.first_name ||= first_name
-        order.bill_address.last_name ||= last_name
-        order.bill_address.phone ||= billing_details.phone
-        order.bill_address.address1 ||= address.line1
-        order.bill_address.address2 ||= address.line2
-        order.bill_address.city ||= address.city
-        order.bill_address.zipcode ||= address.postal_code
-
+        # Countries are reference data now, not records — addresses name one by
+        # ISO code rather than holding a foreign key.
+        owner.bill_address ||= Spree::Address.new(country_code: country.iso, owner: owner.customer)
+        owner.bill_address.quick_checkout = true
+
+        # Google Pay sometimes omits the name entirely.
+        first_name = billing_details.name&.split(' ')&.first || owner.ship_address&.first_name || owner.customer&.first_name
+        last_name = billing_details.name&.split(' ')&.last || owner.ship_address&.last_name || owner.customer&.last_name
+
+        owner.bill_address.first_name ||= first_name
+        owner.bill_address.last_name ||= last_name
+        owner.bill_address.phone ||= billing_details.phone
+        owner.bill_address.address1 ||= address.line1
+        owner.bill_address.address2 ||= address.line2
+        owner.bill_address.city ||= address.city
+        owner.bill_address.postal_code ||= address.postal_code
+
+        # Stripe sends whatever the wallet had — a code or a full name — so it
+        # is resolved to a current subdivision code. The free-text state_name
+        # is kept as the fallback for countries without subdivisions, and as a
+        # record of what the wallet actually said.
         state_name = address.state
         if country.states_required?
-          order.bill_address.state = country.states.find_all_by_name_or_abbr(state_name)&.first
-        else
-          order.bill_address.state_name = state_name
+          owner.bill_address.state_code ||= Spree::IsoData.subdivision_code(country.iso, state_name)
         end
-        order.bill_address.state_name ||= state_name
+        owner.bill_address.state_name ||= state_name
 
-        if order.bill_address.invalid?
-          return if order.ship_address.blank?
+        if owner.bill_address.invalid?
+          return if owner.ship_address.blank?
 
-          order.bill_address = order.ship_address
+          owner.bill_address = owner.ship_address
         end
 
-        order.bill_address.save! if order.bill_address&.changed?
-        order.save!
+        owner.bill_address.save! if owner.bill_address&.changed?
+        owner.save!
 
-        copy_bill_info_to_user(order) if order.user.present?
+        copy_bill_info_to_customer(owner) if owner.customer.present?
       end
 
-      def copy_bill_info_to_user(order)
-        user = order.user
-        user.first_name ||= order.bill_address.first_name
-        user.last_name ||= order.bill_address.last_name
-        user.phone ||= order.bill_address.phone
-        user.bill_address_id ||= order.bill_address.id
-        user.save! if user.changed?
+      def copy_bill_info_to_customer(owner)
+        customer = owner.customer
+        customer.first_name ||= owner.bill_address.first_name
+        customer.last_name ||= owner.bill_address.last_name
+        customer.phone ||= owner.bill_address.phone
+        customer.bill_address_id ||= owner.bill_address.id
+        customer.save! if customer.changed?
       end
     end
   end

data/app/models/spree_stripe/gateway/payment_setup_sessions.rb

@@ -1,5 +1,6 @@
 module SpreeStripe
   class Gateway < ::Spree::Gateway
+    # Saving a payment method for later use, without taking a payment.
     module PaymentSetupSessions
       extend ActiveSupport::Concern
 
@@ -11,8 +12,10 @@ module SpreeStripe
         Spree::PaymentSetupSessions::Stripe
       end
 
+      # @param customer [Spree::Customer]
+      # @return [Spree::PaymentSetupSessions::Stripe]
       def create_payment_setup_session(customer:, external_data: {})
-        gateway_customer = fetch_or_create_customer(user: customer)
+        gateway_customer = fetch_or_create_customer(customer: customer)
 
         setup_intent_response = create_setup_intent(gateway_customer.profile_id)
         ephemeral_key_response = create_ephemeral_key(gateway_customer.profile_id)
@@ -38,15 +41,18 @@ module SpreeStripe
 
           stripe_payment_method = stripe_setup_intent.payment_method
 
-          source = SpreeStripe::CreateSource.new(
-            stripe_payment_method_details: stripe_payment_method,
-            stripe_payment_method_id: stripe_payment_method.id,
-            stripe_billing_details: stripe_payment_method.billing_details,
-            gateway: self,
-            user: setup_session.customer
-          ).call
+          # Persisted explicitly — a status transition writes status alone,
+          # never a ride-along for other dirty attributes.
+          setup_session.update!(
+            payment_source: SpreeStripe::CreateSource.new(
+              stripe_payment_method_details: stripe_payment_method,
+              stripe_payment_method_id: stripe_payment_method.id,
+              stripe_billing_details: stripe_payment_method.billing_details,
+              gateway: self,
+              customer: setup_session.customer
+            ).call
+          )
 
-          setup_session.payment_source = source
           setup_session.complete unless setup_session.completed?
         else
           setup_session.fail if setup_session.can_fail?

data/app/models/spree_stripe/gateway/webhooks.rb

@@ -0,0 +1,107 @@
+module SpreeStripe
+  class Gateway < ::Spree::Gateway
+    # Webhook signature verification and endpoint registration.
+    #
+    # Signing secrets live in the gateway's own preferences. Before 6.0 they were
+    # rows in spree_stripe_webhook_keys joined to payment methods many-to-many;
+    # with a payment method now owned by exactly one store there is a single
+    # endpoint per gateway, so a preference carries the same data. Existing
+    # secrets are carried over by `spree:upgrade:migrate_stripe_webhook_keys`.
+    module Webhooks
+      extend ActiveSupport::Concern
+
+      # Only events with a handler — subscribing to more would silently drop
+      # deliveries and bake phantom events into the endpoint's identity.
+      # setup_intent.succeeded is deliberately absent: healing an abandoned
+      # setup session by webhook needs core's webhook contract to learn about
+      # setup sessions first (it only routes payment sessions today).
+      SUPPORTED_EVENTS = %w[
+        payment_intent.amount_capturable_updated
+        payment_intent.payment_failed
+        payment_intent.succeeded
+      ].freeze
+
+      WEBHOOK_EVENT_ACTIONS = {
+        'payment_intent.succeeded' => :captured,
+        'payment_intent.amount_capturable_updated' => :authorized,
+        'payment_intent.payment_failed' => :failed
+      }.freeze
+
+      included do
+        # Both written by CreateGatewayWebhooks once Stripe has registered the
+        # endpoint — Stripe issues the secret and only reveals it at creation.
+        # An operator has nothing to type here, and a value typed over one
+        # would break the signature check it exists to satisfy.
+        preference :webhook_signing_secret, :password, internal: true
+        preference :webhook_endpoint_id, :string, internal: true
+
+        after_commit :create_webhook_endpoint_async, on: %i[create update]
+      end
+
+      # Translates a Stripe event into the normalized shape core's webhook
+      # controller and `Spree::Payments::HandleWebhook` consume. Everything
+      # after this — idempotency, locking, payment creation, order completion —
+      # belongs to core.
+      #
+      # @param raw_body [String]
+      # @param headers [Hash]
+      # @return [Hash, nil] nil for events this gateway does not act on
+      # @raise [Spree::PaymentMethod::WebhookSignatureError]
+      def parse_webhook_event(raw_body, headers)
+        event = verify_webhook_signature(raw_body, headers)
+
+        action = WEBHOOK_EVENT_ACTIONS[event.type]
+        return nil unless action
+
+        payment_session = Spree::PaymentSessions::Stripe.find_by(
+          payment_method: self,
+          external_id: event.data.object[:id]
+        )
+        return nil unless payment_session
+
+        { action: action, payment_session: payment_session }
+      end
+
+      def create_webhook_endpoint
+        SpreeStripe::CreateGatewayWebhooks.new.call(payment_method: self)
+      end
+
+      private
+
+      def verify_webhook_signature(raw_body, headers)
+        signature = headers['HTTP_STRIPE_SIGNATURE']
+
+        webhook_signing_secrets.each do |secret|
+          return Stripe::Webhook.construct_event(raw_body, signature, secret)
+        rescue Stripe::SignatureVerificationError
+          next
+        rescue JSON::ParserError
+          # construct_event parses before it verifies, so a malformed body
+          # never reaches the signature check. Unauthenticated garbage is a
+          # rejected webhook, not a server error to retry.
+          raise Spree::PaymentMethod::WebhookSignatureError, 'Malformed webhook payload'
+        end
+
+        raise Spree::PaymentMethod::WebhookSignatureError, 'Invalid webhook signature'
+      end
+
+      # Development only: the Stripe CLI signs forwarded events with its own
+      # secret rather than the endpoint's. Accepting it anywhere else would
+      # make one leaked value a forgery key for every gateway in the install.
+      def webhook_signing_secrets
+        secrets = [preferred_webhook_signing_secret]
+        secrets << ENV['STRIPE_SIGNING_SECRET'] if Rails.env.development?
+        secrets.select(&:present?)
+      end
+
+      # A stored secret means the endpoint is already registered — unless the
+      # key now points at a different Stripe account.
+      def create_webhook_endpoint_async
+        return if only_webhook_registration_changed?
+        return if preferred_webhook_signing_secret.present? && !stripe_secret_key_changed?
+
+        SpreeStripe::CreateWebhookEndpointJob.perform_later(id, connect: false)
+      end
+    end
+  end
+end