spree-paypal_merchant 6.0.0 → 6.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 593600084e06843e9fd2f9a1de5e5f503efa118d471fa43d23186029a33c39b0
-  data.tar.gz: 39d6ebce7fde438a61149611af88f3afcf6d913549973a3619428026d5dea7a4
+  metadata.gz: d09d026a692438a7e89cd1eb47700bc34fb8ef077da6475c94dd61471e70dfed
+  data.tar.gz: fca83a3ef6cfb0bb6e27851d65c0ae0daa35b414506acc25218246bbe0a0c19a
 SHA512:
-  metadata.gz: 2039d4bf6952b6b950a3c0d861f05102330d38b815ed82d3257b61caced05d69b0dd7d4b1b438579890d173b5b79c5b482fe4ba4d7ee5ab87bd02471709607ac
-  data.tar.gz: b145c1842d66afaa2b1fac49237d7dfe1054b043cdb20de68a3f8b2416496545ee87bcd38b42e0f3a827141ad34aefe0ecaa8a62be33573b0f4387d963d47396
+  metadata.gz: 765ffdaf6c95115be5c8f51cf31d42b1c3e171ff0cef1435abff604112735d45eae3051dde53ce5da75d6bb52f29108d6b7c811e02b834f997cef954f2c115c8
+  data.tar.gz: 3ddd64eabd1c28835cd4c4760f1c375ede3c45d9dc7251ab69be6f478703633f83f193d4f3498ac13aa7b92c8ea827d12e51e8ceb7f09e9b6a6a65f271c809c2

data/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## 6.0.1
+
+To record refunds made in PayPal, subscribe the webhook to
+`PAYMENT.CAPTURE.REFUNDED` (see "Refunds made in PayPal" in the README).
+
+### Added
+
+- Refunds made in PayPal's dashboard are recorded in Spree, so the order no
+  longer shows as paid. `PAYMENT.CAPTURE.REFUNDED` queues
+  `Spree::PaypalMerchant::SyncRefundsJob` for the payment it is about. The job
+  reads the payment's refunds from PayPal, not from the event, and records each
+  `COMPLETED` one Spree doesn't have: PayPal's amount, the PayPal refund id as
+  the transaction id, and the store's refund reason. The order's payment state
+  and totals update as for a refund made in Spree, and PayPal is never asked to
+  refund it again.
+  - Refunds made from Spree carry their PayPal refund id and are not recorded
+    twice. While one is still waiting for PayPal's answer, the job tries again
+    later.
+  - The reason is the store's "Return processing" reason, or else its first by
+    name. None is created: with no reason, nothing is recorded and a warning
+    is logged.
+  - A refund in another currency, or for more than is left to refund, is
+    logged and not recorded.
+  - Payments taken on 5.x are synced too.
+- `spree:paypal_merchant:sync_refunds[<order number>]` records the refunds made
+  in PayPal for one order, such as those made before the webhook was set up,
+  and prints what it recorded or skipped.
+- The payment method's card under Settings -> Integrations shows PayPal's mark
+  and links to the README. The mark ships with the gem
+  (`lib/spree/paypal_merchant/paypal-mark.svg`) and `Gateway.logo_url` serves
+  it as a data URI, so the dashboard needs no asset pipeline and fetches it
+  from no other host. The mark is PayPal's trademark, not covered by the gem's
+  license.
+
+### Fixed
+
+- `Gateway#webhook_url` is an absolute URL, `https://` in production. It had no
+  scheme, so PayPal would not take it. When the Spree API is on another host
+  than the store's URL, give PayPal the API host (see the README).
+- `PAYMENT.CAPTURE.REFUNDED` no longer maps to canceling the payment session.
+  Its resource is the refund, which names no PayPal order, so the event was
+  dropped; at most it could cancel a session still open, and a refund never
+  cancels one.
+
 ## 6.0.0
 
 Ports the gem to Spree 6. The major version tracks Spree's. Spree 5.6 stays

data/README.md

@@ -66,12 +66,21 @@ Then add a **PayPal** payment method in the admin dashboard and set:
 | `enable_apple_pay` | Offer Apple Pay on the storefront (default on) |
 | `enable_card_fields` | Offer Card Fields on the storefront (default on) |
 
-Webhook URL is the standard Spree v3 payments webhook:
+Webhook URL is the standard Spree v3 payments webhook. PayPal only accepts an
+absolute `https://` URL:
 
 ```text
 https://<store>/api/v3/webhooks/payments/<prefixed-payment-method-id>
 ```
 
