@invonetwork/web-sdk 3.9.0 → 3.10.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,33 @@
1
1
  # Changelog
2
2
 
3
+ ## 3.10.0
4
+
5
+ ### Minor Changes
6
+
7
+ - f66103c: Card-only subscriptions and subscription refund guardrails (INVO backend, 2026-09-17). Everything here is additive: no field, type or behaviour of an existing call was removed or renamed.
8
+
9
+ **Card-only subscriptions (behaviour change on INVO's side, no type changes).** A card subscription's card is now charged the full price every period; the member's coin wallet never pays for it and never moves. Steam subscriptions are unchanged (wallet first, Steam tops up the shortfall).
10
+
11
+ - `subscription.renewed` on the card rail: `funding.balance_applied_coins` is always `"0.00"`, `funding.card_charged_usd` is the price, `mint_order_id` is never `null`.
12
+ - Every paid card renewal also emits `purchase.completed` with `data.metadata.source === "subscription_renewal"`. Do not grant currency from it; `subscription.renewed` is the entitlement signal.
13
+ - A member with no saved card fails with `failure_code: "no_payment_method"` whatever their balance. New additive `failure_code`: `wallet_negative`.
14
+ - `walletOnly` is marked `@deprecated` (still accepted and returned): a wallet-only card subscription can never be paid (`failure_code: "wallet_only"`).
15
+ - `subscription.authentication_required`: `card_amount_usd` now equals `amount_due_usd` on card challenges.
16
+ - Doc fix: the `amountUsd` JSDoc now states the per-charge ceiling of `25000.00` (it still said `500.00`), and `SubscriptionExpiredData` no longer says `steam_containment` is sent.
17
+
18
+ **Subscription refund guardrails.**
19
+
20
+ - `subscriptions.refund` can now return a refund request. `RefundResult` stays a single interface (its `status` is typed `"refunded" | "pending_approval" | (string & {})`, so any string still assigns and compares); branch with the new `isRefundPendingApproval(r)` type guard, which narrows to `RefundPendingApproval`. `"pending_approval"` is the new HTTP 202: the refund would exceed the game's daily self-serve limit ($500 by default), nothing moved, and INVO reviews it as a refund request (`requestId`, `requestStatus`, `requestedAmountUsd`, `requestedAt`, `dailyCapUsd`, `executedTodayUsd`, `message`). Both carry every receipt field; the `request*` fields are optional on `RefundResult` and required on `RefundPendingApproval`. The status string is passed through from INVO unchanged.
21
+ - New optional result fields: `warnings` (`REASON_RECOMMENDED`, `REASON_TRUNCATED`), `subscriptionCanceled`, `subscriptionStatus`, `processingFeeUsd`, `processingFeeBasis`, `processingFeeBorneBy`, `processingFeeTransactionId`, `partnerTotalReversedUsd`, `initiation`, `refundRequestId`. `undefined` on receipts stored before the change.
22
+ - `reason` is documented as recommended now and required after a notice period. Refunds run within 30 days of the charge. A full refund cancels the subscription. Card-only periods are refunded in cash, partial included. The partner bears the card processor fee. INVO emails the member.
23
+ - New `InvoError` classifiers: `isRefundsNotEnabled` (403), `isRefundWindowClosed` (409), `isRefundRequestPending` (409), `isRefundRequestRejected` (409), `isConcurrentRequest` (409), `isRefundMismatch` (502), with body accessors `refundRequestId`, `decisionReason`, `periodChargedAt`, `refundWindowDays`, `refundWindowClosedAt`.
24
+ - New webhook types: `subscription.refund_requested`, `subscription.refund_approved`, `subscription.refund_rejected` (`SubscriptionRefundRequestData`, `SubscriptionRefundApprovedData`, `SubscriptionRefundRejectedData`). Additive fields on `subscription.refunded` (`refund.processing_fee_*`, `refund.partner_total_reversed_usd`, `initiation`, `refund_request_id`, `subscription_canceled`) and `subscription.canceled` (`cancel_cause: "full_refund"`).
25
+ - New exports: `isRefundPendingApproval`; types `RefundReceipt`, `RefundPendingApproval` (both extend `RefundResult`), `RefundWarning`, `RefundInitiation`, `RefundProcessingFeeBasis`.
26
+
27
+ **Compatibility.** Additive only. Code that compares `status` to any string, builds `RefundResult` mocks with a `string` status, or `extends`/`implements` `RefundResult` keeps compiling (pinned by a tsc test). `subscription.refunded`, `subscription.refund_approved` and, on a full refund, `subscription.canceled` are sent together and may arrive in any order.
28
+
29
+ README: the Subscriptions section states card-only funding, the renewal `purchase.completed` trap, the refund limits and the 202, the new events and classifiers, and "what did I earn" now subtracts `partner_total_reversed_usd`.
30
+
3
31
  ## 3.9.0
4
32
 
5
33
  ### Minor Changes
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.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).
5
+ > **Status:** `v3.10.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.10.0** documents **card-only subscriptions** (the card pays the full price every period, the coin wallet never pays; `walletOnly` deprecated; new `failure_code` `wallet_negative`; a renewal's `purchase.completed` is not a purchase) and the **[subscription refund limits](#refunds)**: `subscriptions.refund` can now return a 202 `pending_approval` refund request (`isRefundPendingApproval`), with `warnings`, the processor fee you bear, `subscriptionCanceled` (a full refund cancels), new classifiers (`isRefundsNotEnabled`, `isRefundWindowClosed`, `isRefundRequestPending`, `isRefundRequestRejected`, `isConcurrentRequest`, `isRefundMismatch`) and typed `subscription.refund_requested` / `refund_approved` / `refund_rejected` events, all additive; **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
@@ -14,7 +14,7 @@ Six money flows plus passkey (WebAuthn) authentication, split across a trusted s
14
14
  | **Currency purchase** | real money **→** game currency | yes (card/rails) | no | server initiates, browser opens hosted checkout |
15
15
  | **Item purchase** | game currency **→** in-game item | no (balance debit) | no | server only |
16
16
  | **Platform Commerce** (ecommerce) | balance **or** card **→** a storefront item | card leg only | no | server creates; buyer pays on INVO's **hosted checkout** |
17
- | **Subscriptions** | a fixed USD price on a fixed interval **→** game currency each period (card **or** Steam rail) | yes (the wallet shortfall) | no | server creates, cancels, reprices; renewals arrive by webhook |
17
+ | **Subscriptions** | a fixed USD price on a fixed interval **→** game currency each period (card **or** Steam rail) | yes (card: the full price every period; Steam: the wallet shortfall) | no | server creates, cancels, reprices; renewals arrive by webhook |
18
18
  | **Send** | currency **→** another player (cross-game) | no | yes (sender approves) | server initiates, browser approves/claims |
19
19
  | **Transfer** | currency **→** another player (transfer rail) | no | yes (sender approves) | server initiates, browser approves/claims |
20
20
 
@@ -609,12 +609,17 @@ const ref = await server.platformCommerce.refund({ orderId: r.orderId, reason: "
609
609
 
610
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:
611
611
 
612
- | `fundingRail` | How the shortfall is funded | Created by |
612
+ | `fundingRail` | Who pays each period | Created by |
613
613
  |---|---|---|
614
- | `card` | the member's saved card on file with INVO | `server.subscriptions.create(...)` |
615
- | `steam` | the member's Steam wallet, through a recurring agreement they authorise once | `server.subscriptions.steamInit(...)` then `steamFinalize(...)` |
614
+ | `card` | the member's saved card on file with INVO, charged the **full price** every period | `server.subscriptions.create(...)` |
615
+ | `steam` | the member's Steam wallet, through a recurring agreement they authorise once (the INVO wallet is spent first; Steam tops up the shortfall) | `server.subscriptions.steamInit(...)` then `steamFinalize(...)` |
616
616
 
617
- Each period INVO works out what the period is worth in coins (card: price × the 10-coins-per-USD peg; Steam: what the price buys through Steam for the member's country), **spends the member's wallet first**, tops up from the rail for the **shortfall only**, and splits the coins spent between INVO's platform fee (10% by default, plus $0.30 on the card-funded portion of a renewal) and your revenue. Every figure is reported on the `subscription.renewed` event.
617
+ Each period INVO works out what the period is worth in coins (card: price × the currency's coins-per-USD rate, 10 per USD by default; Steam: what the price buys through Steam for the member's country) and splits it between INVO's platform fee and your revenue. Every figure is reported on the `subscription.renewed` event.
618
+
619
+ - **Card rail: card only (since 2026-09-17).** The card is charged the full price every period, whatever the member's coin wallet holds. The coins that charge buys are minted and spent in the same step, so **the wallet never pays for a card subscription and never moves**. There is no shortfall, no rounding and no minimum top-up. INVO's fee is 10% by default plus $0.30, on the full price ($9.99 pays INVO $1.30 and you $8.69).
620
+ - **Steam rail: unchanged.** INVO spends the member's wallet first and tops up from Steam for the shortfall only.
621
+ - **Save a card before `subscriptions.create`.** A member with coins but no saved card is still subscribed (the create succeeds), but the first charge fails with `failureCode: "no_payment_method"` and the subscription enters dunning. Coins never pay it.
622
+ - **`walletOnly` is deprecated.** It is still accepted and returned, but a `walletOnly: true` card subscription never charges a card and so can never be paid: every charge fails with `failure_code: "wallet_only"` and it lapses to `expired`. Do not send it on new integrations.
618
623
 
619
624
  **Three rules to carry through everything below.**
620
625
 
@@ -725,7 +730,7 @@ const r = await server.subscriptions.create({
725
730
  // intervalCount: 3, // quarterly; 1..36
726
731
  // trialDays: 7, // or trialEnd: "2026-10-01T00:00:00Z"
727
732
  // playerCardId: cards[0].id, // omitted: INVO attaches the newest unexpired saved card
728
- // walletOnly: true, // never charge a card; dunning when the wallet is short
733
+ // walletOnly: true, // DEPRECATED: never charges a card, so it can never be paid ("wallet_only")
729
734
  metadata: { guild_id: "42" }, // echoed on every read and event (`_invo` is reserved)
730
735
  consent: { // send it: INVO is merchant of record and a dispute is argued from this
731
736
  consentAt: new Date().toISOString(),
@@ -753,6 +758,7 @@ switch (r.firstCharge.status) {
753
758
  grantTrialUntil(r.subscription.trialEnd!);
754
759
  break;
755
760
  case "failed": // status is past_due, in dunning; INVO retries at nextRetryAt
761
+ // failureCode: "no_payment_method" (save a card; coins never pay), "card_declined", "wallet_negative", ...
756
762
  tellMemberToFixCard(r.firstCharge.failureCode);
757
763
  break;
758
764
  case "pending": // an ambiguous processor answer; INVO resolves it within ~30 minutes
@@ -805,7 +811,7 @@ try {
805
811
 
806
812
  Not available on Steam, and refused by the SDK before the network: trials, `walletOnly`, card fields, `intervalCount` other than 1. A **price increase** is refused (`err.isSteamReauthorizationRequired`: the member consented to a ceiling; start a new Steam subscription at the new price and cancel this one); a decrease stages. `setPaymentMethod` is refused (`err.isNotACardSubscription`). A member can cancel from their Steam account: you learn it from `subscription.canceled` with `canceled_by: "steam"`. Replaying `steamInit` returns the row's **current** status (already `active`, `canceled`, `expired`, ...). A pending row for the same player + item with **different** terms throws `409 STEAM_AUTHORIZATION_PENDING` (`err.isSteamAuthorizationPending`, the pending id on `err.existingSubscriptionId`); with the **same** terms it is handed back as `pendingReuse: true`. A row never finalised expires after 24 hours with `subscription.expired` and `failure_code: "steam_authorization_abandoned"`.
807
813
 
808
- ### Renewals, dunning and the seven events
814
+ ### Renewals, dunning and the events
809
815
 
810
816
  INVO bills **in advance**, at `nextChargeAt`, within a minute or two. Do not poll for renewals; handle the events. When a charge fails the subscription goes `past_due` and INVO retries on the dunning ladder (default: after 2 days, then 3, then 2, then `expired`), **retaining access through the whole grace window**. A card issuer that wants the cardholder to authenticate moves the subscription to `awaiting_authentication` with no retry consumed: **not a failure**; relay the link.
811
817
 
@@ -820,13 +826,19 @@ export const POST = createWebhookHandler({
820
826
  case "subscription.renewed": { // THE source of truth for entitlement (event.data is typed)
821
827
  const d = event.data; // d.period_seq is the period JUST PAID; d.period_end is the new paid_through
822
828
  await extendAccess(d.subscription_id, d.period_end);
823
- // d.funding.rail ("card" | "steam"), d.funding.card_charged_usd / steam_charged_usd (the shortfall only)
829
+ // d.funding.rail ("card" | "steam"). Card: d.funding.card_charged_usd is the full price and
830
+ // d.funding.balance_applied_coins is always "0.00". Steam: d.funding.steam_charged_usd is the shortfall only.
824
831
  // d.split.basis: "price" on card; "steam_net" on Steam, where d.split.total_usd is what the coins are worth,
825
832
  // not the price (the price is d.amount_usd). d.split.partner_revenue_usd is what you earned.
826
833
  // d.revenue_share_attribution?.attributed_amount_usd: what to pay your recipient yourself (settled_by_invo: false)
827
834
  break;
828
835
  }
836
+ case "purchase.completed": // a paid CARD RENEWAL also sends this, for the coins its charge minted
837
+ if (event.data.metadata?.["source"] === "subscription_renewal") break; // grant NOTHING here; subscription.renewed is the signal
838
+ await grantCurrency(event.data); // (its order_id is the renewal's mint_order_id)
839
+ break;
829
840
  case "subscription.payment_failed": // every failed attempt; access RETAINED. Do not revoke.
841
+ // failure_code: "no_payment_method" (no saved card), "wallet_negative" (coin balance below zero), "card_declined", ...
830
842
  await notifyCardProblem(event.data.subscription_id, event.data.failure_code, event.data.retry_at);
831
843
  break;
832
844
  case "subscription.past_due": // once, on ENTERING past_due. Access retained.
@@ -836,12 +848,22 @@ export const POST = createWebhookHandler({
836
848
  break;
837
849
  case "subscription.canceled": // once, at request time, both modes. Revoke at access_until.
838
850
  await revokeAt(event.data.subscription_id, event.data.access_until); // event.data.canceled_by: "partner" | "steam"
839
- break;
851
+ break; // event.data.cancel_cause === "full_refund" when a full refund ended it
840
852
  case "subscription.expired": // the retry budget ran out (or a Steam row was never authorised)
841
853
  await revokeAt(event.data.subscription_id, event.data.final_period_end); // NOT ended_at; null if nothing was ever paid
842
854
  break; // failure_code "steam_containment" is no longer sent (spending is not restricted by origin)
843
- case "subscription.refunded": // your revenue for the refunded portion is reversed; INVO's fee is retained
844
- await recordReversal(event.data.subscription_id, event.data.refund.partner_revenue_reversed_usd);
855
+ case "subscription.refunded": { // your revenue is reversed, plus the processor fee on a card refund
856
+ const r = event.data.refund; // older events carry no partner_total_reversed_usd
857
+ await recordReversal(event.data.subscription_id, r.partner_total_reversed_usd ?? r.partner_revenue_reversed_usd);
858
+ break; // event.data.subscription_canceled: a full refund cancels (subscription.canceled is sent with it)
859
+ }
860
+ case "subscription.refund_requested": // a refund over your daily limit is waiting for INVO; nothing moved
861
+ await markRefundPending(event.data.request_id, event.data.client_request_id);
862
+ break;
863
+ case "subscription.refund_approved": // INVO approved it; subscription.refunded is sent with it, in any order
864
+ break;
865
+ case "subscription.refund_rejected": // INVO rejected it; nothing moved. A new clientRequestId can try again
866
+ await markRefundRejected(event.data.request_id, event.data.decision_reason);
845
867
  break;
846
868
  }
847
869
  },
@@ -852,7 +874,11 @@ export const POST = createWebhookHandler({
852
874
  |---|---|
853
875
  | Has the member paid for the period they are in? | `subscription.renewed` for that period, or `paidThrough` on `get` |
854
876
  | 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` |
