spree-paypal_merchant 5.2.0 → 6.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab60916880d1d5bea9ba2921266c7780011afe124111ced6ec568ea290749f3c
-  data.tar.gz: 05320b99c8cc4f7f077d9e99761618a05a61ef4a730f412094b4fd705f055469
+  metadata.gz: d09d026a692438a7e89cd1eb47700bc34fb8ef077da6475c94dd61471e70dfed
+  data.tar.gz: fca83a3ef6cfb0bb6e27851d65c0ae0daa35b414506acc25218246bbe0a0c19a
 SHA512:
-  metadata.gz: dd1331f42e0599a7ab58d7271a9f7d85b3d37375c3e5e8b7e5004a72953cff2b6f34ff4c7373c9479d06b442659acc2857c80858479fa21ad6491ad5ed4da2eb
-  data.tar.gz: 38b28e6801bdb7e982cd286a547739a8b44605f6a1a1e524f8680df647a7cf2f955c7b34d247cb11e81b0ccc78d03fcac2cf89091cd5024e51defb660e51f18c
+  metadata.gz: 765ffdaf6c95115be5c8f51cf31d42b1c3e171ff0cef1435abff604112735d45eae3051dde53ce5da75d6bb52f29108d6b7c811e02b834f997cef954f2c115c8
+  data.tar.gz: 3ddd64eabd1c28835cd4c4760f1c375ede3c45d9dc7251ab69be6f478703633f83f193d4f3498ac13aa7b92c8ea827d12e51e8ceb7f09e9b6a6a65f271c809c2

data/CHANGELOG.md

@@ -1,5 +1,221 @@
 # 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