+The gateway's `webhook_url` builds it from the store's URL. When the Spree API
+is served from another host than the store's URL (a headless storefront on its
+own domain, say), give PayPal the **API host** instead:
+
+```text
+https://<api host>/api/v3/webhooks/payments/<prefixed-payment-method-id>
+```
+
 Subscribe it to these events. Others, such as `CHECKOUT.ORDER.APPROVED`, are
 ignored.
 
@@ -80,7 +89,8 @@ ignored.
 | `PAYMENT.CAPTURE.COMPLETED` | Settles the payment as captured |
 | `PAYMENT.CAPTURE.PENDING` | Settles it as pending (an eCheck, say); `COMPLETED` completes it later |
 | `PAYMENT.CAPTURE.DENIED`, `PAYMENT.CAPTURE.DECLINED` | Fails the payment session if it is still open. A payment already left pending by `PAYMENT.CAPTURE.PENDING` stays pending (no money was taken); use Capture in the dashboard: it reads PayPal and fails the payment if PayPal denied the capture (or completes it if PayPal completed it) |
-| `PAYMENT.CAPTURE.REVERSED`, `PAYMENT.CAPTURE.REFUNDED` | Cancels the payment session if it is still open and the event names the PayPal order. A completed session and its payment are left as they are, so a refund or chargeback made in PayPal does not change the Spree payment |
+| `PAYMENT.CAPTURE.REFUNDED` | Records the refund on the Spree payment (see [Refunds made in PayPal](#refunds-made-in-paypal)). PayPal sends it for refunds made from Spree too; those are not recorded twice |
+| `PAYMENT.CAPTURE.REVERSED` | Cancels the payment session if it is still open and the event names the PayPal order. The event leaves a completed session and its payment as they are. But the refund sync records whatever PayPal lists as a `COMPLETED` refund of the capture, so if PayPal lists a reversal (after a chargeback, say) among the order's refunds, a later sync records it as a refund |
 
 ## In the dashboard
 
@@ -98,6 +108,49 @@ ignored.
   instead. One that PayPal is still processing can't be voided or canceled;
   refund it once PayPal completes it.
 
+## Refunds made in PayPal
+
+A refund made in PayPal's own dashboard is recorded in Spree, so the order
+stops showing as paid. When PayPal sends `PAYMENT.CAPTURE.REFUNDED`, the gem
+queues `Spree::PaypalMerchant::SyncRefundsJob` (on Spree's payment webhook
+queue, 30 seconds later) for the payment the refund is about. The job reads the
+payment's refunds from PayPal, not from the event, and records each `COMPLETED`
+one Spree doesn't have yet:
+
+- as a Spree refund for PayPal's amount, with the PayPal refund id as its
+  transaction id, so Spree never asks PayPal to refund it again. Its metadata
+  says it was recorded from PayPal. The order's payment state and totals update
+  as for a refund made in Spree.
+- with the store's **Return processing** refund reason, the one Spree's refund
+  workflow defaults to, or else the store's first reason by name, as the admin
+  API defaults. The gem never creates a reason: with none, nothing is recorded
+  and a warning is logged.
+
+Refunds made from Spree already carry their PayPal refund id, so they are never
+recorded twice, and the job runs again later while one is still waiting for
+PayPal's answer. Not recorded, and logged: a refund PayPal hasn't completed, one
+in another currency than the payment's, one for more than is left to refund,
+and any refund of a payment that isn't completed (one Spree voided, say).
+Payments taken on 5.x are synced too.
+
+The sync records whatever PayPal lists as a `COMPLETED` refund of the
+payment's capture. If PayPal lists a reversal there (after a chargeback, say),
+the sync records it as a refund, though `PAYMENT.CAPTURE.REVERSED` itself
+changes nothing.
+
+Refunds recorded from PayPal don't run Spree's refund workflow, so its
+callbacks (`:validate`, `:before_refund`, `:after_refund`) don't run for them.
+App hooks registered there, such as a customer refund email, won't fire. The
+`refund.created` and `payment.refunded` events do.
+
+For refunds made before the webhook was set up, or ones the job gave up on,
+run the same sync for one order's PayPal payments. It prints what it recorded
+or skipped, and running it again records nothing new:
+
+```bash
+bin/rails 'spree:paypal_merchant:sync_refunds[R123456789]'
+```
+
 ## Apple Pay
 
 1. Enable Apple Pay on the PayPal business account.
@@ -185,3 +238,7 @@ runs Spree 6.0.0 and the newest release, each on Ruby 3.3 and 4.0.
 
 MIT. Derived from [spree/spree_paypal_checkout](https://github.com/spree/spree_paypal_checkout)
 (Vendo Connect Inc.), re-namespaced and extended by Aypex.
+
+The PayPal mark (`lib/spree/paypal_merchant/paypal-mark.svg`) is PayPal's
+trademark, included only to identify the payment method in the Spree
+dashboard, and is not covered by this gem's license.

data/app/jobs/spree/paypal_merchant/sync_refunds_job.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Spree
+  module PaypalMerchant
+    ##
+    # Records in Spree the refunds made in PayPal for one payment
+    # ({SyncRefunds}). Enqueued when PayPal reports a refund.
+    #
+    # Runs on the queue Spree's own payment webhook job uses, after the same
+    # wait. Tries again a few times while PayPal cannot be read, and while a
+    # refund made in Spree waits for PayPal's answer. A payment that is gone
+    # is dropped. Anything it gives up on is logged with the rake task that
+    # records it by hand.
+    #
+    class SyncRefundsJob < Spree::BaseJob
+      ##
+      # How long after PayPal's event the sync runs, as for Spree's own
+      # payment webhooks.
+      #
+      WAIT = 30.seconds
+
+      ##
+      # How to record a payment's PayPal refunds by hand.
+      #
+      BY_HAND = "record them with bin/rails 'spree:paypal_merchant:sync_refunds[<order number>]'"
+
+      queue_as Spree.queues.payment_webhooks
+
+      retry_on SyncRefunds::PaypalUnavailable, wait: :polynomially_longer, attempts: 5
+
+      retry_on SyncRefunds::RefundInProgress, wait: 30.seconds, attempts: 5 do |_job, error|
+        Rails.logger.warn("[spree-paypal_merchant] PayPal refunds not synced: #{error.message}. Once it settles, #{BY_HAND}.")
+      end
+
+      # PayPal refused to show the payment's order or capture. Asking again
+      # changes nothing.
+      discard_on Spree::Core::GatewayError do |_job, error|
+        Rails.logger.warn("[spree-paypal_merchant] PayPal refunds not synced: #{error.message}. Once resolved, #{BY_HAND}.")
+      end
+
+      discard_on ActiveRecord::RecordNotFound
+
+      ##
+      # @param payment_id [Integer] a payment of a {Gateway}
+      # @return [SyncRefunds::Result]
+      #
+      def perform(payment_id:)
+        payment = Spree::Payment.find(payment_id)
+        Spree::Current.store = payment.payment_method.store
+
+        SyncRefunds.new(payment: payment).call
+      end
+    end
+  end
+end

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

@@ -41,15 +41,24 @@ module Spree
         # A pending capture settles as a payment that is not completed yet; the
         # COMPLETED event then completes that same payment.
         #
+        # A refund is not among them ({REFUND_EVENT}): it never cancels a
+        # session.
+        #
         WEBHOOK_ACTIONS = {
           'PAYMENT.CAPTURE.COMPLETED' => :captured,
           'PAYMENT.CAPTURE.PENDING' => :authorized,
           'PAYMENT.CAPTURE.DENIED' => :failed,
           'PAYMENT.CAPTURE.DECLINED' => :failed,
-          'PAYMENT.CAPTURE.REVERSED' => :canceled,
-          'PAYMENT.CAPTURE.REFUNDED' => :canceled
+          'PAYMENT.CAPTURE.REVERSED' => :canceled
         }.freeze
 
+        ##
+        # The event PayPal sends for a refund of a capture, however it was
+        # made. Its resource is the refund, which links up to its capture.
+        # The gem records the refund itself ({SyncRefundsJob}).
+        #
+        REFUND_EVENT = 'PAYMENT.CAPTURE.REFUNDED'
+
         ##
         # @return [TrueClass, FalseClass]
         #
@@ -227,7 +236,7 @@ module Spree
         end
 
         ##
-        # Reads a PayPal order, including its captures.
+        # Reads a PayPal order, including its captures and refunds.
         #
         # @param paypal_order_id [String]
         # @return [PaypalServerSdk::ApiResponse]
@@ -236,6 +245,29 @@ module Spree
           client.orders.get_order('id' => paypal_order_id, 'prefer' => 'return=representation')
         end
 
+        ##
+        # Reads a PayPal capture, which names its order.
+        #
+        # @param capture_id [String]
+        # @return [PaypalServerSdk::ApiResponse]
+        #
+        def fetch_paypal_capture(capture_id)
+          client.payments.get_captured_payment('capture_id' => capture_id)
+        end
+
+        ##
+        # Whether PayPal definitely refused the request. A server error, or a
+        # client error in {AMBIGUOUS_CLIENT_ERROR_STATUSES}, leaves the outcome
+        # unknown, and asking again later may succeed.
+        #
+        # @param error [PaypalServerSdk::APIException]
+        # @return [TrueClass, FalseClass]
+        #
+        def paypal_refusal?(error)
+          status = error.response_code.to_i
+          status.between?(400, 499) && AMBIGUOUS_CLIENT_ERROR_STATUSES.exclude?(status)
+        end
+
         ##
         # Parses an incoming PayPal webhook into a payment-session action.
         #
@@ -244,6 +276,10 @@ module Spree
         # with this method, and for a session settled before Spree 6 (see
         # {#settled_before_spree_6?}).
         #
+        # A refund ({REFUND_EVENT}) also returns nil, once the signature has
+        # been checked: the gem enqueues {SyncRefundsJob} for the payment of
+        # this method the refund is about, if it knows one.
+        #
         # @param raw_body [String]
         # @param headers [Hash]
         # @return [Hash, NilClass]
@@ -253,10 +289,12 @@ module Spree
           verify_webhook_signature!(raw_body, headers)
 
           event = JSON.parse(raw_body).with_indifferent_access
+          resource = event[:resource] || {}
+          return sync_refunds_later(resource) if event[:event_type] == REFUND_EVENT
+
           action = WEBHOOK_ACTIONS[event[:event_type]]
           return nil unless action
 
-          resource = event[:resource] || {}
           paypal_order_id = resource.dig('supplementary_data', 'related_ids', 'order_id')
           return nil unless paypal_order_id
 
@@ -271,6 +309,66 @@ module Spree
 
         private
 
+        ##
+        # Enqueues {SyncRefundsJob} for the payment a PayPal refund is about.
+        # The refund only names the payment: the job reads its refunds from
+        # PayPal.
+        #
+        # @param refund [Hash] the event's resource, a PayPal refund
+        # @return [NilClass] so Spree enqueues no payment-session action
+        #
+        def sync_refunds_later(refund)
+          payment = payment_for_paypal_refund(refund)
+          SyncRefundsJob.set(wait: SyncRefundsJob::WAIT).perform_later(payment_id: payment.id) if payment
+
+          nil
+        end
+
+        ##
+        # The payment of this method a PayPal refund is about. The refund links
+        # up to its capture, and may name its order. A payment settled on Spree
+        # 6 holds the PayPal order id as its response code and the capture id
+        # on its metadata; one taken on 5.x holds the capture id as its
+        # response code.
+        #
+        # Response codes are searched first. The metadata is searched only
+        # when none matches: its expression has no index, so it reads every
+        # payment of the method.
+        #
+        # @param refund [Hash] a PayPal refund, as JSON
+        # @return [Spree::Payment, NilClass]
+        #
+        def payment_for_paypal_refund(refund)
+          related_ids = refund.dig('supplementary_data', 'related_ids') || {}
+          capture_id = PaypalMerchant.linked_id(refund['links'], rel: 'up', path: 'v2/payments/captures').presence ||
+                       related_ids['capture_id'].presence
+          response_codes = [related_ids['order_id'].presence, capture_id].compact
+          return if response_codes.empty?
+
+          payments = Spree::Payment.where(payment_method_id: id).order(:id)
+          payment = payments.find_by(response_code: response_codes)
+          return payment if payment || capture_id.nil?
+
+          payments.find_by(recorded_capture_id_sql, capture_id)
+        end
+
+        ##
+        # Matches the capture id Spree 6 settlement records on a payment's
+        # metadata, which is jsonb on PostgreSQL and json elsewhere. The
+        # expressions are the ones Spree's own metadata specs use.
+        #
+        # @return [String] SQL with one bind for the capture id
+        #
+        def recorded_capture_id_sql
+          column = "#{Spree::Payment.quoted_table_name}.#{Spree::Payment.connection.quote_column_name('metadata')}"
+
+          if Spree::Payment.connection.adapter_name.match?(/postg/i)
+            "#{column}->>'paypal_capture_id' = ?"
+          else
+            "JSON_EXTRACT(#{column}, '$.paypal_capture_id') = ?"
+          end
+        end
+
         ##
         # PayPal captures at checkout. Only this method's own capture method
         # can refuse it: a store-wide default never switches PayPal off.
@@ -333,19 +431,6 @@ module Spree
           fetch_paypal_order(paypal_order_id)
         end
 
-        ##
-        # Whether PayPal definitely refused the request. A server error, or a
-        # client error in {AMBIGUOUS_CLIENT_ERROR_STATUSES}, leaves the outcome
-        # unknown.
-        #
-        # @param error [PaypalServerSdk::APIException]
-        # @return [TrueClass, FalseClass]
-        #
-        def paypal_refusal?(error)
-          status = error.response_code.to_i
-          status.between?(400, 499) && AMBIGUOUS_CLIENT_ERROR_STATUSES.exclude?(status)
-        end
-
         ##
         # @param error [PaypalServerSdk::ErrorException]
         # @param issue [String] a PayPal error issue code

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

@@ -113,6 +113,36 @@ module Spree
 
       validates :preferred_client_id, :preferred_client_secret, presence: true
 
+      ##
+      # PayPal's mark (a square SVG, as PayPal publishes it), shipped with the
+      # gem and read once into a data URI. The dashboard then needs no asset
+      # pipeline, and fetches the logo from no other host.
+      #
+      LOGO_PATH = File.expand_path('../../../../lib/spree/paypal_merchant/paypal-mark.svg', __dir__)
+
+      ##
+      # @see LOGO_PATH
+      #
+      LOGO_DATA_URI = "data:image/svg+xml;base64,#{[File.binread(LOGO_PATH)].pack('m0')}".freeze
+
+      ##
+      # The logo on this payment method's card under Settings -> Integrations.
+      #
+      # @return [String] {LOGO_DATA_URI}
+      #
+      def self.logo_url
+        LOGO_DATA_URI
+      end
+
+      ##
+      # The setup guide the card links to.
+      #
+      # @return [String]
+      #
+      def self.docs_url
+        'https://github.com/aypex-io/spree-paypal_merchant#readme'
+      end
+
       ##
       # @return [Class]
       #
@@ -194,12 +224,19 @@ module Spree
       end
 
       ##
-      # @return [String, NilClass]
+      # The URL to give PayPal for this method's webhooks, on the store's own
+      # host. It is absolute, and https in production, as PayPal requires.
+      #
+      # When the Spree API is served from another host than the store's URL
+      # (a headless storefront on its own domain, say), PayPal must be given
+      # the API host instead, with the same path.
+      #
+      # @return [String, NilClass] nil without a store
       #
       def webhook_url
         return nil unless store
 
-        "#{store.url_or_custom_domain}/api/v3/webhooks/payments/#{prefixed_id}"
+        "#{store.formatted_url}/api/v3/webhooks/payments/#{prefixed_id}"
       end
 
       ##

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

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+module Spree
+  module PaypalMerchant
+    ##
+    # Records in Spree the refunds PayPal holds for one of the gateway's
+    # payments, such as a refund made in PayPal's dashboard, which never passes
+    # through Spree.
+    #
+    # The refunds are read from PayPal, never from the event that prompted the
+    # sync: PayPal's order for the payment lists the refunds of its capture.
+    # Each COMPLETED one that no Spree::Refund on the payment holds (by its
+    # PayPal refund id, as the refund's transaction id) is recorded the way
+    # Spree's refund workflow records a refund, with the PayPal refund id
+    # already set, so Spree never asks PayPal to refund it again. Running it
+    # again records nothing new.
+    #
+    # Not recorded, and reported (logged as a warning where it needs a look):
+    # - a refund already recorded, including one made in Spree;
+    # - a refund PayPal has not completed (PENDING, FAILED, CANCELLED);
+    # - a refund in another currency than the payment's;
+    # - a refund for more than is left to refund on the payment;
+    # - every refund, when the store has no refund reason;
+    # - every refund, when the payment is not completed, or covers several
+    #   orders.
+    #
+    class SyncRefunds
+      ##
+      # A refund made in Spree on the payment has no PayPal refund id yet:
+      # Spree has asked PayPal for it and not stored PayPal's answer. The
+      # refund PayPal reports may be that one, so nothing is recorded until it
+      # settles.
+      #
+      class RefundInProgress < StandardError; end
+
+      ##
+      # PayPal could not be reached, did not answer in time, or answered with
+      # an error that can pass. Reading it again later may succeed.
+      #
+      class PaypalUnavailable < StandardError; end
+
+      ##
+      # What a sync did.
+      #
+      # @!attribute [r] recorded
+      #   @return [Array<Spree::Refund>] the refunds recorded, oldest first
+      # @!attribute [r] skipped
+      #   @return [Array<String>] why each PayPal refund, or the whole
+      #     payment, was not recorded
+      #
+      Result = Data.define(:recorded, :skipped)
+
+      ##
+      # The relation a PayPal refund's link to its capture has, and the one a
+      # capture's link to its order has.
+      #
+      UP = 'up'
+
+      ##
+      # @param payment [Spree::Payment] a payment of a {Gateway}
+      # @raise [ArgumentError] when the payment is not one of a {Gateway}'s
+      #
+      def initialize(payment:)
+        @payment = payment
+        @gateway = payment.payment_method
+        @skipped = []
+
+        raise ArgumentError, "payment #{payment.number} is not a PayPal payment" unless gateway.is_a?(Gateway)
+      end
+
+      ##
+      # Reads PayPal, then records what Spree is missing. PayPal is read
+      # before the payment is locked, so the lock holds across no PayPal I/O.
+      #
+      # @return [Result]
+      # @raise [RefundInProgress] when a refund made in Spree on the payment
+      #   has no PayPal refund id yet
+      # @raise [PaypalUnavailable] when PayPal cannot be read for now
+      # @raise [Spree::Core::GatewayError] when PayPal refuses to show the
+      #   payment's order or capture
+      #
+      def call
+        return result([]) if payment_not_synced?
+
+        paypal_refunds = read_paypal_refunds
+        recorded = payment.with_lock { record(paypal_refunds) }
+        announce(recorded)
+
+        result(recorded)
+      end
+
+      private
+
+      attr_reader :payment, :gateway
+
+      # Whether the payment is not one to sync, noting why. Asked before
+      # PayPal is read, and again once the payment is locked and read afresh.
+      def payment_not_synced?
+        why_not = why_payment_not_synced
+        note(:warn, "PayPal refunds not synced for payment #{payment.number}: #{why_not}") if why_not
+
+        why_not.present?
+      end
+
+      # As Spree's refund workflow: only a completed payment is refunded, and
+      # a payment shared by a split checkout needs to be told which order a
+      # refund puts right.
+      def why_payment_not_synced
+        return "it is #{payment.status}, and only a completed payment can be refunded" unless payment.completed?
+
+        'it covers several orders, so the order each refund is for has to be chosen by hand' if payment.grouped?
+      end
+
+      # Runs inside the payment's lock, which Spree's refund workflow also
+      # takes to create a refund. Two syncs for one payment (two partial
+      # refunds reported together) take turns, and the second finds what the
+      # first recorded. Everything that decides what is recorded is checked
+      # here, on the payment as the lock read it: PayPal was read before the
+      # lock, and the payment may have been voided, or refunded, meanwhile.
+      def record(paypal_refunds)
+        return [] if payment_not_synced?
+
+        ensure_no_refund_in_progress!
+
+        unrecorded = paypal_refunds.select { |paypal_refund| unrecorded_and_completed?(paypal_refund) }
+        return [] if unrecorded.empty?
+
+        reason = refund_reason
+        if reason.nil?
+          unrecorded.each { |paypal_refund| skip(paypal_refund, 'the store has no refund reason; add one, then sync again') }
+          return []
+        end
+
+        unrecorded.filter_map { |paypal_refund| record_refund(paypal_refund, reason) }
+      end
+
+      def ensure_no_refund_in_progress!
+        return unless payment.refunds.exists?(transaction_id: [nil, ''])
+
+        raise RefundInProgress, "Payment #{payment.number} has a refund made in Spree that PayPal has not confirmed yet"
+      end
+
+      # A refund with no PayPal id is never recorded: the id is what keeps it
+      # from being recorded twice, and a blank transaction id would read as a
+      # refund still in progress.
+      def unrecorded_and_completed?(paypal_refund)
+        if paypal_refund['id'].blank?
+          skip(paypal_refund, 'PayPal gives it no id')
+          false
+        elsif payment.refunds.exists?(transaction_id: paypal_refund['id'])
+          note(:info, "#{describe(paypal_refund)} already recorded on payment #{payment.number}")
+          false
+        elsif paypal_refund['status'] != 'COMPLETED'
+          skip(paypal_refund, "it is #{paypal_refund['status'] || 'without a status'} at PayPal", level: :info)
+          false
+        else
+          true
+        end
+      end
+
+      # Created as Spree's refund workflow creates a refund (its own order,
+      # no refunder, no originator), with the PayPal refund id as the
+      # transaction id that the workflow would otherwise get from PayPal.
+      def record_refund(paypal_refund, reason)
+        amount = paypal_refund.dig('amount', 'value').to_d
+        currency = paypal_refund.dig('amount', 'currency_code')
+        left = payment.credit_allowed
+
+        return skip(paypal_refund, "the payment is in #{payment.currency}") if currency != payment.currency
+        return skip(paypal_refund, 'PayPal shows no amount') unless amount.positive?
+        return skip(paypal_refund, "only #{money(left)} is left to refund on the payment") if amount > left
+
+        payment.refunds.create!(
+          amount: amount,
+          order: payment.order,
+          reason: reason,
+          transaction_id: paypal_refund['id'],
+          metadata: provenance(paypal_refund)
+        )
+      end
+
+      # What Spree::Refund#perform! and the refund workflow do once PayPal
+      # has made a refund: the order's totals are summed again, and the
+      # payment announces the refund. The refund's own created event has
+      # already updated the order's payment state.
+      def announce(recorded)
+        return if recorded.empty?
+
+        payment.order&.recalculate_totals!
+        recorded.each { payment.publish_event('payment.refunded') }
+      end
+
+      # The reason Spree's refund workflow gives a refund named without one
+      # ("Return processing"), or else the store's first by name, as Spree's
+      # admin API does. Found, never created.
+      def refund_reason
+        reasons = Spree::RefundReason.where(store: payment.owner&.store || gateway.store)
+
+        reasons.find_by(name: Spree::RefundReason::RETURN_PROCESSING_REASON) || reasons.first
+      end
+
+      def provenance(paypal_refund)
+        {
+          'recorded_from' => 'paypal',
+          'paypal_refund_id' => paypal_refund['id'],
+          'paypal_capture_id' => capture_id,
+          'paypal_create_time' => paypal_refund['create_time']
+        }.compact
+      end
+
+      # The refunds of the payment's capture, oldest first. PayPal's order
+      # lists them by purchase unit; a refund that names no capture is the
+      # capture's, as the gem makes one capture per PayPal order.
+      def read_paypal_refunds
+        paypal_order = gateway.fetch_paypal_order(paypal_order_id).data.as_json
+
+        Array(paypal_order['purchase_units'])
+          .flat_map { |purchase_unit| Array(purchase_unit.dig('payments', 'refunds')) }
+          .select { |paypal_refund| [nil, capture_id].include?(PaypalMerchant.linked_id(paypal_refund['links'], rel: UP, path: 'v2/payments/captures')) }
+          .sort_by { |paypal_refund| paypal_refund['create_time'].to_s }
+      rescue PaypalServerSdk::APIException => e
+        raise PaypalUnavailable, "PayPal answered #{e.response_code}" unless gateway.paypal_refusal?(e)
+
+        raise Spree::Core::GatewayError, "PayPal refused to show payment #{payment.number} (HTTP #{e.response_code}): #{e.message}"
+      rescue *Gateway::UNKNOWN_OUTCOME_ERRORS => e
+        raise PaypalUnavailable, "PayPal could not be read: #{e.message}"
+      end
+
+      # The capture, as {Gateway#credit} finds it: on the metadata of a
+      # payment settled on Spree 6, or the response code of one taken on 5.x.
+      def capture_id
+        @capture_id ||= payment.metadata['paypal_capture_id'].presence || payment.response_code
+      end
+
+      # A payment settled on Spree 6 holds the PayPal order id as its response
+      # code. One taken on 5.x holds the capture id there instead, and
+      # PayPal's capture names its order.
+      def paypal_order_id
+        return payment.response_code if payment.metadata['paypal_capture_id'].present?
+
+        paypal_capture = gateway.fetch_paypal_capture(capture_id).data.as_json
+        order_id = paypal_capture.dig('supplementary_data', 'related_ids', 'order_id').presence ||
+                   PaypalMerchant.linked_id(paypal_capture['links'], rel: UP, path: 'v2/checkout/orders')
+        return order_id if order_id.present?
+
+        raise Spree::Core::GatewayError, "PayPal capture #{capture_id} names no PayPal order"
+      end
+
+      def skip(paypal_refund, why, level: :warn)
+        note(level, "#{describe(paypal_refund)} not recorded on payment #{payment.number}: #{why}")
+        nil
+      end
+
+      def note(level, message)
+        @skipped << message
+        Rails.logger.public_send(level, "[spree-paypal_merchant] #{message}")
+      end
+
+      def describe(paypal_refund)
+        amount = "of #{paypal_refund.dig('amount', 'value')} #{paypal_refund.dig('amount', 'currency_code')}"
+
+        ['PayPal refund', paypal_refund['id'].presence, amount].compact.join(' ')
+      end
+
+      def money(amount)
+        "#{Spree::Money::Rounding.format(amount, payment.currency)} #{payment.currency}"
+      end
+
+      def result(recorded)
+        Result.new(recorded: recorded, skipped: @skipped)
+      end
+    end
+  end
+end

data/lib/spree/paypal_merchant/paypal-mark.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 48 48"><g clip-path="url(#a)"><path fill="#002991" d="M38.914 13.35c0 5.574-5.144 12.15-12.927 12.15H18.49l-.368 2.322L16.373 39H7.056l5.605-36h15.095c5.083 0 9.082 2.833 10.555 6.77a9.687 9.687 0 0 1 .603 3.58z"/><path fill="#60CDFF" d="M44.284 23.7A12.894 12.894 0 0 1 31.53 34.5h-5.206L24.157 48H14.89l1.483-9 1.75-11.178.367-2.322h7.497c7.773 0 12.927-6.576 12.927-12.15 3.825 1.974 6.055 5.963 5.37 10.35z"/><path fill="#008CFF" d="M38.914 13.35C37.31 12.511 35.365 12 33.248 12h-12.64L18.49 25.5h7.497c7.773 0 12.927-6.576 12.927-12.15z"/></g><defs><clipPath id="a"><path fill="#fff" d="M7.056 3h37.35v45H7.056z"/></clipPath></defs></svg>

data/lib/spree/paypal_merchant/version.rb

@@ -4,6 +4,6 @@ module Spree
   module PaypalMerchant
     # Major version tracks Spree's major version: 6.x supports Spree 6.
     # 5.2.x supports Spree 5.6 and lives on the `5-2-stable` branch.
-    VERSION = '6.0.0'
+    VERSION = '6.0.1'
   end
 end

data/lib/spree/paypal_merchant.rb

@@ -28,5 +28,28 @@ module Spree
     def self.gateway_type_names
       ([Gateway.name] + Gateway.descendants.map(&:name)).uniq
     end
+
+    ##
+    # The id a PayPal resource's link names. PayPal links a refund to its
+    # capture, and a capture to its order, with an +up+ link such as
+    # +https://api.paypal.com/v2/payments/captures/<id>+.
+    #
+    # @param links [Array<Hash>, NilClass] the resource's +links+, as JSON
+    # @param rel [String] the link's relation, such as +up+
+    # @param path [String] what precedes the id, such as +v2/payments/captures+
+    # @return [String, NilClass] nil when no such link names an id
+    #
+    def self.linked_id(links, rel:, path:)
+      pattern = %r{/#{Regexp.escape(path)}/([^/?#]+)\z}
+
+      Array(links).each do |link|
+        next unless link.respond_to?(:to_h) && link.to_h.with_indifferent_access[:rel] == rel
+
+        id = link.to_h.with_indifferent_access[:href].to_s[pattern, 1]
+        return id if id.present?
+      end
+
+      nil
+    end
   end
 end

data/lib/tasks/spree_paypal_merchant.rake

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+namespace :spree do
+  namespace :paypal_merchant do
+    desc "Record in Spree the refunds made in PayPal for an order's PayPal payments, e.g. before the webhook was set up"
+    task :sync_refunds, [:order_number] => :environment do |_task, args|
+      order_number = args[:order_number].to_s.strip
+      abort "Usage: bin/rails 'spree:paypal_merchant:sync_refunds[<order number>]'" if order_number.empty?
+
+      order = Spree::Order.find_by(number: order_number)
+      abort "No order #{order_number}" if order.nil?
+
+      Spree::Current.store = order.store
+      payments = order.payments.order(:id).select { |payment| payment.payment_method.is_a?(Spree::PaypalMerchant::Gateway) }
+      puts "Order #{order_number} has no PayPal payments." if payments.empty?
+
+      payments.each do |payment|
+        result = Spree::PaypalMerchant::SyncRefunds.new(payment: payment).call
+
+        puts "Payment #{payment.number}:"
+        result.recorded.each { |refund| puts "  recorded PayPal refund #{refund.transaction_id} (#{refund.display_amount})" }
+        result.skipped.each { |message| puts "  #{message}" }
+        puts '  no PayPal refunds' if result.recorded.empty? && result.skipped.empty?
+      rescue Spree::PaypalMerchant::SyncRefunds::RefundInProgress, Spree::PaypalMerchant::SyncRefunds::PaypalUnavailable,
+             Spree::Core::GatewayError => e
+        puts "Payment #{payment.number}: not synced: #{e.message}"
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: spree-paypal_merchant
 version: !ruby/object:Gem::Version
-  version: 6.0.0
+  version: 6.0.1
 platform: ruby
 authors:
 - Aypex
@@ -133,6 +133,7 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- app/jobs/spree/paypal_merchant/sync_refunds_job.rb
 - app/models/spree/payment_sessions/paypal_merchant.rb
 - app/models/spree/paypal_merchant/gateway.rb
 - app/models/spree/paypal_merchant/gateway/payment_sessions.rb
@@ -144,6 +145,7 @@ files:
 - app/presenters/spree/paypal_merchant/order_presenter.rb
 - app/serializers/spree/api/v3/payment_method_serializer_decorator.rb
 - app/services/spree/paypal_merchant/create_source.rb
+- app/services/spree/paypal_merchant/sync_refunds.rb
 - config/initializers/spree.rb
 - db/migrate/20250528095719_create_spree_paypal_merchant_orders.rb
 - db/migrate/20261003120000_rename_spree_paypal_platform_to_paypal_merchant.rb
@@ -152,7 +154,9 @@ files:
 - lib/spree/paypal_merchant.rb
 - lib/spree/paypal_merchant/engine.rb
 - lib/spree/paypal_merchant/factories.rb
+- lib/spree/paypal_merchant/paypal-mark.svg
 - lib/spree/paypal_merchant/version.rb
+- lib/tasks/spree_paypal_merchant.rake
 homepage: https://github.com/aypex-io/spree-paypal_merchant
 licenses:
 - MIT