855
- | What did I earn? | `split.partner_revenue_usd` on `subscription.renewed`, minus `refund.partner_revenue_reversed_usd` on any `subscription.refunded` |
877
+ | What did I earn? | `split.partner_revenue_usd` on `subscription.renewed`, minus `refund.partner_total_reversed_usd` (revenue reversed plus the card processor fee you bear) on any `subscription.refunded`; on refunds before 2026-09-17, which carry no such field, `refund.partner_revenue_reversed_usd` |
878
+ | Should I grant anything on a renewal's `purchase.completed`? | **No.** Every paid card renewal also sends `purchase.completed` (`data.metadata.source === "subscription_renewal"`) for the coins its charge minted, and the renewal spends them in the same step. Act on `subscription.renewed`. The two share the mint order id: `order_id` there is `mint_order_id` here |
879
+ | Did a refund end the subscription? | `subscription_canceled` on `subscription.refunded`, and the `subscription.canceled` sent with it (`cancel_cause: "full_refund"`; the two are sent together and may arrive in any order) |
880
+
881
+ If a card renewal's charge succeeds but INVO cannot finish the renewal in the same step, you may see `subscription.payment_failed` with a settlement `failure_code` (for example `settlement_error`); the retry then completes the period **without charging the card again**, and `subscription.renewed` follows.
856
882
 
