tillbell 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3a7d7ef87518e743a31df158672d329430f1880a426cc734727147934435dad0
+  data.tar.gz: eb4af5eb06a08afd2936cb12bc7b0d3a77dac981dd9f8c36f2ec82562ef05c1b
+SHA512:
+  metadata.gz: 5c610708ea4584f97b65e0379b0e83b543d696dede9a2f43a8d0273e751043b5f58e7763b8a6468b430bf426776aeab78d8280f424322c362cfde441e06ffc57
+  data.tar.gz: 4920b5c667d27df3813716ebd3413d34e6a3ccbb3b68af34337ea77afbc8253cd7849965b8e73258aeb56ba2805d603350e0879aa9db6742f564ead1e466c73f

data/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project are documented in this file. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Added
+
+- `Pay::GooglePlay` processor: Google Play subscriptions stored as Pay customers and
+  subscriptions, next to Stripe or any other Pay processor.
+- Server-side purchase verification (`POST /tillbell/purchases`) with an ownership check
+  and server-side acknowledgment.
+- Real-time developer notifications endpoint (`POST /tillbell/notifications/google_play`)
+  authenticated with the Pub/Sub OIDC token and processed through Pay's webhook pipeline.
+- Events: `subscription_created`, `subscription_updated`, `subscription_canceled`,
+  `subscription_expired`, `subscription_revoked` and `purchase_rejected`.
+- `tillbell_paywall` view helper, the `tillbell` Stimulus controller and the bridge
+  contract (JSON Schemas) implemented by the native libraries.
+- `rails generate tillbell:install`.
+- `google_play?` on Pay customers and subscriptions, and a `google_play` scope on both.
+
+### Fixed
+
+- Paywall texts fall back to English in a locale that has no translation, instead of
+  rendering a "translation missing" marker.
+- Deleting an owner no longer fails on a subscription that already stopped renewing.
+- A refunded subscription stays `canceled` when a later read reports it as active.

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2026 Pierre Filstroff
+
+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,341 @@
+# Tillbell
+
+[![CI](https://github.com/pmakerhq/tillbell-rails/actions/workflows/ci.yml/badge.svg)](https://github.com/pmakerhq/tillbell-rails/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](MIT-LICENSE)
+
+**Self-hosted in-app subscriptions for Rails + Hotwire Native apps, built on [Pay](https://github.com/pay-rails/pay).**
+
+Your Android app sells subscriptions through Google Play. Your Rails app verifies them, acknowledges them and keeps them in sync. No third-party service sits between the store and your server, and no extra table is added: Google Play subscriptions are regular `Pay::Subscription` records, right next to your Stripe ones.
+
+```ruby
+user.pay_subscriptions.active            # Stripe and Google Play together
+Pay::GooglePlay::Customer.for(user)     # the Google Play customer, next to Stripe
+subscription.active?                     # same rules as for Stripe
+```
+
+> [!NOTE]
+> **Status: v0.1, not released on RubyGems yet.** Google Play only for now. The App Store (StoreKit 2) is planned.
+
+## Table of contents
+
+- [Why Tillbell](#why-tillbell)
+- [Quick start](#quick-start)
+- [How it works](#how-it-works)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [The paywall](#the-paywall)
+- [Subscriptions and statuses](#subscriptions-and-statuses)
+- [Events](#events)
+- [Google Play setup](#google-play-setup)
+- [Security](#security)
+- [Troubleshooting](#troubleshooting)
+- [The Tillbell family](#the-tillbell-family)
+- [Getting help](#getting-help)
+- [Contributing](#contributing)
+- [Acknowledgements](#acknowledgements)
+- [License](#license)
+
+## Why Tillbell
+
+- **Your server is the source of truth.** Every purchase is read back from Google before it grants anything.
+- **One subscription model.** Web (Stripe, Paddle, ...) and Android subscriptions share Pay's tables, scopes and helpers.
+- **Access is immediate.** The paywall posts the purchase as soon as Google Play confirms it, without waiting for a notification.
+- **No vendor in the middle.** Google's real-time notifications go straight to your app. You pay no revenue share and keep your data.
+- **Small and replaceable.** A Rails engine, one Stimulus controller and a [documented bridge contract](docs/bridge-contract.md).
+
+## Quick start
+
+Assuming a Rails 8 app with a `User` model and Pay installed:
+
+1. Add the gems and run the installer:
+
+   ```sh
+   bundle add pay
+   bundle add tillbell --github pmakerhq/tillbell-rails   # until the first RubyGems release
+   bin/rails generate tillbell:install
+   ```
+
+2. Make the buyer a Pay customer:
+
+   ```ruby
+   class User < ApplicationRecord
+     pay_customer
+   end
+   ```
+
+3. Fill in `config/initializers/tillbell.rb`:
+
+   ```ruby
+   Tillbell.configure do |config|
+     config.google.package_name = "com.example.app"
+     config.google.service_account_json = Rails.application.credentials.dig(:tillbell, :google_service_account)
+     config.google.pubsub_service_account_email = "pubsub-push@my-project.iam.gserviceaccount.com"
+   end
+   ```
+
+4. Render a paywall:
+
+   ```erb
+   <%= tillbell_paywall success_url: dashboard_path do |paywall| %>
+     <%= paywall.plan_option product_id: "premium", base_plan_id: "monthly", checked: true do %>
+       Premium, <%= paywall.price %> per month
+     <% end %>
+     <%= paywall.submit %>
+     <%= paywall.fallback %>
+   <% end %>
+   ```
+
+5. Gate features with Pay, whatever the store:
+
+   ```ruby
+   current_user.pay_subscriptions.active.any?
+   ```
+
+Then add [tillbell-android](https://github.com/pmakerhq/tillbell-android) to your Hotwire Native app and follow the [Google Play setup](#google-play-setup).
+
+## How it works
+
+```
+ tillbell_paywall (Rails view) ──► "products" ──► native app ──► localized prices from Google Play
+          │
+          ▼  tap "Subscribe"
+ Stimulus controller ──► "purchase" ──► native app ──► Google Play purchase sheet
+          │                                (obfuscatedAccountId supplied by the server)
+          ▼
+ POST /tillbell/purchases (purchase token) ──► Rails reads the purchase from Google,
+                                               checks it belongs to the signed-in owner,
+                                               saves the Pay::Subscription, acknowledges it
+ Google Pub/Sub ──► POST /tillbell/notifications/google_play ──► Pay::Webhook ──► re-read from Google
+```
+
+The page and the native app talk through a [Hotwire Native bridge component](https://native.hotwired.dev/overview/bridge-components) named `tillbell`. Its messages are specified in [docs/bridge-contract.md](docs/bridge-contract.md), with JSON Schemas in [contract/](contract).
+
+- **The server never trusts the client.** A purchase made with another owner's account id is refused.
+- **Notifications are triggers, not truth.** A notification only says which purchase changed. Tillbell reads the current state from Google, so duplicated or out-of-order notifications end in the same state.
+- **Purchases are acknowledged on the server.** Google refunds subscriptions that are not acknowledged within three days. The native app never acknowledges.
+- **Idempotent.** Syncing the same state twice changes nothing and emits no event.
+
+## Requirements
+
+| | Version |
+|---|---|
+| Ruby | 3.3+ (tested on 3.3, 3.4 and 4.0) |
+| Rails | 8.0+ (tested on 8.0 and 8.1) |
+| Pay | 12+, installed and migrated |
+| Active Job | A queue backend in production (Solid Queue, Sidekiq, ...) |
+| Android app | Hotwire Native with [tillbell-android](https://github.com/pmakerhq/tillbell-android) |
+
+## Installation
+
+```ruby
+# Gemfile
+gem "pay"
+gem "tillbell"
+```
+
+```sh
+bundle install
+bin/rails pay:install:migrations db:migrate   # skip if you already use Pay
+bin/rails generate tillbell:install
+```
+
+The generator:
+
+- creates `config/initializers/tillbell.rb`;
+- mounts the engine with `mount Tillbell::Engine, at: "/tillbell"` (change the path if you like);
+- copies the Stimulus controller to `app/javascript/controllers/tillbell_controller.js`;
+- pins `@hotwired/hotwire-native-bridge` with importmap. With a JavaScript bundler, run `npm install @hotwired/hotwire-native-bridge` yourself.
+
+The model that buys subscriptions must be a Pay customer:
+
+```ruby
+class User < ApplicationRecord
+  pay_customer
+end
+```
+
+## Configuration
+
+```ruby
+# config/initializers/tillbell.rb
+Tillbell.configure do |config|
+  config.google.package_name = "com.example.app"
+  config.google.service_account_json = Rails.application.credentials.dig(:tillbell, :google_service_account)
+  config.google.pubsub_service_account_email = "pubsub-push@my-project.iam.gserviceaccount.com"
+end
+```
+
+| Setting | Default | Description |
+|---|---|---|
+| `google.package_name` | (required) | Application id of the Android app. |
+| `google.service_account_json` | (required) | JSON key (string or hash) of the service account that calls the Google Play Developer API. |
+| `google.pubsub_service_account_email` | (required for notifications) | Service account the Pub/Sub push subscription signs its requests with. |
+| `google.pubsub_audience` | endpoint URL | Audience of the Pub/Sub OIDC token. Set it when a proxy changes the URL Rails sees. |
+| `current_owner` | `-> { current_user }` | Returns who is buying. Evaluated in the controller and in the view, so any helper available there works (`Current.user`, `current_account`, ...). |
+| `parent_controller` | `"ApplicationController"` | Controller the purchase endpoint inherits from, to reuse your authentication, CSRF protection and error handling. |
+| `subscription_name` | `->(product_id:, base_plan_id:) { Pay.default_product_name }` | Pay subscription `name` of a Google Play product, as used by `subscribed?(name:)`. |
+
+## The paywall
+
+```erb
+<%= tillbell_paywall success_url: dashboard_path, class: "paywall" do |paywall| %>
+  <%= paywall.plan_option product_id: "premium", base_plan_id: "monthly", checked: true do %>
+    Monthly, <%= paywall.price %>
+  <% end %>
+  <%= paywall.plan_option product_id: "premium", base_plan_id: "yearly" do %>
+    Yearly, <%= paywall.price %>
+  <% end %>
+
+  <%= paywall.submit %>
+  <%= paywall.restore %>
+  <%= paywall.manage %>
+  <%= paywall.status %>
+  <%= paywall.fallback %>
+<% end %>
+```
+
+The markup is unstyled and every builder method accepts HTML attributes (`class:`, `data:`, ...). Texts default to the `tillbell.paywall` translations in [config/locales/en.yml](config/locales/en.yml). Override them in your locale files, or pass the text as the first argument (`paywall.submit "Go premium"`). A locale without translations falls back to English.
+
+| Builder method | Renders |
+|---|---|
+| `plan_option(product_id:, base_plan_id: nil, checked: false, replacing: nil, replacement_mode: nil)` | A radio button wrapped in a label with the block's content. |
+| `price(placeholder = "")` | Where the price localized by Google Play is written. Use it inside `plan_option`. |
+| `submit(text)` | Starts the purchase of the checked plan. |
+| `restore(text)` | Records again the purchases Google Play knows for the device, e.g. after a reinstall. |
+| `manage(text)` | Opens the Play Store subscription page. |
+| `status` | A polite live region for status messages ("We are checking your purchase", ...). |
+| `fallback(text)` or `fallback { ... }` | Shown in a browser or in an app version without the native component. |
+
+Prices always come from Google Play, never from your app.
+
+**Without the native component** (a browser, or an old app version), the Stimulus controller does not connect. The buttons stay disabled, the fallback stays visible, and no purchase can start.
+
+**Plan changes.** Pass the current subscription and Google's [replacement mode](https://developer.android.com/google/play/billing/subscriptions#replacement-modes). Tillbell passes the mode through and never decides proration:
+
+```erb
+<%= paywall.plan_option product_id: "family", base_plan_id: "monthly",
+      replacing: current_user.pay_subscriptions.active.first,
+      replacement_mode: "CHARGE_PRORATED_PRICE" do %>
+  Switch to Family, <%= paywall.price %>
+<% end %>
+```
+
+**JavaScript events.** The controller dispatches events on the paywall element:
+
+- `tillbell:verified`: the purchase grants access. Call `event.preventDefault()` to stay on the page instead of visiting `success_url`.
+- `tillbell:status`: a status message is shown (`event.detail` is `{ key, message }`).
+
+The controller is copied into your app, so you can also change it.
+
+## Subscriptions and statuses
+
+Google states are mapped to Pay statuses, so Pay helpers behave as they do for Stripe:
+
+| Google `subscriptionState` | Pay `status` | `active?` | Notes |
+|---|---|---|---|
+| `PENDING` | `incomplete` | no | Payment not confirmed yet (e.g. cash). |
+| `ACTIVE` | `active` | yes | |
+| `IN_GRACE_PERIOD` | `active` | yes | Google requires access during the grace period. `in_grace_period?` is true. |
+| `ON_HOLD` | `past_due` | no | Payment failed after the grace period. `on_hold?` is true. |
+| `PAUSED` | `paused` | no | |
+| `CANCELED` | `active` with `ends_at` | until `ends_at` | Will not renew. `canceled?` and `on_grace_period?` are true. |
+| `EXPIRED` | `canceled` | no | |
+| refunded (revoked) | `canceled`, `ends_at` = now | no | `revoked?` is true. |
+
+Whether a status grants access is your decision. The recommended default is `subscription.active?`, which follows Google's rules above.
+
+A `Pay::GooglePlay::Subscription` stores:
+
+- `processor_id`: the purchase token;
+- `processor_plan`: the Google product id;
+- `data`: `base_plan_id`, `subscription_state`, `auto_renewing` and `revoked_at`;
+- `object`: Google's last answer.
+
+Pay only knows its own processors, so Tillbell adds `google_play?` to customers and subscriptions, and a `google_play` scope next to Pay's `stripe` one (`Pay::Subscription.google_play`).
+
+`subscription.cancel` stops the renewal through the Google Play Developer API. `swap`, `pause` and `resume` raise `Tillbell::Error`: plan changes go through the paywall, and the rest happens in the Play Store.
+
+## Events
+
+```ruby
+Tillbell.configure do |config|
+  config.on(:subscription_created)  { |subscription| WelcomeMailer.with(user: subscription.owner).premium.deliver_later }
+  config.on(:subscription_updated)  { |subscription| }  # renewal, grace period, hold, recovery, plan change
+  config.on(:subscription_canceled) { |subscription| }  # will not renew; access until ends_at
+  config.on(:subscription_expired)  { |subscription| }
+  config.on(:subscription_revoked)  { |subscription| }  # refunded or charged back
+  config.on(:purchase_rejected)     { |details| }       # { owner:, purchase_token: } posted by another account
+end
+```
+
+Events go through Pay's webhook delegator, so `Pay::Webhooks.delegator.subscribe "tillbell.subscription_created", MyHandler.new` works too. An event fires once per actual change, after the subscription is saved. An error raised in a callback is reported to `Rails.error` and does not undo the change.
+
+## Google Play setup
+
+1. **Service account.** In Google Cloud, create a service account and a JSON key, and enable the *Google Play Android Developer API*. In the Play Console, under *Users and permissions*, invite the service account with *View financial data* and *Manage orders and subscriptions*. Store the key in your credentials as `tillbell.google_service_account`.
+2. **Pub/Sub topic.** Create a topic, and grant `google-play-developer-notifications@system.gserviceaccount.com` the *Pub/Sub Publisher* role on it. In the Play Console, under *Monetization setup*, enter the topic name for real-time developer notifications.
+3. **Push subscription.** Create a push subscription on the topic:
+   - endpoint: `https://your-app.example.com/tillbell/notifications/google_play`;
+   - *Enable authentication* turned on, with a service account of your choice. Set its e-mail as `google.pubsub_service_account_email`;
+   - audience: leave it empty (it defaults to the endpoint URL), or set the same value as `google.pubsub_audience`.
+4. **Test.** Click *Send test notification* in the Play Console. The endpoint answers 200 and logs `[Tillbell] Google Play notification test_notification`.
+5. **License testers.** Add your testers in the Play Console, and install the app from a Play testing track to buy with test cards.
+
+## Security
+
+- The purchase endpoint inherits from your `ApplicationController`, so your authentication and CSRF protection apply. It never trusts an owner or account id sent by the client.
+- Every purchase is read back from Google, and the purchase's `obfuscatedAccountId` must match the signed-in owner's Google Play customer.
+- Notifications must carry an OIDC token signed by Google for the configured service account. Anything else gets a 401.
+- The account id sent to Google is a random UUID, never an e-mail or a database id.
+- Purchase tokens are never logged in full.
+
+Found a vulnerability? Please report it privately, as described in [SECURITY.md](SECURITY.md).
+
+## Troubleshooting
+
+**The paywall buttons stay disabled.** The page is not running inside an app that registers the `tillbell` bridge component (a browser, or an app without [tillbell-android](https://github.com/pmakerhq/tillbell-android)). This is expected: the fallback is shown instead.
+
+**`POST /tillbell/purchases` answers 401.** `current_owner` returned `nil`: the request is not signed in, or `current_owner` does not match your authentication.
+
+**A purchase is `rejected`.** It was made with the Google Play account id of another owner, for example after switching users on the same device.
+
+**A purchase stays in `verifying`.** Google could not be reached. The purchase is verified by `Tillbell::SyncJob`, so check that your Active Job backend is running.
+
+**Notifications answer 401.** The Pub/Sub token does not match the configuration. Check `google.pubsub_service_account_email`, and set `google.pubsub_audience` when a proxy or load balancer changes the URL Rails sees.
+
+## The Tillbell family
+
+| Repository | Purpose |
+|---|---|
+| **tillbell-rails** (this repo) | Rails engine: Pay processor, purchase verification, notifications, paywall helper |
+| [tillbell-android](https://github.com/pmakerhq/tillbell-android) | Hotwire Native bridge component for Google Play Billing |
+| [tillbell-ios](https://github.com/pmakerhq/tillbell-ios) | Hotwire Native bridge component for StoreKit 2 (planned) |
+
+## Getting help
+
+- Questions and bug reports: [open an issue](https://github.com/pmakerhq/tillbell-rails/issues/new/choose).
+- Security issues: see [SECURITY.md](SECURITY.md). Do not open a public issue.
+- Changes between versions: [CHANGELOG.md](CHANGELOG.md).
+
+## Contributing
+
+Bug reports, documentation fixes and pull requests are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) to set up the project, run the tests and open a pull request. In short:
+
+```sh
+git clone https://github.com/pmakerhq/tillbell-rails.git
+cd tillbell-rails
+bundle install
+bin/rspec      # test suite, with a dummy app in spec/dummy; Google is stubbed
+bin/rubocop    # rubocop-rails-omakase
+```
+
+## Acknowledgements
+
+Tillbell is inspired by [PurchaseKit](https://github.com/PurchaseKit/purchasekit) by Joe Masilotti, which showed that a Rails gem plus small Hotwire Native bridge components is a good shape for in-app purchases, and which is MIT licensed. PurchaseKit routes store notifications through a hosted service. Tillbell is an independent project that does this part inside your own app. It is not affiliated with or endorsed by PurchaseKit. No file in this repository is derived from PurchaseKit's code.
+
+Tillbell stands on [Pay](https://github.com/pay-rails/pay), by Chris Oliver and contributors.
+
+## License
+
+Tillbell is open source under the [MIT License](MIT-LICENSE).

data/app/controllers/tillbell/notifications_controller.rb

@@ -0,0 +1,71 @@
+module Tillbell
+  # Receives Google Play real-time developer notifications from a Cloud Pub/Sub push
+  # subscription.
+  #
+  # The endpoint is public, so every request must carry an OIDC token signed by Google
+  # for the configured Pub/Sub service account; anything else gets a 401. Verified
+  # notifications are stored and processed by Pay (+Pay::Webhook+ and
+  # +Pay::Webhooks::ProcessJob+), exactly like Stripe webhooks, and answered with a 200
+  # straight away. A non-2xx answer would make Pub/Sub deliver the message again.
+  class NotificationsController < Pay::Webhooks::BaseController
+    # Notification kinds, as keys of the decoded Pub/Sub message.
+    # See https://developer.android.com/google/play/billing/rtdn-reference
+    KINDS = %w[subscriptionNotification voidedPurchaseNotification testNotification oneTimeProductNotification].freeze
+
+    # +productType+ of a voided purchase that is a subscription (2 is a one-time product).
+    VOIDED_SUBSCRIPTION = 1
+
+    private
+      # Verifies the Pub/Sub token and returns the decoded notification.
+      def verified_event
+        GooglePlay.verify_pubsub_token!(request.authorization.to_s.delete_prefix("Bearer "), audience: audience)
+
+        # Pub/Sub wraps the notification in a base64 encoded "data" field.
+        JSON.parse(params.dig(:message, :data).to_s.unpack1("m"))
+      rescue JSON::ParserError
+        raise Tillbell::Error, "Malformed Pub/Sub message"
+      end
+
+      def event_type(notification)
+        KINDS.find { |kind| notification.key?(kind) }&.underscore
+      end
+
+      # Only subscription changes of this app are processed; everything else is
+      # acknowledged so Pub/Sub stops sending it.
+      def queue?(notification)
+        kind = event_type(notification)
+        log(notification, kind)
+
+        return false unless notification["packageName"] == GooglePlay.package_name
+
+        case kind
+        when "subscription_notification" then true
+        when "voided_purchase_notification" then notification.dig("voidedPurchaseNotification", "productType") == VOIDED_SUBSCRIPTION
+        else false
+        end
+      end
+
+      # Pay derives the processor from the controller name; this one is not named after it.
+      def processor
+        "google_play"
+      end
+
+      # Pub/Sub signs its requests for the push endpoint URL unless configured otherwise.
+      def audience
+        Tillbell.google.pubsub_audience.presence || "#{request.base_url}#{request.path}"
+      end
+
+      def invalid_signature
+        head :unauthorized
+      end
+
+      # Logs the kind of notification and a shortened token, never the full token.
+      def log(notification, kind)
+        token = notification.dig("subscriptionNotification", "purchaseToken") ||
+          notification.dig("voidedPurchaseNotification", "purchaseToken")
+        type = notification.dig("subscriptionNotification", "notificationType")
+        Rails.logger.info "[Tillbell] Google Play notification #{kind || "unknown"}" \
+          "#{" type=#{type}" if type}#{" token=#{Tillbell.redact(token)}" if token}"
+      end
+  end
+end

data/app/controllers/tillbell/purchases_controller.rb

@@ -0,0 +1,44 @@
+module Tillbell
+  # Records a Google Play purchase made in the native app.
+  #
+  # The paywall posts the purchase token here as soon as the Play purchase sheet
+  # succeeds, so access is granted without waiting for a notification. The token is
+  # never trusted: Tillbell reads the purchase from Google and checks that it was made
+  # with the account id of the signed-in owner.
+  #
+  # Inherits from +Tillbell.parent_controller+ to run the host app's authentication and
+  # CSRF protection.
+  #
+  # Responds with JSON whose +status+ is one of:
+  #
+  # [verified] The purchase is recorded; +active+ tells whether it grants access yet
+  #            (a pending purchase does not).
+  # [verifying] Google could not be reached; the purchase is verified in the background.
+  # [rejected] The purchase belongs to another account.
+  # [invalid] Google does not know this purchase token.
+  class PurchasesController < Tillbell.parent_controller.constantize
+    def create
+      owner = instance_exec(&Tillbell.current_owner)
+      return head :unauthorized if owner.nil?
+
+      purchase_token = params.expect(:purchase_token)
+      purchase = GooglePlay.subscription(purchase_token)
+
+      if GooglePlay.account_id(purchase) == Pay::GooglePlay::Customer.for(owner).processor_id
+        subscription = Pay::GooglePlay::Subscription.sync(purchase_token, object: purchase)
+        render json: { status: "verified", active: subscription.active?, subscription_status: subscription.status }
+      else
+        Tillbell.instrument(:purchase_rejected, owner: owner, purchase_token: Tillbell.redact(purchase_token))
+        render json: { status: "rejected" }, status: :forbidden
+      end
+    rescue *GooglePlay::TRANSIENT_ERRORS
+      # The job only trusts Google's answer, so it can safely finish without the owner check.
+      SyncJob.perform_later(purchase_token)
+      render json: { status: "verifying" }, status: :accepted
+    rescue Google::Apis::ClientError => error
+      raise unless GooglePlay.invalid_token?(error)
+
+      render json: { status: "invalid" }, status: :unprocessable_content
+    end
+  end
+end

data/app/helpers/tillbell/paywall_builder.rb

@@ -0,0 +1,81 @@
+module Tillbell
+  # Builds the parts of a paywall; yielded by +tillbell_paywall+.
+  #
+  # Every method takes HTML attributes, so the host app owns the markup and the styles.
+  # Texts default to the +tillbell.paywall+ translations.
+  class PaywallBuilder
+    def initialize(template)
+      @template = template
+    end
+
+    # A radio button for one Google Play base plan, wrapped in a label with the block's
+    # content. Pass +replacing+ (the current Pay::GooglePlay::Subscription) to make it a
+    # plan change; +replacement_mode+ is Google's proration mode, e.g.
+    # "CHARGE_PRORATED_PRICE", and is passed through untouched.
+    def plan_option(product_id:, base_plan_id: nil, checked: false, replacing: nil, replacement_mode: nil, **html_options, &block)
+      raise ArgumentError, "a plan change needs a replacement_mode" if replacing && replacement_mode.blank?
+
+      radio = tag.input(
+        type: "radio", name: "tillbell_plan", value: [ product_id, base_plan_id ].compact.join(":"),
+        checked: checked, disabled: true,
+        data: {
+          tillbell_target: "plan", product_id: product_id, base_plan_id: base_plan_id,
+          old_purchase_token: replacing&.processor_id, replacement_mode: replacement_mode
+        }.compact
+      )
+      tag.label(**html_options) { radio + @template.capture(&block) }
+    end
+
+    # Placeholder for the localized price, filled in from Google Play. Use it inside a
+    # +plan_option+ block.
+    def price(placeholder = "", **html_options)
+      tag.span(placeholder, **with_data(html_options, tillbell_target: "price"))
+    end
+
+    # Starts the purchase of the checked plan.
+    def submit(text = t("submit"), **html_options)
+      button(text, "purchase", **html_options)
+    end
+
+    # Asks Google Play for existing purchases and records them again, e.g. after a reinstall.
+    def restore(text = t("restore"), **html_options)
+      button(text, "restorePurchases", **html_options)
+    end
+
+    # Opens the Play Store subscription page.
+    def manage(text = t("manage"), **html_options)
+      button(text, "manage", **html_options)
+    end
+
+    # Live region where the controller writes status messages.
+    def status(**html_options)
+      tag.p(role: "status", aria: { live: "polite" }, **with_data(html_options, tillbell_target: "status"))
+    end
+
+    # Shown until the native component connects, i.e. in a browser or an outdated app.
+    def fallback(text = t("fallback"), **html_options, &block)
+      content = block ? @template.capture(&block) : text
+      tag.div(content, **with_data(html_options, tillbell_target: "fallback"))
+    end
+
+    private
+      def button(text, action, **html_options)
+        tag.button(text, type: "button", disabled: true,
+          **with_data(html_options, tillbell_target: "action", action: "tillbell##{action}"))
+      end
+
+      # Adds the data attributes the controller relies on to the caller's attributes,
+      # keeping any data attribute the caller passed.
+      def with_data(html_options, data)
+        html_options.merge(data: data.merge(html_options.fetch(:data, {})))
+      end
+
+      def tag
+        @template.tag
+      end
+
+      def t(key)
+        Tillbell.translate(key)
+      end
+  end
+end

data/app/helpers/tillbell/paywall_helper.rb

@@ -0,0 +1,40 @@
+module Tillbell
+  # View helper rendering the Google Play paywall, available in every view of the host app.
+  module PaywallHelper
+    # Renders an unstyled paywall driven by the +tillbell+ Stimulus controller, which
+    # talks to the +tillbell+ Hotwire Native bridge component.
+    #
+    #   <%= tillbell_paywall success_url: dashboard_path, class: "paywall" do |paywall| %>
+    #     <%= paywall.plan_option product_id: "premium", base_plan_id: "monthly", checked: true do %>
+    #       Monthly, <%= paywall.price %>
+    #     <% end %>
+    #     <%= paywall.submit %>
+    #     <%= paywall.restore %>
+    #     <%= paywall.manage %>
+    #     <%= paywall.status %>
+    #     <%= paywall.fallback %>
+    #   <% end %>
+    #
+    # Outside the native app (or in an app version without the component) the controller
+    # never connects: the buttons stay disabled and only the fallback is shown.
+    #
+    # [success_url] Where to go once a purchase grants access.
+    # [owner] The Pay owner buying; defaults to +Tillbell.current_owner+.
+    # [html_options] Attributes of the wrapping +div+.
+    def tillbell_paywall(success_url:, owner: instance_exec(&Tillbell.current_owner), **html_options, &block)
+      raise ArgumentError, "tillbell_paywall needs a signed-in owner" if owner.nil?
+
+      data = {
+        controller: "tillbell",
+        tillbell_account_id_value: Pay::GooglePlay::Customer.for(owner).processor_id,
+        tillbell_purchase_url_value: tillbell.purchases_path,
+        tillbell_success_url_value: success_url,
+        tillbell_messages_value: Tillbell.translate("messages").to_json
+      }
+
+      tag.div(**html_options, data: data.merge(html_options.fetch(:data, {}))) do
+        capture(PaywallBuilder.new(self), &block)
+      end
+    end
+  end
+end

data/app/jobs/tillbell/sync_job.rb

@@ -0,0 +1,21 @@
+module Tillbell
+  # Reads a Google Play purchase and updates its Pay subscription in the background.
+  #
+  # Enqueued for every real-time developer notification, and when Google could not be
+  # reached while recording a purchase. Google outages and rate limits are retried;
+  # a token Google does not know is dropped.
+  class SyncJob < ActiveJob::Base
+    queue_as :default
+
+    retry_on(*GooglePlay::TRANSIENT_ERRORS, wait: :polynomially_longer, attempts: 10)
+    discard_on(Google::Apis::ClientError) do |_job, error|
+      # Anything but an invalid token is a configuration problem worth failing loudly for.
+      raise error unless GooglePlay.invalid_token?(error)
+    end
+
+    # +revoked+ is true when the notification reports a refund.
+    def perform(purchase_token, revoked: false)
+      Pay::GooglePlay::Subscription.sync(purchase_token, revoked: revoked)
+    end
+  end
+end