0. What exists today (all freshly checked, not copied from old docs)

Verified against origin/master @ e9523ea8b, 2026-09-22.

0.1 Built and working (iOS)

The client's rule deserves repeating (from the header of iap_service.dart):

Call completePurchase() only after the backend has returned 200.

Do it the other way round and a dropped connection or a crash leaves the transaction permanently marked complete by the store, unreachable forever — the user paid and the Sparks vanish, with no way to recover them. Because that rule is held, an unfinished transaction is re-delivered on the next launch, re-submitted automatically, and the backend's primary key makes the retry harmless. Android must copy this rule exactly.

0.2 Entirely missing (Android)

I scanned backend/ and app/lib/ for androidpublisher, play.?billing, purchaseToken and google.?play. Zero hits in the backend — only docs saying it was never built. Missing:

1. Server-side validation of Google Play purchases (needs the Play Developer API + a service account)
2. Real-time Developer Notifications (RTDN, over Pub/Sub) — the Apple equivalent already exists
3. iap_transactions has no platform column, and its primary key is Apple's transaction ID
4. The six products do not exist in Play Console
5. No com.android.vending.BILLING in our AndroidManifest.xml — ⚠️ this may not be a gap: in_app_purchase_android declares it in its own manifest and Gradle merges it. First task is to unpack a release build and run aapt dump permissions to confirm, rather than adding a possibly-duplicate line.

0.3 Real production numbers (queried just now)

iap_transactions   0 rows    — nobody has ever bought anything
payouts            0 rows    — nobody has ever been paid
dev_ledger        24 rows / 6 developers / 1,229 Sparks (≈ MYR 12.29)

That zero is the most valuable number in this plan. Re-anchoring the tiers costs almost nothing: there is no purchase history to stay consistent with, and no user holds a balance bought at the old price. Right now is the cheapest this will ever be.

⚠️ But zero transactions does not prove the products are absent from App Store Connect or Play Console. A product ID, once created, can never be reused on either store. Step one is for a human to log into both consoles and look — that is the one thing I cannot see from here.

1. How the six packages should be organised

1.1 Product types: all six consumable. No non-consumables, no subscriptions.

• Consumable — you buy it, it becomes Sparks, you spend them. All six are this.
• Non-consumable — none. HOOP has nothing you buy once and own forever.
• Subscriptions — no store subscriptions at all, and there should not be any. ⚠️ Easy to get wrong here: the AI assistant does have weekly / monthly / yearly plans (assistant.go:88-92 — 400 / 1,200 / 12,000), but those are paid in Sparks, not through StoreKit or Play Billing. The wallet is debited; no store is involved. The principle: real money enters through exactly one door — buying Sparks. Everything after that is internal. This is worth defending. A second real-money entrance means refunds, tax handling and reconciliation all have to be built twice.

1.2 Pricing: Spark amounts stay, prices anchored directly in MYR

🗓️ Decided by Leong, 2026-09-22: the six tiers keep exactly the Spark amounts they have today, and prices are set directly in MYR — never by converting from USD. This section previously proposed a different set of six tiers with a narrower bonus ladder; that version is retired, and why is recorded in 1.2.3.

1.2.1 The price table (single source of truth; products.go follows this)

The floor is anchored to the rate Li Min set on 2026-09-15: 100 Sparks = MYR 1. The smallest tier sits exactly on that rate; the larger tiers are not discounts — they give more Sparks for the same money.

No bonus badge has to change: the percentages land exactly on the BonusPct values already written in products.go — 0 / 7 / 13 / 18 / 27 / 36 — so the existing UI badges stay as they are.

⚠️ Rounding is always downward (14.95 → 14.90, 55.08 → 55.00). The direction is deliberate: rounding down means the buyer gets slightly more bonus than the badge claims, never less. The other direction would make the badge a lie.

1.2.2 The worst case, worked out (this is the only real constraint on pricing)