+on 5.2.x, on the `5-2-stable` branch. To upgrade, see "Upgrading from 5.2" in
+the README.
+
+The storefront contract is unchanged. The Store API type is still
+`paypal_merchant`, and the payment session's `external_data` and the payment
+method's `public_preferences` keep their keys.
+
+### Requirements
+
+- Spree `~> 6.0` and Ruby 3.3 or newer.
+- The `spree_admin` dependency is gone. Spree 6 has no Rails admin; its
+  dashboard builds the settings form from the gateway's preferences.
+- `faraday` (`~> 2.0`) and `net-http-persistent` (`~> 4.0`) are declared. The
+  gem uses both directly; before, they came only through `paypal-server-sdk`.
+
+### Checkout
+
+- Sessions belong to the cart. The amount is the cart total less store
+  credit and gift cards. A zero amount raises `Spree::Core::GatewayError`.
+- A session's amount can't change once its PayPal order exists. Updating a
+  session with a different amount raises `Spree::Core::GatewayError` (a 422
+  from the Store API) telling the storefront to create a new session, and
+  `external_data` sent by the client is not stored. The payment records the
+  amount PayPal captured, not the session's. Before, a client could change the
+  amount, and a cart with store credit could be placed as paid in full while
+  PayPal took less and the store credit went unspent.
+- A payment source Spree refuses no longer blocks settlement. Spree keeps a
+  source's profile id unique per source type, not per payment method, so a
+  PayPal account that already had a source under another PayPal method (a
+  second store, a recreated method) made settlement fail after PayPal took
+  the money, and every retry failed the same way. The payment now settles
+  without a source, and the refusal is logged.
+- The storefront's confirm call and PayPal's webhook settle through Spree 6's
+  shared path, in either order, and produce one payment. A webhook that arrives
+  first reads PayPal's order, creates the payment and completes the cart.
+- Settlement reads the capture, not the order. PayPal can report an order as
+  `COMPLETED` whose capture was declined, as can happen with Card Fields.
+
+  | Capture status | Result |
+  |---|---|
+  | `COMPLETED` | A captured payment |
+  | `PENDING` | A pending payment; the `COMPLETED` event completes it later |
+  | `DECLINED`, `FAILED`, none | The session fails; no payment is created |
+
+  5.2.0 treated a pending capture as paid.
+- `PAYMENT.CAPTURE.PENDING` (an eCheck, say) leaves the Spree payment pending.
+  `PAYMENT.CAPTURE.COMPLETED` completes it.
+- A webhook settles only when PayPal's order shows the capture `COMPLETED`,
+  `PENDING` or `PARTIALLY_REFUNDED`. If PayPal's order can't be read, or shows
+  none of these, the event is dropped. Spree does not retry it and PayPal does not resend it. See the
+  README.
+- `CHECKOUT.ORDER.APPROVED` is ignored. An approved order holds no capture.
+- A webhook for a checkout settled under 5.x is ignored, so it can't create a
+  second payment.
+- A session that can no longer be used is never captured. Confirming one that
+  was canceled or failed, or whose cart is already a placed order, is refused.
+  This stops a stale browser tab from paying twice.
+- Creating a session cancels the cart's earlier open PayPal sessions. It
+  raises if one of them is already completed.
+- If a capture gets no clear answer from PayPal, the session stays open. A
+  retry reads the order first, so a capture that went through is settled, not
+  repeated.
+- PayPal captures at checkout, whatever the store's default capture method is.
+  A payment method whose own capture method is `on_dispatch` or `manual` is
+  refused. The gateway's capture method is always `checkout`, so a store that
+  defaults to `on_dispatch` or `manual` never captures a PayPal payment on
+  dispatch, and never ships an unpaid PayPal order as one left for staff.
+- Canceling a payment session is refused while PayPal's capture is `PENDING`,
+  `COMPLETED` or `PARTIALLY_REFUNDED`, because money has moved or is on its
+  way. Otherwise it cancels.
+- The gateway customer profile is looked up by the owner's customer. An owner
+  with no customer (a guest) gets none.
+
+### Refunds and cancels
+
+- A refund reads the capture id from the payment. A payment taken on 5.x
+  refunds as before, through its response code.
+- Refund amounts follow the currency's decimals, so a yen refund has none.
+- When a refund's outcome is unknown (a timeout or connection error), the
+  refund fails with a message telling the admin to check PayPal before
+  retrying. PayPal may have issued it.
+- A refund that PayPal reports as `FAILED` or `CANCELLED` fails. A `PENDING`
+  refund is recorded.
+- Canceling a completed payment refunds it through Spree's refund workflow,
+  unless told to keep the money.
+- Void and cancel refuse a payment PayPal may still complete (checkout,
+  pending or processing state), with a "still processing" message. Capture
+  settles it as PayPal did, or refund it once PayPal completes it.
+- Capture in the dashboard reads PayPal and never captures again. A
+  `COMPLETED` capture completes the payment, and a denied or declined one fails
+  it. While PayPal is still processing the capture, or can't be read, Capture
+  says so and leaves the payment pending, so it can be pressed again. It takes
+  the whole payment only, since PayPal captured it all at checkout.
+- Spree's checkout processing can't authorize or purchase with this gateway.
+  It fails, saying PayPal payments are taken through a payment session.
+  Before, it raised `ActiveModel::UnknownAttributeError`.
+- Canceling an order with Spree's default (`refund_payments: false`) marks a
+  completed PayPal payment void in Spree while PayPal keeps the money. Refund
+  it before canceling, or refund it in PayPal.
+- A failed, void or invalid payment cancels in Spree with no PayPal call.
+- Void always fails. PayPal payments are captured at checkout, so there is
+  nothing to void: refund the payment instead.
+
+### Order payload
+
+- Every discount counts, promotion and manual.
+- A free-shipping discount goes in PayPal's `shipping_discount`.
+- Fees go in `handling`.
+- Amounts are rounded with Spree's currency rules, so a unit price with four
+  decimals is sent with the currency's own.
+- Line items are left out when they don't add up to the item total. The buyer
+  sees no itemised list in PayPal for that order only. With two-decimal prices
+  it never happens.
+- When the breakdown can't balance, or has a negative figure, only the amount
+  is sent.
+- The breakdown still sends only `additional_tax_total`.
+
+### Timeouts and retries
+
+- Every Orders and Payments API request has a 15-second timeout. The
+  gem's own webhook-verification and token requests time out after 5 seconds
+  to connect and 10 to read.
+- PayPal reads (GET) are retried up to 3 times. Only GET and PUT are
+  retried, and the client says so explicitly.
+- Creating, capturing and refunding are never re-sent automatically.
+- A PayPal server error whose body isn't JSON (an HTML 502 page, say) is
+  treated like a timeout: PayPal may have acted. A refund fails with the
+  message to check PayPal before retrying, a confirm leaves the session open,
+  and Capture leaves the payment pending. Before, the SDK's `TypeError`
+  escaped, and the refund failed with a generic error.
+- The webhook signature check treats more transient failures as a failed
+  check: a reset connection, a TLS error, a broken HTTP exchange. Spree answers
+  401 and PayPal sends the event again. The Card Fields token request handles
+  the same failures by creating the session without a token.
+- A PayPal error with no message of its own is reported with PayPal's issue
+  descriptions.
+
+### Payment sources
+
+- The PayPal, Apple Pay and card sources store their fields in `metadata`
+  (Spree 6 merged `private_metadata` into it). The accessors keep their names.
+- A PayPal wallet with no PayPal account id is keyed by the cart's (or
+  order's) prefixed id instead of the order number, so a 5.x source of that
+  kind isn't reused.
+
+### Removed
+
+- The 5.x checkout flow: `Spree::PaypalMerchant::Order`, `CreatePayment`,
+  `CaptureOrder`, the order's `paypal_id`, and the gateway's `find_order`. It
+  had no routes. The gateway's `authorize`, `purchase` and `capture` are
+  rewritten for Spree 6 (see "Refunds and cancels").
+- The ERB admin views and the `*_partial_name` hooks.
+- `Spree::PaypalMerchant::Base`, an abstract model class nothing inherits from
+  any more.
+- The `spree_paypal_merchant_orders` table stays, and no migration drops it in
+  this release.
+
+### Known limitations
+
+- PayPal treats HUF and TWD as zero-decimal currencies, but Spree formats them
+  with two decimals, so those currencies aren't supported.
+- Multi-seller checkouts, where one payment covers several orders, aren't
+  tested.
+- A payment the storefront confirmed on a cart it never completed isn't
+  placed by PayPal's later webhook. It has to be placed by hand.
+- If the webhook settles first and completing the cart then fails, Spree rolls
+  the payment back and the event is dropped. The storefront's confirm call
+  settles it instead.
+
 ## 5.2.0
 
 Renamed from `spree-paypal_platform`. Same code, new name.

