spree_paypal_checkout 0.7.0 → 6.0.3

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

@@ -1,203 +1,286 @@
-require 'net/http'
-
 module SpreePaypalCheckout
   class Gateway < ::Spree::Gateway
+    # A PayPal payment session is a PayPal order. Creating the session creates
+    # the order, the buyer approves it in PayPal's window, and completing the
+    # session captures or authorizes it. Until then the order is inert: nothing
+    # but this server can take money against it.
     module PaymentSessions
       extend ActiveSupport::Concern
 
-      def session_required?
-        !SpreePaypalCheckout::Config[:use_legacy_api]
-      end
+      # Written by the gem; a client's values for them are ignored.
+      OWNED_EXTERNAL_DATA_KEYS = %w[client_id intent attempt paypal_result].freeze
+      # The buyer's card or account was refused and PayPal lets them pick
+      # another in the same window, so the session stays open for them.
+      RECOVERABLE_DECLINE = 'INSTRUMENT_DECLINED'.freeze
+      # Answers that say nothing about the order: PayPal turned the request away
+      # before looking, or could not be reached at all.
+      RETRYABLE_STATUS_CODES = [401, 408, 429].freeze
+
+      # Opens a new session on every call, canceling the cart's open PayPal
+      # sessions first so only one order can ever be paid.
+      #
+      # @param order [Spree::Cart, Spree::Order]
+      # @return [Spree::PaymentSessions::PaypalCheckout]
+      # @raise [Spree::Core::GatewayError] for a zero amount, an amount PayPal
+      #   cannot take, or a cart this method has already been paid for
+      def create_payment_session(order:, amount: nil, external_data: {})
+        total = amount.present? ? BigDecimal(amount.to_s) : order.total_minus_store_credits
+        raise Spree::Core::GatewayError, I18n.t('spree.paypal_checkout.payment_session_errors.zero_amount') unless total.positive?
 
-      def payment_session_class
-        Spree::PaymentSessions::PaypalCheckout
-      end
+        SpreePaypalCheckout::Amounts.to_paypal(total, order.currency)
+        replace_open_sessions(order)
 
-      # Creates a PayPal order via the PayPal Orders API and persists
-      # a Spree::PaymentSessions::PaypalCheckout record.
-      def create_payment_session(order:, amount: nil, external_data: {})
-        total = amount.presence || order.total_minus_store_credits
-
-        return nil if total.zero?
-
-        protect_from_error do
-          order_presenter = SpreePaypalCheckout::OrderPresenter.new(order)
-          paypal_response = client.orders.create_order(order_presenter.to_json)
-
-          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: paypal_response.data.as_json
+        intent = paypal_intent
+        presenter = SpreePaypalCheckout::OrderPresenter.new(order: order, amount: total, intent: intent)
+        paypal_order = protect_from_error { create_paypal_order(presenter.order_request) }
+
+        payment_session_class.create!(
+          owner: order,
+          payment_method: self,
+          amount: total,
+          currency: order.currency,
+          status: 'pending',
+          external_id: paypal_order['id'],
+          customer: order.customer,
+          # The JS SDK must load with the client id that created the order and
+          # the order's own intent, or PayPal's buttons refuse it.
+          external_data: client_external_data(external_data).merge(
+            'client_id' => preferred_client_id,
+            'intent' => intent
           )
-        end
+        )
       end
 
+      # A new amount is sent to PayPal before the session takes it, so PayPal
+      # never captures a total Spree no longer charges. The whole purchase unit
+      # is replaced: items and breakdown come and go with whether they add up.
       def update_payment_session(payment_session:, amount: nil, external_data: {})
         attrs = {}
-        attrs[:amount] = amount if amount.present?
 
-        if external_data.present?
-          attrs[:external_data] = (payment_session.external_data || {}).merge(external_data.stringify_keys)
+        new_amount = BigDecimal(amount.to_s) if amount.present?
+        if new_amount && new_amount != payment_session.amount
+          presenter = SpreePaypalCheckout::OrderPresenter.new(
+            order: payment_session.owner, amount: new_amount, intent: payment_session.intent || paypal_intent
+          )
+          protect_from_error { patch_paypal_order(payment_session.external_id, presenter.purchase_unit) }
+          attrs[:amount] = new_amount
         end
 