Worst case = an entire pack spent wholly on music tips, where the creator takes 50% (revshare.go:27). Our side of that liability is valued at the accounting rate, 100 Sparks = MYR 1.

All six are positive in the worst case — which is exactly what the re-anchor was for: under the old USD pricing the largest tier was −MYR 12.53 (arithmetic kept in 1.2.4 for contrast).

⚠️ But see where it is thin: the +MYR 5.00 on the largest tier is 2% of the sale price. The cause is not an underpriced tier — it is the 36% bonus ladder and the 50% creator share together consuming most of what Apple leaves behind.

🔴 The one sentence worth taking from this section: enrolling in the App Store Small Business Program (30% → 15%) is worth more than any price point on this table — with the very same prices, the top tier's margin goes from MYR 5 to MYR 42.50, more than eight times better, without changing a single number. It is already a checkbox in §10.1, but there it looks like a formality; it is in fact the highest-return step on this whole track.

1.2.3 Why the earlier "narrow the bonus ladder" proposal was dropped

This section used to propose a different six (500 / 1,050 / 2,750 / 5,700 / 11,800 / 24,000, with the bonus capped at +18%), specifically to widen that 2% margin. Leong's decision on 09-22 was to keep the existing Spark amounts, so that version is retired.

The cost is recorded here rather than hidden: keeping the 36% bonus ladder means accepting a 2% worst-case margin on the largest tier. That is not a wrong choice — what it buys is that the catalogue need not be rebuilt, no badge changes, and no buyer sees less content than before. But it does turn the Small Business Program from an option into effectively a precondition.

1.2.4 The old USD pricing, for contrast (do not build from this)

Buyer pays        US$49.99  ≈ MYR 224.96 (at 1 USD = 4.5 MYR)
Apple takes 30%   →  we keep MYR 157.47
That pack mints   34,000 Sparks
If all of it goes to music tips (creator takes 50%)
  → we owe the creator 17,000 Sparks = MYR 170.00
Net               157.47 − 170.00 = −12.53   ❌ a loss

1.2.5 This table still cannot be typed into the consoles as-is

⚠️ "Price" is not the same as "a price you can enter": both stores make you pick from their own price-point grid, not type an arbitrary number. The table above is the target anchor; the real work is picking the nearest available point in each console — a person has to confirm this, and I will not invent Apple's Malaysian price grid for them. Once picked, come back and change this table to the numbers actually entered, and recompute the six rows in 1.2.2.

1.3 Product ID / SKU naming

Rule: com.hooptech.hoop.spark.<spark amount>

• Prefix matches the bundle ID and applicationId (com.hooptech.hoop, identical on both platforms — see build.gradle.kts:50)
• Use spark, not green: the public name changed on 2026-09-15, and a product ID can never be changed. Do not carve a retired name into something permanent.
• Suffix is the Spark amount, not a tier number: t1…t6 tells you nothing, while the amount is fixed for the life of the product (changing it means a new product anyway)
• Same IDs on both platforms — that is what lets the backend keep one mapping table

🗓️ Since 2026-09-22 there is a cheaper path here — read this first

Now that the Spark amounts no longer change, the only remaining reason to create six new products is the rename — and product ids are invisible to users: topup_screen.dart:153 uses the id purely as a lookup key (_svc.products[id]) and never draws it on screen.

So if Phase 0 finds that the six …green.500 products already exist in ASC: just change their prices — do not create six and retire six. Price is editable, and the Spark amount lives in our own backend table, not in the store.

The criterion: this re-anchor changes price, not content. New ids are only unavoidable when the content amount changes. The cost is that the retired word green stays in the id forever — but it lives only in the two console back-office lists, nowhere a user can see.

⚠️ Either path can only be settled after a person checks the consoles. That is Phase 0.