data/README.md

@@ -1,6 +1,6 @@
 # spree-paypal_merchant
 
-PayPal Checkout for Spree 5.6+, as a single payment method covering the PayPal
+PayPal Checkout for Spree 6, as a single payment method covering the PayPal
 wallet, Apple Pay, and Card Fields.
 
 Published gem: **`spree-paypal_merchant`**  
@@ -11,6 +11,11 @@ This is not the official `spree_paypal_checkout` gem. It started from that
 extension (VAT `AMOUNT_MISMATCH` guard, storefront-owned address) and adds
 Apple Pay as a funding source of the same gateway.
 
+## Requirements
+
+Spree 6 (`spree ~> 6.0`) and Ruby 3.3 or newer. Spree 5.6 uses the 5.2.x
+releases, on the `5-2-stable` branch.
+
 ## What it is
 
 - One `Spree::PaypalMerchant::Gateway` payment method.
@@ -18,6 +23,16 @@ Apple Pay as a funding source of the same gateway.
   (`POST /api/v3/store/carts/:id/payment_sessions` → complete).
 - The storefront owns the address. The gem pins it with
   `SET_PROVIDED_ADDRESS` so PayPal does not re-collect it.
+- PayPal **captures at checkout**, whatever capture method the store defaults
+  to. Authorize now, capture later is not supported: a payment method whose own
+  capture method is `on_dispatch` or `manual` is refused. Spree never captures a
+  PayPal payment on dispatch, and never treats one as left for staff to collect.
+- A payment session's amount is fixed once its PayPal order exists. Changing
+  it is refused: the storefront creates a new session instead. The payment
+  records the amount PayPal captured.
+- The storefront's confirm call and PayPal's webhook settle through the same
+  Spree path, in either order. Whichever arrives first creates the payment; the
+  other changes nothing.
 - Amount breakdown sends **only `additional_tax_total`**. Sending full
   `tax_total` double-counts included VAT and trips PayPal `AMOUNT_MISMATCH`.
 - Talks to PayPal via the official
@@ -41,7 +56,7 @@ bin/rails g spree:paypal_merchant:install
 The generator copies the migrations. Pass `--auto-run-migrations` to skip the
 prompt.
 
-Then add a **PayPal** payment method in admin and set:
+Then add a **PayPal** payment method in the admin dashboard and set:
 
 | Preference | Purpose |
 |---|---|
