pay-whop 0.1.0.alpha.4

data/db/migrate/20261107120000_create_pay_whop_resources.rb

@@ -0,0 +1,18 @@
+class CreatePayWhopResources < ActiveRecord::Migration[7.0]
+  def change
+    create_table :pay_whop_resources do |t|
+      t.string :type, null: false
+      t.string :processor_id, null: false
+      t.string :account_id, null: false
+      t.string :environment, null: false
+      t.references :customer, foreign_key: {to_table: :pay_customers}
+      t.references :merchant, foreign_key: {to_table: :pay_merchants}
+      t.string :status
+      t.bigint :amount
+      t.string :currency
+      t.json :data, default: {}, null: false
+      t.timestamps
+    end
+    add_index :pay_whop_resources, [:type, :environment, :account_id, :processor_id], unique: true, name: "pay_whop_resource_identity"
+  end
+end

data/docs/advanced-usage.md

@@ -0,0 +1,203 @@
+# Billing and marketplaces
+
+All amounts accepted by adapter convenience methods are integer minor units: `500` means USD 5.00. Specify `decimals: 0` for JPY or `decimals: 3` for KWD when creating prices or transfers; refund precision comes from the original payment. Arbitrary inline `variant` prices follow Whop's API and use major units.
+
+## One-time and recurring checkout
+
+```ruby
+customer = user.set_payment_processor(:whop)
+checkout = customer.checkout_charge(
+  amount: 500, currency: "usd", redirect_url: billing_url,
+  idempotency_key: order.id.to_s
+)
+redirect_to checkout.purchase_url, allow_other_host: true
+
+# Existing recurring variant:
+customer.checkout(variant_id: "plan_...", redirect_url: billing_url)
+
+# Inline recurring variant, including a trial:
+customer.checkout(
+  variant: {currency: "usd", billing_type: "renewal", renewal_price: 10,
+            billing_period: 30, trial_period_days: 7, product_id: "prod_..."},
+  redirect_url: billing_url
+)
+```
+
+Successful one-time purchases become `Pay::Whop::Charge` records without a recurring subscription. They do not make `subscribed?` true. Your application fulfills the order after the verified payment is synchronized. An inline recurring variant's `initial_price` is an additional first-payment fee, not its recurring price.
+
+## Saved methods and direct payments
+
+```ruby
+checkout = customer.setup_checkout(redirect_url: billing_url)
+# Redirect the buyer; setup_intent.succeeded links the saved method.
+customer.sync_payment_methods
+customer.add_payment_method("payt_...", default: true)
+charge = customer.charge(500, idempotency_key: order.id.to_s)
+subscription = customer.subscribe(plan: "plan_...", name: "default")
+```
+
+The default is local to this adapter. It does not silently replace the payment method on existing Whop memberships. Use `subscription.update_payment_method("payt_...")` for that. `payment_method.detach` deletes the saved provider method after verifying it belongs to the linked member.
+
+Direct payments can return before completion. `charge`, `subscribe`, `capture` and `retry_payment` raise `Pay::Whop::PaymentIncomplete` with an SDK `payment` object when it is not yet `paid`. Handle this as pending or buyer action required, not as a successful purchase or a reason to create another payment. Reuse the same idempotency key. Webhooks reconcile successful settlement.
+
+```ruby
+begin
+  customer.charge(500, idempotency_key: order.id.to_s)
+rescue Pay::Whop::PaymentIncomplete => error
+  payment_id = error.payment.id
+  if error.recovery_url
+    redirect_to error.recovery_url, allow_other_host: true
+  else
+    # Present a pending state and await the verified webhook.
+  end
+end
+```
+
+For custom payment-element frontends, `create_payment_intent(confirmation_token:, return_url:, variant_id:)` and `create_setup_intent(confirmation_token:, return_url:)` attach the same signed identity metadata and return SDK objects. Render Whop's official elements and follow their authentication/status flow; never collect raw card numbers in Rails. These methods do not imply payment success or save a Pay charge themselves.
+
+For authorizations, `customer.authorize(500, idempotency_key: ...)` returns the provider payment; `customer.capture(payment_id)` captures in full and reconciles it, while `customer.void(payment_id)` releases it. Whop must still accept the authorization/capture state and deadline. `customer.retry_payment(payment_id)` retries an existing payment; it does not create a new order.
+
+## Refunds and subscriptions
+
+```ruby
+charge.refund!(100, idempotency_key: "refund-order-42-part-1") # USD 1.00
+charge.refund!(idempotency_key: "refund-order-42-rest")       # remaining balance
+
+subscription.pause                         # pause billing; retain paid-period access
+subscription.pause(until_time: 1.week.from_now)
+subscription.unpause                       # resume paused billing
+subscription.cancel                        # cancel at period end
+subscription.resume                        # undo scheduled cancellation or resume a pause
+subscription.cancel_now!
+subscription.add_free_days(7)
+subscription.apply_promo_code(promo_code: "SAVE20")
+subscription.update_payment_method("payt_...")
+customer.billing_portal                    # existing membership's manage URL
+customer.sync_subscriptions
+```
+
+A refund is separate from cancellation and can settle asynchronously. The adapter refreshes the provider's confirmed refunded amount, rather than setting it optimistically. Refund requests fail when funds or provider rules prevent them. SDK 2.7 types partial refunds as integers and ignores its advertised extra-body option; a small authenticated HTTP fallback sends the exact fractional amount and retains the pinned API date and idempotency key.
+
+`paused?` describes billing collection. Access continues until the current paid period ends; both `active?` and Pay's active subscription query preserve that distinction. Whop exposes a pause through `most_recent_action == "paused_at"`, not a `paused` membership status. The adapter refreshes provider state after every mutation; it never reports a pause solely because the request returned HTTP 200.
+
+Ended recurring subscriptions require a new checkout: Whop rejected recurring reactivation in sandbox. One-time product memberships are stored separately as `customer.entitlements`; their `active?` checks status and expiry, and `entitlement.reactivate(days: 30)` uses the one-time reactivation API.
+
+```ruby
+subscription.retry_failed_payment(idempotency_key: "retry-payment-42")
+subscription.retry_failed_payment(payment_id: "pay_...", idempotency_key: "retry-payment-42")
+subscription.reduce_renewal_price(855, idempotency_key: "discount-membership-42")
+subscription.change_billing_period(90, idempotency_key: "cadence-membership-42")
+subscription.change_next_renewal(60.days.from_now, idempotency_key: "renew-membership-42")
+```
+
+Retry resolves an existing payment belonging to this membership. Already-paid payments only synchronize; no new payment is created. A still-incomplete retry raises `PaymentIncomplete`. The returned `recovery_url` is limited to HTTPS on the configured Whop environment's host; only a confirmed provider payment creates a charge.
+
+Renewal prices can only decrease, using the existing currency precision. Whop emails the buyer about a price reduction. Billing periods accept 1–365 days; next-renewal dates must be after today in UTC. Each change sends one field and then refreshes actual membership state. Whop additionally enforces eligibility (for example, active/trialing, recurring, unpaused, auto-billed memberships for price reductions, and restrictions on invoice billing, cancellation and daily cadence). These changes are not arbitrary plan swaps or Stripe-style proration. Provider rejection leaves local state unchanged. New renewal controls have HTTP-contract tests, not completed provider billing-cycle validation.
+
+Plan swaps, proration, recurring seat changes and usage metering are not implemented. Whop's `swaps` resource converts currencies; it is not a subscription-plan swap API.
+
+## Invoices
+
+```ruby
+invoice = customer.create_invoice(items: [{variant_id: "plan_...", quantity: 1}])
+invoice.issue
+invoice.checkout_url
+invoice.pdf_url
+invoice.charge(payment_method_id: "payt_...")
+invoice.void
+invoice.mark_uncollectible
+invoice.unschedule
+invoice.update_details(memo: "Order 42", due_at: 7.days.from_now)
+invoice.deliver # Explicitly sends Whop's invoice email; only call when intended.
+
+# Create and issue in one call, with separate stable creation/issue keys:
+customer.invoice!(items: [{variant_id: "plan_...", quantity: 1}], idempotency_key: "invoice-42")
+```
+
+Invoice records store a billing summary, not the buyer's address or email. Only a paid invoice creates a Pay charge. Issuing or charging can require verified account capabilities. The demo account can create drafts but Whop currently blocks issuance until account verification is completed. No invoice emails were sent during verification.
+
+## Marketplace / Connect-style flows
+
+Configure the platform's Account API key and account ID normally. Add `pay_merchant` to your seller model:
+
+```ruby
+class Seller < ApplicationRecord
+  pay_merchant
+end
+
+merchant = seller.set_merchant_processor(:whop)
+merchant.create_account(email: seller.email, title: seller.name,
+                        idempotency_key: "seller-#{seller.id}")
+link = merchant.account_link(refresh_url: onboarding_url, return_url: sellers_url)
+# Redirect the seller to link.url for Whop's onboarding/KYC.
+payouts = merchant.account_link(use_case: "payouts_portal",
+                              refresh_url: onboarding_url, return_url: sellers_url)
+
+buyer = merchant.customer_for(user)
+checkout = buyer.checkout_charge(amount: 500, application_fee_amount: 100,
+                                 redirect_url: billing_url, idempotency_key: order.id.to_s)
+
+# Alternatively collect on the platform, then transfer to the seller:
+transfer = merchant.transfer(amount: 400, currency: "usd", idempotency_key: "seller-share-42")
+transfer.status # processing, succeeded or failed; creation is not settlement
+```
+
+`customer_for` creates a separate seller-scoped Pay customer without replacing the user's default payment processor. Never switch the global account ID per request. The adapter trusts only the configured platform and locally registered subaccounts whose parent was checked through Whop's API. Member references are signed per environment and seller account; webhook envelope and fetched resource accounts must agree. Reuse one environment per database.
+
+Register the platform webhook with **subaccount events enabled** and all events in `Pay::Whop::Delivery::EVENTS`. The platform signing secret verifies those child deliveries. Successful transfers are recorded separately from Pay charges. Whop requires sufficient available funds and may require identity verification for transfers or payouts; the adapter does not bypass those requirements or mark rejected transfers successful.
+
+`account.updated` stores the subaccount's status/capability summary. `merchant.readiness` retrieves status, capabilities and required actions. `merchant.capability_active?(:transfer)` checks one capability. `merchant.onboarding_complete?` requires an active account with card payments enabled; pass `capabilities: %w[transfer]` or another explicit list for a different workflow. This does not imply every payout method is enabled. Unknown or missing capabilities are unavailable. Account creation and redirects alone do not satisfy these checks.
+
+```ruby
+merchant.readiness
+merchant.balance # currency + BigDecimal balance/pending_balance/reserve_balance, in major units
+merchant.login_link(refresh_url: onboarding_url, return_url: sellers_url) # hosted payouts portal
+merchant.reconcile! # {transfers: ..., payouts: ...}
+merchant.payouts.each { |payout| payout.sync! }
+```
+
+Payout status is synchronized through the authenticated account-filtered list, including pagination. Whop's public payout tracking endpoint is not used to establish ownership. Platform payout events also synchronize without inventing a seller: use `Pay::Whop::Payout.where(account_id: Pay::Whop.account_id, environment: Pay::Whop.environment)` from an authorized platform-administration context. Payout records retain decimal-string amount/fee summaries in `data`, without bank details; these are major units, unlike Pay charge amounts. A completed payout may later reverse. This adapter delegates bank withdrawal initiation to Whop's hosted portal; it does not implement payout quotes or direct bank withdrawal creation. [Whop documents that payouts are unavailable in sandbox](https://docs.whop.com/developer/guides/sandbox). Sandbox tests therefore do not prove bank settlement.
+
+## Disputes
+
+Verified dispute webhooks create `Pay::Whop::Dispute` records tied to the original charge's customer. They retain status, reason, due date and payment ID, not the buyer or submitted evidence.
+
+```ruby
+dispute.update_evidence(evidence: {product_description: "Digital course"})
+dispute.upload_evidence(documents: [{document_type: "...", direct_upload_id: "..."}])
+dispute.submit # Send the prepared evidence to Whop.
+# Or explicitly accept the dispute:
+dispute.accept
+```
+
+Use the current SDK/OpenAPI document schema for evidence fields. Disputes were tested with synthetic HTTP fixtures, not by creating a real chargeback.
+
+## Permissions and operations
+
+Use custom scopes for the features you enable: checkout read/create; product/plan read/create for inline prices; member read and payment-method read/manage/charge; membership update/cancel; payment read/charge/manage; invoice read/create/update; setup-intent read/manage; dispute read/manage; payout-account read/update; and the relevant webhook receive scopes. Platform account inspection additionally requires `company:balance:read`.
+
+Hosted onboarding/payout links delegate a bundle of financial scopes. Whop required payout destination create/read/update/delete, withdrawal read/export/withdraw, transfer read/export/create, and balance read/export in the tested sandbox. Missing scopes produce an explicit API error. Webhook-management access is needed only by provisioning tools. Use separate provisioning/runtime credentials in a production deployment if your workflow allows it.
+
+Use a durable Active Job adapter, retain receipt IDs for replay protection, monitor pending deliveries and choose a retention policy. The demo uses PostgreSQL-backed GoodJob. Applications should scope invoice/dispute/transfer lookups through the authenticated customer or merchant; the adapter does not provide authentication for your own controllers.
+
+## Errors, callbacks and recovery
+
+Adapter API calls raise `Pay::Whop::ApiError < Pay::Error`, exposing `status`, provider `code`, `retryable?` and the original `provider_error`/cause. Network timeouts have no HTTP status. A timeout may follow a successful provider write: reuse the operation's idempotency key and reconcile before creating a replacement. `Pay::Whop.client` deliberately remains the raw official SDK and raises its native errors.
+
+```ruby
+Pay::Webhooks.configure do |events|
+  events.subscribe "whop.payment.succeeded" do |event|
+    delivery = event.fetch(:delivery)
+    # Billing state is already synchronized. Fulfill idempotently using delivery.event_id.
+  end
+end
+
+Pay::Whop::RecoverDeliveriesJob.perform_later
+customer.reconcile! # {memberships: ..., payments: ..., invoices: ..., skipped: ...}
+```
+
+Callbacks run after resource synchronization and before marking a delivery processed. Handler failure keeps the delivery pending; callbacks may repeat. They receive a delivery record containing IDs, not a captured provider payload. Retrieve application-owned records through the appropriate customer/merchant scope.
+
+Customer reconciliation requires an already-linked member. It paginates that account/member's memberships, payments and invoices, and verifies resource identity before import. Unverifiable signed references (for example, another app's checkout on the same account) are skipped, counted and reported through `reconciliation_skipped.pay_whop`; they are never matched by email or silently reassigned. Preserve the Rails signing secret and investigate skips for known records after key rotation. This is not a global import of unrelated Whop customers. Reconciliation and missed-delivery recovery are separate operations; schedule both as appropriate for your application.
+
+Monitor `delivery_failed.pay_whop` (delivery ID, HTTP status and provider code) and retained pending deliveries. The recovery job can re-enqueue failures after the underlying problem is fixed; periodic recovery will also encounter persistent errors, so alert on them rather than hiding them.

