@invonetwork/web-sdk 3.8.0 → 3.9.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/CHANGELOG.md CHANGED
@@ -1,5 +1,57 @@
1
1
  # Changelog
2
2
 
3
+ ## 3.9.0
4
+
5
+ ### Minor Changes
6
+
7
+ - The INVO-hosted card page is the recommended way to save a card for a subscription.
8
+
9
+ New on `invo.cards`:
10
+
11
+ - **`createSetupSession({ playerEmail, successUrl?, cancelUrl?, metadata? })`** ->
12
+ `{ sessionId, cardSetupUrl, expiresAt, raw }` (`POST /api/checkout/card-setup-sessions`,
13
+ game secret header). Mint a 10-minute link server-side, send the member to `cardSetupUrl`
14
+ (top-level, never framed), and read the saved card's `id` back from `cards.list`; it appears
15
+ there immediately, carries the off-session consent a subscription needs, and no event fires
16
+ for it. No browser code, no client secret, no card processor named anywhere, so INVO can change
17
+ processor without partners changing anything. Never auto-retried: each call mints a fresh link.
18
+ Script-scheme `successUrl` / `cancelUrl` values are refused before the network (`INVALID_INPUT`,
19
+ status 0), matching INVO's own rule.
20
+ - `beginSetup` / `confirmSetup` are now documented as the **processor-bound alternative**: they
21
+ hand back a `clientSecret` only the current processor's client library can consume, so a card
22
+ form built on them needs rework when INVO changes processor.
23
+
24
+ New error classifiers: `isPlayerNotFound` (404 `PLAYER_NOT_FOUND`: the card page never creates
25
+ players), `isInvalidPlayerEmail` (400 `INVALID_PLAYER_EMAIL`), `isInvalidInput` (`INVALID_INPUT`,
26
+ at status 0 from the SDK's own guards or 400 from INVO for a script-scheme URL).
27
+
28
+ Fixed: `subscriptions.get(id, { includePlayer: true })` never populated `player`. INVO puts
29
+ `player_email` / `player_name` on the subscription object itself, not in a separate block; they
30
+ are now surfaced as `subscription.playerEmail` / `subscription.playerName`, and `player` is
31
+ derived from them.
32
+
33
+ README: a "Cards for subscriptions" section a partner can follow start to finish (mint, send,
34
+ read the card back, subscribe, what each error means, the 10-minute session, no browser code).
35
+
36
+ README corrections that ride along in this release: `subscription.expired` no longer carries
37
+ `failure_code: "steam_containment"` (a balance is spendable in any title whatever rail bought
38
+ it, so the "wallet value that cannot be spent in this game" deferral is gone from the deferrals
39
+ paragraph and the event table); the Steam transfer-policy note now says it is a rule about
40
+ currency moving between titles, not about spending (an item purchase never fails on origin);
41
+ and "game" reads "title" in a few places so a platform tenant is not misled by the word.
42
+ Line endings: a `.gitattributes` (`* text=auto eol=lf`) keeps the packed README, CHANGELOG and
43
+ package.json LF on every checkout (3.9.0's first build packed CRLF from a Windows checkout).
44
+
45
+ ## 3.8.1
46
+
47
+ ### Patch Changes
48
+
49
+ - Subscription docs: the per-charge ceiling is 25000.00, not 500.00, and it is
50
+ per CHARGE rather than per month. An annual plan bills the whole year in one
51
+ go, so a $500 a month plan sold as a 12-month plan is a single $6,000 charge
52
+ and is chargeable. The old number quietly refused every annual plan above
53
+ $41.66 a month.
54
+
3
55
  ## 3.8.0
4
56
 
5
57
  ### Minor Changes
package/LICENSE CHANGED
@@ -1,18 +1,18 @@
1
- Copyright (c) 2026 Invo Tech Inc. All rights reserved.
2
-
3
- This software and associated documentation files (the "Software") are the
4
- proprietary property of Invo Tech Inc. ("INVO"). The Software is licensed, not
5
- sold.
6
-
7
- GRANT. INVO grants you a non-exclusive, non-transferable, royalty-free license to
8
- install and use the Software, in unmodified form, solely to build and operate
9
- integrations with the INVO platform, subject to INVO's developer terms at
10
- https://invo.network.
11
-
12
- RESTRICTIONS. Except as expressly permitted above, you may not copy, modify,
13
- distribute, sublicense, sell, or create derivative works of the Software, or
14
- remove any proprietary notices, without INVO's prior written consent.
15
-
16
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17
- IMPLIED. IN NO EVENT SHALL INVO BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
18
- LIABILITY ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE.
1
+ Copyright (c) 2026 Invo Tech Inc. All rights reserved.
2
+
3
+ This software and associated documentation files (the "Software") are the
4
+ proprietary property of Invo Tech Inc. ("INVO"). The Software is licensed, not
5
+ sold.
6
+
7
+ GRANT. INVO grants you a non-exclusive, non-transferable, royalty-free license to
8
+ install and use the Software, in unmodified form, solely to build and operate
9
+ integrations with the INVO platform, subject to INVO's developer terms at
10
+ https://invo.network.
11
+
12
+ RESTRICTIONS. Except as expressly permitted above, you may not copy, modify,
13
+ distribute, sublicense, sell, or create derivative works of the Software, or
14
+ remove any proprietary notices, without INVO's prior written consent.
15
+
16
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17
+ IMPLIED. IN NO EVENT SHALL INVO BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
18
+ LIABILITY ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE.
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.8.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.8.0** adds **[Subscriptions](#subscriptions-recurring-billing)** as a first-class server surface on both rails — `invo.subscriptions.create/get/listForPlayer/cancel/changeAmount/setPaymentMethod/refund/steamInit/steamFinalize`, the off-session card capture (`invo.cards.beginSetup/confirmSetup/list`), the sandbox clock tools (`invo.sandbox.subscriptions.*`, which post to `/subscriptions/<id>/...` **relative to the sandbox base, not under `/api`**, with the new `sandboxClockKey`), typed `data` for all seven `subscription.*` webhook events, and eleven new error classifiers; **3.7.0** makes the **device approval grant a first-class SDK surface** — `beginDeviceApproval`, `pollDeviceApproval`, `confirmDeviceEnrollment` and, the step that actually moves the money, **`approveWithDeviceCode`** (plus the optional `completeDeviceApproval` loop); a grant that is polled to `approved` and left there settles **nothing**, which is the failure this release exists to make impossible, and `TRANSACTION_NOT_PENDING` now comes back as a typed `status: "not_pending"` result with `alreadySettled` rather than a thrown error you would have to string-match; **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).
5
+ > **Status:** `v3.9.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.9.0** adds the **[INVO-hosted card page for subscriptions](#cards-for-subscriptions)**, `invo.cards.createSetupSession`: mint a 10-minute link server-side, send the member to it, read the card back from `cards.list`, with no browser code and no card processor named anywhere (`beginSetup`/`confirmSetup` remain as the processor-bound alternative), plus the `isPlayerNotFound`, `isInvalidPlayerEmail` and `isInvalidInput` classifiers and a fix that makes `includePlayer` reads actually surface `playerEmail`/`playerName`; **3.8.0** adds **[Subscriptions](#subscriptions-recurring-billing)** as a first-class server surface on both rails — `invo.subscriptions.create/get/listForPlayer/cancel/changeAmount/setPaymentMethod/refund/steamInit/steamFinalize`, the off-session card capture (`invo.cards.beginSetup/confirmSetup/list`), the sandbox clock tools (`invo.sandbox.subscriptions.*`, which post to `/subscriptions/<id>/...` **relative to the sandbox base, not under `/api`**, with the new `sandboxClockKey`), typed `data` for all seven `subscription.*` webhook events, and eleven new error classifiers; **3.7.0** makes the **device approval grant a first-class SDK surface** — `beginDeviceApproval`, `pollDeviceApproval`, `confirmDeviceEnrollment` and, the step that actually moves the money, **`approveWithDeviceCode`** (plus the optional `completeDeviceApproval` loop); a grant that is polled to `approved` and left there settles **nothing**, which is the failure this release exists to make impossible, and `TRANSACTION_NOT_PENDING` now comes back as a typed `status: "not_pending"` result with `alreadySettled` rather than a thrown error you would have to string-match; **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
@@ -24,6 +24,8 @@ Six money flows plus passkey (WebAuthn) authentication, split across a trusted s
24
24
 
25
25
  The **game secret stays on your server**; the browser only ever holds a short-lived, game-scoped **player token** (and, for the card leg, a per-purchase `checkoutUrl`).
26
26
 
27
+ > **This applies to a game or a platform alike:** the SDK calls the tenant a game and names the option `gameSecret`, but a platform tenant uses the same option and the same flow.
28
+
27
29
  ## Passkeys are the gold standard — don't build on SMS
28
30
 
29
31
  **If you take one thing from this README: authorize money movement with a passkey. Do not design your verification UX around the SMS PIN.**
@@ -44,7 +46,7 @@ So:
44
46
  **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:
45
47
 
46
48
  - **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`).
47
- - **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.
49
+ - **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 title from then on.
48
50
 
49
51
  `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:
50
52
 
@@ -97,6 +99,7 @@ The right approval method is a property of the **client the player is sitting in
97
99
  - [Item purchase (spend game currency)](#item-purchase-spend-game-currency)
98
100
  - [Platform Commerce (ecommerce)](#platform-commerce-ecommerce)
99
101
  - [Subscriptions (recurring billing)](#subscriptions-recurring-billing)
102
+ - [Cards for subscriptions](#cards-for-subscriptions)
100
103
  - [Player balance](#player-balance)
101
104
  - [Sends & transfers (move currency between players)](#sends--transfers-move-currency-between-players)
102
105
  - [Legacy fallback: the SMS PIN (being retired)](#legacy-fallback-the-sms-pin-being-retired)
@@ -123,9 +126,9 @@ Node ≥ 18 on the server (uses the global `fetch`). The browser build ships ESM
123
126
 
124
127
  ## Get your account & game secret (INVO console)
125
128
 
126
- Sign up, create your game, and copy its credentials (the **game secret**, plus your WebAuthn **RP ID / origins**) in the INVO console. Use the console that matches the environment you're building against:
129
+ Sign up, create your title, and copy its credentials (the **game secret**, plus your WebAuthn **RP ID / origins**) in the INVO console. Use the console that matches the environment you're building against:
127
130
 
128
- | Environment | Console — sign up, manage games, copy your game secret | API `baseUrl` |
131
+ | Environment | Console: sign up, manage titles, copy your game secret | API `baseUrl` |
129
132
  |---|---|---|
130
133
  | **Testing / sandbox** | **https://dev.console.invo.network** | `https://sandbox.invo.network/sandbox` |
131
134
  | **Production** | **https://console.invo.network** | `https://invo.network` |
@@ -163,7 +166,7 @@ Build and test against the **dev console + sandbox** first, then switch to the *
163
166
  ### Player token (session mint for an existing player)
164
167
 
165
168
  `mintPlayerToken` mints a short-lived, game-scoped **session token** for a player who
166
- **already exists** on your game. It is *not* a registration call — the backend looks the
169
+ **already exists** on your title. It is *not* a registration call: the backend looks the
167
170
  player up by `playerEmail` and returns a token for their existing identity (or `404` if no
168
171
  such player exists). It only needs `playerEmail`:
169
172
 
@@ -237,7 +240,7 @@ INVO enables each flow for your tenant in the [console](#get-your-account--game-
237
240
  - **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)).
238
241
  - **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).