⚠️ Google Play's ID rules are stricter: lowercase letters, digits, underscores and periods only, and it must start with a letter or digit. The naming above is legal on both — but on both, an ID that has been created can never be reused (Apple says so explicitly; Play blocks re-creating a deleted ID). Do not press "create" in either console until this table is final.

2. Wireframes (screen by screen, state by state)

2.1 Screen inventory

2.2 Screen B — top-up

┌──────────────────────────────────────┐
│  ←   Top up                 Restore  │   ← Restore disabled while pending
├──────────────────────────────────────┤
│  ┌────────────────────────────────┐  │
│  │  Your balance                  │  │
│  │  ❇️  1,250                     │  │   ← shows "—" when unknown, never 0
│  │  Sparks are spent inside HOOP  │  │
│  └────────────────────────────────┘  │
│                                      │
│  ┌──────────┐  ┌──────────┐          │
│  │   500    │  │  1,600   │          │
│  │  Sparks  │  │  Sparks  │          │
│  │          │  │  +7%     │          │
│  │ RM 5.00  │  │ RM 14.90 │          │   ← must be the store's localised string
│  └──────────┘  └──────────┘          │
│  ┌──────────┐  ┌──────────┐          │
│  │  3,400   │  │  6,500   │ POPULAR  │
│  │  +13%    │  │  +18%    │          │
│  │ RM 30.00 │  │ RM 55.00 │          │
│  └──────────┘  └──────────┘          │
│  ┌──────────┐  ┌──────────┐          │
│  │ 14,000   │  │  34,000  │          │
│  │  +27%    │  │  +36%    │          │
│  │ RM 110   │  │ RM 250   │          │
│  └──────────┘  └──────────┘          │
│                                      │
│  Prices are shown in your local      │
│  currency by the store. Hoop Spark   │
│  is non-refundable, cannot be        │
│  transferred or cashed out.          │
│           Terms · Privacy            │
└──────────────────────────────────────┘

Three things that must not change (already written at the top of topup_screen.dart; both stores check them at review):

1. The price must be the store's localised string. Hardcoding gets the app rejected, and shows the wrong currency and amount to anyone outside Malaysia.
2. The footer must state non-refundable / non-transferable / cannot be cashed out, with links to terms and privacy.
3. Restore is not decoration. Stores do not "restore" consumables, but the action makes the store re-deliver unfinished transactions — it is the user's own way out of "I paid and got nothing".

2.3 Every state

① Loading           six skeleton cards, Restore disabled
② Normal            as above
③ One tier busy     that card's price becomes a spinner; the other five disable (one at a time)
④ Success           green SnackBar: ⚡ 500 Sparks added; balance card animates
⑤ User cancelled    silent. Nothing.      ← cancelling is not an error; do not punish it with a dialog
⑥ Failed            red SnackBar + "Try again"  ⚠️ currently logs only — this is work to do
⑦ Already credited  "Already added", balance refreshes, no second celebration
⑧ Paid but not yet confirmed  ⚠️ the most important missing screen:
                      "Payment received. Adding your Sparks…
                       This can take a moment. You can close this page —
                       it will finish by itself."
                      ← must not say failed (we took the money) and must not say
                        success (it has not landed yet)
⑨ Store unavailable "The store isn't available right now" + Retry
⑩ Zero products     same as ⑨ — usually not a code bug but an unfinished console agreement
⑪ Pending (Android) "Waiting for your payment to clear"
                      ← Android-only: some payment methods (cash at a store) take days

⑧ and ⑪ are the two new states, and neither is decoration. ⑧ is the only explanation a user gets during the seconds when their money is gone and their Sparks have not arrived. ⑪ is Android's PENDING transaction, effectively unseen on iOS — without it, a user assumes the purchase failed and buys again.

2.4 Screen H — purchase history (new)