+        data = client_external_data(external_data)
+        attrs[:external_data] = (payment_session.external_data || {}).merge(data) if data.any?
+
         payment_session.update!(attrs) if attrs.any?
       end
 
-      # Completes a payment session by capturing the PayPal order,
-      # creating the Payment record, and transitioning the session.
+      # Captures or authorizes the order the buyer approved, then settles the
+      # payment. Does NOT complete the cart: the storefront's cart-complete
+      # call or the webhook handler does that.
       #
-      # Does NOT complete the order -- that is handled by Carts::Complete
-      # (called by the storefront or by the webhook handler).
+      # @raise [Spree::Core::GatewayError] when the session is not open, or
+      #   PayPal declines; a recoverable decline leaves the session open
       def complete_payment_session(payment_session:, params: {})
-        paypal_order_id = payment_session.external_id
+        unless payment_session.pending? || payment_session.processing?
+          raise Spree::Core::GatewayError, I18n.t('spree.paypal_checkout.payment_session_errors.not_open')
+        end
 
-        response = client.orders.capture_order({
-          'id' => paypal_order_id,
-          'prefer' => 'return=representation'
-        })
+        paypal_order = protect_from_error { paypal_order(payment_session.external_id) }
 
-        # Persist capture data outside the lock so it survives if post-capture bookkeeping fails
-        payment_session.update!(external_data: response.data.as_json)
+        # A capture that timed out may have gone through; it is settled, not
+        # taken again.
+        unless money_moved?(paypal_order)
+          unless order_matches_session?(paypal_order, payment_session)
+            payment_session.fail if payment_session.can_fail?
+            return payment_session
+          end
 
-        payment_session.order.with_lock do
-          if response.data.status == 'COMPLETED'
-            payment_session.process if payment_session.can_process?
+          paypal_order = move_money(payment_session)
+        end
 
-            payment = payment_session.find_or_create_payment!
+        settle(payment_session, paypal_order)
+      end
 
-            if payment.present? && !payment.completed?
-              payment.started_processing! if payment.checkout?
-              payment.complete! if payment.can_complete?
-            end
+      # A session that never reached Complete is canceled here alone: its order
+      # can only ever be paid by this server. Otherwise the order is read,
+      # since a capture that timed out may have gone through.
+      #
+      # @return [Boolean] whether the session was canceled
+      # @raise [Spree::Core::GatewayError] when PayPal has taken the money
+      # @raise [StandardError] PayPal's own error when it could not be asked
+      def cancel_payment_session(payment_session:)
+        return payment_session.cancel unless payment_session.complete_attempted?
 
-            create_profile(payment) if payment&.source.present?
+        paypal_order = paypal_order(payment_session.external_id)
 
-            payment_session.complete unless payment_session.completed?
-          else
-            payment_session.fail if payment_session.can_fail?
-          end
+        if capture_taken?(paypal_order)
+          raise Spree::Core::GatewayError, I18n.t('spree.paypal_checkout.payment_session_errors.payment_captured')
         end
-      rescue PaypalServerSdk::APIException => e
-        payment_session.fail if payment_session.can_fail?
-        raise Spree::Core::GatewayError, "PayPal API error: #{e.message}"
-      end
 
-      # Parses incoming PayPal webhook events.
-      def parse_webhook_event(raw_body, headers)
-        verify_webhook_signature!(raw_body, headers)
+        authorization = open_authorization(paypal_order)
+        void_authorization(authorization['id'], request_id: "#{payment_session.prefixed_id}-void") if authorization
 
-        event = JSON.parse(raw_body).with_indifferent_access
-        event_type = event[:event_type]
-        resource = event[:resource] || {}
+        payment_session.cancel
+      rescue PaypalServerSdk::ErrorException => e
+        raise if retryable_paypal_error?(e)
+        # An order the account the credentials now reach does not know can no
+        # longer be paid.
+        return payment_session.cancel if e.response_code == 404
 
-        paypal_order_id = extract_order_id_from_webhook(event_type, resource)
-        return nil unless paypal_order_id
+        raise Spree::Core::GatewayError, paypal_error_message(e)
+      end
 