data/docs/compatibility.md

@@ -0,0 +1,35 @@
+# Pay compatibility
+
+`pay-whop` is an alpha adapter for Whop's billing model. It does not claim parity with every Stripe feature. The raw SDK is available for Whop services outside payment processing.
+
+| Pay / billing operation | Whop adapter behavior |
+| --- | --- |
+| `set_payment_processor`, customer association | Seller/environment-scoped Whop member identity, signed references |
+| Hosted checkout | Existing or inline variants; one-time, recurring and setup |
+| `charge`, `subscribe` | Saved method required; incomplete payments raise `PaymentIncomplete` |
+| Authorization, capture, void | Full capture; fresh paid state required for Pay charge |
+| `refund!` | Full/partial, exact currency precision, asynchronous confirmation |
+| Cancel, cancel now, resume | Scheduled cancellation, immediate end, reversal of scheduled cancellation |
+| Pause, unpause, free days, promo code | Dedicated Whop operations, actual provider state refreshed |
+| Failed payment retry | Existing membership payment only; no replacement order |
+| 3DS / action required | Provider recovery URL plus verified webhook completion |
+| Renewal price / cadence / date | Price reductions and permitted changes; provider eligibility applies |
+| Saved methods / default / replacement / detach | Member-scoped methods; local default; explicit subscription replacement |
+| Customer billing portal | Existing membership's management URL |
+| Draft/issued/paid/void/past-due/uncollectible invoices | Separate invoice summary; paid invoices create charges; issuance currently verification-blocked in this sandbox |
+| Dispute preparation, evidence, submit, accept | HTTP-tested wrappers; no real dispute certification |
+| One-time membership access | Separate entitlement with status/expiry, not `subscribed?` |
+| `pay_merchant`, seller onboarding | Child account parent validation, hosted onboarding, fresh capabilities |
+| Marketplace charges / application fees | Separate seller-scoped buyers and signed child webhooks |
+| Internal transfers | Idempotent requests and separate settlement state; this sandbox still verification-blocked |
+| Balances and payout status | Read/reconcile; payout initiation through hosted portal; no bank settlement proof |
+| Webhooks / app callbacks | Signature validation, persisted IDs, account checks, fresh API reads, at-least-once callbacks |
+| Recovery / backfill | Pending-delivery recovery job and linked-customer/merchant reconciliation |
+| Emails / receipts | Whop messaging; Pay receipt/subscription emails are not generated by this adapter |
+| Plan swaps / Stripe-style proration | Unsupported; price/cadence changes are narrower operations |
+| Recurring seat quantity / metering | Unsupported; quantity remains 1 |
+| Ended recurring reactivation | New checkout required; one-time entitlements have a separate reactivation API |
+| Direct bank payouts / FX / tax accounting | No direct withdrawal creator or general accounting reconciliation |
+| Whop chat, ads, cards, affiliates, trading | Outside this adapter; use the official SDK |
+
+Implemented does not mean validated against real money or every provider state. [Verification evidence](verification.md) separates automated tests, sandbox observations and remaining limitations. [Advanced usage](advanced-usage.md) documents method signatures and provider restrictions.