┌──────────────────────────────────────┐
│  ←   Spark history                   │
├──────────────────────────────────────┤
│  ❇️ +500      Top up        22 Sep   │
│     RM 5.00 · Apple                  │
│  ❇️ −1,200    AI assistant  20 Sep   │
│  ❇️ −50       Tip · song     19 Sep  │
│  ❇️ +100      Daily check-in 18 Sep  │
│  ❇️ +1,000    Welcome gift  01 Sep   │
├──────────────────────────────────────┤
│         Load more                    │
└──────────────────────────────────────┘

The backend is already there (wallet_ledger, with kind in grant / iap_topup / purchase / tip / refund / admin / checkin) and api_client.dart:4551 already wraps it — only the screen is missing. ⚠️ The journal only starts in August 2026; earlier balance changes have no rows. The footer has to say so, or users will think we lost their history.

2.5 Navigation

"Me" tab → wallet card ─┬─→ [Top up]   → B top-up → C store sheet → D/E
                        └─→ [History]  → H purchase history (new)

3. User flow / state diagram

        ┌──────────────┐
        │  idle        │
        └──────┬───────┘
               │ taps a tier
               ▼
        ┌──────────────┐   cancelled in store sheet
        │  purchasing  ├────────────────────────────→ idle (silent)
        └──────┬───────┘
               │ store reports purchased / restored
               ▼
        ┌──────────────┐
        │  redeeming   │  ← send the receipt to our backend
        └──┬────────┬──┘
           │        │
       200 OK    non-200 / timeout / offline
           │        │
           ▼        ▼
     ┌─────────┐  ┌──────────────────────────┐
     │ credited│  │ unconfirmed              │
     │ finish()│  │ **never finish**          │
     └─────────┘  │ transaction stays at the  │
                  │ store; next launch        │
                  │ re-delivers → redeeming   │
                  └──────────────────────────┘

Android adds one branch:
        purchasing ──→ ┌─────────┐ clears days later ┌──────────┐
                       │ PENDING ├──────────────────→│ PURCHASED│→ redeeming
                       └─────────┘                    └──────────┘
                       ⚠️ grant zero Sparks while PENDING

The whole diagram reduces to one rule: nothing that can fail may sit between credited and finish(), and unconfirmed must be a state that can walk itself out, not a dead end.

4. What each store needs configured

4.1 Apple / App Store Connect

✅ On our side: step 7's endpoint is already written, signature checks and REFUND/REVOKE clawback included.

4.2 Google / Play Console

4.3 The differences that actually bite

⚠️ "Must verify online" changes the availability design. On iOS, crediting works even if Google is down. On Android, if Google's API is unreachable we must take the unconfirmed path — do not finish, do not consume, retry next launch. The good news: that path already exists for Apple and Android reuses it unchanged.

5. Architecture

5.1 Layers (reusing what exists — no new technologies)

┌─ UI ───────────────────────────────────────────┐
│  topup_screen.dart          tiers · states      │
│  spark_history_screen.dart  (new)               │
└───────────────┬────────────────────────────────┘
                │ reads IapService fields only; never touches a store SDK
┌───────────────▼────────────────────────────────┐
│  IapService (exists, extended to two platforms) │
│  · subscribe to purchase stream  · load tiers   │
│  · start a purchase                             │
│  · **finish only after the backend returns 200**│
└───────────────┬────────────────────────────────┘
                │ ApiClient
┌───────────────▼────────────────────────────────┐
│  backend domain/iap                             │
│  handler.go    products / verify / notify /     │
│                **google_verify / google_notify (new)** │
│  verify.go     Apple offline verification (exists)     │
│  google.go     Google online validation (new)   │
│  repository.go idempotent credit · refund (exists, + platform cols) │
└───────────────┬────────────────────────────────┘
                ▼
        Postgres: iap_transactions · wallets · wallet_ledger

Deliberately not doing: no payment middleware, no new state management library, no separate Android table. The in_app_purchase plugin already covers both platforms, and the backend pipeline (verify → credit idempotently → journal) is platform-neutral. The only fork is "how do I check this receipt".