@@ -51,12 +66,91 @@ Then add a **PayPal** payment method in admin 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.
+
+| Event | What the gem does |
+|---|---|
+| `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.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
+
+- **Capture** on a pending PayPal payment reads PayPal and settles the payment
+  the way PayPal did. It completes the payment if PayPal completed the capture,
+  and fails it if PayPal denied or declined it. It never captures again. While
+  PayPal is still processing the capture, or can't be reached, Capture says so
+  and the payment stays pending, so Capture can be pressed again. Capture takes
+  the whole payment: PayPal captured it all at checkout.
+- **Canceling an order** with Spree's default (`refund_payments: false`) marks
+  a completed PayPal payment void in Spree while PayPal keeps the money. Refund
+  the payment in the dashboard before canceling the order, or refund it in
+  PayPal.
+- **Void** always fails. A PayPal payment holds captured money, so refund it
+  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.
@@ -70,6 +164,64 @@ https://<store>/api/v3/webhooks/payments/<prefixed-payment-method-id>
    `Spree::PaypalMerchant::PaymentSources::ApplePay`.
 4. Safari + HTTPS only.
 
+## Upgrading from 5.2
+
+Bump the gem to `~> 6.0` as part of your Spree 6 upgrade.
+
+- **No data migration of the gem's own.** Payment methods, sources and
+  sessions keep their types. Spree's migrations move the sources' metadata.
+- **The webhook URL is unchanged.** `CHECKOUT.ORDER.APPROVED` is no longer
+  needed; the gem ignores it.
+- **PayPal captures at checkout, whatever the store default is.** A store whose
+  default capture method is `on_dispatch` still captures PayPal at checkout. Only
+  a PayPal payment method whose own capture method is `on_dispatch` or `manual`
+  is refused.
+- **Old payments refund as before.** A payment taken on 5.x refunds through the
+  capture id stored on it.
+- **The storefront contract is the same.** The Store API type,
+  `external_data` keys and `public_preferences` are unchanged. One thing is
+  refused: a session's amount can't be changed after it is created, so a
+  storefront that updated it must create a new payment session instead.
+- **The 5.x checkout flow is gone.** `Spree::PaypalMerchant::Order`,
+  `CreatePayment`, `CaptureOrder`, the order's `paypal_id` and the gateway's
+  `find_order` are removed, along with the ERB admin views. Spree 6 has no Rails
+  admin; its dashboard builds the settings form from the gateway's preferences.
+  The `spree_paypal_merchant_orders` table stays. The gateway's `authorize` and
+  `purchase` now fail, since PayPal payments are taken through a payment
+  session, and `capture` reads PayPal (see "In the dashboard").
+
+Three things to know before you cut over:
+
+1. **Webhooks are one-shot.** Spree 6 settles a payment webhook in a
+   background job and does not retry a failed one. PayPal does not send it
+   again, because Spree already answered 200. If the gem cannot read PayPal's
+   order, or the order shows no completed, pending or partly refunded capture,
+   that event is dropped. The storefront's confirm step, or a later PayPal event, settles the
+   payment instead.
+2. **Check PayPal for captures still pending** (an eCheck, say). Under 5.x a
+   pending capture was recorded as a completed payment. After the upgrade the
+   gem ignores later PayPal events for checkouts settled under 5.x, so if
+   PayPal denies or reverses one of those captures, Spree won't change. Handle
+   any that fail by hand.
+3. **A source's profile id can change.** A PayPal wallet with no PayPal account
+   id is now keyed by the cart's (or order's) prefixed id instead of the order
+   number. Such a source isn't reused, and a new one is created.
+
+## Known limitations
+
+- PayPal treats HUF and TWD as zero-decimal currencies, but Spree formats them
+  with two decimals, so those currencies aren't supported.
+- Multi-seller checkouts, where one payment covers several orders, aren't
+  tested.
+- If the storefront confirms the payment but never completes the cart (the
+  buyer closes the tab between the two calls), PayPal's later `COMPLETED`
+  event doesn't place the cart. That is Spree's design: a webhook places the
+  cart only when it is what settles the payment. The payment sits on an
+  unplaced cart, and the order has to be placed by hand.
+- If the webhook settles first and completing the cart then fails (stock, a
+  validation, tax), Spree rolls the payment back with it, and the one-shot event
+  is dropped. The storefront's confirm call settles the payment instead.
+
 ## Developing
 
 ```bash
@@ -78,7 +230,15 @@ bundle exec rake test_app
 bundle exec rspec
 ```
 
+Specs run against PostgreSQL (set `DATABASE_URL`). To test one Spree version,
+set `SPREE_VERSION`, for example `SPREE_VERSION=6.0.0 bundle update spree`. CI
+runs Spree 6.0.0 and the newest release, each on Ruby 3.3 and 4.0.
+
 ## License
 
 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/Rakefile

@@ -23,5 +23,6 @@ task :test_app do
   # "#{LIB_NAME.camelize}::Generators::InstallGenerator".
   ENV['LIB_NAME'] = 'spree/paypal_merchant'
   ENV['DB'] ||= 'postgres'
-  Rake::Task['extension:test_app'].execute(install_storefront: true, install_admin: true)
+  # Spree 6's extension:test_app takes no install_storefront/install_admin options.
+  Rake::Task['extension:test_app'].execute
 end

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