857
883
  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.
858
884
 
@@ -873,27 +899,53 @@ const a = await server.subscriptions.changeAmount(id, "14.99");
873
899
  // Sending the current price clears a staged change. More than double, or above 25000.00, stays pending forever.
874
900
 
875
901
  await server.subscriptions.setPaymentMethod(id, { playerCardId: 43 }); // used from the next charge, incl. a pending retry
876
- await server.subscriptions.setPaymentMethod(id, { playerCardId: 43, walletOnly: false }); // convert a wallet-only subscription back
877
- await server.subscriptions.setPaymentMethod(id, { walletOnly: true }); // stop charging a card until you flip it back
902
+ await server.subscriptions.setPaymentMethod(id, { playerCardId: 43, walletOnly: false }); // convert a wallet-only subscription back (do this for any you have)
903
+ // setPaymentMethod(id, { walletOnly: true }) still works but is DEPRECATED: the subscription can then never be paid
878
904
  ```
879
905
 
880
906
  ### Refunds
881
907
 
882
908
  ```ts
883
- const receipt = await server.subscriptions.refund(id, {
909
+ import { isRefundPendingApproval } from "@invonetwork/web-sdk/server";
910
+
911
+ const r = await server.subscriptions.refund(id, {
884
912
  clientRequestId: "refund-2026-11-guild-42-member-7", // one per refund; reuse it on retries (the receipt replays)
885
913
  // periodSeq: 2, // default: the most recent billed period
886
914
  // amountUsd: "4.00", // default: the full remaining refundable amount
887
- reason: "member request",
915
+ reason: "member request", // recommended now, required after a notice period
888
916
  });
889
- // receipt.isFullRefund, receipt.fundingShape ("wallet" | "card" | "mixed"), receipt.cardRefundedUsd,
890
- // receipt.balanceDeltaCoins (signed: coins the card charge minted are taken back; can go negative),
891
- // receipt.partnerRevenueReversedUsd (your revenue reversed; INVO's fee is retained),
892
- // receipt.revenueShareAttribution?.netAttributedAmountUsd (the corrected figure to pay your recipient),
893
- // receipt.idempotentReplay === true on a repeat.
917
+ if (isRefundPendingApproval(r)) { // narrows r; status === "pending_approval"
918
+ // Over the game's daily self-serve limit: NOTHING moved. INVO reviews request r.requestId.
919
+ // Wait for subscription.refund_approved (sent with subscription.refunded) or subscription.refund_rejected.
920
+ await markRefundPending(r.requestId, r.requestedAmountUsd);
921
+ } else {
922
+ // r.status === "refunded". r.isFullRefund, r.fundingShape ("card" for every card period since 2026-09-17),
923
+ // r.cardRefundedUsd (card-only periods: equals the amount, partial included), r.balanceDeltaCoins,
924
+ // r.partnerRevenueReversedUsd (your revenue reversed; INVO's fee is retained),
925
+ // r.processingFeeUsd (the card processor fee you bear), r.partnerTotalReversedUsd (the two together),
926
+ // r.subscriptionCanceled (a full refund cancels the subscription), r.idempotentReplay on a repeat,
927
+ // r.revenueShareAttribution?.netAttributedAmountUsd (the corrected figure to pay your recipient).
928
+ }
929
+ for (const w of r.warnings ?? []) log(w.code); // "REASON_RECOMMENDED" | "REASON_TRUNCATED"
894
930
  ```
895
931
 
896
- A full refund returns the whole card charge for that period and reclaims the coins that charge minted; a partial refund credits the wallet in coins at the 10:1 peg. A fully refunded period no longer counts toward `paidThrough`; **the subscription itself is not cancelled** (cancel it separately if that is what the member wants). **Refunds of periods charged through Steam are not supported yet**: `409 STEAM_REFUND_NOT_SUPPORTED` (`err.isSteamRefundNotSupported`); periods of a Steam subscription that the wallet covered entirely are refundable in coins.
932
+ **What is refunded.** A card subscription is card only (since 2026-09-17), so its period is refunded **in cash, full or partial**: the amount goes back to the card (`cardRefundedUsd` equals the amount, `balanceDeltaCoins` is `"0.00"`), and partials plus the refund that completes them add up to exactly the card charge. A period charged **before** 2026-09-17, or a Steam period the wallet covered, keeps the earlier rule: a full refund returns the whole card charge and reclaims the coins that charge minted (`balanceDeltaCoins` is signed and can go negative), a partial refund credits coins at the currency's rate (10 coins per USD by default). A fully refunded period no longer counts toward `paidThrough`.
933
+
934
+ **What else happens.**
935
+
936
+ - **A full refund cancels the subscription** immediately (`subscriptionCanceled: true`, `subscriptionStatus: "canceled"`), and you receive `subscription.canceled` (`canceled_by: "partner"`, `cancel_cause: "full_refund"`) together with `subscription.refunded`; the two are sent together and may arrive in any order. A partial refund leaves it live. Before 2026-09-17 a full refund did not cancel.
937
+ - **You bear the card processor fee** on any refund that returns money to a card: `processingFeeUsd` (`processingFeeBasis` `actual` or `estimated`, `processingFeeBorneBy: "partner"`) is deducted from your revenue as its own line. `partnerTotalReversedUsd` is your revenue reversed plus that fee. A coin refund has no fee.
938
+ - **INVO emails the member** when a refund executes (the amount, where it went, and whether the subscription ended). Your `reason` is not in that email.
939
+ - **Refunds of periods charged through Steam are not supported yet**: `409 STEAM_REFUND_NOT_SUPPORTED` (`err.isSteamRefundNotSupported`); periods of a Steam subscription that the wallet covered entirely are refundable in coins.
940
+
941
+ **Limits.** Self-serve refunds run inside four limits:
942
+
943
+ 1. **Enabled per game.** On by default for every game; INVO can turn them off for a game (`403 REFUNDS_NOT_ENABLED`, `err.isRefundsNotEnabled`).
944
+ 2. **30 days.** A period can be refunded for 30 days after it was charged (`409 REFUND_WINDOW_CLOSED`, `err.isRefundWindowClosed`, with `err.periodChargedAt`, `err.refundWindowDays`, `err.refundWindowClosedAt`). A retry of a refund that already ran still returns its receipt.
945
+ 3. **A daily limit per game** (per UTC day; $500 by default in sandbox and production, adjustable by INVO). A refund that would exceed it does **not** run: the call answers HTTP 202 with `status: "pending_approval"` and `requestId` (check with `isRefundPendingApproval(r)`), carrying every receipt field with nothing moved, and INVO reviews the request. Approved: the refund runs as if your call had (the 30 days count from when you asked), you receive `subscription.refunded`, `subscription.refund_approved` and, for a full refund, `subscription.canceled`, sent together and may arrive in any order, and a retry of your key returns the receipt. Rejected: you receive `subscription.refund_rejected` with `decision_reason`, and your key throws `409 REFUND_REQUEST_REJECTED` (`err.isRefundRequestRejected`); use a new key to try again. While a request is pending, other refunds of that period throw `409 REFUND_REQUEST_PENDING` (`err.isRefundRequestPending`, the id on `err.refundRequestId`). The same key returns the same 202 with `idempotentReplay: true`.
946
+ 4. **A reason.** Recommended now, required after a notice period. Without it the refund still runs (`reason: null`) and `warnings` carries `REASON_RECOMMENDED`; a reason longer than 500 characters is cut, with `REASON_TRUNCATED` (the SDK refuses one over 500 before the network).
947
+
948
+ Your developer console session can list your refund requests (`GET /api/dev/subscriptions/refund-requests?status=pending|approved|rejected|all`); that console read is not wrapped by this SDK, which authenticates with the game key.
897
949
 
898
950
  ### Sandbox: the clock tools
899
951
 
@@ -918,7 +970,7 @@ await sb.forceAuthChallenge(id); // moves it to awaiting_authenticati
918
970
  >
919
971
  > **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.
920
972
 
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.
973
+ **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 (a full refund cancels the subscription, so refund a partial amount first if you want to keep testing it; the $500 daily limit applies in sandbox too, and a refund over it answers `pending_approval`); and create one with `trialDays: 7` to see `skipped_trial` convert.
922
974
 
923
975
  **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"`.
924
976
 
@@ -940,10 +992,16 @@ Match on `err.code` (and on `body.status` where the body carries one), never on
940
992
  | `.isNotAuthorized` | (409) `steamFinalize` before the member authorised. The normal wait state: call it again |
941
993
  | `.isSteamRefundNotSupported` | (409) `refund` on a period charged through Steam |
942
994
  | `.isAlreadyRefunded` | (409) the period was already refunded; treat as done |
995
+ | `.isRefundsNotEnabled` | (403) refunds are turned off for this game; contact INVO |
996
+ | `.isRefundWindowClosed` + `.periodChargedAt` / `.refundWindowDays` / `.refundWindowClosedAt` | (409) the period was charged more than 30 days ago |
997
+ | `.isRefundRequestPending` + `.refundRequestId` | (409) a refund request for this period is waiting for INVO's review |
998
+ | `.isRefundRequestRejected` + `.refundRequestId` / `.decisionReason` | (409) this key was a refund request INVO rejected; use a new key to try again |
999
+ | `.isConcurrentRequest` | (409) two requests collided (two creates for a new player, or two refund requests for one period); retry with the **same** key |
1000
+ | `.isRefundMismatch` | (502) a card refund needs manual reconciliation; contact INVO, do not retry-loop |
943
1001
  | `.isSandboxClockUnauthorized` | (401) missing/wrong `X-Sandbox-Clock-Key`; reveal it in the sandbox console |
944
1002
  | `.isPhoneShareApprovalRequired` | (409) the supplied `playerPhone` belongs to another identity; run the phone-share flow, then retry |
945
1003
  | `PAYMENT_METHOD_NOT_FOUND` / `PAYMENT_METHOD_EXPIRED` / `PAYMENT_METHOD_INVALID` | the card is not this player's in this game, is expired, or the id is malformed |
946
- | `WALLET_ONLY_SUBSCRIPTION` / `WALLET_ONLY_CONFLICT` | `walletOnly: true` with a card; or a wallet-only subscription needs `walletOnly: false` beside the new card |
1004
+ | `WALLET_ONLY_SUBSCRIPTION` / `WALLET_ONLY_CONFLICT` | `walletOnly: true` with a card; or a wallet-only subscription needs `walletOnly: false` beside the new card (`walletOnly` is deprecated: such a subscription can never be paid) |
947
1005
  | `NO_PAID_PERIOD` / `PERIOD_NOT_REFUNDABLE` / `AMOUNT_EXCEEDS_REMAINING` | refund refusals (the last carries `remaining_refundable_usd`) |
948
1006
  | `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 |
949
1007
  | `.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`) |
@@ -958,6 +1016,9 @@ Client-side guards (missing key, a `sub_`-prefixed key, a bad amount, a non-E.16
958
1016
  3. **`pending` is not `failed`.** Wait for the event; INVO resolves it.
959
1017
  4. **`currentPeriodEnd` is not entitlement.** Use `paidThrough`.
960
1018
  5. **`payment_failed` and `past_due` do not revoke access.** Only `expired` (at `final_period_end`) and `canceled` (at `access_until`) do.
1019
+ 6. **Coins never pay a card subscription.** Save a card before `create`; a member without one fails with `no_payment_method` whatever their balance.
1020
+ 7. **A renewal's `purchase.completed` is not a purchase.** Skip it when `data.metadata.source === "subscription_renewal"`; grant on `subscription.renewed`.
1021
+ 8. **`pending_approval` is not `refunded`.** Nothing moved (`isRefundPendingApproval(r)`); wait for `subscription.refund_approved` or `subscription.refund_rejected`.
961
1022
  6. **`authentication_required` is not a failure.** Send the link, not a "payment failed" message.
962
1023
  7. **Do not poll for renewals.** Handle `subscription.renewed`.
963
1024
  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`.
@@ -1783,7 +1844,7 @@ export const POST = createWebhookHandler({
1783
1844
 
1784
1845
  | Event | Fires for | Use it to |
1785
1846
  |---|---|---|
1786
- | `purchase.completed` | every currency-purchase rail | grant currency (payload: `transaction_id, order_id, player_email, identity_id, usd_amount, currency_amount, currency_name, new_balance, rail`, `metadata`) — `metadata` echoes what you passed to `createCheckout`/`purchaseCurrency` (all rails); `order_id` is also on every webhook as a secondary reconciliation key (`getOrderDetails`). |
1847
+ | `purchase.completed` | every currency-purchase rail, **and every paid card subscription renewal** | grant currency (payload: `transaction_id, order_id, player_email, identity_id, usd_amount, currency_amount, currency_name, new_balance, rail`, `metadata`) — `metadata` echoes what you passed to `createCheckout`/`purchaseCurrency` (all rails); `order_id` is also on every webhook as a secondary reconciliation key (`getOrderDetails`). **Skip it when `metadata.source` is `"subscription_renewal"`**: those coins are spent by the renewal itself; grant on `subscription.renewed`. |
1787
1848
  | `purchase.failed` / `purchase.disputed` | `platform` rail only | handle failures/disputes |
1788
1849
  | `purchase.refunded` | `game` / `steam` rails | handle refunds |
1789
1850
  | `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`) |
@@ -1792,9 +1853,10 @@ export const POST = createWebhookHandler({
1792
1853
  | `subscription.renewed` | every successfully charged subscription period, **including period 1** | **extend access** to `period_end` (the new `paid_through`) — the source of truth for entitlement (payload: `subscription_id, item_id, period_seq, transaction_id, order_id, mint_order_id, player_email, identity_id, amount_usd, amount_coins, period_start, period_end, current_period_*, next_charge_at, funding { rail, balance_applied_coins, card_charged_usd, steam_charged_usd, minted_coins, new_balance }, split { basis, total_usd, invo_fee_usd, partner_revenue_usd, … }, revenue_share_attribution, metadata`) |
1793
1854
  | `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`) |
1794
1855
  | `subscription.authentication_required` | a card issuer wants the cardholder to authenticate (card rail) | **not a failure** — relay `confirmation_url` before `expires_at` |
1795
- | `subscription.canceled` | a cancel request (yours, or the member's from Steam: `canceled_by`) | revoke at `access_until` |
1856
+ | `subscription.canceled` | a cancel request (yours, or the member's from Steam: `canceled_by`), or a full refund (`cancel_cause: "full_refund"`) | revoke at `access_until` |
1796
1857
  | `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) |
1797
- | `subscription.refunded` | a period refund | record the reversal (`refund.partner_revenue_reversed_usd`, `is_full_refund`, `revenue_share_attribution`) |
1858
+ | `subscription.refunded` | a period refund | record the reversal (`refund.partner_total_reversed_usd` = revenue reversed plus the card processor fee you bear, `refund.partner_revenue_reversed_usd`, `refund.processing_fee_usd`, `is_full_refund`, `subscription_canceled`, `initiation`, `refund_request_id`, `revenue_share_attribution`) |
1859
+ | `subscription.refund_requested` / `subscription.refund_approved` / `subscription.refund_rejected` | a refund over the game's daily self-serve limit became a request / INVO approved it (sent together with `subscription.refunded`, and `subscription.canceled` on a full refund, in any order) / INVO rejected it | track the request (`request_id, status, subscription_id, item_id, period_seq, client_request_id, amount_usd, reason, requested_at, daily_cap_usd, executed_today_usd, player_email, identity_id, metadata`; approved adds `decided_at, transaction_id`; rejected adds `decided_at, decision_reason`) |
1798
1860
  | `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 |
1799
1861
 
1800
1862
  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.
@@ -1887,7 +1949,7 @@ Helpers:
1887
1949
  | `.isPhoneShareAlreadyApproved` | phone-share was already approved (e.g. from a `/reject`) |
1888
1950
  | `.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 |
1889
1951
  | `.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 |
1890
- | `.isActiveSubscriptionExists` / `.isIdempotentReplayMismatch` / `.isSubscriptionTerminal` / `.isSteamReauthorizationRequired` / `.isNotACardSubscription` / `.isSteamChannelRequired` / `.isNotAuthorized` / `.isSteamRefundNotSupported` / `.isSandboxClockUnauthorized` / `.isFlowPaused` / `.isGameNotLive` | the subscription refusals — see [Subscriptions → Errors](#subscription-errors) |
1952
+ | `.isActiveSubscriptionExists` / `.isIdempotentReplayMismatch` / `.isSubscriptionTerminal` / `.isSteamReauthorizationRequired` / `.isNotACardSubscription` / `.isSteamChannelRequired` / `.isNotAuthorized` / `.isSteamRefundNotSupported` / `.isRefundsNotEnabled` / `.isRefundWindowClosed` / `.isRefundRequestPending` / `.isRefundRequestRejected` / `.isConcurrentRequest` / `.isRefundMismatch` / `.isSandboxClockUnauthorized` / `.isFlowPaused` / `.isGameNotLive` | the subscription refusals — see [Subscriptions → Errors](#subscription-errors) |
1891
1953
  | `.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) |
1892
1954
 
1893
1955
  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`.
@@ -1930,7 +1992,7 @@ try {
1930
1992
  | `subscriptions.cancel(id, { atPeriodEnd?, reason? })` | `CancelResult` — `{ alreadyCanceled, cancelAtPeriodEnd, terminatedImmediately, effectiveAt, accessUntil, paidThrough, subscription, raw }`; an already-terminal row is a 200 with `alreadyCanceled: true` |
1931
1993
  | `subscriptions.changeAmount(id, amountUsd)` | `ChangeAmountResult` — `{ oldAmountUsd, newAmountUsd, pendingAmountUsd, changeQueued, appliesFrom, appliesFromPeriodSeq, prorated, subscription, raw }`; staged for the next renewal (Steam: increases throw `isSteamReauthorizationRequired`) |
1932
1994
  | `subscriptions.setPaymentMethod(id, { playerCardId, walletOnly? } \| { walletOnly: true })` | `{ status, replaced, walletOnly, card, subscription, raw }` — card rail only (`isNotACardSubscription` on Steam) |
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` |
1995
+ | `subscriptions.refund(id, { clientRequestId, periodSeq?, amountUsd?, reason? })` | `RefundResult` (one interface; branch with `isRefundPendingApproval(r)`): `status: "refunded"` (the receipt: `isFullRefund, fundingShape, balanceDeltaCoins, cardRefundedUsd, partnerRevenueReversedUsd, revenueShareAttribution, idempotentReplay`, plus `subscriptionCanceled, subscriptionStatus, processingFeeUsd, processingFeeBasis, partnerTotalReversedUsd, initiation, refundRequestId, warnings?, raw`) or `"pending_approval"` (HTTP 202, over the daily limit, nothing moved: the same fields plus `requestId, requestStatus, requestedAmountUsd, requestedAt, dailyCapUsd, executedTodayUsd, message`, required on the narrowed `RefundPendingApproval`); idempotent on `clientRequestId` (a replay, `idempotentReplay: true`, never carries `newBalance` or `revenueShareAttribution`); a full refund cancels the subscription; Steam-charged periods throw `isSteamRefundNotSupported` |
1934
1996
  | `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` |
1935
1997
  | `subscriptions.steamFinalize(subscriptionId)` | `SteamFinalizeSubscriptionResult` — the `SubscriptionResult` plus `{ alreadyProcessed, steamAgreementStatus, sandboxAutoApproved }`; `isNotAuthorized` (409) is the normal wait state |
1936
1998
  | `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` |
@@ -530,6 +530,82 @@ var InvoError = class _InvoError extends Error {
530
530
  get isSteamRefundNotSupported() {
531
531
  return this.code === "STEAM_REFUND_NOT_SUPPORTED";
532
532
  }
533
+ /**
534
+ * True when `subscriptions.refund` was refused because refunds are turned off for this
535
+ * game (`REFUNDS_NOT_ENABLED`, 403). Refunds are on by default for every game; INVO turns
536
+ * them off per game. Contact INVO.
537
+ */
538
+ get isRefundsNotEnabled() {
539
+ return this.code === "REFUNDS_NOT_ENABLED";
540
+ }
541
+ /**
542
+ * True when `subscriptions.refund` targeted a period charged more than 30 days ago
543
+ * (`REFUND_WINDOW_CLOSED`, 409). See `periodChargedAt`, `refundWindowDays` and
544
+ * `refundWindowClosedAt`. A retry of a refund that already ran still returns its receipt.
545
+ */
546
+ get isRefundWindowClosed() {
547
+ return this.code === "REFUND_WINDOW_CLOSED";
548
+ }
549
+ /**
550
+ * True when a refund request for this period is waiting for INVO's review
551
+ * (`REFUND_REQUEST_PENDING`, 409). No other refund of the period can run until it is
552
+ * decided. The request id is on `refundRequestId`.
553
+ */
554
+ get isRefundRequestPending() {
555
+ return this.code === "REFUND_REQUEST_PENDING";
556
+ }
557
+ /**
558
+ * True when this `clientRequestId` was filed as a refund request and INVO rejected it
559
+ * (`REFUND_REQUEST_REJECTED`, 409). See `refundRequestId` and `decisionReason`. To try
560
+ * again use a NEW `clientRequestId`.
561
+ */
562
+ get isRefundRequestRejected() {
563
+ return this.code === "REFUND_REQUEST_REJECTED";
564
+ }
565
+ /**
566
+ * True when two requests collided (`CONCURRENT_REQUEST`, 409): two creates for a
567
+ * brand-new player, or two refund requests for one period filed at the same moment.
568
+ * Retry with the SAME key.
569
+ */
570
+ get isConcurrentRequest() {
571
+ return this.code === "CONCURRENT_REQUEST";
572
+ }
573
+ /**
574
+ * True when a subscription refund needs manual reconciliation (`REFUND_MISMATCH`, 502):
575
+ * the card processor already holds a refund for this request with a different amount, or
576
+ * the charge was already fully refunded outside this flow. Contact INVO; do not retry-loop.
577
+ */
578
+ get isRefundMismatch() {
579
+ return this.code === "REFUND_MISMATCH";
580
+ }
581
+ /**
582
+ * The refund request id (`request_id`) on `REFUND_REQUEST_PENDING` and
583
+ * `REFUND_REQUEST_REJECTED`. Not the backend request id, which is {@link requestId}.
584
+ */
585
+ get refundRequestId() {
586
+ const v = this.bodyObject()["request_id"];
587
+ return typeof v === "string" && v ? v : void 0;
588
+ }
589
+ /** INVO's reason on `REFUND_REQUEST_REJECTED` (may be absent). */
590
+ get decisionReason() {
591
+ const v = this.bodyObject()["decision_reason"];
592
+ return typeof v === "string" && v ? v : void 0;
593
+ }
594
+ /** On `REFUND_WINDOW_CLOSED`: when the period was charged (ISO 8601). */
595
+ get periodChargedAt() {
596
+ const v = this.bodyObject()["period_charged_at"];
597
+ return typeof v === "string" && v ? v : void 0;
598
+ }
599
+ /** On `REFUND_WINDOW_CLOSED`: the window length in days (30). */
600
+ get refundWindowDays() {
601
+ const v = this.bodyObject()["refund_window_days"];
602
+ return typeof v === "number" && Number.isFinite(v) ? v : void 0;
603
+ }
604
+ /** On `REFUND_WINDOW_CLOSED`: when the window closed (ISO 8601). */
605
+ get refundWindowClosedAt() {
606
+ const v = this.bodyObject()["window_closed_at"];
607
+ return typeof v === "string" && v ? v : void 0;
608
+ }
533
609
  /** True when the subscription is `canceled` or `expired` and the call cannot apply (`SUBSCRIPTION_TERMINAL`, 409). Start a new one. */
534
610
  get isSubscriptionTerminal() {
535
611
  return this.code === "SUBSCRIPTION_TERMINAL";
@@ -874,5 +950,5 @@ function toDestinationsResult(raw, direction) {
874
950
  }
875
951
 
876
952
  export { Http, InvoError, assertSecureBaseUrl, toDestinationsResult };
877
- //# sourceMappingURL=chunk-NB6UF657.js.map
878
- //# sourceMappingURL=chunk-NB6UF657.js.map
953
+ //# sourceMappingURL=chunk-L4A6OV54.js.map
954
+ //# sourceMappingURL=chunk-L4A6OV54.js.map
package/dist/index.cjs CHANGED
@@ -532,6 +532,82 @@ var InvoError = class _InvoError extends Error {
532
532
  get isSteamRefundNotSupported() {
533
533
  return this.code === "STEAM_REFUND_NOT_SUPPORTED";
534
534
  }
535
+ /**
536
+ * True when `subscriptions.refund` was refused because refunds are turned off for this
537
+ * game (`REFUNDS_NOT_ENABLED`, 403). Refunds are on by default for every game; INVO turns
538
+ * them off per game. Contact INVO.
539
+ */
540
+ get isRefundsNotEnabled() {
541
+ return this.code === "REFUNDS_NOT_ENABLED";
542
+ }
543
+ /**
544
+ * True when `subscriptions.refund` targeted a period charged more than 30 days ago
545
+ * (`REFUND_WINDOW_CLOSED`, 409). See `periodChargedAt`, `refundWindowDays` and
546
+ * `refundWindowClosedAt`. A retry of a refund that already ran still returns its receipt.
547
+ */
548
+ get isRefundWindowClosed() {
549
+ return this.code === "REFUND_WINDOW_CLOSED";
550
+ }
551
+ /**
552
+ * True when a refund request for this period is waiting for INVO's review
553
+ * (`REFUND_REQUEST_PENDING`, 409). No other refund of the period can run until it is
554
+ * decided. The request id is on `refundRequestId`.
555
+ */
556
+ get isRefundRequestPending() {
557
+ return this.code === "REFUND_REQUEST_PENDING";
558
+ }
559
+ /**
560
+ * True when this `clientRequestId` was filed as a refund request and INVO rejected it
561
+ * (`REFUND_REQUEST_REJECTED`, 409). See `refundRequestId` and `decisionReason`. To try
562
+ * again use a NEW `clientRequestId`.
563
+ */
564
+ get isRefundRequestRejected() {
565
+ return this.code === "REFUND_REQUEST_REJECTED";
566
+ }
567
+ /**
568
+ * True when two requests collided (`CONCURRENT_REQUEST`, 409): two creates for a
569
+ * brand-new player, or two refund requests for one period filed at the same moment.
570
+ * Retry with the SAME key.
571
+ */
572
+ get isConcurrentRequest() {
573
+ return this.code === "CONCURRENT_REQUEST";
574
+ }
575
+ /**
576
+ * True when a subscription refund needs manual reconciliation (`REFUND_MISMATCH`, 502):
577
+ * the card processor already holds a refund for this request with a different amount, or
578
+ * the charge was already fully refunded outside this flow. Contact INVO; do not retry-loop.
579
+ */
580
+ get isRefundMismatch() {
581
+ return this.code === "REFUND_MISMATCH";
582
+ }
583
+ /**
584
+ * The refund request id (`request_id`) on `REFUND_REQUEST_PENDING` and
585
+ * `REFUND_REQUEST_REJECTED`. Not the backend request id, which is {@link requestId}.
586
+ */
587
+ get refundRequestId() {
588
+ const v = this.bodyObject()["request_id"];
589
+ return typeof v === "string" && v ? v : void 0;
590
+ }
591
+ /** INVO's reason on `REFUND_REQUEST_REJECTED` (may be absent). */
592
+ get decisionReason() {
593
+ const v = this.bodyObject()["decision_reason"];
594
+ return typeof v === "string" && v ? v : void 0;
595
+ }
596
+ /** On `REFUND_WINDOW_CLOSED`: when the period was charged (ISO 8601). */
597
+ get periodChargedAt() {
598
+ const v = this.bodyObject()["period_charged_at"];
599
+ return typeof v === "string" && v ? v : void 0;
600
+ }
601
+ /** On `REFUND_WINDOW_CLOSED`: the window length in days (30). */
602
+ get refundWindowDays() {
603
+ const v = this.bodyObject()["refund_window_days"];
604
+ return typeof v === "number" && Number.isFinite(v) ? v : void 0;
605
+ }
606
+ /** On `REFUND_WINDOW_CLOSED`: when the window closed (ISO 8601). */
607
+ get refundWindowClosedAt() {
608
+ const v = this.bodyObject()["window_closed_at"];
609
+ return typeof v === "string" && v ? v : void 0;
610
+ }
535
611
  /** True when the subscription is `canceled` or `expired` and the call cannot apply (`SUBSCRIPTION_TERMINAL`, 409). Start a new one. */
536
612
  get isSubscriptionTerminal() {
537
613
  return this.code === "SUBSCRIPTION_TERMINAL";
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-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';
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-CBxpXgAM.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-CBxpXgAM.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-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';
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-CBxpXgAM.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-CBxpXgAM.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-NB6UF657.js';
2
- export { InvoError } from './chunk-NB6UF657.js';
1
+ import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult } from './chunk-L4A6OV54.js';
2
+ export { InvoError } from './chunk-L4A6OV54.js';
3
3
 
4
4
  // src/shared/webauthn.ts
5
5
  function malformedOptions(field) {