5.2 New backend surface

⚠️ Like Apple's, google/notify is a public endpoint that carries none of our tokens. Apple's is secured by the certificate chain. Google's must verify the Pub/Sub push OIDC token — aud must match our own endpoint and the sender must be the expected service account. Skip that and anyone can POST a "refund" and drain someone's Sparks. Follow the shape of verify.go: verify first, touch the ledger second.

6. Database

6.1 Existing (structure unchanged, columns added)

iap_transactions
  transaction_id          TEXT PRIMARY KEY   -- ⚠️ currently holds Apple's ID
  original_transaction_id TEXT
  user_id                 UUID → users(id) ON DELETE CASCADE
  product_id              TEXT
  green                   BIGINT             -- server-computed, client never trusted
  environment             TEXT               -- Sandbox / Production
  status                  TEXT               -- credited / refunded
  purchased_at            TIMESTAMPTZ
  created_at              TIMESTAMPTZ
  raw_jws                 TEXT               -- the raw receipt, kept as evidence

wallet_ledger
  id, user_id, kind, green, balance, ref, created_at

6.2 What this version adds (one migration)

-- Take the number from backend/migrations/LEDGER.md and write back +1 immediately
ALTER TABLE iap_transactions
  ADD COLUMN IF NOT EXISTS platform TEXT NOT NULL DEFAULT 'apple',   -- apple / google
  ADD COLUMN IF NOT EXISTS purchase_token TEXT NOT NULL DEFAULT '',  -- Google's; empty for Apple
  ADD COLUMN IF NOT EXISTS state TEXT NOT NULL DEFAULT 'credited',   -- pending / credited / refunded
  ADD COLUMN IF NOT EXISTS currency TEXT NOT NULL DEFAULT 'MYR',     -- what the store actually charged
  ADD COLUMN IF NOT EXISTS price_micros BIGINT NOT NULL DEFAULT 0;   -- what the store actually charged

-- Google's idempotency key: orderId can be empty, purchase_token is the one always present
CREATE UNIQUE INDEX IF NOT EXISTS iap_tx_google_token
  ON iap_transactions(purchase_token) WHERE purchase_token <> '';

The decisions here and why:

• No separate google_transactions table. The two platforms share ~90% of their fields. Split them and "how much has this user topped up" has to be written twice — and when two implementations drift, nothing on screen shows it.
• platform defaults to 'apple'. The table is empty today (0 rows), but the default means this migration is also safe on any environment that does have rows.
• purchase_token gets a partial unique index, not a primary key. It is an empty string on the Apple side, and empty strings cannot be globally unique — hence WHERE purchase_token <> ''.
• price_micros + currency: what the store actually charged. This is the only place we can learn what the user really paid, and buyers are charged in their own storefront currency (an accepted, documented exception). Without these two columns, reconciliation is guesswork. ⚠️ Related: the payouts table still has no currency column at all — that is where money actually leaves the company, and it needs one more than this table does. Reported separately.

6.3 Tables deliberately not created

• A products table. The catalogue lives in code (products.go); changing tiers needs no migration. ⚠️ Do not "tidy" it into the database — that creates a second source of truth, and the credited amount must be compiled into the binary, not a row anyone can UPDATE.
• An entitlements table. Sparks are the entitlement; wallets.green already is that record. A second table would be the same fact stored twice.

7. Edge cases

⚠️ The refund case is worth singling out, because I chased it to the end. When the clawback cannot take the full amount, the code writes :short on the journal row, meaning "this one has bad debt". I grepped the whole repository: one place writes it, nothing reads it.

A marker with no reader is not a safeguard. Bad debt would accumulate in silence, with nothing and nobody ever speaking up. The rule worth keeping: whenever you write a counter, a log line or a flag, name who reads it — if you cannot, it is not done. So the thing to add in Phase 3 is not more logic, it is somewhere :short surfaces (an admin row, or a periodic reconciliation), rather than another marker nobody looks at.

