pay-whop 0.1.0.alpha.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 58ea5a5b9fdad1ae77611d95fab01fa1d5ed7b37b44ec6e9be9233b8b85735d5
+  data.tar.gz: a0e778f255afb610388a95f88cb8619fa2ca507e1e1c5fac6e6c7019edbc5e08
+SHA512:
+  metadata.gz: 307ca5fcfa6fafec82611cb257ae300395e43ca7791c37e8eae90681c2bd31b3b3f0702d244a6ff8a6de673cc1111d5a4c82f488d149b1cceafb80f542771974
+  data.tar.gz: c7c540c9b1d3e14fc5b3600938ee362665bc47c1d42c4b7296b43fcc874a6db3db69b771a2062eae9d24a03002a46e5a6ab8feabadeaf0c0c93df50f9b7d08bd

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 0.1.0.alpha.4
+
+- Keep reversed payouts terminal when overlapping reads return an older completed state, for both platform and seller payouts.
+
+## 0.1.0.alpha.3
+
+- Retry existing failed membership payments and expose environment-validated 3DS recovery links.
+- Add permitted renewal price reductions, billing period changes and next-renewal updates.
+- Add fresh merchant readiness/capability checks, ledger balances, scoped payout status and reversal handling.
+- Reconcile linked customer billing and merchant transfers/payouts; report unverifiable references without importing them.
+- Normalize adapter API failures under `Pay::Error`, retain provider status/type and avoid automatic write retries.
+- Deliver application webhook callbacks after synchronization; add payout and trial-ending events and reusable pending-delivery recovery.
+- Expand CI across Pay 12.3/12.4 and SQLite/PostgreSQL; smoke-test installation from the packaged gem in a fresh Rails app.
+- Extend the sandbox demo with failed-payment retry, reconciliation, recovery links and decline/3DS test instructions.
+
+Provider limitations remain: invoice issuance and transfers are blocked by this sandbox's verification; bank payouts are unavailable in sandbox. Plan swaps, recurring quantity and metering remain unsupported.
+
+## 0.1.0.alpha.2
+
+Initial community adapter for one-time/recurring checkout, verified webhooks, saved methods, direct payments, refunds, invoices, disputes, entitlements and marketplace subaccounts. Public Rails playground with separate invoice/transfer simulations.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yaroslav Shmarov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,178 @@
+# pay-whop
+
+Whop payments, recurring billing and marketplace subaccounts for [Pay](https://github.com/pay-rails/pay), the Ruby on Rails payments engine.
+
+**[Try the public sandbox demo →](https://pay-whop.onrender.com/)** — one-time payments, subscriptions, marketplace fees, saved methods and refunds with test money. Free hosting can take about a minute to wake up.
+
+The demo also includes **[invoice and transfer simulations](https://pay-whop.onrender.com/#simulations)**. Start a browser session, then try invoice issuance, overdue/payment/void outcomes and transfer success/failure. No Whop account or KYC is needed for these controls. They update separate demo records with `sim_` references and a visible activity history; they never call Whop, create Pay charges, grant subscription access or generate provider webhooks. Reset each flow to try another outcome. These simulations do not certify real invoice issuance or transfer settlement.
+
+**Early community adapter, not an official Whop or Pay integration.** Start in Whop's sandbox. The alpha supports direct billing and registered Whop subaccounts. Use one platform account and one environment per Rails database.
+
+```ruby
+user.set_payment_processor(:whop)
+
+checkout = user.payment_processor.checkout(
+  variant_id: "plan_...",
+  redirect_url: billing_url,
+  idempotency_key: checkout_attempt.id.to_s
+)
+redirect_to checkout.purchase_url, allow_other_host: true
+
+# After Whop's verified webhook has been processed:
+user.payment_processor.subscribed?
+user.payment_processor.subscription.cancel
+user.payment_processor.charges.last.refund!
+```
+
+## Status and scope
+
+| Capability | Status |
+| --- | --- |
+| Hosted checkout for an existing Whop variant | Implemented |
+| Link a Rails customer using signed checkout metadata | Implemented; never matched by email |
+| Recurring membership and successful payment synchronization | Implemented |
+| Cancel at period end, cancel immediately, reverse a pending cancellation | Implemented |
+| Full and partial refunds | Implemented; exact partial refund verified in sandbox |
+| Verified webhooks, duplicate record prevention, stale snapshot protection | Implemented |
+| Trial and past-due state synchronization | Implemented; provider behavior still needs sandbox coverage |
+| Pause/resume billing, one-time entitlements, free days and promo codes | Implemented; see provider-state caveats in the advanced guide |
+| Saved methods, direct charging, authorization/capture/void | Implemented; saved-method charging verified in sandbox |
+| Draft/issued invoices, invoice settlement and dispute workflows | Implemented; invoice issuance requires account verification |
+| Subaccounts, onboarding/payout links, application fees, transfers | Implemented; settlement depends on provider capabilities and available balance |
+| Existing-payment retry and 3DS recovery URL | Implemented; HTTP and demo error-path coverage |
+| Reduce renewal price, change billing period or next renewal date | Implemented within Whop restrictions; HTTP coverage |
+| Merchant capabilities, balances, payout status and reconciliation | Implemented; sandbox reads verified, bank payouts unavailable in sandbox |
+| Application webhook callbacks and pending-delivery recovery job | Implemented |
+| Plan swaps, proration, recurring seat changes, metered usage | Not supported |
+| Seller isolation under one platform | Implemented; never mix sandbox and production in one database |
+| One-time purchases | Implemented as Pay charges, not recurring subscriptions |
+
+See the [compatibility matrix](docs/compatibility.md) and [advanced usage](docs/advanced-usage.md) for one-time purchases, saved cards, invoices, marketplace fees and payouts, and dispute workflows.
+
+Unsupported adapter operations raise `Pay::NotSupportedError`. The SDK remains available through `Pay::Whop.client`, but SDK calls alone do not synchronize Pay records.
+
+Requires Ruby 3.3+, Pay 12.3–12.x, and `whop_sdk` 2.7.x. The bundled demo uses Rails 8.1. API requests and webhook registration use the dated API version `2026-10-28-1`. There is no RubyGems release yet.
+
+## Install in a Rails application
+
+Until published on RubyGems, install from GitHub:
+
+```ruby
+# Gemfile
+gem "pay-whop", git: "https://github.com/yshmarov/pay-whop", branch: "main"
+```
+
+Install both engines' migrations, including Pay's STI and object-column migrations:
+
+```sh
+bundle install
+bin/rails pay:install:migrations
+bin/rails pay_whop:install:migrations
+bin/rails db:migrate
+```
+
+Configure the adapter in an initializer. Keep credentials outside version control:
+
+```ruby
+Pay::Whop.configure do |config|
+  config.environment = ENV.fetch("WHOP_ENVIRONMENT", "sandbox")
+  config.api_key = ENV.fetch("WHOP_API_KEY")
+  config.account_id = ENV.fetch("WHOP_ACCOUNT_ID")
+  config.webhook_secret = ENV.fetch("WHOP_WEBHOOK_SECRET")
+end
+```
+
+Configure your billable model as usual:
+
+```ruby
+class User < ApplicationRecord
+  pay_customer
+end
+```
+
+The gem mounts `POST /pay/whop/webhooks`. For marketplaces, enable subaccount events on the platform webhook. Register a webhook on the same Whop account and API version, using the event names in `Pay::Whop::Delivery::EVENTS`. Supply its signing secret verbatim, including the `ws_` prefix.
+
+Use an Account API key with permissions for checkout configuration creation, member reads, membership reads/updates/cancellation, and payment reads/refunds. Product/variant and webhook-management permissions are needed only if your application provisions those resources. Whop's sandbox Admin role can create checkouts; its `accounts.me` endpoint additionally requires balance-read access, so the connection checker deliberately uses the checkout API.
+
+Run an Active Job worker. Production needs a durable queue adapter. The example uses PostgreSQL-backed GoodJob in production and the in-memory `:async` adapter for local development.
+
+## How synchronization works
+
+1. Checkout metadata contains a signed Pay customer ID, scoped to the seller account and environment. Treat the customer-specific checkout URL as private: Whop checkout configurations are reusable links, not single-use sessions.
+2. The webhook endpoint verifies Whop's signature and timestamp, checks the seller account, then persists the event ID, type and resource ID. It does not persist the raw webhook body.
+3. A job retrieves the current payment or membership from Whop. It verifies the account again and resolves the signed customer reference or an already-linked Whop member.
+4. Pay records are updated under a customer row lock. Provider `updated_at` values prevent older snapshots from overwriting newer ones. API calls run outside database transactions.
+5. Payment records become Pay charges only when their provider status is `paid`. A checkout redirect, pending payment or authorized card is not a paid charge.
+
+A Whop member can belong to only one Pay customer in this application. Conflicting links fail explicitly. Marketplace buyers use separate seller-scoped customer records created by `merchant.customer_for(user)`; changing the configured platform or environment requires a separate database.
+
+Duplicate webhook jobs may run, but synchronization does not create duplicate charges or subscriptions. This is not an exactly-once notification system. This version does not send Pay receipts or subscription emails; Whop's own messaging settings remain in effect.
+
+Deliveries remain pending if processing fails. Network, rate-limit and server errors receive bounded Active Job retries; other API failures emit `delivery_failed.pay_whop` without retrying that job automatically. After fixing a persistent error, enqueue retained deliveries again:
+
+```ruby
+Pay::Whop::RecoverDeliveriesJob.perform_later
+```
+
+Schedule that recovery job periodically (it defaults to deliveries older than two minutes, with no one-day cutoff): a process can stop after the database write but before job enqueue. Monitor failed jobs rather than treating an HTTP 200 webhook acknowledgment as completed synchronization. Completed delivery IDs are retained for deduplication; choose a retention policy before running at scale.
+
+## Billing differences
+
+- Whop variants map to Pay's `processor_plan`, memberships to subscriptions, members to customers, and payments to charges.
+- A scheduled cancellation retains access through the current billing period. `resume` reverses that scheduled cancellation; it does not reactivate an ended subscription.
+- `refund!` asks Whop to refund the remaining balance, or the specified integer minor-unit amount, then retrieves current payment and membership state. Refunds settle asynchronously and do not themselves cancel a subscription; cancel separately when access should end. Insufficient seller funds raise `Pay::Whop::ApiError` and leave the local refund amount unchanged.
+- Pay stores integer minor units. Whop money objects are converted with `BigDecimal` and the provider's currency precision, without rounding fractions away.
+- Amounts currently use Whop's account-facing `total` and `refunded_amount`, not buyer fees. Currency mismatches are rejected; adaptive-pricing/FX refunds and tax reconciliation require further validation before enabling them.
+- Supply a stable `idempotency_key:` for each checkout, charge, cancellation, resumption, invoice, transfer or refund attempt. Reuse it when retrying the same operation after a timeout. A new operation needs a new key. SDK automatic retries are disabled so unexamined writes are not automatically repeated.
+
+## Run the example
+
+```sh
+bundle install
+cp .env.example .env
+# Fill in sandbox credentials, an existing recurring WHOP_VARIANT_ID,
+# never commit .env.
+bundle exec bin/sandbox-check
+bundle exec examples/rails/bin/setup
+cd examples/rails
+bundle exec bin/rails server -b 127.0.0.1 -p 3001
+```
+
+Open `http://localhost:3001` and start a sandbox session. Each browser gets its own synthetic customer in an encrypted session cookie; all billing actions are scoped to that customer. Reuse the same browser session with your Whop sandbox account. The public playground requires PostgreSQL and a secret key; its development secret key cannot be used in production. This example is not a production SaaS starter.
+
+Whop requires an HTTPS checkout return URL. Set `WHOP_RETURN_URL` to an HTTPS page you control; for local testing it can be a static page that links back to localhost. Expose only the webhook route through your local tunnel, register that HTTPS URL in Whop, and set `WHOP_WEBHOOK_SECRET` before restarting the server. Checkout returns to the billing page; refresh after the webhook arrives. A successful subscription, cancellation and refund should be visible in both Pay and Whop.
+
+Recover pending local deliveries with:
+
+```sh
+bundle exec examples/rails/bin/reconcile
+```
+
+## Deploy the playground
+
+`render.yaml` defines a free Rails web service. Supply a separate persistent PostgreSQL database (for example, Neon Free); Render’s free database expires after 30 days. The app uses GoodJob with PostgreSQL-backed jobs, bounded retries and a recovery job for pending deliveries. It only boots against Whop sandbox. Free hosting has usage limits and the web service sleeps when idle.
+
+Set the listed environment variables in the host’s secret settings. Optionally set `DEMO_MERCHANT_ID` to a registered sandbox subaccount to show marketplace checkout, and `WHOP_ONE_TIME_VARIANT_ID` to a USD 5.00 one-time variant to show draft invoices. Set `WHOP_RETURN_URL` to the public HTTPS root URL, register `/pay/whop/webhooks` with Whop using the adapter’s event list and dated API version, then set `WHOP_WEBHOOK_SECRET`. `examples/rails/bin/start` applies migrations and starts Puma. Keep a stable `SECRET_KEY_BASE`: changing it invalidates sessions and the customer references already stored in Whop.
+
+Never expose the local developer database or reuse a production Whop API key for this demo. The public app has no admin interface and never accepts visitor API keys.
+
+## Develop
+
+```sh
+bin/test
+# Or:
+bundle exec rake test
+bundle exec standardrb
+```
+
+The tests use a real Rails application and Pay models, WebMock at the HTTP boundary, and genuinely signed webhook requests. They require no credentials and block external network calls. CI covers Ruby 3.3/3.4/4.0 × Pay 12.3.0/12.4.0 × SQLite/PostgreSQL. `TEST_DATABASE_URL=postgresql://localhost/pay_whop_test bundle exec rake test` uses a temporary schema in a dedicated database ending in `_test`. Run `bundle exec ruby bin/install-smoke` to build the gem, extract it and install/migrate/boot a fresh Rails application. See [release instructions](docs/releasing.md). See [verification notes](docs/verification.md) for tested versions and sandbox evidence.
+
+## References
+
+- [Pay processor guide](https://github.com/pay-rails/pay/blob/main/docs/contributing/adding_a_payment_processor.md)
+- [Whop sandbox quickstart](https://docs.whop.com/developer/quickstart)
+- [Whop Ruby SDK](https://github.com/whopio/whopsdk-ruby)
+- [Whop webhook verification](https://docs.whop.com/developer/guides/webhooks)
+- [Whop API stability](https://docs.whop.com/api-reference/stability)
+
+MIT license. Contributions welcome.

data/app/controllers/pay/whop/webhooks_controller.rb

@@ -0,0 +1,31 @@
+module Pay
+  module Whop
+    class WebhooksController < ActionController::API
+      def create
+        raise ConfigurationError, "Set Pay::Whop.webhook_secret" if Whop.webhook_secret.blank?
+        event = ::WhopSDK::Helpers::VerifyWebhook.unwrap(request.raw_post,
+          headers: %w[webhook-id webhook-timestamp webhook-signature].to_h { |name| [name, request.headers[name]] },
+          key: Whop.webhook_secret).deep_stringify_keys
+        account = Whop.verify_account!(event)
+        return head :ok unless Delivery::EVENTS.include?(event["type"])
+        raise InvalidPayload, "Webhook ID mismatch" unless event.fetch("id") == request.headers["webhook-id"]
+        object = event.fetch("data")
+        resource_id = event["type"].start_with?("refund.") ? object.fetch("payment_id") : object.fetch("id")
+        raise InvalidPayload, "Missing resource ID" if resource_id.blank?
+        delivery = Delivery.create_or_find_by!(environment: Whop.environment, account_id: account, event_id: event.fetch("id")) do |record|
+          record.event_type = event.fetch("type")
+          record.resource_id = resource_id
+        end
+        unless delivery.event_type == event["type"] && delivery.resource_id == resource_id
+          raise InvalidPayload, "Webhook ID reused for a different event"
+        end
+        unless delivery.processed_at?
+          return head :service_unavailable unless ProcessDeliveryJob.perform_later(delivery)
+        end
+        head :ok
+      rescue ::StandardWebhooks::WebhookVerificationError, JSON::ParserError, KeyError, IdentityError, InvalidPayload
+        head :bad_request
+      end
+    end
+  end
+end

data/app/jobs/pay/whop/process_delivery_job.rb

@@ -0,0 +1,22 @@
+module Pay
+  module Whop
+    class ProcessDeliveryJob < ActiveJob::Base
+      queue_as { Whop.queue_name }
+      retry_on ApiError, wait: :polynomially_longer, attempts: 5 do |job, error|
+        job.report_failure(error)
+      end
+      retry_on ActiveRecord::Deadlocked, ActiveRecord::RecordNotUnique, wait: 2.seconds, attempts: 5
+
+      def perform(delivery)
+        delivery.process!
+      rescue ApiError => error
+        raise if error.retryable?
+        report_failure(error)
+      end
+
+      def report_failure(error)
+        ActiveSupport::Notifications.instrument("delivery_failed.pay_whop", delivery_id: arguments.first.id, status: error.status, code: error.code)
+      end
+    end
+  end
+end

data/app/jobs/pay/whop/recover_deliveries_job.rb

@@ -0,0 +1,13 @@
+module Pay
+  module Whop
+    class RecoverDeliveriesJob < ActiveJob::Base
+      queue_as { Whop.queue_name }
+
+      def perform(older_than: 2.minutes.ago, since: nil)
+        scope = Delivery.pending.where(created_at: ..older_than)
+        scope = scope.where(created_at: since..) if since
+        scope.find_each { |delivery| ProcessDeliveryJob.perform_later(delivery) }
+      end
+    end
+  end
+end

data/app/models/pay/whop/charge.rb

@@ -0,0 +1,68 @@
+module Pay
+  module Whop
+    class Charge < Pay::Charge
+      def self.sync(id, account_id: nil)
+        object = Whop.api_attributes(Whop.api.payments.retrieve(id: id, request_options: Whop.request_options))
+        raise InvalidPayload, "Unexpected payment ID" unless object.fetch("id") == id
+        Whop.verify_account!(object, expected: account_id)
+        subscription = Subscription.sync(object["membership_id"], account_id: object["account_id"]) if object["membership_id"].present?
+        return unless object.fetch("status") == "paid"
+        customer = Customer.resolve!(object)
+        if subscription && subscription.customer_id != customer.id
+          raise IdentityError, "Payment and membership belong to different customers"
+        end
+        customer.with_lock do
+          record = customer.charges.find_or_initialize_by(processor_id: id)
+          source_time = Whop.timestamp(object.fetch("updated_at"))
+          saved_time = Whop.timestamp(record.data.to_h["whop_updated_at"])
+          return record if saved_time && saved_time > source_time
+          total = object.fetch("total")
+          currency = total.fetch("currency").downcase
+          refunded = object["refunded_amount"]
+          record.update!(
+            amount: Whop.minor_units(total), currency: currency,
+            amount_refunded: refunded ? Whop.minor_units(refunded, currency: currency) : 0,
+            subscription: subscription,
+            created_at: Whop.timestamp(object["paid_at"] || object.fetch("created_at")),
+            data: record.data.to_h.merge("whop_updated_at" => source_time.iso8601(6), "payment_method_type" => object["payment_method_type"], "whop_decimals" => total.fetch("decimals"))
+          )
+          record
+        end
+      end
+
+      def sync!(**options)
+        customer.verify_configuration!
+        self.class.sync(processor_id, **options, account_id: customer.account_id)
+        reload
+      end
+
+      def api_record
+        customer.verify_configuration!
+        customer.payment(processor_id)
+      end
+
+      def refund!(amount_to_refund = nil, idempotency_key: SecureRandom.uuid)
+        customer.verify_configuration!
+        object = Whop.api_attributes(api_record)
+        customer.verify_resource!(object)
+        total = object.fetch("total")
+        remaining = Whop.minor_units(total) - Whop.minor_units(object.fetch("refunded_amount"), currency: total.fetch("currency"))
+        raise Error, "Payment is already fully refunded" unless remaining.positive?
+        body = {}
+        if amount_to_refund
+          raise ArgumentError, "Refund exceeds remaining balance" if amount_to_refund > remaining
+          body = {partial_amount: Whop.major_units(amount_to_refund, decimals: total.fetch("decimals"))}
+        end
+        Whop.api_request(:post, "payments/#{ERB::Util.url_encode(processor_id)}/refund", body: body, idempotency_key: idempotency_key)
+        sync!
+      end
+
+      def fees
+        api_record
+        Whop.api.payments.list_fees(id: processor_id, request_options: Whop.request_options)
+      end
+
+      def whop? = true
+    end
+  end
+end

data/app/models/pay/whop/customer.rb

@@ -0,0 +1,251 @@
+module Pay
+  module Whop
+    class Customer < Pay::Customer
+      has_many :charges, dependent: :destroy, class_name: "Pay::Whop::Charge"
+      has_many :subscriptions, dependent: :destroy, class_name: "Pay::Whop::Subscription"
+      has_many :payment_methods, dependent: :destroy, class_name: "Pay::Whop::PaymentMethod"
+
+      has_many :entitlements, class_name: "Pay::Whop::Entitlement", dependent: :destroy
+      has_many :disputes, class_name: "Pay::Whop::Dispute", dependent: :destroy
+      has_many :invoices, class_name: "Pay::Whop::Invoice", dependent: :destroy
+      has_one :default_payment_method, -> { where(default: true) }, class_name: "Pay::Whop::PaymentMethod", foreign_key: :customer_id
+
+      def account_id = data.to_h["whop_account_id"] || Whop.account_id
+
+      def checkout(redirect_url:, variant_id: nil, variant: nil, name: Pay.default_product_name, metadata: {}, mode: "payment", idempotency_key: SecureRandom.uuid, **options)
+        bind_account!
+        raise ArgumentError, "Choose a variant or variant_id" if mode == "payment" && [variant_id, variant].compact.size != 1
+        raise ArgumentError, "Unknown checkout option" unless (options.keys - %i[affiliate_code currency payment_method_configuration three_ds_level]).empty?
+        Whop.api.checkout_configurations.create(**options,
+          account_id: account_id, variant_id: variant_id, variant: variant, mode: mode, redirect_url: redirect_url,
+          metadata: checkout_metadata(metadata, name: name),
+          request_options: Whop.request_options(idempotency_key: idempotency_key))
+      end
+
+      def checkout_charge(amount:, redirect_url:, currency: "usd", decimals: 2, application_fee_amount: nil, **options)
+        variant = {currency: currency, billing_type: "one_time", initial_price: Whop.major_units(amount, decimals: decimals)}
+        if application_fee_amount
+          raise ArgumentError, "Application fee must be below the price" unless application_fee_amount < amount
+          variant[:application_fee_amount] = Whop.major_units(application_fee_amount, decimals: decimals)
+        end
+        checkout(variant: variant, redirect_url: redirect_url, **options)
+      end
+
+      def setup_checkout(redirect_url:, **options)
+        checkout(redirect_url: redirect_url, mode: "setup", **options)
+      end
+
+      def checkout_metadata(metadata = {}, name: Pay.default_product_name)
+        metadata.stringify_keys.merge("pay_customer" => signed_id(purpose: Whop.identity_purpose(account_id)), "pay_subscription_name" => name)
+      end
+
+      def bind_account!
+        Whop.validate_configuration!
+        with_lock do
+          if data.to_h["whop_account_id"].present?
+            verify_configuration!
+          else
+            update!(data: data.to_h.merge("whop_account_id" => Whop.account_id, "whop_environment" => Whop.environment))
+          end
+        end
+      end
+
+      def verify_configuration!
+        unless data.to_h["whop_environment"] == Whop.environment && data.to_h["whop_account_id"].present?
+          raise IdentityError, "Pay customer belongs to another Whop environment"
+        end
+        Whop.verify_account!({"account_id" => account_id})
+      end
+
+      def verify_resource!(object)
+        verify_configuration!
+        Whop.verify_account!(object, expected: account_id)
+        unless self.class.resolve!(object).id == id
+          raise IdentityError, "Whop resource belongs to another customer"
+        end
+        object
+      end
+
+      def sync_payment_methods
+        verify_configuration!
+        raise Error, "Complete checkout or payment setup first" if processor_id.blank?
+        ids = []
+        Whop.each_page(Whop.api.payment_methods, member_id: processor_id) do |object|
+          ids << PaymentMethod.sync(object, customer: self).processor_id
+        end
+        payment_methods.where.not(processor_id: ids).destroy_all
+        payment_methods.reload
+      end
+
+      def add_payment_method(payment_method_id, default: false)
+        sync_payment_methods
+        method = payment_methods.find_by!(processor_id: payment_method_id)
+        method.make_default! if default
+        method
+      end
+
+      def create_setup_intent(confirmation_token:, return_url:, currency: "usd", metadata: {}, idempotency_key: SecureRandom.uuid)
+        bind_account!
+        Whop.api.setup_intents.create(account_id: account_id, confirmation_token: confirmation_token,
+          return_url: return_url, currency: currency, metadata: checkout_metadata(metadata),
+          request_options: Whop.request_options(idempotency_key: idempotency_key))
+      end
+
+      def create_payment_intent(confirmation_token:, return_url:, variant_id: nil, variant: nil, metadata: {}, capture: true, idempotency_key: SecureRandom.uuid)
+        bind_account!
+        raise ArgumentError, "Choose a variant or variant_id" unless [variant_id, variant].compact.size == 1
+        Whop.api.payments.create(account_id: account_id, confirmation_token: confirmation_token,
+          return_url: return_url, variant_id: variant_id, variant: variant, capture: capture,
+          metadata: checkout_metadata(metadata), request_options: Whop.request_options(idempotency_key: idempotency_key))
+      end
+
+      def billing_portal(name: Pay.default_product_name)
+        verify_configuration!
+        subscription(name: name)&.portal_url || raise(Error, "No Whop membership management URL is available")
+      end
+
+      def create_payment(variant_id: nil, variant: nil, payment_method_id: nil, off_session: true, return_url: nil, metadata: {}, name: Pay.default_product_name, capture: true, idempotency_key: SecureRandom.uuid)
+        verify_configuration!
+        raise ArgumentError, "Choose a variant or variant_id" unless [variant_id, variant].compact.size == 1
+        method = payment_method_id ? add_payment_method(payment_method_id) : default_payment_method
+        raise Error, "Save a payment method and select a default first" unless method
+        Whop.api.payments.create(account_id: account_id, member_id: processor_id,
+          payment_method_id: method.processor_id, variant_id: variant_id, variant: variant,
+          off_session: off_session, return_url: return_url, capture: capture,
+          metadata: checkout_metadata(metadata, name: name), request_options: Whop.request_options(idempotency_key: idempotency_key))
+      end
+
+      def charge(amount, currency: "usd", decimals: 2, **options)
+        result = create_payment(variant: {currency: currency, billing_type: "one_time", initial_price: Whop.major_units(amount, decimals: decimals)}, **options)
+        confirmed_charge(result)
+      end
+
+      def subscribe(plan:, name: Pay.default_product_name, **options)
+        result = create_payment(variant_id: plan, name: name, **options)
+        confirmed_charge(result).subscription || raise(Error, "Payment did not create a recurring subscription")
+      end
+
+      def authorize(amount, currency: "usd", decimals: 2, **options)
+        create_payment(variant: {currency: currency, billing_type: "one_time", initial_price: Whop.major_units(amount, decimals: decimals)}, capture: false, **options)
+      end
+
+      def payment(id)
+        result = Whop.api.payments.retrieve(id: id, request_options: Whop.request_options)
+        object = Whop.api_attributes(result)
+        raise InvalidPayload, "Unexpected payment ID" unless object.fetch("id") == id
+        verify_resource!(object)
+        result
+      end
+
+      def capture(payment_id, idempotency_key: SecureRandom.uuid)
+        payment(payment_id)
+        Whop.api.payments.capture(id: payment_id, request_options: Whop.request_options(idempotency_key: idempotency_key))
+        confirmed_charge(payment(payment_id))
+      end
+
+      def void(payment_id, idempotency_key: SecureRandom.uuid)
+        payment(payment_id)
+        Whop.api.payments.void(id: payment_id, request_options: Whop.request_options(idempotency_key: idempotency_key))
+      end
+
+      def retry_payment(payment_id, idempotency_key: SecureRandom.uuid)
+        payment(payment_id)
+        Whop.api.payments.retry_(id: payment_id, request_options: Whop.request_options(idempotency_key: idempotency_key))
+        confirmed_charge(payment(payment_id))
+      end
+
+      def confirmed_charge(result)
+        verify_resource!(Whop.api_attributes(result))
+        raise PaymentIncomplete, result unless result.status == "paid"
+        Charge.sync(result.id, account_id: account_id)
+      end
+
+      def create_invoice(items:, metadata: {}, idempotency_key: SecureRandom.uuid, **options)
+        verify_configuration!
+        raise Error, "Complete checkout or payment setup first" if processor_id.blank?
+        raise ArgumentError, "Unknown invoice option" unless (options.keys - %i[due_at memo payment_method_id]).empty?
+        add_payment_method(options[:payment_method_id]) if options[:payment_method_id]
+        result = Whop.api.invoices.create(**options, account_id: account_id, member_id: processor_id, items: items,
+          metadata: checkout_metadata(metadata), request_options: Whop.request_options(idempotency_key: idempotency_key))
+        Invoice.sync(result.id, account_id: account_id)
+      end
+
+      def invoice!(idempotency_key: SecureRandom.uuid, **options)
+        create_invoice(**options, idempotency_key: idempotency_key).issue(idempotency_key: "#{idempotency_key}-issue")
+      end
+
+      def sync_subscriptions
+        verify_configuration!
+        raise Error, "Customer has not completed checkout" if processor_id.blank?
+        Whop.each_page(Whop.api.memberships, account_id: account_id, member_id: processor_id) do |object|
+          verify_resource!(object)
+          Subscription.sync(object.fetch("id"), account_id: account_id)
+        end
+        subscriptions.reload
+      end
+
+      def reconcile!
+        verify_configuration!
+        raise Error, "Customer has not completed checkout" if processor_id.blank?
+        counts = {memberships: 0, payments: 0, invoices: 0, skipped: 0}
+        {memberships: Whop.api.memberships, payments: Whop.api.payments, invoices: Whop.api.invoices}.each do |kind, endpoint|
+          Whop.each_page(endpoint, account_id: account_id, member_id: processor_id) do |object|
+            Whop.verify_account!(object, expected: account_id)
+            raise IdentityError, "Reconciliation returned another member" unless object["member_id"] == processor_id
+            token = object.dig("metadata", "pay_customer")
+            if token.present? && self.class.find_signed(token, purpose: Whop.identity_purpose(account_id)).nil?
+              counts[:skipped] += 1
+              ActiveSupport::Notifications.instrument("reconciliation_skipped.pay_whop", customer_id: id, resource_id: object.fetch("id"), resource_type: kind)
+              next
+            end
+            verify_resource!(object)
+            case kind
+            when :memberships then Subscription.sync(object.fetch("id"), account_id: account_id)
+            when :payments then Charge.sync(object.fetch("id"), account_id: account_id)
+            when :invoices then Invoice.sync(object.fetch("id"), account_id: account_id)
+            end
+            counts[kind] += 1
+          end
+        end
+        counts
+      end
+
+      def api_record
+        verify_configuration!
+        raise Error, "Customer has not completed a Whop checkout" if processor_id.blank?
+        Whop.api.members.retrieve(id: processor_id, request_options: Whop.request_options)
+      end
+
+      def update_api_record(**attributes)
+        # Whop owns the buyer's email; changing it locally must not change their Whop identity.
+        nil
+      end
+
+      def whop? = true
+
+      def self.resolve!(object)
+        account = Whop.verify_account!(object)
+        member_id = object.fetch("member_id")
+        raise IdentityError, "Whop resource has no member" if member_id.blank?
+        token = object.dig("metadata", "pay_customer")
+        signed_customer = find_signed(token, purpose: Whop.identity_purpose(account)) if token.present?
+        raise IdentityError, "Invalid Pay customer reference" if token.present? && signed_customer.nil?
+        existing = find_by(processor_id: member_id)
+        if existing && signed_customer && existing.id != signed_customer.id
+          raise IdentityError, "Whop member is already linked to a different Pay customer"
+        end
+        customer = signed_customer || existing
+        raise IdentityError, "Whop resource is not linked to a Pay customer" unless customer
+        customer.verify_configuration!
+        raise IdentityError, "Customer belongs to another seller" unless customer.account_id == account
+        customer.with_lock do
+          if customer.processor_id.present? && customer.processor_id != member_id
+            raise IdentityError, "Pay customer is already linked to a different Whop member"
+          end
+          customer.update!(processor_id: member_id) if customer.processor_id.blank?
+        end
+        customer
+      end
+    end
+  end
+end