-        payment_session = Spree::PaymentSessions::PaypalCheckout.find_by(
-          payment_method: self,
-          external_id: paypal_order_id
+      # @return [Hash] the created order
+      def create_paypal_order(order_request)
+        client.orders.create_order('body' => order_request, 'prefer' => 'return=minimal').data.to_hash
+      end
+
+      def patch_paypal_order(paypal_order_id, purchase_unit)
+        client.orders.patch_order(
+          'id' => paypal_order_id,
+          'body' => [
+            PaypalServerSdk::Patch.new(
+              op: PaypalServerSdk::PatchOp::REPLACE,
+              path: "/purchase_units/@reference_id=='default'",
+              value: purchase_unit.to_hash
+            )
+          ]
         )
-        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 } }
-        else
-          nil
-        end
+      end
+
+      # @return [Hash] the order, with its capture
+      def capture_paypal_order(paypal_order_id, request_id:)
+        client.orders.capture_order(
+          'id' => paypal_order_id,
+          'paypal_request_id' => request_id,
+          'prefer' => 'return=representation'
+        ).data.to_hash
+      end
+
+      # @return [Hash] the order, with its authorization
+      def authorize_paypal_order(paypal_order_id, request_id:)
+        client.orders.authorize_order(
+          'id' => paypal_order_id,
+          'paypal_request_id' => request_id,
+          'prefer' => 'return=representation'
+        ).data.to_hash
       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')
+      # The attempt is stored before PayPal is asked, so a cancel after a
+      # timeout knows to look at the order, and a retry of the same attempt
+      # reaches PayPal as the same request.
+      def move_money(payment_session)
+        attempt = payment_session.attempt
+        payment_session.update!(external_data: payment_session.external_data.merge('attempt' => attempt))
+        action = payment_session.intent == PaypalServerSdk::CheckoutPaymentIntent::AUTHORIZE ? 'authorize' : 'capture'
+        request_id = "#{payment_session.prefixed_id}-#{action}-#{attempt}"
+
+        paypal_order = protect_from_error(money_moving: true) do
+          action == 'authorize' ? authorize_paypal_order(payment_session.external_id, request_id: request_id) : capture_paypal_order(payment_session.external_id, request_id: request_id)
         end
+        return paypal_order if money_moved?(paypal_order)
+
+        payment_session.fail if payment_session.can_fail?
+        status = payment_status(paypal_order)
+        raise PaypalError.new(I18n.t('spree.paypal_checkout.payment_session_errors.declined', status: status), issue: status)
+      rescue PaypalError => e
+        if e.issue == RECOVERABLE_DECLINE
+          payment_session.update!(external_data: payment_session.external_data.merge('attempt' => attempt + 1))
+        elsif !e.status.to_i.in?(RETRYABLE_STATUS_CODES) && payment_session.reload.can_fail?
+          # A rate limit or a refused token is not a decline: the buyer can
+          # complete the same session again.
+          payment_session.fail
+        end
+        raise
       end
 
-      def verify_webhook_signature!(raw_body, headers)
-        if preferred_webhook_secret.blank?
-          return if Rails.env.development? || Rails.env.test?
+      # Once money has moved the session is never failed: a failed session
+      # lets the storefront open another and charge again.
+      def settle(payment_session, paypal_order)
+        payment_session.paypal_order = paypal_order
+        payment_session.update!(
+          external_data: payment_session.external_data.merge('paypal_result' => paypal_result(paypal_order))
+        )
+        report_amount_mismatch(payment_session, paypal_order)
 
-          raise Spree::PaymentMethod::WebhookSignatureError,
-                'PayPal webhook_secret is not configured'
-        end
+        payment_session.process if payment_session.can_process?
+        capture = captures(paypal_order).first
+        payment_session.settle_payment!(captured: capture.present? && capture['status'] == 'COMPLETED')
+        payment_session.complete unless payment_session.completed?
+        payment_session
+      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']
+      def order_matches_session?(paypal_order, payment_session)
+        amount_matches?(Array(paypal_order['purchase_units']).first&.dig('amount'), payment_session.amount, payment_session.currency)
+      end
+
+      def report_amount_mismatch(payment_session, paypal_order)
+        moved = first_payment(paypal_order)
+        return if moved.nil? || amount_matches?(moved['amount'], payment_session.amount, payment_session.currency)
+
+        expected = SpreePaypalCheckout::Amounts.to_paypal(payment_session.amount, payment_session.currency)
+
+        Rails.error.report(
+          Spree::Core::GatewayError.new(
+            "PayPal took #{moved.dig('amount', 'value')} #{moved.dig('amount', 'currency_code')} " \
+            "for a session of #{expected} #{payment_session.currency.upcase}"
+          ),
+          context: { payment_session_id: payment_session.id, paypal_order_id: payment_session.external_id },
+          source: 'spree_paypal_checkout.complete_payment_session'
+        )
+      end
+
+      def paypal_result(paypal_order)
+        capture = captures(paypal_order).first
+        authorization = authorizations(paypal_order).first
+        {
+          'status' => paypal_order['status'],
+          'capture_id' => capture&.dig('id'),
+          'capture_status' => capture&.dig('status'),
+          'authorization_id' => authorization&.dig('id'),
+          'authorization_status' => authorization&.dig('status')
+        }.compact
+      end
 