8. Testing plan

8.1 Shared acceptance criteria

Every one of these must be seen to fail first before it is trusted:

8.2 Android-specific

8.3 iOS-specific

8.4 Knife tests (break each guard on purpose)

• Remove the idempotency step → T2 must go red
• Remove the environment check → T4 must go red
• Finish before the backend confirms → T3 must go red
• Remove RTDN signature verification → T8 must go red

A guard that has never been seen to fail is not a guard.

9. Build order (phases and dependencies)

Principle: the system is shippable at the end of every phase. Nothing half-built is left behind.

Phase 0 — look in both consoles (half a day, human only)

1. Do those six product IDs already exist in App Store Connect?
2. Is the Paid Apps Agreement in effect (tax + banking complete)?
3. Do we have a Play developer account and a merchant account?

⚠️ This answer changes everything after it. If …green.500 already exists in ASC, the re-anchor in §1.2 means "create six new products and retire six old ones". If it was never created, it is just editing numbers. This is the one step that must happen before anything else, and the one I cannot do.

Phase 1 — re-anchor pricing (backend, 1 day)

• [ ] products.go: the six tiers from §1.2; USDCents → PriceMYRSen
• [ ] Stop sending the price field to clients — usd_cents really is in the payload today, while two separate comments claim it is not
• [ ] Update the tier guard in verify_test.go to MYR — do not delete it; it is the one thing that will speak up if the re-anchor goes wrong
• [ ] IAP_GREEN_ENERGY.md updated in the same commit

Depends on: Phase 0. Does not depend on Android.

Phase 2 — database + backend abstraction (1 day)

• [ ] Migration from §6.2 (take the number from LEDGER.md, write back +1 immediately)
• [ ] repository.go records platform / purchase_token / currency / price_micros
• [ ] Extract "verify a receipt" into an interface, with Apple as the first implementation — extract before adding, not after

Phase 3 — Google validation (backend, 2-3 days)

• [ ] Service account credentials: file on the server, path in .env, never in git
• [ ] google.go: validate purchase tokens against the Play Developer API
• [ ] POST /v1/iap/google/verify
• [ ] POST /v1/iap/google/notify + Pub/Sub OIDC verification (see the warning in §5.2)
• [ ] Reuse the existing Refund() for clawback
• [ ] Somewhere :short bad debt becomes visible (see §7)
• [ ] Fake-server tests: ⚠️ the stand-in must copy the real API's auth and error codes, or it only proves "I sent a request"

Phase 4 — client, both platforms (2 days)

• [ ] IapService: pick the verify endpoint by platform; handle Android PENDING
• [ ] Confirm Android really does consume (A2)
• [ ] Build states ⑧ (paid, not yet confirmed) and ⑪ (pending)
• [ ] Failures get something the user can read, not just a log line
• [ ] Goldens: the six tier cards and the three new states

Phase 5 — purchase history (1 day, parallel)

• [ ] spark_history_screen.dart reading the existing GET /v1/wallet/ledger
• [ ] Entry point on the wallet card
• [ ] Footer explaining the journal starts in August 2026

Depends on no store configuration at all — it can be finished and shipped first.

Phase 6 — sandbox testing (2 days, a human present)

Run all of §8, once per platform.

Phase 7 — launch

• [ ] Small Business Program applied for (the arithmetic in §1.2)
• [ ] Re-confirm AllowSandbox = false in production
• [ ] Both notification endpoints have received a real notification in production
• [ ] Release one tier to an internal account and buy it with real money, then check the ledger, the journal and the balance all agree

Dependency graph

Phase 0 (human) ──┬──→ Phase 1 ──┐
                  └──→ Phase 2 ──┴──→ Phase 3 ──→ Phase 4 ──→ Phase 6 ──→ Phase 7
                       Phase 5 (independent, any time)