239
242
  - **For item purchase:** nothing extra — it's a currency-balance debit.
240
- - **For subscriptions:** the game must be **`live`** (a `testing` game cannot create one), a **webhook target must be registered first** (several `subscription.*` events carry data you cannot fetch any other way), and a card subscription needs a card captured **off-session** via `cards.beginSetup` — the hosted checkout does not save one. See [Subscriptions](#subscriptions-recurring-billing).
243
+ - **For subscriptions:** the game must be **`live`** (a `testing` game cannot create one), a **webhook target must be registered first** (several `subscription.*` events carry data you cannot fetch any other way), and a card subscription needs a card captured **off-session** via `cards.createSetupSession` (the INVO-hosted card page; `cards.beginSetup` is the processor-bound alternative); the hosted checkout does not save one. See [Cards for subscriptions](#cards-for-subscriptions).
241
244
 
242
245
  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.
243
246
 
@@ -604,7 +607,7 @@ const ref = await server.platformCommerce.refund({ orderId: r.orderId, reason: "
604
607
 
605
608
  ## Subscriptions (recurring billing)
606
609
 
607
- A subscription is a standing agreement, created by **your server**, under which INVO bills one of your players a fixed USD price on a fixed interval and grants them your game's currency each period. **You keep the entitlement** (what the member gets in your game). INVO keeps the clock, the charges, the retries, the notifications and the revenue split. Two rails, fixed at creation:
610
+ A subscription is a standing agreement, created by **your server**, under which INVO bills one of your players a fixed USD price on a fixed interval and grants them your title's currency each period. **You keep the entitlement** (what the member gets in your title). INVO keeps the clock, the charges, the retries, the notifications and the revenue split. Two rails, fixed at creation:
608
611
 
609
612
  | `fundingRail` | How the shortfall is funded | Created by |
610
613
  |---|---|---|
@@ -621,12 +624,65 @@ Each period INVO works out what the period is worth in coins (card: price × the
621
624
 
622
625
  **Before you start:** the game must be `live` in the environment you're calling (a `testing` game is refused `403 GAME_NOT_LIVE`, `err.isGameNotLive`, though it may still read/cancel/reprice existing subscriptions); register a webhook target first (several events carry data you cannot fetch any other way); use the primary game key (`ivsdk_...`) or a channel key in `X-Game-Secret-Key` (on the Steam rail only the primary key or the `steam` channel key may start a subscription: `err.isSteamChannelRequired`). Money and coin figures are **decimal strings** on the wire and in every typed result, so nothing rounds silently.
623
626
 
624
- ### The card road
627
+ ### Cards for subscriptions
628
+
629
+ A card subscription needs a card saved for later, off-session use. **The recommended way to save one is the INVO-hosted card page:** two server-to-server calls and one redirect, **no browser code**, and nothing in your integration references a card processor or loads its script, so INVO can change processor without you changing anything. Your PCI scope does not change: the subscription endpoints never receive card data and neither does this SDK.
630
+
631
+ **1. Mint a card-setup session on your server.** The member must already exist in your title; this call never creates players.
632
+
633
+ ```ts
634
+ const session = await server.cards.createSetupSession({
635
+ playerEmail: "member@example.com",
636
+ successUrl: "https://your.game/billing/card-saved?member=7", // optional: where the page sends the member after the save; put your own correlation id here
637
+ });
638
+ // session.sessionId, session.cardSetupUrl, session.expiresAt (10 minutes from now)
639
+ ```
640
+
641
+ **2. Send the member to `session.cardSetupUrl`.** Open it as a top-level page (a redirect or a new tab); **do not frame it**. The page says in words that no money moves. The member enters the card, authenticates with their issuer if the issuer asks, and INVO saves the card and then redirects to your `successUrl` (or shows "Card saved, you can close this window" when you gave none). You write no browser code for this step and you never see a client secret, a publishable key or a processor name.
625
642
 
626
- **1. Capture a card (off-session).** A card subscription needs a card saved for later, off-session use. The subscription endpoints never receive card data and neither does this SDK: the card form on your client tokenises it. Two ways to save one, and **the hosted checkout is not one of them** (a member who paid through the hosted checkout page does *not* thereby have a card on file for recurring billing; neither does a card saved through a `savedCardId` purchase):
643
+ **3. Read the card back and subscribe.** A card saved this way **appears in `cards.list` immediately**, carries the off-session consent a subscription needs, and is indistinguishable from one saved any other way. The `id` is the only handle INVO returns for a card.
627
644
 
628
645
  ```ts
629
- // Option A: the setup flow (charges nothing). The player must already exist in this game.
646
+ const { cards } = await server.cards.list("member@example.com"); // unexpired, newest first
647
+ const r = await server.subscriptions.create({
648
+ clientRequestId: "guild-42-member-7",
649
+ playerEmail: "member@example.com",
650
+ playerName: "Member",
651
+ itemId: "guild-42-membership",
652
+ amountUsd: "9.99",
653
+ playerCardId: cards[0].id, // or omit it: INVO attaches the member's newest unexpired saved card
654
+ });
655
+ ```
656
+
657
+ **A brand-new member (no player in your title yet).** The card page needs an existing player and there is no create-player call, so bring the member into your title first. Two ways that move no money: `subscriptions.create` with `trialDays` creates the player and a `trialing` subscription (`firstCharge.status: "skipped_trial"`); or a card-less `subscriptions.create` (no `playerCardId`, no saved card yet) creates the player and the subscription, and its first charge is recorded as failed with `failureCode: "no_payment_method"` (outcome `insufficient_funds`), so the subscription sits in dunning with access retained. Then mint the card session and send the member to the page. After the save either call `subscriptions.setPaymentMethod(id, { playerCardId })` or do nothing: INVO adopts the member's newest saved card at the next attempt and attaches it. A currency purchase also creates the player, and with `save_card: true` saves the card in the same step.
658
+
659
+ **What to expect.**
660
+
661
+ - **The session lives 10 minutes.** Entering a card is one sitting. Mint the link when the member is about to use it, not ahead of time. An expired link shows the member a message asking for a new one; a new `createSetupSession` call is all it takes.
662
+ - **The link may be reloaded freely before the card is saved.** A reload after the issuer has authorised the card opens directly on the final "finish saving" step rather than asking for the card again.
663
+ - **Once the card is saved the link is spent.** Reopening it returns the same saved card and redirects to `successUrl` again; nothing is saved twice.
664
+ - **If saving fails after the issuer authorised the card,** the page tells the member to try again and the same link keeps working; nothing is recorded until the save succeeds. If what the member entered is not a card (a bank account, for instance) the page stops with a terminal message and a new link is needed.
665
+ - **There is no webhook for a saved card.** `cards.list` is the signal: read it when the member lands on `successUrl`, or right before the next `subscriptions.create`.
666
+ - **`createSetupSession` is never auto-retried.** Each call mints a fresh link, so on a timeout or 5xx just call it again.
667
+ - **`successUrl` is redirected to verbatim**, with nothing appended, and `metadata` is stored on the session and not returned anywhere today (no read returns the session). Put your own correlation id in `successUrl`. `cancelUrl` is carried on the session but not used by the page today.
668
+
669
+ **Errors from `createSetupSession`.** Match on `err.code`, never on the message.
670
+
671
+ | Helper / code | HTTP | Meaning |
672
+ |---|---|---|
673
+ | `.isInvalidPlayerEmail` (`INVALID_PLAYER_EMAIL`) | 400 | `playerEmail` is not an email address (INVO checks for an `@`). A missing or blank `playerEmail` never reaches INVO: the SDK throws `INVALID_INPUT` with `.status === 0` first |
674
+ | `.isPlayerNotFound` (`PLAYER_NOT_FOUND`) | 404 | the member does not exist in this title yet. Create the player first (any call that creates players, for example a currency purchase); the card page never creates one |
675
+ | `.isInvalidInput` (`INVALID_INPUT`) | 400 | `successUrl` or `cancelUrl` uses a script scheme (`javascript:`, `data:`, `vbscript:`). http(s) and app deep-link schemes are fine. The SDK refuses the same values before the network with `.status === 0` |
676
+ | no code, `err.status === 401` | 401 | the game key is missing or wrong for this environment (body is `{ message }`) |
677
+ | no code, `err.status === 403` | 403 | the game is not `live` or `testing` |
678
+ | `err.status === 503` (the `error_code` names the cause) | 503 | card setup is not available right now; retry shortly |
679
+
680
+ Rate limit: 2000 per minute per game key with a per-IP floor; on a 429 honour `err.retryAfter`.
681
+
682
+ **The processor-bound alternative: `cards.beginSetup` / `cards.confirmSetup`.** Use these only if you already run a card form in your own client against INVO's current card processor. `beginSetup` hands back a `clientSecret` that only that processor's client library can consume, so the browser code you write for it is bound to the processor of the day and will need rework when INVO changes processor. `createSetupSession` does not have that problem, which is why it is the recommended path.
683
+
684
+ ```ts
685
+ // The processor-bound alternative (charges nothing). The player must already exist in this game.
630
686
  const setup = await server.cards.beginSetup({
631
687
  playerEmail: "member@example.com",
632
688
  setupReference: "setup-guild-42-member-7", // idempotency anchor: resend the same value on a retry
@@ -643,10 +699,15 @@ switch (setup.status) {
643
699
  // saved.card.id (a 400 with body.status === "still_requires_action" means the client hasn't finished)
644
700
  break;
645
701
  }
702
+ ```
646
703
 
647
- // Option B: save the card during a purchase, purchaseCurrency(...) with a new paymentMethodId and
648
- // `save_card: true` in the body saves it with the off-session consent as a side effect.
704
+ **Saving the card during a purchase** also works: `purchaseCurrency(...)` with a new `paymentMethodId` and `save_card: true` in the body saves it with the off-session consent as a side effect; the purchase response carries `card_saved: true` and you read the `id` from `cards.list`.
649
705
 
706
+ ### The card road
707
+
708
+ **1. Capture a card (off-session).** Three ways to save one, and **the hosted checkout is not one of them** (a member who paid through the hosted checkout page does *not* thereby have a card on file for recurring billing; neither does a card saved through a `savedCardId` purchase): the INVO-hosted card page through `cards.createSetupSession` (recommended; see [Cards for subscriptions](#cards-for-subscriptions) above), the processor-bound `cards.beginSetup` / `cards.confirmSetup` pair, or a purchase with `save_card: true`. Whichever you use, the card's `id` comes from `cards.list`:
709
+
710
+ ```ts
650
711
  const { cards } = await server.cards.list("member@example.com"); // unexpired, newest first; `id` is the only handle
651
712
  ```
652
713
 
@@ -659,7 +720,7 @@ const r = await server.subscriptions.create({
659
720
  playerName: "Member", // used only if the player is created
660
721
  itemId: "guild-42-membership", // your entitlement handle; one live subscription per (player, item)
661
722
  itemName: "Guild 42 membership",
662
- amountUsd: "9.99", // 0.01..999999.99; keep it <= 500.00 or it is never charged
723
+ amountUsd: "9.99", // 0.01..999999.99; keep it <= 25000.00 PER CHARGE or it is never charged
663
724
  interval: "month", // "month" (default) | "year"
664
725
  // intervalCount: 3, // quarterly; 1..36
665
726
  // trialDays: 7, // or trialEnd: "2026-10-01T00:00:00Z"
@@ -778,7 +839,7 @@ export const POST = createWebhookHandler({
778
839
  break;
779
840
  case "subscription.expired": // the retry budget ran out (or a Steam row was never authorised)
780
841
  await revokeAt(event.data.subscription_id, event.data.final_period_end); // NOT ended_at; null if nothing was ever paid
781
- break; // failure_code "steam_containment": retired with NO payment_failed before it
842
+ break; // failure_code "steam_containment" is no longer sent (spending is not restricted by origin)
782
843
  case "subscription.refunded": // your revenue for the refunded portion is reversed; INVO's fee is retained
783
844
  await recordReversal(event.data.subscription_id, event.data.refund.partner_revenue_reversed_usd);
784
845
  break;
@@ -793,7 +854,7 @@ export const POST = createWebhookHandler({
793
854
  | Should I revoke access? | only on `subscription.expired` (at `final_period_end`) or `subscription.canceled` (at `access_until`); **never** on `payment_failed`, `past_due` or `authentication_required` |
794
855
  | What did I earn? | `split.partner_revenue_usd` on `subscription.renewed`, minus `refund.partner_revenue_reversed_usd` on any `subscription.refunded` |
795
856
 
796
- A few renewal outcomes are **deferrals**, not failures, with no event and no retry consumed (a price above the 500.00 per-charge ceiling; wallet value that cannot be spent in this game; on Steam, your billing setup or Steam configuration being unusable). You see them on `get` as an unchanged (or `past_due`) status with `nextChargeAt` about 24 hours out.
857
+ A few renewal outcomes are **deferrals**, not failures, with no event and no retry consumed (a price above the 25000.00 per-charge ceiling; on Steam, your billing setup or Steam configuration being unusable). You see them on `get` as an unchanged (or `past_due`) status with `nextChargeAt` about 24 hours out. There used to be a third: a wallet holding currency bought through Steam, in a title that was not on Steam. **That deferral is gone.** A balance is spendable in any title whatever rail bought it, so a renewal spends the whole wallet.
797
858
 
798
859
  ### Reading, cancelling, repricing, changing the card
799
860
 
@@ -809,7 +870,7 @@ const c = await server.subscriptions.cancel(id, { atPeriodEnd: true, reason: "me
809
870
 
810
871
  const a = await server.subscriptions.changeAmount(id, "14.99");
811
872
  // Staged: the current window bills at the old price, the new price applies from a.appliesFromPeriodSeq. No proration.
812
- // Sending the current price clears a staged change. More than double, or above 500.00, stays pending forever.
873
+ // Sending the current price clears a staged change. More than double, or above 25000.00, stays pending forever.
813
874
 
814
875
  await server.subscriptions.setPaymentMethod(id, { playerCardId: 43 }); // used from the next charge, incl. a pending retry
815
876
  await server.subscriptions.setPaymentMethod(id, { playerCardId: 43, walletOnly: false }); // convert a wallet-only subscription back
@@ -857,7 +918,7 @@ await sb.forceAuthChallenge(id); // moves it to awaiting_authenticati
857
918
  >
858
919
  > **Second credential.** Every clock call sends `X-Game-Secret-Key` *and* `X-Sandbox-Clock-Key`, a separate per-game key (`ivclk_...`). Get it from the sandbox console: open the game, **Game Settings**, the **"Sandbox clock key"** card (generated the first time you reveal it; the same card rotates it, with a 7-day grace). Pass it as `sandboxClockKey`; a missing key throws `INVALID_INPUT` before the network, a wrong one is `401 SANDBOX_CLOCK_UNAUTHORIZED` (`err.isSandboxClockUnauthorized`). Keep it out of game clients and source control. None of these calls is auto-retried: each one moves the clock or runs the engine.
859
920
 
860
- **Card recipe.** Make the sandbox game live and register a webhook. Save a card with `cards.beginSetup` using `paymentMethodId: "pm_card_visa"` (immediate) or `"pm_card_threeDSecure2Required"` (returns `requires_action`; finish on the client, then `confirmSetup`). `subscriptions.create` with that `playerCardId`: expect `firstCharge.status: "paid"`, `subscription.periodSeq: 2`, and a `subscription.renewed` delivery with `period_seq: 1`. Replay the same input: expect `idempotentReplay: true`. Then `advanceClock` + `forceRenewal` for as many periods as you like (`engineStats.renewed: 1`, `period_seq` advancing on each `subscription.renewed`); `forceFailure` four times (or swap in `"pm_card_chargeDeclined"` through `setPaymentMethod`, then advance + force four times) to walk `past_due` to `expired` with `final_period_end`; `changeAmount` then advance + force to see the old price on that renewal and the new one on the next; `cancel({ atPeriodEnd: true })` then advance + force to get `action: "retired-at-period-end"`; `refund` a paid period; and create one with `trialDays: 7` to see `skipped_trial` convert.
921
+ **Card recipe.** Make the sandbox game live and register a webhook. Save a card with `cards.createSetupSession` (open `cardSetupUrl` in a browser; the sandbox page runs against the test-mode card processor, so enter a test card there, never a real one; the sandbox recipe on the public docs site is at https://docs.invo.network/docs/subscriptions-sandbox), or, on the processor-bound path, with `cards.beginSetup` using `paymentMethodId: "pm_card_visa"` (immediate) or `"pm_card_threeDSecure2Required"` (returns `requires_action`; finish on the client, then `confirmSetup`). `subscriptions.create` with that `playerCardId`: expect `firstCharge.status: "paid"`, `subscription.periodSeq: 2`, and a `subscription.renewed` delivery with `period_seq: 1`. Replay the same input: expect `idempotentReplay: true`. Then `advanceClock` + `forceRenewal` for as many periods as you like (`engineStats.renewed: 1`, `period_seq` advancing on each `subscription.renewed`); `forceFailure` four times (or swap in `"pm_card_chargeDeclined"` through `setPaymentMethod`, then advance + force four times) to walk `past_due` to `expired` with `final_period_end`; `changeAmount` then advance + force to see the old price on that renewal and the new one on the next; `cancel({ atPeriodEnd: true })` then advance + force to get `action: "retired-at-period-end"`; `refund` a paid period; and create one with `trialDays: 7` to see `skipped_trial` convert.
861
922
 
862
923
  **Steam recipe.** In sandbox `steamFinalize` **does not call Steam**: it auto-approves a stand-in agreement and runs the real settlement (`fin.sandboxAutoApproved === true`), and `forceRenewal` treats the Steam charge as captured (`engineStats.steam_charged: 1, sandbox_synthetic: 1`). So sandbox proves INVO's currency path (coins, split, events, dunning), not Valve's charge: do one real Steam sandbox authorisation before launch. Credit the wallet above the price (a sandbox purchase), advance + force, and expect `funding.steam_charged_usd: "0.00"`.
863
924
 
@@ -885,7 +946,8 @@ Match on `err.code` (and on `body.status` where the body carries one), never on
885
946
  | `WALLET_ONLY_SUBSCRIPTION` / `WALLET_ONLY_CONFLICT` | `walletOnly: true` with a card; or a wallet-only subscription needs `walletOnly: false` beside the new card |
886
947
  | `NO_PAID_PERIOD` / `PERIOD_NOT_REFUNDABLE` / `AMOUNT_EXCEEDS_REMAINING` | refund refusals (the last carries `remaining_refundable_usd`) |
887
948
  | `AMOUNT_TOO_SMALL_FOR_STEAM` / `STEAM_CHARGE_UNPLANNABLE` / `STEAM_UNAVAILABLE` / `STEAM_ERROR` | Steam init refusals; the last three abandoned the row (its id on `.existingSubscriptionId`): retry with a **new** key |
888
- | `SETUP_REFERENCE_REUSED` / `PLAYER_NOT_FOUND` / `CARD_DECLINED` / `RAW_CARD_NOT_SUPPORTED` / `CARD_PERSIST_FAILED` | card capture; on `CARD_PERSIST_FAILED` (500) retry `confirmSetup` with the same `setupIntentId` |
949
+ | `.isPlayerNotFound` / `.isInvalidPlayerEmail` / `.isInvalidInput` | (404 / 400 / 400) `cards.createSetupSession`: the member does not exist yet (the card page never creates players); `playerEmail` is not an email; `successUrl`/`cancelUrl` uses a script scheme (`isInvalidInput` is also the SDK's own pre-network guard code, at `.status === 0`) |
950
+ | `SETUP_REFERENCE_REUSED` / `PLAYER_NOT_FOUND` / `CARD_DECLINED` / `RAW_CARD_NOT_SUPPORTED` / `CARD_PERSIST_FAILED` | the processor-bound card capture (`beginSetup`/`confirmSetup`); on `CARD_PERSIST_FAILED` (500) retry `confirmSetup` with the same `setupIntentId` |
889
951
 
890
952
  Client-side guards (missing key, a `sub_`-prefixed key, a bad amount, a non-E.164 `playerPhone`, a trial or card field on Steam, a web session without `playerIp`, a missing `sandboxClockKey`) throw `InvoError` with `.status === 0` **before** any network call.
891
953
 
@@ -900,9 +962,9 @@ Client-side guards (missing key, a `sub_`-prefixed key, a bad amount, a non-E.16
900
962
  7. **Do not poll for renewals.** Handle `subscription.renewed`.
901
963
  8. **One live subscription per item, across rails.** Cancel the old one before creating a new one for the same `itemId`, or reprice with `changeAmount`.
902
964
  9. **Period numbers differ by road.** `subscription.periodSeq` after a paid charge is the *next* period; `firstCharge.paidPeriodSeq` and the webhook's `period_seq` are the period *just paid*. Key entitlement on the latter.
903
- 10. **A card saved without off-session consent cannot back a subscription.** Hosted checkout and `savedCardId` purchases do not save one; use `cards.beginSetup` or a `save_card: true` purchase.
965
+ 10. **A card saved without off-session consent cannot back a subscription.** Hosted checkout and `savedCardId` purchases do not save one; use `cards.createSetupSession` (the INVO-hosted card page), the processor-bound `cards.beginSetup`, or a `save_card: true` purchase.
904
966
  11. **`walletOnly` is absolute.** A card attached later is ignored until you pass `walletOnly: false` on `setPaymentMethod`.
905
- 12. **Price changes apply next period, and big jumps never apply.** More than double, or above 500.00, stays pending.
967
+ 12. **Price changes apply next period, and big jumps never apply.** More than double, or above 25000.00, stays pending.
906
968
  13. **`sub_` is reserved** as a prefix for every idempotency key on the platform.
907
969
  14. **Do not store or log `confirmationUrl`** beside anything you publish. It is a bearer link.
908
970
  15. **Steam: finalize is your call**, the member has 24 hours, `web` needs `playerIp` and a top-level window, match the client callback on `steamOrderId`, show `amountCoins` (country-dependent, fixed at init), and `split.total_usd` on a Steam renewal is *not* the price.
@@ -1027,7 +1089,7 @@ try {
1027
1089
  `transfer.refunded` remain the source of truth — reconcile off those, not the messages.
1028
1090
  - **`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.
1029
1091
  - **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.
1030
- - **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.
1092
+ - **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. **This is a rule about currency moving between titles, not about spending.** A player can spend any balance on items in any title, Steam-distributed or not, including currency bought through Steam, so an item purchase never fails on origin and there is nothing to branch on there.
1031
1093
  - Transfer self-claim may be disabled for your tenant; if it is, surface the claim-code path instead.
1032
1094
  - **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`).
1033
1095
  - **Guardian approval goes by email first.** When a minor's initiate returns the 202, the guardian gets a
@@ -1446,7 +1508,7 @@ Each settle call takes the body `{"device_code": "..."}` and the player's bearer
1446
1508
  the same token that began the grant.
1447
1509
 
1448
1510
  **Available to every title, with nothing to configure.** The constraint is a property of
1449
- the *device*, not your game: a title with a website *and* a console build uses the normal
1511
+ the *device*, not your title: a title with a website *and* a console build uses the normal
1450
1512
  ceremony in the browser and this one on the console.
1451
1513
 
1452
1514
  **Native Steam and desktop game clients (Mac & Windows) belong here too.** Even though the
@@ -1731,7 +1793,7 @@ export const POST = createWebhookHandler({
1731
1793
  | `subscription.payment_failed` / `subscription.past_due` | every failed attempt / entering `past_due` once | notify the member; **access is retained** — do not revoke (`failure_code, retry_at, retries_remaining, grace_period_end, access_retained`) |
1732
1794
  | `subscription.authentication_required` | a card issuer wants the cardholder to authenticate (card rail) | **not a failure** — relay `confirmation_url` before `expires_at` |
1733
1795
  | `subscription.canceled` | a cancel request (yours, or the member's from Steam: `canceled_by`) | revoke at `access_until` |
1734
- | `subscription.expired` | the retry budget ran out, a Steam row was never authorised (`steam_authorization_abandoned`), or Steam value could no longer be spent here (`steam_containment`) | **revoke at `final_period_end`** (not `ended_at`; `null` if nothing was ever paid) |
1796
+ | `subscription.expired` | the retry budget ran out, or a Steam row was never authorised (`steam_authorization_abandoned`). `steam_containment` is **no longer returned**: spending is not restricted by which rail bought the currency | **revoke at `final_period_end`** (not `ended_at`; `null` if nothing was ever paid) |
1735
1797
  | `subscription.refunded` | a period refund | record the reversal (`refund.partner_revenue_reversed_usd`, `is_full_refund`, `revenue_share_attribution`) |
1736
1798
  | `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 |
1737
1799
 
@@ -1863,7 +1925,7 @@ try {
1863
1925
  | `platformCommerce.getStatus(orderId)` | `{ orderId, status, gameCurrencyAmount?, usdAmount?, paymentMethod?, createdAt?, raw }` |
1864
1926
  | `platformCommerce.refund({ orderId? \| clientRequestId?, reason? })` | `{ status, orderId?, fundingSource?, refundedAmount?, amountUnit?, feeRetained?, raw }` — pass **exactly one** id; INVO keeps its fee |
1865
1927
  | `subscriptions.create(input)` | `SubscriptionResult` — `{ status, idempotentReplay, subscription, card, firstCharge, warning?, raw }`; **card rail**, charges the first period before answering; branch on `firstCharge.status` (`paid` \| `requires_action` \| `skipped_trial` \| `failed` \| `pending`); idempotent on `clientRequestId` (a repeat is `idempotentReplay: true`, never thrown) |
1866
- | `subscriptions.get(id, { includePlayer? })` | `{ subscription, player?, raw }` — `subscription.paidThrough` is the entitlement boundary; `currentPeriodEnd` is only the billing window |
1928
+ | `subscriptions.get(id, { includePlayer? })` | `{ subscription, player?, raw }`: `subscription.paidThrough` is the entitlement boundary; `currentPeriodEnd` is only the billing window; `includePlayer: true` adds `subscription.playerEmail` / `subscription.playerName` (INVO puts them on the object; `player` is derived from them) |
1867
1929
  | `subscriptions.listForPlayer(playerEmail, { status?, limit?, offset?, includePlayer? })` | `{ playerEmail, subscriptions, pagination: { totalCount, limit, offset, hasMore }, raw }` — newest first; `status: "live"` expands to the four live statuses |
1868
1930
  | `subscriptions.cancel(id, { atPeriodEnd?, reason? })` | `CancelResult` — `{ alreadyCanceled, cancelAtPeriodEnd, terminatedImmediately, effectiveAt, accessUntil, paidThrough, subscription, raw }`; an already-terminal row is a 200 with `alreadyCanceled: true` |
1869
1931
  | `subscriptions.changeAmount(id, amountUsd)` | `ChangeAmountResult` — `{ oldAmountUsd, newAmountUsd, pendingAmountUsd, changeQueued, appliesFrom, appliesFromPeriodSeq, prorated, subscription, raw }`; staged for the next renewal (Steam: increases throw `isSteamReauthorizationRequired`) |
@@ -1871,8 +1933,9 @@ try {
1871
1933
  | `subscriptions.refund(id, { clientRequestId, periodSeq?, amountUsd?, reason? })` | `RefundResult` — the receipt (`isFullRefund, fundingShape, balanceDeltaCoins, cardRefundedUsd, partnerRevenueReversedUsd, revenueShareAttribution, idempotentReplay, raw`); idempotent on `clientRequestId`; Steam-charged periods throw `isSteamRefundNotSupported` |
1872
1934
  | `subscriptions.steamInit(input)` | `SteamInitResult` — `{ status, subscriptionStatus, idempotentReplay, pendingReuse, subscription, subscriptionId, orderId, steamOrderId, steamTransid, steamCheckoutUrl, amountUsd, amountCoins, steamChargeUsd, recurringAmountUsd, firstCharge, message, raw }`; **Steam rail**, nothing charged until finalize; match the Steam client callback on `steamOrderId` |
1873
1935
  | `subscriptions.steamFinalize(subscriptionId)` | `SteamFinalizeSubscriptionResult` — the `SubscriptionResult` plus `{ alreadyProcessed, steamAgreementStatus, sandboxAutoApproved }`; `isNotAuthorized` (409) is the normal wait state |
1874
- | `cards.beginSetup({ playerEmail, setupReference, paymentMethodId? })` | `CardSetupResult` — `{ status, setupIntentId, clientSecret?, publishableKey?, card, alreadySaved, raw }`; off-session card capture for subscriptions (charges nothing; idempotent on `setupReference`) |
1875
- | `cards.confirmSetup({ setupIntentId })` | `{ status, setupIntentId, card, alreadySaved, raw }` — finish a client-confirmed setup |
1936
+ | `cards.createSetupSession({ playerEmail, successUrl?, cancelUrl?, metadata? })` | `CardSetupSessionResult`: `{ sessionId, cardSetupUrl, expiresAt, raw }`. **The recommended card capture for subscriptions**: mint a 10-minute link to the INVO-hosted card page, send the member to `cardSetupUrl` (top-level), then read the card's `id` from `cards.list`; no browser code, no processor named; never auto-retried; `isPlayerNotFound` / `isInvalidPlayerEmail` / `isInvalidInput` |
1937
+ | `cards.beginSetup({ playerEmail, setupReference, paymentMethodId? })` | `CardSetupResult`: `{ status, setupIntentId, clientSecret?, publishableKey?, card, alreadySaved, raw }`; the **processor-bound** card capture (you run the card form; charges nothing; idempotent on `setupReference`) |
1938
+ | `cards.confirmSetup({ setupIntentId })` | `{ status, setupIntentId, card, alreadySaved, raw }`: finish a client-confirmed setup on the processor-bound path |
1876
1939
  | `cards.list(playerEmail)` | `{ cards: SavedCard[], raw }` — unexpired cards, newest first; `card.id` is the `playerCardId` |
1877
1940
  | `sandbox.subscriptions.advanceClock(id, intervals?)` / `forceRenewal(id)` / `forceFailure(id, outcome?, { failureCode?, failureMessage? })` / `forceAuthChallenge(id, { failureMessage? })` | `SandboxClockResult` — `{ status, action, subscription, before?, after?, engineStats?, retryScheduleDays?, retriesRemaining?, authChallengesUsed?, …, raw }`; **sandbox only**, posts to `/subscriptions/<id>/...` relative to the sandbox base (not `/api`), needs `sandboxClockKey`; never auto-retried |
1878
1941
  | `getPlayerBalance({ playerEmail })` | `{ player, balances, summary, raw }` — **by email only** (no by-id route; use `InvoClient.getBalance()` client-side) |
@@ -563,6 +563,34 @@ var InvoError = class _InvoError extends Error {
563
563
  get isGameNotLive() {
564
564
  return this.code === "GAME_NOT_LIVE";
565
565
  }
566
+ // ---- Card setup session (the INVO-hosted card page) ----
567
+ /**
568
+ * True when `cards.createSetupSession` was refused because the member does not exist
569
+ * in this game yet (`PLAYER_NOT_FOUND`, 404). The card page never creates players;
570
+ * create the member first (any endpoint that creates players, for example a currency
571
+ * purchase), then mint the session again. The same code comes back from
572
+ * `cards.beginSetup` and from `mintPlayerToken` for the same reason.
573
+ */
574
+ get isPlayerNotFound() {
575
+ return this.code === "PLAYER_NOT_FOUND";
576
+ }
577
+ /**
578
+ * True when `cards.createSetupSession` was refused because `playerEmail` was missing or
579
+ * is not an email address (`INVALID_PLAYER_EMAIL`, 400).
580
+ */
581
+ get isInvalidPlayerEmail() {
582
+ return this.code === "INVALID_PLAYER_EMAIL";
583
+ }
584
+ /**
585
+ * True on an `INVALID_INPUT` refusal. Two sources, told apart by `status`:
586
+ * `status === 0` is this SDK refusing a value before the network (every client-side
587
+ * guard uses this code); `status === 400` is INVO refusing one, on
588
+ * `cards.createSetupSession` a `successUrl` / `cancelUrl` that uses a script scheme
589
+ * (`javascript:`, `data:`, `vbscript:`). http(s) and app deep-link schemes are fine.
590
+ */
591
+ get isInvalidInput() {
592
+ return this.code === "INVALID_INPUT";
593
+ }
566
594
  /** Seconds to wait before retrying, when the backend throttled the call (429 `retry_after`). */
567
595
  get retryAfter() {
568
596
  const v = this.bodyObject()["retry_after"];
@@ -846,5 +874,5 @@ function toDestinationsResult(raw, direction) {
846
874
  }
847
875
 
848
876
  export { Http, InvoError, assertSecureBaseUrl, toDestinationsResult };
849
- //# sourceMappingURL=chunk-HYGBTUEJ.js.map
850
- //# sourceMappingURL=chunk-HYGBTUEJ.js.map
877
+ //# sourceMappingURL=chunk-NB6UF657.js.map
878
+ //# sourceMappingURL=chunk-NB6UF657.js.map
package/dist/index.cjs CHANGED
@@ -565,6 +565,34 @@ var InvoError = class _InvoError extends Error {
565
565
  get isGameNotLive() {
566
566
  return this.code === "GAME_NOT_LIVE";
567
567
  }
568
+ // ---- Card setup session (the INVO-hosted card page) ----
569
+ /**
570
+ * True when `cards.createSetupSession` was refused because the member does not exist
571
+ * in this game yet (`PLAYER_NOT_FOUND`, 404). The card page never creates players;
572
+ * create the member first (any endpoint that creates players, for example a currency
573
+ * purchase), then mint the session again. The same code comes back from
574
+ * `cards.beginSetup` and from `mintPlayerToken` for the same reason.
575
+ */
576
+ get isPlayerNotFound() {
577
+ return this.code === "PLAYER_NOT_FOUND";
578
+ }
579
+ /**
580
+ * True when `cards.createSetupSession` was refused because `playerEmail` was missing or
581
+ * is not an email address (`INVALID_PLAYER_EMAIL`, 400).
582
+ */
583
+ get isInvalidPlayerEmail() {
584
+ return this.code === "INVALID_PLAYER_EMAIL";
585
+ }
586
+ /**
587
+ * True on an `INVALID_INPUT` refusal. Two sources, told apart by `status`:
588
+ * `status === 0` is this SDK refusing a value before the network (every client-side
589
+ * guard uses this code); `status === 400` is INVO refusing one, on
590
+ * `cards.createSetupSession` a `successUrl` / `cancelUrl` that uses a script scheme
591
+ * (`javascript:`, `data:`, `vbscript:`). http(s) and app deep-link schemes are fine.
592
+ */
593
+ get isInvalidInput() {
594
+ return this.code === "INVALID_INPUT";
595
+ }
568
596
  /** Seconds to wait before retrying, when the backend throttled the call (429 `retry_after`). */
569
597
  get retryAfter() {
570
598
  const v = this.bodyObject()["retry_after"];
package/dist/index.d.cts CHANGED
@@ -1,5 +1,5 @@
1
- import { A as ApproveResult, C as ConfirmReceiptResult, M as MountCheckoutOptions, a as CheckoutMountHandle, b as ClientConfig, c as CallOptions, L as LinkDeviceResult, P as PendingCollectResult, D as DestinationsQuery, d as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, e as EnrollmentVerifyResult, R as RecoveryBeginResult, f as RecoveryCompleteResult } from './types-DqRuqbqI.cjs';
2
- export { g as BalanceRow, h as DestinationGame, I as InvoError, i as InvoErrorInfo, j as InvoHooks, k as InvoRequestInfo, l as InvoResponseInfo, m as PendingCollectItem, n as Rail, V as VerificationMethod } from './types-DqRuqbqI.cjs';
1
+ import { A as ApproveResult, C as ConfirmReceiptResult, M as MountCheckoutOptions, a as CheckoutMountHandle, b as ClientConfig, c as CallOptions, L as LinkDeviceResult, P as PendingCollectResult, D as DestinationsQuery, d as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, e as EnrollmentVerifyResult, R as RecoveryBeginResult, f as RecoveryCompleteResult } from './types-CUzSzV8-.cjs';
2
+ export { g as BalanceRow, h as DestinationGame, I as InvoError, i as InvoErrorInfo, j as InvoHooks, k as InvoRequestInfo, l as InvoResponseInfo, m as PendingCollectItem, n as Rail, V as VerificationMethod } from './types-CUzSzV8-.cjs';
3
3
 
4
4
  /** The four device-approval flows (`begin.flow`). */
5
5
  type HostedFlow = "transfer" | "send" | "send_receipt" | "transfer_receipt";
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { A as ApproveResult, C as ConfirmReceiptResult, M as MountCheckoutOptions, a as CheckoutMountHandle, b as ClientConfig, c as CallOptions, L as LinkDeviceResult, P as PendingCollectResult, D as DestinationsQuery, d as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, e as EnrollmentVerifyResult, R as RecoveryBeginResult, f as RecoveryCompleteResult } from './types-DqRuqbqI.js';
2
- export { g as BalanceRow, h as DestinationGame, I as InvoError, i as InvoErrorInfo, j as InvoHooks, k as InvoRequestInfo, l as InvoResponseInfo, m as PendingCollectItem, n as Rail, V as VerificationMethod } from './types-DqRuqbqI.js';
1
+ import { A as ApproveResult, C as ConfirmReceiptResult, M as MountCheckoutOptions, a as CheckoutMountHandle, b as ClientConfig, c as CallOptions, L as LinkDeviceResult, P as PendingCollectResult, D as DestinationsQuery, d as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, e as EnrollmentVerifyResult, R as RecoveryBeginResult, f as RecoveryCompleteResult } from './types-CUzSzV8-.js';
2
+ export { g as BalanceRow, h as DestinationGame, I as InvoError, i as InvoErrorInfo, j as InvoHooks, k as InvoRequestInfo, l as InvoResponseInfo, m as PendingCollectItem, n as Rail, V as VerificationMethod } from './types-CUzSzV8-.js';
3
3
 
4
4
  /** The four device-approval flows (`begin.flow`). */
5
5
  type HostedFlow = "transfer" | "send" | "send_receipt" | "transfer_receipt";
package/dist/index.js CHANGED
@@ -1,5 +1,5 @@
1
- import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult } from './chunk-HYGBTUEJ.js';
2
- export { InvoError } from './chunk-HYGBTUEJ.js';
1
+ import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult } from './chunk-NB6UF657.js';
2
+ export { InvoError } from './chunk-NB6UF657.js';
3
3
 
4
4
  // src/shared/webauthn.ts
5
5
  function malformedOptions(field) {