data/docs/releasing.md

@@ -0,0 +1,12 @@
+# Releasing
+
+The prepared alpha is `0.1.0.alpha.4`. Installation from GitHub works without RubyGems publishing credentials.
+
+1. Run `bin/test`, the PostgreSQL suite, and `bundle exec ruby bin/install-smoke`. Confirm the GitHub CI matrix is green.
+2. Update the version, lockfile, changelog and verification evidence together.
+3. Build with `gem build pay-whop.gemspec --output pkg/pay-whop-0.1.0.alpha.4.gem` (create `pkg` first).
+4. Inspect `gem specification pkg/pay-whop-0.1.0.alpha.4.gem files` and ensure no credentials, private fixtures or developer environment files are packaged.
+5. A gem owner publishes with `gem push pkg/pay-whop-0.1.0.alpha.4.gem`. RubyGems MFA is required by the gem metadata. Configure credentials locally; never commit or paste an API key.
+6. Create the matching GitHub prerelease with the built artifact and release notes. Register the deployed adapter's current webhook event list only after deploying the compatible code.
+
+Do not label this production-ready while real invoice issuance, transfers and bank payouts lack provider validation. Keep sandbox-only demo simulations visibly separate from real adapter behavior.

data/docs/verification.md

@@ -0,0 +1,75 @@
+# Verification
+
+Provider payment-flow verification: 7 November 2026. Expanded adapter, read-only sandbox operations and demo verification: 12 November 2026. Release: `0.1.0.alpha.4`.
+
+## Versions and automated coverage
+
+Ruby 4.0.9, Rails 8.1.4.1, Pay 12.4.0, Whop Ruby SDK 2.7.0, and Whop API date `2026-10-28-1`. The demo runs PostgreSQL and GoodJob on Render Free / Neon Free. Unit and integration tests use SQLite and PostgreSQL, with WebMock at the SDK/HTTP boundary. No test credentials or captured customer payloads are committed.
+
+The local suite passes **100 tests / 369 assertions** and Standard Ruby linting. The local suite also passes with Pay 12.3.0; installation from the built gem into a fresh Rails application passes. GitHub Actions runs Ruby 3.3/3.4/4.0 × Pay 12.3.0/12.4.0 × SQLite/PostgreSQL; see [CI runs](https://github.com/yshmarov/pay-whop/actions/workflows/ci.yml).
+
+Coverage includes signed owner mapping, environment and seller isolation, conflicting identities, forged references, webhook authentication/replays/collisions, duplicate processing, pending-event recovery, enqueue refusal, stale snapshots, exact money conversion, full/partial refunds, asynchronous direct payments, saved methods, setup intents, invoice/dispute summaries, marketplace registration and transfers, terminal transfer-state protection, pause/access semantics, trial and past-due state mapping, and browser-session/CSRF/cross-customer boundaries. Expanded tests cover existing-payment retries without duplicate charges, renewal restrictions, normalized API errors including lazy pagination/timeouts, application callback failure recovery, payout ownership/pagination/reversals, merchant capabilities, decimal balances and linked-customer reconciliation.
+
+## Actual sandbox evidence
+
+The [hosted playground](https://pay-whop.onrender.com/) uses the adapter and receives actual signed Whop events. Its database persists across deployments and idle shutdowns. The app is sandbox-only; no live-money transactions were performed.
+
+| Flow | Observed result |
+| --- | --- |
+| Hosted recurring checkout | Paid USD 24.00 including tax; one Pay charge and active subscription created by verified webhooks |
+| Cancellation | Immediate and period-end cancellation, and reversal of scheduled cancellation, verified |
+| Full refund | Provider reported USD 24.00 refunded; local Pay charge agreed |
+| Saved payment methods | Retrieved a method through the linked member and selected the adapter's local default |
+| Hosted setup checkout | Saved the test method without a charge; signed `setup_intent.succeeded` delivery processed |
+| Hosted one-time checkout | Paid USD 6.00 including tax; signed webhook created a charge without a recurring subscription |
+| Authorization / capture / void | Two payments became `authorized`; capture became `paid` with a Pay charge, void became `void` without a Pay charge |
+| Direct one-time saved-method payment | Initially `open`, later `paid`; USD 6.00 including tax, with no recurring subscription |
+| Partial refund | Requested 100 minor units; provider and Pay reported exactly USD 1.00 refunded from the USD 6.00 payment |
+| Pause / resume billing | Provider reported `paused_at`; adapter showed billing paused while retaining paid-period access; resume cleared the pause |
+| Free days | Added one day and observed the changed provider period end |
+| Draft invoice | Created and persisted a USD 5.00 draft; generated an HTTPS invoice PDF URL |
+| Invoice issue | Whop rejected issuance: account verification required. Draft remained unissued |
+| Subaccount creation | Created a sandbox seller and verified its parent account before registering it locally |
+| Hosted onboarding and payout links | Both generated valid sandbox Whop URLs after the required scopes were configured |
+| Marketplace checkout | Completed a USD 5.00 subaccount checkout; provider reported USD 6.00 including tax. The fee report confirmed a collected USD 1.00 application fee; the signed child event created a charge under the seller-scoped customer |
+| Platform transfer | Whop rejected the request because the platform business is not verified; no transfer was recorded as successful |
+| Merchant readiness / balances (12 Nov) | Fresh account capabilities and USD ledger balances retrieved; card payments active, transfer and payout capabilities inactive |
+| Merchant reconciliation (12 Nov) | Authenticated transfer/payout lists returned successfully with zero records; this does not prove settlement |
+| Linked customer reconciliation (12 Nov) | One membership and one payment recovered; seven references from a different application signing context were skipped and reported |
+| Visitor isolation | A separate hosted visitor could not see or cancel/refund another visitor's records; cross-customer actions returned 404 |
+| Queue and deployment | PostgreSQL migrations, eager loading and persisted GoodJob execution verified; earlier deployment-time webhook failures recovered on Whop retry |
+
+A generated checkout or payout URL is not proof of settled payment or bank withdrawal. Completed provider authentication challenges, dispute submission and evidence upload, one-time entitlement reactivation, payment-method deletion, promo-code application, and full trial/failed-renewal lifecycles have HTTP-contract coverage only where exercised by tests, not complete real-provider coverage. Do not describe them as sandbox-certified.
+
+The adapter event list now includes 30 events (payout changes and trial-ending notifications added); deployment updates the hosted webhook to match, with subaccount events enabled. No pending deliveries remained after the checkout and setup tests. The earlier provider-flow review covered desktop layout; a full mobile/accessibility assessment remains outstanding.
+
+## Integration findings
+
+1. The sandbox Admin API-key role does not include `company:balance:read`, which account inspection needs. The expanded integration uses explicit custom scopes.
+2. Hosted onboarding/payout links require additional financial scopes, including transfer/withdrawal exports and payout-destination operations. The API reports missing scopes explicitly.
+3. Saved-payment-method listing accepts a member filter or an account filter, not both. The adapter lists through the linked member and never imports arbitrary supplied method IDs.
+4. SDK 2.7 declares `partial_amount` as an integer even though the API accepts major-unit decimal amounts. Its JSON transport also ignores the documented `additional_body_parameters` option. Refunds therefore use a small authenticated HTTP fallback with exact decimal JSON numbers, a pinned API date, a stable idempotency key, TLS and bounded timeouts. Tests assert the outgoing fractional amount and no automatic write retry.
+5. Payment capture returns a status object, not a complete Payment. The adapter retrieves the payment again before creating a Pay charge.
+6. Under Rails, SDK objects must be converted via `to_h` before JSON serialization. Nullable SDK values can normalize to empty hashes; non-renewing memberships and unsettled transfer amounts are handled accordingly.
+7. Whop's membership pause is reflected in `most_recent_action`, while the billing status can remain `active`. Pay access remains available through the current paid period.
+8. Successful API responses may describe a pending operation. Neither a checkout return, an HTTP 200 nor a created transfer is treated as settlement.
+9. Immediate cancellation can leave `cancel_at_period_end: true` on the provider object. Terminal status and `canceled_at` take precedence so ended subscriptions cannot retain access or appear resumable.
+10. Refunds and transfers can fail due to available balance or account capabilities, even in the sandbox. The adapter does not bypass identity verification.
+
+## Remaining limits
+
+This is an alpha integration, not a declaration of production readiness or full Pay/Stripe parity. Live-money processing, high-concurrency PostgreSQL races, full accessibility assessment, completed provider SCA recovery, FX/tax reconciliation, global historical imports, compatibility beyond the tested matrix and long-running renewal/retry behavior remain unverified. Renewal price/cadence/date mutations and bank payout transitions have HTTP-contract coverage; they were not validated by running a complete real provider billing cycle. Local browser checks confirmed the recovery URL/error state and new demo controls at desktop, 320px and 390px widths; the preview used blocked-network HTTP fixtures, not a completed Whop challenge.
+
+Plan swaps/proration, recurring seat changes and metered billing are not implemented. The Whop `swaps` API is for currencies, not subscription plans. The adapter does not implement Whop's unrelated chat, ads, trading, cards or affiliate administration APIs; callers can use the official SDK for those.
+
+The public playground intentionally has no seller administration or money-transfer controls. Marketplace buyers use a preconfigured sandbox seller. Invoice controls create drafts until the account can issue invoices. Secrets stay in private environment settings. The app's encrypted session lasts 30 days; reusing the same Whop buyer in an unrelated new session can trigger the adapter's deliberate identity-conflict protection.
+
+## Demo-only simulations
+
+The public playground has a separate, amber-labelled simulation section. Invoice flows cover draft → issued → paid, past due → paid, and void outcomes. Transfer flows cover pending → succeeded/failed. Each can be reset. State and activity persist for the visitor's own demo session; another session cannot read or advance those records.
+
+These controls only write separate demo records. They make no Whop API calls, create no provider resources, enqueue no provider webhook deliveries, create no Pay charges or subscriptions and move no funds. A simulated outcome is not proof of API compatibility, business verification, actual invoice payment or settled transfer. The gem's real invoice and transfer methods keep their provider checks and errors. The simulator is available before linking a Whop buyer, and mutation requests reject a production Whop environment.
+
+Automated coverage checks lifecycle transitions, repeated starts, reset, terminal outcomes, session isolation, CSRF, the sandbox guard and absence of Pay billing records or external requests. Local browser checks exercised invoice issuance/overdue/payment and transfer failure before deployment. The simulation section was inspected at 320px and 390px viewport widths with no page overflow; this is not a full accessibility assessment.
+
+The fresh-install smoke check builds and extracts the actual gem, generates a separate Rails application, installs Pay and adapter migrations in separate commands, migrates the database, eager-loads, creates a Whop customer and verifies the webhook route and recovery job. It uses no API credentials or external payment calls.

data/docs/worklog/2026-11-12-demo-billing-simulations.md

@@ -0,0 +1,9 @@
+# Keep the public demo usable while sandbox verification is blocked
+
+**Outcome:** Visitors can explore labelled invoice and transfer simulations without completing KYC.
+
+- **Keep moving:** The user chose simulations after invoice issuance and transfers remained blocked by sandbox account verification.
+- **Honest outcomes:** A simulation demonstrates the workflow only; it is never evidence that Whop approved an account, paid an invoice or settled a transfer.
+- **Separate visitor state:** Each browser owns its simulated scenarios so public visitors can experiment independently.
+- **Easy retries:** Reset clears the simulated history and lets a visitor explore another outcome.
+- **Deferred:** Real invoice issuance and transfer settlement still require validation through a provider-supported verification path. Real identity documents are not part of this demo task.

data/docs/worklog/2026-11-12-integration-release.md

@@ -0,0 +1,12 @@
+# Expanded alpha ready for developers
+
+**Outcome:** Move the integration toward a usable community release while keeping provider validation distinct from automated coverage.
+
+- **Whop's model sets the scope.** Implement permitted renewal changes and existing-payment recovery, without promising Stripe plan swaps, proration or usage billing that the provider does not expose in the same way.
+- **Keep moving around verification.** Preserve real invoice/transfer methods and their errors; clearly labelled demo simulations remain separate. Real-money validation is deferred until provider capability access and a specific test budget are available.
+- **Reconcile ownership carefully.** The same sandbox account/member can contain checkouts from different application signing contexts. Report unverifiable references and skip them; never guess an owner from email.
+- **Payout readiness is capability-specific.** Card acceptance does not prove transfers or bank payouts are available. Hosted payout initiation remains with Whop; this release adds reads and reconciliation.
+- **Publish an alpha.** Package a reusable gem and document installation and recovery; do not claim full Stripe parity or production readiness from HTTP fixtures.
+- **User handles new publishing credentials.** Existing RubyGems CLI credentials were subsequently found in Ruby 4's configuration location, so no additional API key was needed.
+
+**Next step:** Complete real invoice issuance and transfer validation when Whop provides supported sandbox verification; bank settlement needs a supported environment because Whop documents payouts as unavailable in sandbox.

data/lib/pay/whop/api_proxy.rb

@@ -0,0 +1,24 @@
+module Pay
+  module Whop
+    class ApiProxy
+      def initialize(target)
+        @target = target
+      end
+
+      def method_missing(name, *args, **options, &block)
+        result = Whop.with_api_errors { @target.public_send(name, *args, **options, &block) }
+        if result.class.name.start_with?("Whop_sdk::") && result.class.name.end_with?("::Client")
+          self.class.new(result)
+        elsif result.is_a?(::Whop_sdk::Internal::CursorItemIterator)
+          Enumerator.new { |output| Whop.with_api_errors { result.each { |item| output << item } } }
+        else
+          result
+        end
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        @target.respond_to?(name, include_private) || super
+      end
+    end
+  end
+end

data/lib/pay/whop/engine.rb

@@ -0,0 +1,13 @@
+module Pay
+  module Whop
+    class Engine < ::Rails::Engine
+      engine_name "pay_whop"
+
+      initializer "pay_whop.routes" do |app|
+        app.routes.append do
+          mount Pay::Whop::Engine, at: "/pay/whop", as: "pay_whop"
+        end
+      end
+    end
+  end
+end

data/lib/pay/whop/version.rb

@@ -0,0 +1,5 @@
+module Pay
+  module Whop
+    VERSION = "0.1.0.alpha.4"
+  end
+end

data/lib/pay/whop.rb

@@ -0,0 +1,186 @@
+require "rails"
+require "active_job/railtie"
+require "pay"
+require "whop_sdk"
+require "whop_sdk/helpers/verify_webhook"
+require "bigdecimal"
+require "net/http"
+require "pay/whop/version"
+require "pay/whop/api_proxy"
+
+module Pay
+  module Whop
+    class Error < Pay::Error; end
+    class ConfigurationError < Error; end
+    class IdentityError < Error; end
+    class InvalidPayload < Error; end
+
+    class ApiError < Error
+      attr_reader :status, :code, :provider_error
+
+      def initialize(error)
+        @provider_error = error
+        @status = error.code if error.respond_to?(:code)
+        details = begin
+          body = JSON.parse(error.message)
+          body["error"] if body.is_a?(Hash)
+        rescue JSON::ParserError
+          nil
+        end
+        @code = details["type"] if details.is_a?(Hash)
+        super(if details.is_a?(Hash)
+                details["message"].presence || "Whop request failed"
+              else
+                "Whop request failed#{" (HTTP #{status})" if status}"
+              end)
+      end
+
+      def retryable? = status.nil? || status == 429 || status >= 500
+    end
+
+    class PaymentIncomplete < Error
+      attr_reader :payment
+
+      def initialize(payment)
+        @payment = payment
+        super("Whop payment #{payment.id} is #{payment.status}; payment is not confirmed")
+      end
+
+      def recovery_url
+        value = Whop.api_attributes(payment)["recovery_url"]
+        return if value.blank?
+        uri = URI.parse(value)
+        value if uri.scheme == "https" && uri.host == ((Whop.environment == "sandbox") ? "sandbox.whop.com" : "whop.com")
+      rescue URI::InvalidURIError
+        nil
+      end
+    end
+
+    mattr_accessor :api_key, :account_id, :webhook_secret
+    mattr_accessor :environment, default: "sandbox"
+    mattr_accessor :api_version, default: "2026-10-28-1"
+    mattr_accessor :queue_name, default: :default
+
+    def self.configure
+      yield self
+    end
+
+    def self.validate_configuration!
+      raise ConfigurationError, "Set Pay::Whop.api_key" if api_key.blank?
+      raise ConfigurationError, "Set Pay::Whop.account_id" if account_id.blank?
+      raise ConfigurationError, "Whop environment must be sandbox or production" unless %w[sandbox production].include?(environment)
+    end
+
+    def self.client
+      validate_configuration!
+      ::Whop_sdk::Client.new(
+        token: api_key,
+        environment: (environment == "sandbox") ? ::Whop_sdk::Environment::SANDBOX : ::Whop_sdk::Environment::PRODUCTION,
+        api_version_date: api_version,
+        max_retries: 0
+      )
+    end
+
+    def self.request_options(idempotency_key: nil)
+      {timeout_in_seconds: 20, additional_headers: {"Idempotency-Key" => idempotency_key}.compact}
+    end
+
+    def self.api = ApiProxy.new(client)
+
+    def self.with_api_errors
+      yield
+    rescue ::Whop_sdk::Errors::ApiError, Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout, SocketError, EOFError, Errno::ECONNRESET, Errno::ECONNREFUSED => error
+      raise ApiError.new(error)
+    end
+
+    def self.each_api_page(path, **query)
+      cursor = nil
+      seen = []
+      loop do
+        page = api_request(:get, path, query: query.merge(first: 100, after: cursor).compact)
+        page.fetch("data").each { |object| yield object }
+        break unless page.dig("page_info", "has_next_page")
+        cursor = page.dig("page_info", "end_cursor")
+        raise InvalidPayload, "Invalid pagination cursor" if cursor.blank? || seen.include?(cursor)
+        seen << cursor
+      end
+    end
+
+    def self.identity_purpose(account = account_id)
+      "pay-whop:#{environment}:#{account}"
+    end
+
+    def self.api_attributes(object)
+      JSON.parse(object.to_h.to_json)
+    end
+
+    def self.verify_account!(object, expected: nil)
+      actual = object["account_id"] || object.dig("account", "id")
+      raise IdentityError, "Whop account does not match resource" if expected && actual != expected
+      registered = actual.present? && (actual == account_id || Merchant.registered?(actual))
+      unless registered
+        raise IdentityError, "Whop account is not registered with this platform"
+      end
+      actual
+    end
+
+    def self.major_units(amount, decimals: 2)
+      raise ArgumentError, "Amount must be positive integer minor units" unless amount.is_a?(Integer) && amount.positive?
+      raise ArgumentError, "Invalid currency precision" unless decimals.is_a?(Integer) && (0..8).cover?(decimals)
+      value = BigDecimal(amount.to_s) / (10**decimals)
+      number = value.to_f
+      raise ArgumentError, "Amount exceeds JSON number precision" unless number.finite? && BigDecimal(number.to_s) == value
+      number
+    end
+
+    def self.each_page(endpoint, **filters)
+      endpoint.list(**filters, first: 100, request_options: request_options).each do |object|
+        yield api_attributes(object)
+      end
+    end
+
+    # SDK 2.7 truncates refund decimals and ignores additional_body_parameters.
+    def self.api_request(method, path, body: nil, query: {}, idempotency_key: nil)
+      with_api_errors { raw_api_request(method, path, body: body, query: query, idempotency_key: idempotency_key) }
+    end
+
+    def self.raw_api_request(method, path, body:, query:, idempotency_key:)
+      validate_configuration!
+      host = (environment == "sandbox") ? "sandbox-api.whop.com" : "api.whop.com"
+      uri = URI::HTTPS.build(host: host, path: "/api/v1/#{path}")
+      uri.query = URI.encode_www_form(query) if query.any?
+      request = Net::HTTP.const_get(method.to_s.capitalize).new(uri)
+      request["Authorization"] = "Bearer #{api_key}"
+      request["Api-Version-Date"] = api_version
+      request["Content-Type"] = "application/json"
+      request["Idempotency-Key"] = idempotency_key if idempotency_key
+      request.body = JSON.generate(body) if body
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+      http.open_timeout = http.read_timeout = http.write_timeout = 20
+      http.max_retries = 0
+      response = http.start { |connection| connection.request(request) }
+      unless response.is_a?(Net::HTTPSuccess)
+        error = ::Whop_sdk::Errors::ResponseError.subclass_for_code(response.code.to_i)
+        raise error.new(response.body, code: response.code.to_i)
+      end
+      response.body.to_s.empty? ? {} : JSON.parse(response.body, decimal_class: BigDecimal)
+    end
+
+    def self.minor_units(money, currency: nil)
+      raise InvalidPayload, "Missing Whop money object" unless money.is_a?(Hash)
+      raise InvalidPayload, "Currency mismatch" if currency && money.fetch("currency").downcase != currency.downcase
+      decimals = Integer(money.fetch("decimals"))
+      raise InvalidPayload, "Invalid currency precision" unless (0..8).cover?(decimals)
+      amount = BigDecimal(money.fetch("amount").to_s) * (10**decimals)
+      raise InvalidPayload, "Money is not an exact minor-unit amount" unless amount.finite? && amount.frac.zero? && amount >= 0
+      amount.to_i
+    end
+
+    def self.timestamp(value)
+      Time.iso8601(value) if value.present?
+    end
+  end
+end
+
+require "pay/whop/engine"

data/lib/pay-whop.rb

@@ -0,0 +1 @@
+require "pay/whop"