10. Checklists

10.1 Before launch

Apple - [ ] Paid Apps Agreement in effect (tax + banking) - [ ] Six consumable products created and approved - [ ] Prices set from the Malaysia tier table - [ ] Server Notifications V2 pointed at production, and one real notification received - [ ] Sandbox accounts working - [ ] Small Business Program applied for

Google - [ ] Developer and merchant accounts ready - [ ] A release build is on an internal track (products cannot exist before this) - [ ] Six one-time products created with IDs identical to iOS - [ ] Service account credentials on the server, not in git - [ ] RTDN topic and push endpoint working, and one real notification received - [ ] Licensed tester accounts working

Backend - [ ] Migration number taken from LEDGER.md and written back +1 - [ ] AllowSandbox = false in production - [ ] Both notification endpoints verify signatures, and a bad signature is rejected (T8 / A4 actually run) - [ ] Credentials never leave the server

Product - [ ] The six prices are approved - [ ] Decided whether FAMILY_SHARED transactions are granted (I1) - [ ] Confirmed that cascade-deleting financial records on account deletion is acceptable

10.2 What I did not decide for you

1. The exact price points — the table gives target anchors; the real tier has to be picked from each store's price matrix, in the console.
2. Whether the products already exist in ASC / Play — this decides whether the re-anchor is editing numbers or creating and retiring products.
3. Whether family-shared purchases grant Sparks — the code does not check today.
4. Whether financial ledger rows should survive account deletion — currently ON DELETE CASCADE. The behaviour is confirmed; whether to change it is a legal and finance call.