-        unless transmission_id && transmission_sig
-          raise Spree::PaymentMethod::WebhookSignatureError, 'Missing PayPal webhook headers'
+      def payment_status(paypal_order)
+        first_payment(paypal_order)&.dig('status') || paypal_order['status']
+      end
+
+      def first_payment(paypal_order)
+        captures(paypal_order).first || authorizations(paypal_order).first
+      end
+
+      # Only the payable ones are canceled; a failed session's order can no
+      # longer be completed by anyone.
+      def replace_open_sessions(order)
+        sessions = order.payment_sessions.where(payment_method: self)
+        if sessions.exists?(status: 'completed')
+          raise Spree::Core::GatewayError, I18n.t('spree.paypal_checkout.payment_session_errors.payment_in_progress')
         end
 
-        token = obtain_access_token
-
-        api_base = preferred_test_mode ? 'https://api-m.sandbox.paypal.com' : 'https://api-m.paypal.com'
-        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)
-        result = JSON.parse(response.body)
-
-        unless result['verification_status'] == 'SUCCESS'
-          raise Spree::PaymentMethod::WebhookSignatureError, 'Invalid webhook signature'
+        sessions.active.order(:id).each do |payment_session|
+          cancel_payment_session(payment_session: payment_session)
         end
-      rescue Spree::PaymentMethod::WebhookSignatureError
+      rescue Spree::Core::GatewayError
         raise
-      rescue Net::OpenTimeout, Net::ReadTimeout, SocketError, JSON::ParserError, Errno::ECONNREFUSED => e
-        raise Spree::PaymentMethod::WebhookSignatureError, "Webhook verification failed: #{e.message}"
+      rescue StandardError => e
+        raise unless retryable_error?(e)
+
+        # Checkout speaks GatewayError. The unused-session job does not: it
+        # retries these, and has to see them unwrapped.
+        raise Spree::Core::GatewayError, e.message
       end
 
-      def obtain_access_token
-        api_base = preferred_test_mode ? 'https://api-m.sandbox.paypal.com' : 'https://api-m.paypal.com'
-        uri = URI("#{api_base}/v1/oauth2/token")
+      def retryable_error?(error)
+        error.is_a?(PaypalServerSdk::ErrorException) ? retryable_paypal_error?(error) : error.is_a?(Faraday::Error) || error.is_a?(CoreLibrary::AuthValidationException)
+      end
 
-        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'
+      def retryable_paypal_error?(error)
+        error.response_code.in?(RETRYABLE_STATUS_CODES) || error.response_code.to_i >= 500
+      end
 
-        response = http.request(request)
-        JSON.parse(response.body)['access_token']
+      def client_external_data(external_data)
+        external_data.to_h.stringify_keys.except(*OWNED_EXTERNAL_DATA_KEYS)
       end
     end
   end

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

