@invonetwork/web-sdk 3.3.0 → 3.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  First-party TypeScript SDK for integrating **INVO** into partner **web** platforms (storefronts, web games, dashboards). It wraps INVO's web money flows behind a typed, versioned API — the web analog of the Unity/Unreal plugins.
4
4
 
5
- > **Status:** `v3.2.3` — stable, published on npm. The backend it wraps is **live** on sandbox + production. The API is covered by a [stability commitment](#stability): no breaking changes without a major bump. Recent highlights: **3.2.3** corrects the base path and auth header in the Steam snippets (`/api/currency-purchases`, `X-Game-Secret-Key`) — 3.2.2 published both wrong, and copying them returned a 404; **3.2.x** documents **Steam currency purchases on a pack model** — INVO owns the catalogue, you pass a `pack_id` and never a price, and the currency inside a pack varies by country because Steam prices are VAT-inclusive; **3.1.0** makes the authentication guidance explicit — **[passkeys are the gold standard](#passkeys-are-the-gold-standard-dont-build-on-sms)** and the SMS-PIN completion (`verifySmsTransfer`/`verifySmsSend`) is **deprecated and being phased out** (documentation only — no behavior change, no runtime warnings); **3.0.0** moves the Platform Commerce card leg to **INVO's hosted checkout** — the server `purchase()` now returns a `checkoutUrl` and the browser just sends the buyer there (redirect or `mountCheckout` iframe); the 2.5.x card-element surface (`confirmCardPayment`/`mountCardPayment`, `billingAddress`, `commercePublishableKey`) is **removed** — see the [CHANGELOG](CHANGELOG.md) migration note; **2.5.0** added **Platform Commerce** (ecommerce) — a platform tenant selling items funded by balance **or** card, with `invo.platformCommerce.purchase/getStatus/refund` (server) and the `platform_commerce.*` webhooks; **2.4.0** adds Steam transfer-policy handling (`isSteamValueNonTransferable`/`isNonSteamValueIntoSteamBlocked` + `DestinationGame.acceptsSteamOriginValue`); **2.3.0** surfaces the claim-time phone-share `409` on `confirmReceipt*`/`claim*` (+ `err.phoneShareLast4`). Full history in the [CHANGELOG](CHANGELOG.md).
5
+ > **Status:** `v3.5.0` — stable, published on npm. The backend it wraps is **live** on sandbox + production. The API is covered by a [stability commitment](#stability): no breaking changes without a major bump. Recent highlights: **3.4.0** documents that a Steam title now bills through **its own Steam application** — the studio registers their appid + publisher Web API key and keeps a payment method on file, because Valve pays the studio and INVO settles afterwards (new `isSteamNotConfigured`, `isPartnerBillingNotSetUp`, `isPartnerSettlementUnavailable`, `isSteamAppChanged` error helpers); **3.2.3** corrects the base path and auth header in the Steam snippets (`/api/currency-purchases`, `X-Game-Secret-Key`) — 3.2.2 published both wrong, and copying them returned a 404; **3.2.x** documents **Steam currency purchases on a pack model** — INVO owns the catalogue, you pass a `pack_id` and never a price, and the currency inside a pack varies by country because Steam prices are VAT-inclusive; **3.1.0** makes the authentication guidance explicit — **[passkeys are the gold standard](#passkeys-are-the-gold-standard-dont-build-on-sms)** and the SMS-PIN completion (`verifySmsTransfer`/`verifySmsSend`) is **deprecated and being phased out** (documentation only — no behavior change, no runtime warnings); **3.0.0** moves the Platform Commerce card leg to **INVO's hosted checkout** — the server `purchase()` now returns a `checkoutUrl` and the browser just sends the buyer there (redirect or `mountCheckout` iframe); the 2.5.x card-element surface (`confirmCardPayment`/`mountCardPayment`, `billingAddress`, `commercePublishableKey`) is **removed** — see the [CHANGELOG](CHANGELOG.md) migration note; **2.5.0** added **Platform Commerce** (ecommerce) — a platform tenant selling items funded by balance **or** card, with `invo.platformCommerce.purchase/getStatus/refund` (server) and the `platform_commerce.*` webhooks; **2.4.0** adds Steam transfer-policy handling (`isSteamValueNonTransferable`/`isNonSteamValueIntoSteamBlocked` + `DestinationGame.acceptsSteamOriginValue`); **2.3.0** surfaces the claim-time phone-share `409` on `confirmReceipt*`/`claim*` (+ `err.phoneShareLast4`). Full history in the [CHANGELOG](CHANGELOG.md).
6
6
  > Canonical partner reference: **https://docs.invo.network/docs/currency-purchase** and **https://docs.invo.network/docs/game-developer-integration**.
7
7
 
8
8
  ## What it does
@@ -37,29 +37,30 @@ So:
37
37
  | `initiate*` returns `verificationMethod: "sms"` | read it as *"this user has no passkey"* → offer enrollment | route straight to PIN entry |
38
38
  | Recipient collects | `client.confirmReceiptSend` / `confirmReceiptTransfer` (passkey) | claim code as the primary path |
39
39
 
40
- ### Prerequisite: passkeys are dark until your tenant verifies a domain
40
+ ### Prerequisite: which passkey path serves your tenant
41
41
 
42
- **Read this before you wire up `enrollPasskey()`.** Passkey step-up is enabled **per tenant** and stays off until you verify ownership of a domain (your RP ID) in the developer console. Until then every passkey endpoint returns `403 WEBAUTHN_NOT_ENABLED_FOR_TENANT`.
42
+ **Read this before you wire up `enrollPasskey()`.** There are two places a passkey ceremony can run, and which one serves your title is decided by whether you hold a partner passkey domain:
43
43
 
44
- **This is the common case today, not an edge case.** As of 2026-08-05 only **4 of 23 sandbox tenants** and **0 of 3 production tenants** have a verified RP ID. If you skip this, your integration will 403 on its first `enrollPasskey()` call and you'll be debugging a configuration state as if it were a bug.
44
+ - **No partner domain (every new title):** INVO runs the ceremony **on its own domain** — the hosted approval page — for every platform. There is **no domain to verify and nothing to configure**; submitting one is refused (`409 PARTNER_RP_FROZEN`). On the web the path is [`approveHosted()`](#web-games--approving-on-invos-hosted-page); on consoles it is the QR flow; on iOS/Android the mobile plugins open the same page. The in-app `enrollPasskey()` / `approveSend` / `approveTransfer` calls return `403 WEBAUTHN_NOT_ENABLED_FOR_TENANT` for you — that is the **expected state, not a setup gap** (the body's `hosted_flow` says so and points at `device_code`).
45
+ - **A domain verified before the freeze (existing tenants):** your passkeys are bound to that RP ID for life, so `enrollPasskey()` and the in-app approves keep working exactly as documented below. You may still change or re-verify the domain. Removing it is **irreversible** — it can never be re-added, and the hosted flow serves the game from then on.
45
46
 
46
- `WEBAUTHN_NOT_ENABLED_FOR_TENANT` is **configuration state, not an error** — the ceremony was never available to fail. Don't show the player a failure; fall back to the existing path:
47
+ `WEBAUTHN_NOT_ENABLED_FOR_TENANT` is **configuration state, not an error** — the in-app ceremony was never available to fail. Don't show the player a failure; use the hosted page:
47
48
 
48
49
  ```ts
49
50
  try {
50
51
  await client.enrollPasskey();
51
52
  } catch (e) {
52
53
  if (e instanceof InvoError && e.isWebauthnNotEnabledForTenant) {
53
- // Not a failure — this tenant simply hasn't verified a domain yet.
54
- // Fall back to the SMS/in-app path and (if this is YOUR tenant) go verify a domain.
55
- usePinFallback();
54
+ // Not a failure — this tenant has no partner passkey domain, which is now the norm.
55
+ // Approve on INVO's hosted page instead (nothing to configure):
56
+ await client.approveHosted({ transactionId, flow: "transfer" });
56
57
  } else throw e;
57
58
  }
58
59
  ```
59
60
 
60
- So the honest sequence is: **verify your domain → enroll passkeys → you're on the gold-standard path.** Until step one is done, the SMS path is carrying you whether you like it or not — which is exactly why the deprecation below has no removal date attached.
61
+ So the honest sequence is: **start the transfer → `approveHosted()` (or the in-app approve if you hold a domain) → you're on the gold-standard path.** The SMS PIN is what carries a player who cannot or will not enrol — which is exactly why the deprecation below has no removal date attached.
61
62
 
62
- > ⚠️ **`verifySmsTransfer` / `verifySmsSend` are deprecated as of `3.1.0` and a future major version will remove them.** They still work exactly as before — this release changes documentation only, emits no runtime warning, and breaks nothing. Keep the PIN path as a genuine last resort for: users who **cannot** enroll (unsupported device, no platform authenticator), users who decline, and **tenants that haven't verified a domain yet** (see above). Just don't make it the road everyone walks down once passkeys are available to you.
63
+ > ⚠️ **`verifySmsTransfer` / `verifySmsSend` are deprecated as of `3.1.0` and a future major version will remove them.** They still work exactly as before — this release changes documentation only, emits no runtime warning, and breaks nothing. Keep the PIN path as a genuine last resort for: users who **cannot** enroll (unsupported device, no platform authenticator), users who decline, and **players who will not use the hosted page** (see above). Just don't make it the road everyone walks down once passkeys are available to you.
63
64
 
64
65
  **What is *not* discouraged.** These use a one-time code, but they are the on-ramp *to* a passkey — not a substitute for one. Use them freely:
65
66
 
@@ -69,6 +70,20 @@ So the honest sequence is: **verify your domain → enroll passkeys → you're o
69
70
 
70
71
  Beyond security, this is also an economics story: SMS costs real money per message at every scale, and INVO's architecture targets passkey/in-app verification as the primary path so the platform never depends on carrier delivery. A passkey-first integration is faster for your users, cheaper to run, and won't need migrating later.
71
72
 
73
+ ### Which method fits which platform
74
+
75
+ The right approval method is a property of the **client the player is sitting in front of**, not of your title. Pick it per platform:
76
+
77
+ | Where the player is | Approve with | Why |
78
+ |---|---|---|
79
+ | Mobile app & mobile web (iOS 16+ / Android 9+) | **a passkey, directly** | the platform authenticator (Face ID / Touch ID / fingerprint) is available in-client — strongest option, zero messaging cost |
80
+ | Desktop web (browser) | **a passkey, directly** | Touch ID / Windows Hello are available to the browser |
81
+ | Web, player has no in-app passkey yet | **INVO's hosted page in a popup** ([`approveHosted`](#web-games--approving-on-invos-hosted-page), below) | the same page a console scans, opened by the SDK from the browser; the player enrols an INVO passkey on INVO's own domain and the SDK polls and approves — one call, nothing new on your server |
82
+ | Consoles (PlayStation / Xbox / Switch) | **the QR device-approval flow** ([RFC 8628](#consoles-and-tvs--approving-without-a-browser-rfc-8628), below) | no browser and no WebAuthn in-client — show the QR, the player scans it and completes the passkey on their phone, and the console polls for approval |
83
+ | Native Steam / desktop game clients (Mac & Windows) | **the QR device-approval flow** ([RFC 8628](#consoles-and-tvs--approving-without-a-browser-rfc-8628), below) | the OS supports passkeys, but the embedded game client can't invoke the platform authenticator from inside the engine — it is the **client**, not the OS, that forces QR here |
84
+
85
+ **When there is no passkey path at all** — a remote approval that can't run a ceremony (a guardian, a phone's existing owner) — INVO goes **email first, SMS on request**: a signed link to a hosted page to the oldest verified address, and a text only when there is no verified email, the email could not be delivered, or the player asks for one. SMS is the last resort, not the primary channel.
86
+
72
87
  ## Contents
73
88
 
74
89
  - [Passkeys are the gold standard — don't build on SMS](#passkeys-are-the-gold-standard--dont-build-on-sms)
@@ -82,6 +97,8 @@ Beyond security, this is also an economics story: SMS costs real money per messa
82
97
  - [Player balance](#player-balance)
83
98
  - [Sends & transfers (move currency between players)](#sends--transfers-move-currency-between-players)
84
99
  - [Passkeys (enroll, approve, link, recover)](#passkeys-enroll-approve-link-recover)
100
+ - [Web games — approving on INVO's hosted page](#web-games--approving-on-invos-hosted-page)
101
+ - [Consoles and TVs — approving without a browser (RFC 8628)](#consoles-and-tvs--approving-without-a-browser-rfc-8628)
85
102
  - [Webhooks](#webhooks)
86
103
  - [Resilience & observability](#resilience--observability)
87
104
  - [Errors](#errors)
@@ -209,8 +226,8 @@ INVO enables each flow for your tenant in the [console](#get-your-account--game-
209
226
  - **Store the game secret server-side** and expose a small endpoint that calls `mintPlayerToken` so the browser can fetch/refresh its token. Never ship the secret to the browser.
210
227
  - **Make sure players have a phone (E.164) at creation/enrollment** — it's required on the money calls (`initiateSend`/`initiateTransfer`) and for cross-game receive, though not on the token mint itself (see [Player token](#player-token-session-mint-for-an-existing-player)).
211
228
  - **If you use browser-direct ([Mode A](#mode-a--browser-direct-default)):** ask INVO to **CORS-allow your web origin(s)** so the browser can call the API directly. (Not needed for [Mode B / proxy](#mode-b--behind-your-proxy-keep-the-token-server-side) — those requests are same-origin to your backend.)
212
- - **For passkeys (sends/transfers):** give INVO the **RP ID + web origin(s)** you'll serve from. Passkeys only validate on approved origins — if a call returns `WEBAUTHN_NOT_ENABLED_FOR_TENANT`, your origins aren't set up yet; contact INVO. **Get this configured before launch:** until a sender is enrolled the backend falls back to the deprecated SMS-PIN path, which is the flow you don't want your users on (see [Passkeys are the gold standard](#passkeys-are-the-gold-standard--dont-build-on-sms)).
213
- - **For currency purchase:** card checkout works out of the box; ask INVO to enable the `game`/`steam` rails if you need them.
229
+ - **For passkeys (sends/transfers):** nothing to configure — new titles approve on INVO's hosted page ([`approveHosted()`](#web-games--approving-on-invos-hosted-page)); there is no partner domain to verify. Only a tenant that verified an **RP ID + web origin(s)** before the freeze uses the in-app `enrollPasskey()` / `approveSend` path, and those passkeys only validate on the approved origins. **Wire the approve step before launch:** until a sender is enrolled the backend falls back to the deprecated SMS-PIN path, which is the flow you don't want your users on (see [Passkeys are the gold standard](#passkeys-are-the-gold-standard--dont-build-on-sms)).
230
+ - **For currency purchase:** card checkout works out of the box; ask INVO to enable the `game`/`steam` rails if you need them. **The `steam` rail additionally requires the studio to register their own Steam app id + publisher Web API key and put a payment method on file** — see [Steam purchases](#steam-purchases-packs-not-prices).
214
231
  - **For item purchase:** nothing extra — it's a currency-balance debit.
215
232
 
216
233
  If a flow isn't enabled for your tenant yet, calls return a clear `InvoError` (e.g. `TENANT_NOT_MIGRATED`, `WEBAUTHN_NOT_ENABLED_FOR_TENANT`, or `flow_paused`) — coordinate with your INVO contact to turn it on.
@@ -300,6 +317,33 @@ The `rail` selects the in-page experience — all branded INVO, no visible redir
300
317
  - `"game"` — regional / game-store methods (may redirect to the regional hosted page).
301
318
  - `"steam"` — Steam titles hand off to the in-client Steam flow.
302
319
 
320
+ > ### Steam titles: before any of this works, the studio has setup to do
321
+ >
322
+ > **Steam pays whoever owns the Steam application.** Every INVO title therefore
323
+ > sells currency through **its own Steam app**, and the money lands in the
324
+ > studio's own Steamworks account. INVO issues the player's currency the moment
325
+ > Steam captures the charge, then settles with the studio separately against a
326
+ > payment method they keep on file.
327
+ >
328
+ > Once per title, in the INVO dashboard:
329
+ >
330
+ > 1. Enable **in-game purchases (microtransactions)** for the app in Steamworks.
331
+ > 2. Create a **publisher Web API key** — a *publisher group* key, not a personal
332
+ > user key, with the app in the group. A personal key fails verification.
333
+ > 3. Enter the **app id** and that **key** under the title's Steam settings. INVO
334
+ > calls Steam to prove the pair before saving it.
335
+ > 4. Add a **payment method** on the Billing screen and accept the authorisation.
336
+ >
337
+ > Until all four are done, purchases are refused **before the player is charged**:
338
+ > `STEAM_NOT_CONFIGURED` (503) or `PARTNER_BILLING_NOT_SET_UP` (409). That is
339
+ > deliberate — the alternative is taking a player's money for currency that
340
+ > cannot be issued.
341
+ >
342
+ > **This changed in September 2026.** Versions before 3.4.0 said Steam purchases
343
+ > ran through an INVO-owned Steam app and there was nothing to register. That was
344
+ > true while one INVO application billed every title; it is not true now, and
345
+ > following the old text leaves the rail closed.
346
+
303
347
  > **Steam titles: currency must be bought through Steam, and INVO sets the packs.**
304
348
  >
305
349
  > A title distributed on Steam may only sell currency on the `steam` rail — any other
@@ -323,54 +367,92 @@ Provider/processor names are an internal detail and never appear in the API.
323
367
 
324
368
  ### Steam purchases (packs, not prices)
325
369
 
326
- Steam is **not** an SDK method — it is a server-to-server REST flow, because the
327
- purchase is authorised inside the Steam client and your game has to relay that.
328
- `purchaseCurrency` rejects `rail: "steam"` with `WRONG_RAIL_ENDPOINT` for that reason.
370
+ Steam has first-class SDK methods as of 3.5.0: `steamPacks()`, `steamInitPurchase()`,
371
+ `steamFinalizePurchase()` — all on `InvoServer`, all server-side, because the game
372
+ secret must never reach a client. `purchaseCurrency` still rejects `rail: "steam"`
373
+ with `WRONG_RAIL_ENDPOINT` and points you here.
329
374
 
330
375
  **INVO owns the pack catalogue.** You never send a price. Fetch the packs, show them,
331
- pass a `pack_id` back.
376
+ pass a `packId` back.
332
377
 
333
378
  ```ts
334
379
  // 1. The catalogue, priced for THIS player. Always pass steamid.
335
- const res = await fetch(
336
- `${INVO_BASE}/api/currency-purchases/steam/packs?steamid=${steamId}`,
337
- { headers: { "X-Game-Secret-Key": GAME_SECRET } },
338
- );
339
- const { country, vat_rate_pct, packs } = await res.json();
340
- // packs: [{ pack_id, label, price_usd, currency_amount }, ...]
380
+ const { packs, country, vatRatePct } = await server.steamPacks({ steamid: steamId });
381
+ // packs: [{ packId, label, priceUsd, currencyAmount }, ...]
341
382
 
342
383
  // 2. Start the purchase with the pack the player chose.
343
- const init = await fetch(`${INVO_BASE}/api/currency-purchases/steam/init-purchase`, {
344
- method: "POST",
345
- headers: { "X-Game-Secret-Key": GAME_SECRET, "Content-Type": "application/json" },
346
- body: JSON.stringify({
347
- player_email: "player@example.com",
348
- steamid: steamId,
349
- pack_id: "steam_medium", // NOT a price
350
- purchase_reference: crypto.randomUUID(),
351
- }),
384
+ const init = await server.steamInitPurchase({
385
+ playerEmail: "player@example.com",
386
+ steamid: steamId,
387
+ packId: "steam_medium", // NOT a price
388
+ purchaseReference: myIdempotencyKey, // unique per INTENDED purchase; reuse on retry
389
+ metadata: { playerId: myPlayerId }, // echoed on the purchase.completed webhook
352
390
  });
353
- // -> { order_id, steam_transid, pack_id, charged_usd, currency_amount }
354
-
355
- // 3. Steam shows its overlay. Your game client receives
356
- // MicroTxnAuthorizationResponse_t and tells your backend to finalize.
357
- // 4. POST /steam/finalize-purchase { order_id } -> currency is credited.
391
+ // -> { orderId, steamTransid, packId, chargedUsd, currencyAmount }
392
+
393
+ // 3a. CLIENT SESSION (default): Steam shows its in-game overlay. Your game
394
+ // client receives MicroTxnAuthorizationResponse_t and tells your backend.
395
+ // 3b. WEB SESSION: for platforms where the overlay does not render (observed:
396
+ // Electron on macOS). Pass usersession: "web" + playerIp (the PLAYER's IP,
397
+ // never your server's) and open the returned steamCheckoutUrl as a
398
+ // TOP-LEVEL browser tab — it cannot be iframed.
399
+
400
+ // 4. Finalize: INVO re-checks the authorization with Steam, captures, credits.
401
+ const done = await server.steamFinalizePurchase({ orderId: init.orderId });
402
+ // -> { status: "success", newBalance, alreadyProcessed }
358
403
  ```
359
404
 
360
405
  **The price is identical everywhere; the currency inside is not.** Steam prices are
361
- VAT-inclusive wherever VAT is collected, so more of a fixed price goes to tax in a
362
- high-VAT country and less is left to buy currency with — the same `$9.99` pack yields
363
- **69** units in the US and **58** in France.
406
+ VAT-inclusive wherever VAT is collected, and the storefront's revenue share comes out
407
+ before currency is derived — so the same `$9.99` pack yields **69** units in the US
408
+ and **58** in France, and a `$4.99` pack yields **34**, not 50. Render
409
+ `currencyAmount` verbatim; never compute currency from the sticker price.
410
+
411
+ **Finalize is idempotent, and not every 409 means "try later".** A replay returns
412
+ `alreadyProcessed: true` and never credits twice. For a poller, branch on the error:
364
413
 
365
- - **Always pass `steamid`** to `/steam/packs`. Without it the amounts are quoted with
414
+ | Signal | Meaning | Do |
415
+ |---|---|---|
416
+ | `err.isSteamAuthorizationPending` | player has not approved yet (`Init`) | keep polling / wait for the callback |
417
+ | `err.isSteamAuthorizationDead` | any settled status: `Cancelled` / `Failed` / `Refunded` / `PartialRefund` / `Chargedback` / anything else non-Init | **stop** — no later call can succeed |
418
+ | `err.isSteamAppChanged` | the title's registration changed under the order | stop; terminal for this order |
419
+ | HTTP 502 / 503 | transient | retry |
420
+ | `"Order is not finalizable"` (4xx, no `not_authorized`) | the reconciler already settled the order's fate | **stop** |
421
+
422
+ A poller that treats every 409 as "not yet" polls a dead order forever. And a missed
423
+ finalize is not a lost credit — INVO's reconciler independently detects the authorized
424
+ transaction and credits, on a delay.
425
+
426
+ **Refusals before any charge**, so a player is never charged for currency that cannot
427
+ be issued:
428
+
429
+ - `err.isPartnerCreditUnavailable` — the studio's settlement float cannot cover it.
430
+ Plain failure toast; do **not** hot-poll init (each attempt briefly re-reserves
431
+ headroom), and reuse the same `purchaseReference` on a manual retry.
432
+ - `err.isPartnerRailSuspended` — terminal from the game's seat until the studio
433
+ resolves it in the INVO console.
434
+ - `err.isUnknownSteamPack` — re-fetch `steamPacks()`; the body's `valid_pack_ids`
435
+ lists what exists. The catalogue is INVO's and changes without an SDK release.
436
+ - `err.isSteamNotConfigured` (503) / `err.isSteamRailNotEntitled` (403) — the studio's
437
+ one-time Steam setup is incomplete.
438
+ - A locked Steam account is refused up front with `409 STEAM_ACCOUNT_LOCKED`.
439
+
440
+ - **Always pass `steamid`** to `steamPacks()`. Without it the amounts are quoted with
366
441
  no VAT deducted — the most any pack yields — so your store promises more than the
367
442
  purchase delivers.
368
443
  - **Do not cache one catalogue for all players**, and do not hard-code amounts. Pack
369
444
  prices and VAT rates are both configuration and change without an SDK release.
370
- - **A Steam-distributed title may only sell on this rail.** Any other is refused with
371
- `409 STEAM_PURCHASE_LAYER_REQUIRED`, across every storefront the title ships on,
372
- because a player's balance is shared between them.
373
- - A locked Steam account is refused up front with `409 STEAM_ACCOUNT_LOCKED`.
445
+ - **On a Steam-distributed title, a channel key may only sell on its own channel's
446
+ rail.** A mismatched caller is refused with `409 STEAM_PURCHASE_LAYER_REQUIRED`.
447
+ (The old absolute form — "only the Steam rail, across every storefront" — was
448
+ the rule before 2026-08-31 and no longer holds for channel-keyed callers.)
449
+ - **Correlation is `metadata`, not `purchase_reference`.** The webhook payload
450
+ deliberately omits your idempotency key; put your own player/order ids in
451
+ `metadata` and read them back at `data.metadata` on `purchase.completed` — note the
452
+ Steam rail ADDS its own context keys (`steam_wallet_currency`, `steam_country`,
453
+ `steam_account_status`, `vat_rate_pct`) into the echoed object, so avoid those
454
+ names in yours
455
+ (`data.channel` is the channel of the KEY you presented — `"steam"` when you call with your Steam channel key; `null` on a legacy game key).
374
456
 
375
457
  ### Direct rail (advanced — you tokenize the card yourself)
376
458
 
@@ -589,11 +671,50 @@ try {
589
671
  - **`verificationMethod`** (from initiate): `"in_app"` → the sender has a passkey, go approve (the recommended path); `"sms"` → **the sender has no passkey** and a PIN was sent as a deprecated fallback — the best response is to offer `enrollPasskey()` and then `approveSend`/`approveTransfer`, showing the PIN pad only if they can't or won't enroll; `undefined` + `guardianApproval` → minor/guardian (HTTP 202), do **not** show the PIN UI. On the guardian path the SDK reports `verificationMethod: undefined` (even though the raw 202 body also carries `"sms"`) so `guardianApproval` wins — but branch on it first to be safe.
590
672
  - **Claim codes** are returned only by `approveTransfer`; they're the out-of-band fallback when the recipient isn't enrolled.
591
673
  - **`err.isReceiverNotEnrolled`** on `confirmReceipt*` is the explicit signal to switch to claim-code entry.
674
+ - **Recipients without the game collect from the SMS.** The claim text a send's receiver gets
675
+ now ends with a link to a hosted INVO page ("Or collect here: …"). They see who sent what in
676
+ which game, enter **one email** (the same thing in-game claim already requires), confirm it
677
+ with an emailed 6-digit code, and their phone's fingerprint / face / screen lock creates an
678
+ INVO passkey — a recipient who already has one just confirms with it. The currency lands in
679
+ their balance for the receiving game; the page shows the new balance and tells them to sign
680
+ in to the game with that email + phone. In-game claim (`claimCurrency` / `confirmReceiptSend`)
681
+ is unchanged — point a player at the link when they don't have the game open, at in-game
682
+ claim when they do; both are the same claim with one lifetime. `transfer.received` fires
683
+ the same either way, and you change nothing.
684
+ - **Resend the claim SMS — a REST call, not an SDK method.**
685
+ `POST /api/sdk/send/{transactionId}/resend-claim` with the **sender's** player token, no
686
+ body. It re-sends the identical message (same code, same link); nothing new is minted.
687
+ 30-second cooldown (`429 RESEND_COOLDOWN` + `retry_after`), at most 10 per transaction per
688
+ hour; `400 CLAIM_EXPIRED` / `NOT_CLAIMABLE` once the send can no longer be claimed; `403`
689
+ for anyone but the sender. `200 { status: "resent", transaction_id, retry_after }`.
690
+ - **Uncollected after 24 hours → refunded, and both parties are told.** The refund to the
691
+ sender is as before; what's new is that the sender gets an email and the recipient a single
692
+ text saying the currency was returned, instead of silence. `transfer.claim_expired` +
693
+ `transfer.refunded` remain the source of truth — reconcile off those, not the messages.
592
694
  - **`err.isPhoneShareApprovalRequired` on `confirmReceipt*` / `claimTransfer` / `claimCurrency`** (409): the receiver phone is contested, so INVO **holds the money** and texts the phone owner to approve. Not a failure — show `err.message` verbatim (`err.phoneShareLast4` names the phone), then **retry the same call** once approved (it succeeds idempotently); on denial/expiry the sender is refunded. Same handling as the initiate-time phone-share 409.
593
695
  - **Both games must be Live.** `initiateSend`/`initiateTransfer` throw `403` if either side is still in testing, and the two cases are **deliberately separate** because the fix differs: `err.isSourceGameNotLive` is **your** game (self-serve — switch it to Live in the console under Game Settings → Status), `err.isTargetGameNotLive` is the **destination** game, usually owned by another developer, so you can't flip it — show `err.message` and steer the player elsewhere via `getDestinations`. `err.gameStatus` carries the current state. Don't merge these into one "not live" branch; it produces a "go fix it" button that leads nowhere half the time.
594
696
  - **Steam titles** (dark until a title is Steam-distributed): `initiateSend`/`initiateTransfer` can throw `err.isSteamValueNonTransferable` (moving more than the non-Steam balance to a non-Steam destination — show `err.message`, cap the amount at `err.steamTransferableMax`; `err.steamOriginAmount` is the Steam-locked portion) or `err.isNonSteamValueIntoSteamBlocked` (non-Steam value into a Steam title). Prevent both up front: `getDestinations` rows carry **`acceptsSteamOriginValue`** — disable non-Steam destinations for a player holding Steam-purchased currency.
595
697
  - Transfer self-claim may be disabled for your tenant; if it is, surface the claim-code path instead.
596
698
  - **Holds:** an approve/claim can return an HTTP 202 hold instead of success — inspect `result.holdReason` (`"RISK_HOLD"`, `"GUARDIAN_APPROVAL_PENDING"`, and on confirm-receipt `"RECIPIENT_IDENTITY_PENDING"`); success has no `holdReason` (and `next: "pending_claim"`). Terminal guardian outcomes throw (`GUARDIAN_APPROVAL_REJECTED`/`_EXPIRED`).
699
+ - **Guardian approval goes by email first.** When a minor's initiate returns the 202, the guardian gets a
700
+ signed, single-use link to a hosted INVO page with Approve / Decline — not a text. A reply-YES text goes
701
+ out only when the guardian has no verified email or the email could not be delivered. The raw 202
702
+ `guardian_approval` block (`t.raw`) now carries **`consent_channel`** (`"email"` | `"sms"`) — use it for
703
+ your waiting copy — and **`resend_endpoint`**. Poll `getGuardianApprovalStatus` exactly as before; the
704
+ approval object's `consent_channel` says how it went out and `decision_source` is `email_link` for a
705
+ page decision.
706
+ - **"Text my parent instead" — a REST call, not an SDK method.** `POST /api/sdk/approvals/guardian/{approvalId}/resend`
707
+ with the **minor's** player token (the session that started the transaction) and body `{ "channel": "sms" }`
708
+ — the only accepted value. Once per approval. `200 { status: "sent", channel: "sms" }`; `403 NOT_INITIATOR`;
709
+ `409 CHANNEL_WAS_SMS` (it already went by text — hide the button when `consent_channel` is `"sms"`);
710
+ `409 ALREADY_RESENT`; `410 APPROVAL_GONE` (decided or expired); `503 DELIVERY_FAILED` (retryable — does not
711
+ use up the one allowance). The emailed link keeps working alongside the text.
712
+ - **Phone-share and recipient-identity consents use the same hosted page.** On `err.isPhoneShareApprovalRequired`
713
+ the phone's existing owner gets an emailed link (Allow / Decline) when INVO has itself proven an address for
714
+ them — at most three holders, one email per request — and the 409 body carries `consent_channel: "email"`;
715
+ the OTP text goes out instead only when no proven holder exists (`consent_channel: "sms"`). The
716
+ `RECIPIENT_IDENTITY_PENDING` hold emails the phone owner's oldest verified address the same way. **Nothing
717
+ changes for you:** same 409 / 202 codes, same poll-and-retry, and the typed-code and in-app approves still work.
597
718
 
598
719
  **"You have X to collect"**
599
720
 
@@ -623,8 +744,8 @@ await client.enrollPasskey();
623
744
  ```
624
745
 
625
746
  **First-enrollment OTP grant.** For tenants that require it, the first `enrollPasskey()`
626
- throws `ENROLLMENT_REQUIRES_AUTHORIZATION`. Send a one-time code (to the player's phone +
627
- email on file), verify it, then **retry the same `enrollPasskey()`** — the server-side
747
+ throws `ENROLLMENT_REQUIRES_AUTHORIZATION`. Send a one-time code (to the player's email on
748
+ file first; by text only on request or when there is no email), verify it, then **retry the same `enrollPasskey()`** — the server-side
628
749
  grant is consumed automatically:
629
750
 
630
751
  ```ts
@@ -632,7 +753,7 @@ try {
632
753
  await client.enrollPasskey();
633
754
  } catch (e) {
634
755
  if (e instanceof InvoError && e.isEnrollmentAuthorizationRequired) {
635
- await client.enrollmentBegin(); // → { status: "sent", channels: ["sms","email"] }
756
+ await client.enrollmentBegin(); // → { status: "sent", channels: ["email"] } — email first; { channel: "sms" } to text instead
636
757
  await client.enrollmentVerify(codeFromUser); // 6-digit OTP
637
758
  await client.enrollPasskey(); // retry — grant auto-consumed
638
759
  } else if (e instanceof InvoError && e.isEnrollmentProofRequired) {
@@ -655,7 +776,7 @@ try {
655
776
  } catch (e) {
656
777
  if (e instanceof InvoError && e.isEnrollmentProofRequired) {
657
778
  // Player still HAS the other method → linkDevice (above). Lost/deleted it → recover:
658
- await client.recoveryBegin(); // → { status:"sent", channels:["sms","email"] }
779
+ await client.recoveryBegin(); // → { status:"sent", channels:["email"] } — email first; { channel: "sms" } to text instead
659
780
  await client.recoveryComplete(codeFromUser); // → { status:"recovered", deactivatedCount }
660
781
  await client.enrollPasskey(); // same call — now succeeds
661
782
  } else throw e;
@@ -679,6 +800,96 @@ try {
679
800
  - Challenges are single-use and bound to `{flow}:{transactionId}`.
680
801
  - The SDK passes the backend's WebAuthn options through unchanged (it does not hard-code `pubKeyCredParams`/`timeout`/`attestation`).
681
802
 
803
+ ### Web games — approving on INVO's hosted page
804
+
805
+ A player on the **web** who has no INVO passkey yet — or whose passkey lives on your domain
806
+ and so cannot approve on INVO's — uses the same hosted page a console player scans. On the
807
+ web the **browser is the client**: one SDK call runs the whole device-approval grant with
808
+ the player token it already holds, exactly as the in-app passkey calls do. Your **server does
809
+ nothing new** — it initiates the transfer/send as today and its `device_approval.approved`
810
+ webhook still fires.
811
+
812
+ **This is the path for every new title** — there is no partner passkey domain to verify any
813
+ more (see [which passkey path serves your tenant](#prerequisite-which-passkey-path-serves-your-tenant)).
814
+ In-app passkeys on your own domain (`enrollPasskey`, `approveSend`, `approveTransfer`) remain
815
+ fully supported for tenants that verified a domain before the freeze.
816
+
817
+ ```ts
818
+ import { InvoClient, InvoError } from "@invonetwork/web-sdk";
819
+
820
+ const client = new InvoClient({ token: playerToken, baseUrl: INVO_BASE });
821
+
822
+ // Call from a click handler: the popup is opened synchronously, before any network call.
823
+ approveButton.onclick = async () => {
824
+ try {
825
+ const result = await client.approveHosted({
826
+ transactionId: transferId, // the transfer/send your server initiated
827
+ flow: "transfer", // "transfer" | "send" | "send_receipt" | "transfer_receipt"
828
+ // onEnrollment: (e, respond) => …, // optional: observe / draw your own prompt (renderPrompt:false)
829
+ });
830
+ switch (result.status) {
831
+ case "approved": // money moved (or is held: result.approval.holdReason) — same shape as approveTransfer()
832
+ showClaimCode(result.approval?.claimCode); break;
833
+ case "denied": // the player said no on INVO's page (or denied the enrolment)
834
+ case "expired": // start a new approval
835
+ case "closed": // the player closed the popup
836
+ break;
837
+ case "blocked": // popup blocked or severed — nothing started; show a button and call again
838
+ showRetry(result.message); break;
839
+ }
840
+ } catch (e) {
841
+ if (e instanceof InvoError) handleBackendRefusal(e); // begin 400, invalid_grant, approve gates (e.g. PASSKEY_RECOVERY_COOLDOWN)
842
+ }
843
+ };
844
+ ```
845
+
846
+ What the one call does, in order — the same REST flow as the console section below, driven
847
+ from the browser:
848
+
849
+ 1. `POST /api/sdk/approvals/device/begin` with `{ transaction_id, flow, channel: "popup" }`.
850
+ INVO records this page's `Origin` as the popup's opener. **The SDK holds the returned
851
+ `device_code` for the duration of the call** — it is never on the result and never
852
+ logged; your code never sees it.
853
+ 2. Opens `verification_uri_complete` in a popup (480×720). The player enrols or uses their
854
+ INVO passkey there, on INVO's own domain.
855
+ 3. Polls `POST /api/sdk/approvals/device/poll` at the server's `interval`, backing off by
856
+ 5 s on `slow_down`.
857
+ 4. First-time enrolment: while the page waits on your screen, the poll carries
858
+ `enrollment { state: "awaiting_screen", device_label, match_code }` and the SDK shows
859
+ the INVO match-code prompt — *"Set up INVO on iPhone? Code 48-27. Say Yes only if the
860
+ phone you just scanned/opened shows this code."* — with **Yes, it shows this code** /
861
+ **No, that is not my phone** (focus-trapped dialog; Escape = No). The answer goes to
862
+ `POST /api/sdk/approvals/device/confirm-enrollment`; `confirmed` shows a quiet
863
+ "Finishing on iPhone… / Stop it, wrong code" row; a 409 already-decided (the backup
864
+ email answered first) takes the prompt down quietly.
865
+ 5. When the poll says `approved`, the SDK calls the flow's approve endpoint with the
866
+ `device_code` — `transfers/{id}/approve`, `send/{id}/approve`,
867
+ `send/{id}/confirm-receipt` or `transfers/{id}/confirm-receipt` — through every gate your
868
+ in-app approve already runs, and resolves `{ status: "approved", approval }`.
869
+
870
+ Security notes, in plain language:
871
+
872
+ - **The page's message is a wake-up, not a result.** When INVO's page finishes it posts a
873
+ status-only message to the window that opened it; the SDK uses it to poll *right now*
874
+ and nothing else. The outcome always comes from the poll and the approve call.
875
+ - **Origin check.** The SDK accepts that message only from the hosted page's own https
876
+ origin (parsed from `verification_uri_complete`; pass `platformOrigin` to pin it — the
877
+ URL must then match it exactly) and only from the popup it opened. Anything else is
878
+ ignored. The page posts only to its opener — the origin your `begin` request carried —
879
+ never to `*`.
880
+ - **No redirect parameter.** The hosted page never navigates to your site; there is no
881
+ `return`/`redirect` URL to supply or to spoof. The popup is closed on `approved` and left
882
+ readable on denied/expired. If the browser blocks the popup the default is to resolve
883
+ `blocked` *before anything is started*, so you can show a button and call again from its
884
+ click; `popupBlocked: "redirect"` opts in to sending this tab to the hosted page instead
885
+ (your page unloads; the `device_approval.approved` webhook is then your server's signal).
886
+ - **COOP.** Do not send `Cross-Origin-Opener-Policy: same-origin` on the page that calls
887
+ `approveHosted` — it severs the popup from its opener and the wake-up can never arrive.
888
+ Use `same-origin-allow-popups`. The SDK detects a severed popup and resolves `blocked`
889
+ with a hint.
890
+ - **Cancel with `signal`** (resolves `closed` and closes the popup). Nothing is called after
891
+ the promise settles.
892
+
682
893
  ### Consoles and TVs — approving without a browser (RFC 8628)
683
894
 
684
895
  A console has no browser, so it cannot run a passkey ceremony at all. **Device
@@ -695,16 +906,24 @@ happen on your backend, not in the game client.
695
906
  the *device*, not your game: a title with a website *and* a console build uses the normal
696
907
  ceremony in the browser and this one on the console.
697
908
 
909
+ **Native Steam and desktop game clients (Mac & Windows) belong here too.** Even though the
910
+ operating system supports passkeys, an embedded game client can't invoke the platform
911
+ authenticator from inside the engine — so a native desktop title uses this QR flow exactly as
912
+ a console does. It is the **client** that forces QR here, not the OS.
913
+
698
914
  ```ts
699
915
  // 1. Your server starts an approval for ONE transaction.
700
916
  // flow: "transfer" | "send" | "send_receipt" | "transfer_receipt"
917
+ // channel (optional, default "qr"): how the page is delivered — "qr" (console / TV /
918
+ // native desktop), "popup" (the browser itself calls begin: that is approveHosted),
919
+ // "app_browser" (the Unity / Unreal plugin opens the system browser)
701
920
  const start = await fetch(`${INVO_BASE}/api/sdk/approvals/device/begin`, {
702
921
  method: "POST",
703
922
  headers: { Authorization: `Bearer ${sdkSessionToken}`, "Content-Type": "application/json" },
704
- body: JSON.stringify({ transaction_id: transferId, flow: "transfer" }),
923
+ body: JSON.stringify({ transaction_id: transferId, flow: "transfer", channel: "qr" }),
705
924
  }).then((r) => r.json());
706
925
  // -> { device_code, user_code, verification_uri, verification_uri_complete,
707
- // expires_in, interval }
926
+ // expires_in, interval, channel }
708
927
 
709
928
  // 2. The game renders `verification_uri_complete` as a QR and prints `user_code`
710
929
  // under it. The QR already contains the code, so most players never type.
@@ -728,13 +947,99 @@ const poll = await fetch(`${INVO_BASE}/api/sdk/approvals/device/poll`, {
728
947
  consumed when used. It cannot approve anything else and cannot be reused.
729
948
  - **`user_code` is meant to be seen; `device_code` is not.** Poll from your backend.
730
949
  - **One live code per transaction.** Starting a second returns
731
- `409 DEVICE_APPROVAL_ALREADY_PENDING` — reuse the one you have or let it expire.
950
+ `409 DEVICE_APPROVAL_ALREADY_PENDING` — reuse the one you have or let it expire. Once an
951
+ *approved* code's own window has passed, `begin` works again for the same transaction
952
+ (useful if your server lost the `device_code` after the player approved — that used to
953
+ 409 until the transaction itself expired).
954
+ - **Starting an approval extends the transaction's window.** For `transfer` and `send`,
955
+ `begin` pushes the transaction's own approval window past the code's expiry, so an
956
+ approval at minute nine can't land on a transfer that has already expired and been
957
+ refunded.
732
958
  - **Subscribe to `device_approval.approved`** to learn the moment an approval lands
733
959
  instead of waiting for the next poll. Polling still works alone; the webhook is a
734
960
  latency improvement, not a replacement.
735
- - **The player needs an INVO passkey.** A passkey they set up on *your* domain is a
736
- different credential and cannot be used here — that is how passkeys work. The approval
737
- page says so plainly when they need to set one up.
961
+ - **First-time approvers enrol on the spot — your only job is one Yes/No prompt.** The
962
+ approval page uses a passkey registered with INVO, on INVO's own domain; a passkey the
963
+ player set up on *your* domain is a different credential and cannot be used there — that
964
+ is how passkeys work. So the first scan enrols one, and the proof it's really them is
965
+ **your game screen**: the phone says "Confirm on your game screen", your game shows "Set
966
+ up INVO on this phone: iPhone?", the player presses Yes on the console, and their phone's
967
+ fingerprint / face / screen lock creates the passkey and approves. No code to type, no
968
+ SMS, ever. Every later scan is scan, biometric, done. Same `begin`/`poll`, same
969
+ `device_approval.approved` webhook, same `method` value `device_grant_webauthn`, same
970
+ approve call with the `device_code` afterwards.
971
+ - **Poll: the `enrollment` object.** While a phone is waiting on your screen, the
972
+ `authorization_pending` body gains it (absent when no phone asked — an already-enrolled
973
+ phone never triggers it):
974
+
975
+ ```json
976
+ { "error": "authorization_pending",
977
+ "enrollment": { "state": "awaiting_screen", "device_label": "iPhone",
978
+ "match_code": "48-27", "recovery": false,
979
+ "requested_at": "2026-09-03T18:04:12+00:00" } }
980
+ ```
981
+
982
+ Show the prompt while `state` is `awaiting_screen`; remove it the moment it changes
983
+ (`confirmed` / `denied`) or the object disappears. `device_label` is from a fixed list
984
+ (iPhone, iPad, Android phone, Android device, Mac, Windows PC, Chromebook, Linux device,
985
+ phone), derived from the scanning phone's browser — a hint, not an identity. Lead the
986
+ copy with "scanned just now". **`recovery: true`** means the phone declared it is
987
+ *replacing* a lost INVO passkey — word the prompt "Replace your INVO passkey with this
988
+ iPhone? Code 48-27" and answer through the same `confirm-enrollment` (see *Recovering a
989
+ lost passkey* below).
990
+ - **Answer it: `POST /api/sdk/approvals/device/confirm-enrollment`** — same auth as
991
+ begin/poll (the sender's SDK session token).
992
+
993
+ ```ts
994
+ const r = await fetch(`${INVO_BASE}/api/sdk/approvals/device/confirm-enrollment`, {
995
+ method: "POST",
996
+ headers: { Authorization: `Bearer ${sdkSessionToken}`, "Content-Type": "application/json" },
997
+ body: JSON.stringify({ device_code: start.device_code, decision: "approve" }), // or "deny"
998
+ }).then((r) => r.json());
999
+ // 200 { status: "confirmed" | "denied" }
1000
+ // 409 DEVICE_APPROVAL_ENROLLMENT_ALREADY_DECIDED { decided, via }
1001
+ // -> the backup email answered first; take the prompt down quietly
1002
+ // 409 DEVICE_APPROVAL_NO_ENROLLMENT_PENDING -> no phone has asked
1003
+ // 400 invalid_grant / expired_token
1004
+ ```
1005
+
1006
+ **Deny ends the grant**: poll returns `access_denied`, and the phone says it was declined
1007
+ on the game screen.
1008
+ - **Backup email.** At the scan, an email goes to the address on file — "confirm on your game
1009
+ screen; can't see the prompt? tap here; wasn't you? tap here; ignore this if you already
1010
+ confirmed". Opened after the screen answered, it says "you already confirmed this". A
1011
+ backup for a missed prompt, not the proof channel; nothing for you to do.
1012
+ - **Mobile (`channel: "app_browser"`): enrolment is auto-confirmed, no prompt.** The Unity /
1013
+ Unreal plugins open the same page in the system browser (`ASWebAuthenticationSession` /
1014
+ Custom Tabs) and return on `invo-sdk-<game_id>://done`, which carries nothing. Because the
1015
+ phone running the page *is* the device that opened it, the game's prompt is unreachable
1016
+ and a match code proves nothing — so INVO confirms the enrolment itself: the poll's
1017
+ `enrollment` object appears already `confirmed` and goes straight to `approved`; the
1018
+ backup email still goes out as the "if this wasn't you" alert. Start polling on
1019
+ `interval` the moment `begin` returns — the return is only a hint to poll sooner.
1020
+ - **Recovering a lost passkey — from the page, nothing new on your side.** A player whose
1021
+ only INVO passkey was on a phone they no longer have taps "Recover my passkey by email"
1022
+ on the page. Recovery needs **both** halves of the identity: your game screen confirms
1023
+ the phone (the `recovery: true` prompt above — auto-confirmed on mobile), and *only then*
1024
+ a single-use recovery link is emailed to the address on file (never an address the page
1025
+ supplies; one recovery per identity per 24 h). Opened on the same phone, that tab
1026
+ confirms and the page carries on: INVO deactivates the old INVO passkeys, notifies the
1027
+ owner on every channel, enqueues an **`identity.passkey_reset`** webhook to your game,
1028
+ and the phone enrols a fresh passkey and settles the approval — your poll reports
1029
+ `approved` and `device_approval.approved` fires as usual.
1030
+
1031
+ > ⚠️ **Money out is paused for 24 hours after a recovery.** The approval settles, but the
1032
+ > approve call for a `transfer` / `send` is refused with `403 PASSKEY_RECOVERY_COOLDOWN`
1033
+ > (+ `retry_after`). The page tells the player "recovered; start this transfer again after
1034
+ > the hold" — expect a fresh initiate later, not a retry. Receiving and collecting are
1035
+ > unaffected.
1036
+ - **An identity with a method elsewhere must vouch for the new one.** If the identity
1037
+ already has an active approver — a passkey on a partner domain, the INVO app's device key —
1038
+ the page refuses to enrol beside it with `409 ENROLLMENT_REQUIRES_PROOF` and tells the
1039
+ player to add this phone from where that method lives (`linkDevice`), then scan again. An
1040
+ identity with no method enrols freely.
1041
+ - **The code box on the page is the RFC 8628 `user_code`,** there for a TV with no camera.
1042
+ When the QR pre-fills it, the box isn't shown. It is not an SMS field.
738
1043
  - **Currency purchases on a console go through that console's store**, as the platform
739
1044
  holder requires. This flow is for approving transfers and sends.
740
1045
 
@@ -798,6 +1103,7 @@ export const POST = createWebhookHandler({
798
1103
  | `item.purchased` | every item purchase | **grant the in-game item** (payload includes `transaction_id, order_id, player_email, identity_id, item_id, item_name, item_quantity, unit_price, total_price, currency_name, new_balance, fee_breakdown`) |
799
1104
  | `platform_commerce.purchased` | every Platform Commerce purchase (balance immediately; **card after payment settles**) | **fulfill the ecommerce order** — never on the browser confirm (payload: `transaction_id, order_id, funding_source, player_email, identity_id, item_id, item_name, item_quantity, total_price`; + `unit_price, currency_name, new_balance` on balance; `total_price_usd` on card; `fee_breakdown`) |
800
1105
  | `platform_commerce.refunded` | a Platform Commerce refund | handle the reversal (payload: `order_id, funding_source, player_email, refunded_amount, amount_unit, fee_retained`) |
1106
+ | `transfer.received` / `transfer.claim_expired` / `transfer.refunded` | sends & transfers | reconcile claim state — credited to the recipient (by any claim path, the hosted claim page included) / not collected within 24h / returned to the sender |
801
1107
 
802
1108
  Don't block waiting on `purchase.failed` for the `game`/`steam` rails — they only emit `completed`/`refunded`. Reconcile off `*.completed` + the status endpoints. For Platform Commerce **card** orders, fulfill on `platform_commerce.purchased`, not the browser confirmation.
803
1109
 
@@ -889,7 +1195,7 @@ Helpers:
889
1195
  | `.isPhoneShareAlreadyApproved` | phone-share was already approved (e.g. from a `/reject`) |
890
1196
  | `.isSourceGameNotLive` | **(403)** the caller's OWN game is in testing → **self-serve**: switch it to Live in the console (Game Settings → Status). Show `.message`; `.gameStatus` has the current state |
891
1197
  | `.isTargetGameNotLive` | **(403)** the DESTINATION game is in testing → the caller usually **can't fix this** (someone else's game). Show `.message`; steer to another destination via `getDestinations`. Deliberately **distinct** from `.isSourceGameNotLive` — don't collapse them, the remediation differs |
892
- | `.isWebauthnNotEnabledForTenant` | **(403)** tenant has no verified RP ID → **configuration state, not a failure**. Fall back to the SMS/in-app path; see [passkey prerequisites](#prerequisite-passkeys-are-dark-until-your-tenant-verifies-a-domain) |
1198
+ | `.isWebauthnNotEnabledForTenant` | **(403)** tenant has no partner passkey domain — the normal state now that new domains are frozen → **configuration state, not a failure**. Approve on INVO's hosted page (`approveHosted`); see [which passkey path serves your tenant](#prerequisite-which-passkey-path-serves-your-tenant) |
893
1199
 
894
1200
  Client-side guards (bad amount, missing idempotency key, `rail:"steam"` on `purchaseCurrency`, item validation) throw `InvoError` with `.status === 0` **before** any network call. Notable backend codes: `SDK_TOKEN_EXPIRED`, `TENANT_NOT_MIGRATED`, `WEBAUTHN_NOT_ENABLED_FOR_TENANT`, `WEBAUTHN_UV_REQUIRED`, `ENROLLMENT_REQUIRES_PROOF`, `ENROLLMENT_CODE_INVALID`, `PASSKEY_RECOVERY_COOLDOWN` (403, `retryAfterAt`), `no_channel_on_file`, `rate_limited`, `WRONG_RAIL_ENDPOINT`, `flow_paused`.
895
1201
 
@@ -954,6 +1260,7 @@ Every method also accepts an optional final `{ signal }` (`AbortSignal`) for can
954
1260
  | `getPendingCollect()` | `{ pending, raw }` — the player's own pending-to-collect list (player-token) |
955
1261
  | `getDestinations({ direction? })` | `{ availableGames, sourceGameName, transferMode, … }` — where the player can send/transfer, metadata inline |
956
1262
  | `getBalance()` | `{ gameId, gameName, balances, totalValue, currencyCount, hasFunds, raw }` — the player's balances for this game |
1263
+ | `approveHosted({ transactionId, flow, platformOrigin?, onEnrollment?, renderPrompt?, popupBlocked?, popup?, signal? })` | `{ status: "approved" \| "denied" \| "expired" \| "closed" \| "blocked" \| "redirected", popupBlocked, message?, approval? }` — runs the whole RFC 8628 device-approval grant from the browser on INVO's hosted page (begin `channel:"popup"` → popup → poll → match-code prompt → confirm-enrollment → approve with the `device_code`, which the SDK holds and never exposes); `approval` is the `ApproveResult` / `ConfirmReceiptResult` of the flow's approve endpoint |
957
1264
  | `platformCommerce.mountCheckout(el, checkoutUrl, { onComplete? })` | `{ iframe, destroy() }` — optional embed of INVO's hosted checkout (or just `location.href = checkoutUrl`); `onComplete` fires on the page's origin-checked `INVO_CHECKOUT_COMPLETE` message |
958
1265
 
959
1266
  Every method throws `InvoError` on failure and takes an optional final `{ signal }`. Full inline types ship with the package. The Platform Commerce card leg needs **no keys and no payment code in the browser** — INVO's hosted page owns the card form.