11. Refunds: where the money is actually recovered from (added 2026-09-22, from Leong's questions)

This section came out of a question-and-answer session in the workroom on the morning of 09-22. It is not design — it is what the code does today, checked line by line. Refunds used to live in two rows of the §7 table, and the real hole was in neither of them.

11.1 One refund has to be recovered from two places, not one

The rule in one line: take it back from whoever is holding it now.

• The part the user has not spent → clawed back from wallets. Already done (Refund()).
• The part the user has spent → it did not vanish, it went into the recipient's ledger. → Nothing is recovered today.
• Our own cut → never left us, nothing to recover.

Those three add up to the whole amount. Every Spark is either still in the wallet, sitting in some creator's ledger, or retained by us. So recovering from both sides does not double-count — worth writing down, because it looks like it would.

Walked through with real numbers (smallest tier, US$0.99 = 500 Sparks):

Result: we are out US$0.69 and still owe the creator 250 Sparks. Money in once, out twice.

⚠️ The games side is identical — do not read this as a music-only problem. shop/repository.go:186 writes the developer's 20% (GameDevPct = 20) into dev_ledger on an item purchase, exactly the same way. Both third-party paths leak. The only safe spend is buying an AI assistant — that money stays with us, and the assistant/ package contains no dev_ledger reference at all.

11.2 Why the code does not do it — it only opens three tables

The whole Refund() transaction (iap/repository.go) touches three tables:

iap_transactions   ← marks status='refunded'
wallets            ← claws the balance back
wallet_ledger      ← writes a negative ledger line

dev_ledger is not among them. This is not a faulty condition — the path simply never goes there.

11.3 The terms already say so, so this is not a pending product decision

This belongs first, because it closes what would otherwise be a debate about who should bear the loss:

• Developer Agreement §6 (deploy/www/developer-terms.html:47) defines the 20% as a share of net revenue — spelled out as "after app-store commissions, payment processing, refunds, chargebacks, and taxes". The same section at :51 adds a Clawback clause: earnings from fraud, self-dealing or manipulated transactions are void and may be deducted from future payouts.
• Creator Terms §4 (creator-terms.html:35) grants 50% of net tip value, and explicitly inherits the Developer Agreement §6 payout rules, clawback included.

So "should the creator's share come back after a refund" is already answered, and the answer is yes. The gap is not policy. It is code that does not execute terms we have already signed: the contract says net, the code pays gross.

11.4 Recovery only counts if it is still collectible — the hold

A clawback only works while the money has not left yet. Once a creator has requested a payout and received a bank transfer, there is nothing left to deduct.

How others solve it: TikTok reviews a withdrawal request for up to 15 calendar days before releasing payment (their Cash Award Withdrawal Terms), and their Rewards Policy carries the clause that matches our case exactly — when a user is entitled to a refund, the payment the creator withdrew for those gifts is forfeited; a separate clause allows deducting Diamonds with reasonable notice. Those 15 days are not bureaucracy — they are what makes the second clause enforceable.

Where we stand today: payouts are request-based and paid by hand (developer.go:2550 requestPayout, minimum 1000), so a delay exists in practice, but it is written down nowhere and enforced by no code. It relies on nobody having asked yet. That is not a mechanism.

⚠️ Related, and easy to underestimate: Apple's refund window is longer than people assume. A refund can arrive long after the purchase, so "credited today, withdrawable today" is unsound by design, not merely risky.

11.5 Apple's CONSUMPTION_REQUEST — we do not answer it

When a user disputes a consumable, Apple asks us for consumption data and allows 12 hours. The type is named in a comment at verify.go:202, but the switch in handler.go has only the REFUND and REVOKE branches. It is not handled.

Not answering does not produce an error. It means Apple decides the dispute without our side of the evidence, which generally does not go our way. This is the cheapest item in this section: one handler.

11.6 Refund abuse is invisible to everyone

This one surfaced while checking the above, and it may be worth more than the clawback itself:

The iap_transactions.status='refunded' marker has exactly one reader in the entire repository — its own idempotency check at repository.go:104, guarding against Apple resending the same notification. No risk logic reads it, and neither the iap nor the wallet package contains any suspension or restriction function.

So this chain is wide open today: buy → spend → refund → repeat, with nothing anywhere making a sound. Clawback addresses this transaction; a refund record somebody actually reads addresses the next one.

For contrast, TikTok's Virtual Items Policy states plainly that if a payment fails, is returned or remains unpaid, they may suspend the account or cut off access to virtual items until it is settled. That is their backstop. We have none.

11.7 So the work is these items (with dependencies)

⚠️ R6 deserves its own reason: refunds are always the half that gets deferred, and on Android it is the only path that loses money silently — with no RTDN listener, an Android refund simply leaves the Sparks in the wallet forever and nobody ever finds out.

11.8 What I have not decided for him in this section

1. How many days the hold should be. TikTok uses up to 15 calendar days. Ours depends on how long we are willing to make creators wait — a product trade-off, not a technical one.
2. Whether repeat refunds should cost account access. TikTok's terms reserve that. We have nothing today, and whether we should is a product decision.
3. What happens when the creator did nothing wrong. The terms permit deducting from future earnings, but between "deduct" and "we absorb it" there is a middle setting — do not chase amounts below some threshold. Nobody has drawn that line.

11.9 Current exposure: zero

Production iap_transactions has zero rows — nobody has ever bought, so nobody has ever been refunded, and not one line above has ever actually run.

That cuts both ways: it means this is not urgent, and it means this is the cheapest it will ever be to fix — no historical data to migrate, no money already paid out to chase, and no user who would notice.

Appendix: how this relates to the existing docs

• docs/IAP_GREEN_ENERGY.md — the design rationale for the Apple side; still valid. This document is its two-platform sequel.
• docs/GREEN_ENERGY_ASBUILT.md — as-built; ⚠️ several of its line references have drifted. Everything above was re-checked against current code.
• docs/wallet.md — the wallet in full, plus the decision ledger.
• backend/migrations/LEDGER.md — where migration numbers come from.

When you actually build this, the code is the source of truth — not any document, including this one.