@@ -0,0 +1,112 @@
+module SpreePaypalCheckout
+  class Gateway < ::Spree::Gateway
+    # Webhook signature verification and registration. Webhooks only report
+    # money that has moved: the storefront completes the session as soon as the
+    # buyer approves, so the approval itself is not subscribed to.
+    module Webhooks
+      extend ActiveSupport::Concern
+
+      WEBHOOK_EVENT_ACTIONS = {
+        'PAYMENT.CAPTURE.COMPLETED' => :captured,
+        'PAYMENT.CAPTURE.PENDING' => :authorized,
+        'PAYMENT.AUTHORIZATION.CREATED' => :authorized,
+        'PAYMENT.CAPTURE.DENIED' => :failed,
+        'PAYMENT.CAPTURE.DECLINED' => :failed
+      }.freeze
+
+      # Registration subscribes to exactly the events with a handler.
+      SUPPORTED_EVENTS = WEBHOOK_EVENT_ACTIONS.keys.freeze
+
+      # Where PayPal puts each value the verification call needs.
+      SIGNATURE_HEADERS = {
+        auth_algo: 'HTTP_PAYPAL_AUTH_ALGO',
+        cert_url: 'HTTP_PAYPAL_CERT_URL',
+        transmission_id: 'HTTP_PAYPAL_TRANSMISSION_ID',
+        transmission_sig: 'HTTP_PAYPAL_TRANSMISSION_SIG',
+        transmission_time: 'HTTP_PAYPAL_TRANSMISSION_TIME'
+      }.freeze
+
+      included do
+        after_commit :register_webhook_async, on: %i[create update]
+      end
+
+      # Translates a PayPal event into the shape core's webhook handler takes.
+      # Everything after this (idempotency, locking, payment creation, order
+      # completion) belongs to core.
+      #
+      # @param raw_body [String]
+      # @param headers [Hash, ActionDispatch::Http::Headers]
+      # @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['event_type']]
+        return nil unless action
+
+        paypal_order_id = event.dig('resource', 'supplementary_data', 'related_ids', 'order_id')
+        return nil if paypal_order_id.blank?
+
+        payment_session = Spree::PaymentSessions::PaypalCheckout.find_by(payment_method: self, external_id: paypal_order_id)
+        return nil unless payment_session
+
+        { action: action, payment_session: payment_session }
+      end
+
+      def register_webhook
+        SpreePaypalCheckout::RegisterWebhook.new.call(payment_method: self)
+      end
+
+      # @return [SpreePaypalCheckout::NotificationsClient]
+      def notifications_client
+        SpreePaypalCheckout::NotificationsClient.new(self)
+      end
+
+      private
+
+      # Every delivery is checked with PayPal, in every environment. Anything
+      # short of PayPal's SUCCESS is a rejected webhook, which PayPal delivers
+      # again later.
+      def verify_webhook_signature(raw_body, headers)
+        if preferred_webhook_id.blank?
+          raise Spree::PaymentMethod::WebhookSignatureError, 'PayPal webhook is not registered for this payment method'
+        end
+
+        event = parse_event(raw_body)
+        signature = SIGNATURE_HEADERS.transform_values { |key| headers[key] }
+        raise Spree::PaymentMethod::WebhookSignatureError, 'Missing PayPal signature headers' if signature.values.any?(&:blank?)
+
+        verdict = notifications_client.verify_webhook_signature(
+          raw_body: raw_body, headers: signature, webhook_id: preferred_webhook_id
+        )
+        raise Spree::PaymentMethod::WebhookSignatureError, 'Invalid webhook signature' unless verdict == 'SUCCESS'
+
+        event
+      rescue SpreePaypalCheckout::NotificationsClient::Error, *SpreePaypalCheckout::NotificationsClient::NETWORK_ERRORS,
+             PaypalServerSdk::APIException, CoreLibrary::AuthValidationException, Faraday::Error, JSON::ParserError => e
+        raise Spree::PaymentMethod::WebhookSignatureError, "PayPal could not verify the webhook: #{e.message}"
+      end
+
+      def parse_event(raw_body)
+        event = JSON.parse(raw_body.to_s)
+        raise Spree::PaymentMethod::WebhookSignatureError, 'Malformed webhook payload' unless event.is_a?(Hash)
+
+        event
+      rescue JSON::ParserError
+        raise Spree::PaymentMethod::WebhookSignatureError, 'Malformed webhook payload'
+      end
+
+      # Registered when the method is created and whenever the credentials
+      # change, since a webhook belongs to the REST app they name. Not when
+      # registration itself stores the webhook id.
+      def register_webhook_async
+        return unless previously_new_record? ||
+                      saved_change_to_preferred_client_id? ||
+                      saved_change_to_preferred_client_secret? ||
+                      saved_change_to_preferred_test_mode?
+
+        SpreePaypalCheckout::RegisterWebhookJob.perform_later(id)
+      end
+    end
+  end
+end