@invonetwork/web-sdk 3.12.1 → 3.13.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,26 @@
1
1
  # Changelog
2
2
 
3
+ ## 3.13.0
4
+
5
+ ### Minor Changes
6
+
7
+ - INVO's card fee on coin purchases, paid trials, and the two tiers.
8
+
9
+ **Coin purchases carry INVO's card fee: 3.5% + $0.30** of the price (on the Open tier), never less than the card cost. `purchaseCurrency` charges in the same request, so there are now two shapes and you pick one by what you send:
10
+
11
+ - **Quote, show, acknowledge.** New `server.quoteCurrencyPurchase({ playerEmail, usdAmount, country?, subdivision? })` calls `POST /api/currency-purchases/quote`. It moves no money and creates nothing, and returns `totalUsd`, `amountCents`, `subtotalUsd`, `processingFeeUsd`, `coins`, `currencyName`, a camelCase `breakdown` and `ifUnacknowledged`. Show the player `totalUsd`, then pass it as the new optional `acknowledgedTotalUsd` on `purchaseCurrency`: the card is charged that total, to the cent, and the coins are priced off `usdAmount`. $10.00 quotes $10.65.
12
+ - **Send only `usdAmount`.** The card is charged exactly `usdAmount`, never more, and the fee comes out of the coins: $10.00 credits 93.70 coins at the default 10 per USD.
13
+
14
+ A `success` result now also carries `processingFeeUsd`, `feeTakenFrom` (`"charge"` or `"coins"`), `coinsCredited` and `chargeTotalUsd`. New error helpers: `err.isQuoteStale` (409 `QUOTE_STALE`, with `err.expectedTotalUsd` and `err.acknowledgedTotalUsd`) and `err.isAmountBelowFee` (400 `AMOUNT_BELOW_FEE`). Nothing is charged on either. `acknowledgedTotalUsd` is shape-checked locally (a positive two-decimal amount) with a ceiling above the largest price, because the fee rides above INVO's card maximum.
15
+
16
+ **Refunds of coin purchases:** only unspent coins are refundable; spent coins are never refunded. Documented; no SDK call refunds a coin purchase.
17
+
18
+ **Paid trials on card subscriptions.** `subscriptions.create` accepts `trialAmountUsd` (with `trialDays` or `trialEnd`, card only, at least 0.50 and less than `amountUsd`): period 1 is charged the trial price inside the call and `amountUsd` from period 2. The consent object accepts `disclosedTrialAmountUsd`, `disclosedTrialDays` and `disclosedTrialEnd`, and returns `disclosed_trial_amount_usd`, `disclosed_trial_days` and `disclosed_trial_end`. The subscription gains `trialAmountUsd` and, on create and finalize bodies, `trialAmountCoinsEstimate`. Webhook types: `is_trial` on `subscription.renewed`; `is_trial` and `trial_amount_usd` on the trial period's `payment_failed`, `past_due`, `authentication_required` and `expired` (new `SubscriptionTrialEventFields`); `expire_cause` (`"trial_payment_failed"`) on `subscription.expired`. New error helpers: `isPaymentMethodRequired`, `isTrialAmountInvalid`, `isTrialAmountRequiresTrial`, `isTrialAmountNotSupportedForFunding`, `isConsentDisclosedTrialInvalid`. The SDK refuses, before the network and with INVO's own codes, a `trialAmountUsd` without a trial, with `walletOnly: true`, or on `steamInit`; the $0.50 floor and the "less than `amountUsd`" rule are left to INVO.
19
+
20
+ **README:** a new Tiers section (Open by default: you are the seller and handle tax; Merchant of Record by application: INVO is the seller and handles tax; fees per tier), the coin fee flow, the refund rule and paid trials. Every statement that INVO is the merchant of record on the card rail for everyone is removed.
21
+
22
+ All additive: no export was removed, renamed or retyped, and every new field on an existing type is optional.
23
+
3
24
  ## 3.12.1
4
25
 
5
26
  ### Patch 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.11.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.11.0** adds the **[purchase status read](#did-the-purchase-go-through-the-status-read)**, where `invo.checkout.getPurchaseStatus()` / `waitForPurchase()` (and the standalone `CheckoutClient`) answer what happened to a hosted-checkout purchase in six words, four of them terminal, so a buyer is never shown a page that closes on nothing; stopping is decided by INVO's `terminal` and never re-derived from `status`, `nothingWasCharged()` says when a **Try again** is safe, `createCheckout()` now also returns `sessionToken`, and the subscription fee is corrected to **7% + $0.30** (it is its own rate; item purchases stay at 10/90); **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).
5
+ > **Status:** `v3.13.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.13.0** documents the two **[tiers](#tiers)** (Open by default, Merchant of Record by application), adds **[INVO's card fee on coin purchases](#invos-card-fee-quote-show-acknowledge)** (3.5% + $0.30): `quoteCurrencyPurchase()`, `acknowledgedTotalUsd` on `purchaseCurrency()`, the new `processingFeeUsd` / `feeTakenFrom` / `coinsCredited` / `chargeTotalUsd` fields and `err.isAmountBelowFee` / `err.isQuoteStale`, states the coin refund rule (only unspent coins), and adds **[paid trials](#paid-trials)** on card subscriptions (`trialAmountUsd`, the disclosed trial consent fields, `is_trial` / `expire_cause` on the events, `err.isPaymentMethodRequired` and the `isTrialAmount*` helpers); **3.12.0** removes the SDK's own card maximum (INVO's is a runtime setting, $100,000.00 by default); **3.11.0** adds the **[purchase status read](#did-the-purchase-go-through-the-status-read)**, where `invo.checkout.getPurchaseStatus()` / `waitForPurchase()` (and the standalone `CheckoutClient`) answer what happened to a hosted-checkout purchase in six words, four of them terminal, so a buyer is never shown a page that closes on nothing; stopping is decided by INVO's `terminal` and never re-derived from `status`, `nothingWasCharged()` says when a **Try again** is safe, `createCheckout()` now also returns `sessionToken`, and the subscription fee is corrected to **7% + $0.30** (it is its own rate; item purchases stay at 10/90); **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
@@ -20,7 +20,7 @@ Six money flows plus passkey (WebAuthn) authentication, split across a trusted s
20
20
 
21
21
  > **Item purchase vs Platform Commerce — don't mix them up.** They share a body shape (`itemId`, `unitPrice`, `totalPrice`, `clientRequestId`) but are different products:
22
22
  > - **[Item purchase](#item-purchase-spend-game-currency)** — a **game** tenant. A player spends **game currency they already hold** on an **in-game** item (a sword, a skin). Always a balance debit — **never a card, never new money, no refunds**. `server.purchaseItem(...)` → `/api/item-purchases`.
23
- > - **[Platform Commerce](#platform-commerce-ecommerce)** — a **platform** tenant (a non-game app: vertical video, creator merch, marketplace). A **storefront** sale funded by **INVO balance or a real card** (new money), with **INVO as merchant of record** and **refunds**. `server.platformCommerce.purchase(...)` → `/api/platform-commerce`. A game tenant calling it gets `403 NOT_A_PLATFORM_TENANT`.
23
+ > - **[Platform Commerce](#platform-commerce-ecommerce)** — a **platform** tenant (a non-game app: vertical video, creator merch, marketplace). A **storefront** sale funded by **INVO balance or a real card** (new money), with **refunds**. Who is the seller of record depends on your [tier](#tiers). `server.platformCommerce.purchase(...)` → `/api/platform-commerce`. A game tenant calling it gets `403 NOT_A_PLATFORM_TENANT`.
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
 
@@ -95,13 +95,17 @@ The right approval method is a property of the **client the player is sitting in
95
95
  - [Architecture & the two entry points](#architecture--the-two-entry-points)
96
96
  - [Before you go live](#before-you-go-live)
97
97
  - [Configuration](#configuration)
98
+ - [Tiers](#tiers)
98
99
  - [Currency purchase (real money in)](#currency-purchase-real-money-in)
99
100
  - [The card maximum is INVO's, not the SDK's](#the-card-maximum-is-invos-not-the-sdks)
101
+ - [INVO's card fee: quote, show, acknowledge](#invos-card-fee-quote-show-acknowledge)
102
+ - [Refunds of coin purchases](#refunds-of-coin-purchases)
100
103
  - [Did the purchase go through? (the status read)](#did-the-purchase-go-through-the-status-read)
101
104
  - [Item purchase (spend game currency)](#item-purchase-spend-game-currency)
102
105
  - [Platform Commerce (ecommerce)](#platform-commerce-ecommerce)
103
106
  - [Subscriptions (recurring billing)](#subscriptions-recurring-billing)
104
107
  - [Cards for subscriptions](#cards-for-subscriptions)
108
+ - [Paid trials](#paid-trials)
105
109
  - [Subscription packages](#subscription-packages)
106
110
  - [Player balance](#player-balance)
107
111
  - [Sends & transfers (move currency between players)](#sends--transfers-move-currency-between-players)
@@ -282,13 +286,28 @@ const client = new InvoClient({
282
286
 
283
287
  ---
284
288
 
289
+ ## Tiers
290
+
291
+ Every INVO developer account is on one of two tiers. The SDK calls are the same on both; what differs is who the seller is, who handles tax, and the fees.
292
+
293
+ | | **Open** (default) | **Merchant of Record** (by application) |
294
+ |---|---|---|
295
+ | Who it is for | every account, including all current ones | accounts INVO has approved |
296
+ | Who the seller is | **you** | **INVO** |
297
+ | Tax on sales | **you** are responsible for it; INVO collects none | **INVO** calculates, collects and remits it |
298
+ | Card purchase of coins | 3.5% + $0.30 | 5% + $0.30 |
299
+ | Subscriptions | 7% + $0.30 per card charge | 8.5% + $0.30 per card charge |
300
+ | Item purchases (coins spent on an item) | 10% | 10% |
301
+
302
+ On both tiers every card charge runs on INVO's card rail and INVO pays you out, as today. Merchant of Record is applied for per developer account, not per game, and INVO reviews each application. Full details: https://docs.invo.network/docs/tiers/
303
+
285
304
  ## Currency purchase (real money in)
286
305
 
287
306
  Buy game currency with real money. Authenticated by the **payment rail**, not a passkey — there's no WebAuthn step. Two paths:
288
307
 
289
308
  ### The card maximum is INVO's, not the SDK's
290
309
 
291
- **Minimum: $0.50.** That is the card rail's own floor: below it a charge cannot settle at all, so this SDK checks it locally and always will.
310
+ **Minimum: $0.50.** That is the card rail's own floor: below it a charge cannot settle at all. (The SDK checks it locally on the Platform Commerce card leg.) A direct `purchaseCurrency` sent **without** an acknowledged total must also be large enough to carry INVO's card fee, or INVO refuses it before charging anything (`400 AMOUNT_BELOW_FEE`, see [below](#invos-card-fee-quote-show-acknowledge)).
292
311
 
293
312
  **Maximum: an INVO setting, $100,000.00 by default.** It is changed by an INVO admin without a deploy, and it differs between sandbox and production, so **this package does not pin it and never refuses an amount for being too large.** Your amount is sent; INVO decides.
294
313
 
@@ -403,7 +422,7 @@ Rules worth taking literally:
403
422
  - **A failed poll is not a failed purchase.** `waitForPurchase` polls through a dropped connection, a timeout, a 429 and a 5xx; it raises a `401`, `403` or `410` at once (`err.isWrongSessionPurpose`, `err.isCheckoutSessionMismatch`, `err.isCheckoutSessionExpired`).
404
423
  - **Render `message` verbatim and never show `reasonCode` on its own.** The six post-charge refusal codes all read the same to a buyer (they paid and the coins are not there), and the code exists for support to quote. Offer a **Try again** only where `nothingWasCharged(r)` is true (`PAYMENT_DECLINED`, `PAYMENT_CANCELLED`, `expired`); every other refusal happened *after* the card was charged.
405
424
  - **`expired` is not declared the second the link lapses.** A payment made in the last minutes of a checkout can leave no order row until a recovery sweep finds it, so an unpaid checkout reads `pending` for about 30 minutes past expiry. Poll through it.
406
- - **`amountChargedUsd` minus `listedUsd`** is the processing fee the buyer pays on the card rail. A buyer billed 206.29 for a 200 pack will ask; both numbers are here.
425
+ - **`amountChargedUsd` minus `listedUsd`** is INVO's card fee the buyer pays on the card rail (3.5% + $0.30 on the Open tier). A buyer billed 207.30 for a 200 pack will ask; both numbers are here.
407
426
  - **Storefront (in-client) purchases do not reach this read.** Those orders are keyed on your own purchase reference rather than on a checkout session, so a lookup by session id finds nothing and answers `pending`. Do not conclude the purchase never happened.
408
427
  - `newBalance` is `null` once the session is past its expiry: the token rides in the checkout URL, so a stale link must not serve a live wallet. `coinsCredited` and `transactionId`, which are about *this* purchase, still come back.
409
428
 
@@ -570,6 +589,49 @@ const purchase = await server.purchaseCurrency({
570
589
  ```
571
590
  `rail: "steam"` is rejected here (`WRONG_RAIL_ENDPOINT`) — Steam uses its own in-client flow. Reconcile with `server.getOrderDetails({ orderId })`. Most browser integrations should use hosted checkout instead.
572
591
 
592
+ ### INVO's card fee: quote, show, acknowledge
593
+
594
+ A card purchase of coins carries INVO's card fee: **3.5% + $0.30** of the price on the Open [tier](#tiers), never less than the card cost. The hosted checkout adds it to the total on its own page, so there is nothing to do there. `purchaseCurrency` charges in the same request it is called, so it cannot show the buyer anything first. You choose what happens by what you send:
595
+
596
+ - **Quote, show, acknowledge (recommended).** Ask `quoteCurrencyPurchase()` for the total, show the player that total, then send the same figure back as `acknowledgedTotalUsd`. The card is charged that total and the player gets coins for the full price.
597
+ - **Send only `usdAmount`.** The card is charged **exactly `usdAmount`, never more**, and the fee comes out of the coins instead.
598
+
599
+ ```ts
600
+ // 1) SERVER: quote. Moves no money and creates nothing: safe on every price render.
601
+ const q = await server.quoteCurrencyPurchase({
602
+ playerEmail: "p@example.com",
603
+ usdAmount: "10.00",
604
+ // country: "US", subdivision: "NY", // optional: the buyer's billing place, for any tax
605
+ });
606
+ // q.subtotalUsd "10.00" + q.processingFeeUsd "0.65" = q.totalUsd "10.65" (q.coins "100.00")
607
+ // q.breakdown: every line, with taxNote / processingFeeNote sentences you can show as is
608
+ // q.ifUnacknowledged: { chargeTotalUsd: "10.00", processingFeeUsd: "0.63", coins: "93.70", feeTakenFrom: "coins" }
609
+
610
+ // 2) Show the player q.totalUsd ("$10.65"). 3) Charge exactly what they saw:
611
+ const purchase = await server.purchaseCurrency({
612
+ playerEmail: "p@example.com",
613
+ usdAmount: "10.00", // the price; the coins are priced off this
614
+ acknowledgedTotalUsd: q.totalUsd, // "10.65": the card is charged this, to the cent
615
+ purchaseReference: crypto.randomUUID(),
616
+ paymentMethodId: "pm_...",
617
+ });
618
+ // On "success": purchase.chargeTotalUsd "10.65", purchase.processingFeeUsd "0.65",
619
+ // purchase.feeTakenFrom "charge", purchase.coinsCredited "100.00"
620
+ ```
621
+
622
+ The same $10.00 **unacknowledged** charges the card $10.00, takes the $0.63 fee out of the coins and credits **93.70 coins** at the default rate of 10 per USD (`feeTakenFrom: "coins"`). Sending $10.65 unacknowledged buys the same $10.00 of coins as the acknowledged path: the fee is never charged on the fee.
623
+
624
+ | Error | When | What to do |
625
+ |---|---|---|
626
+ | `409 QUOTE_STALE` (`err.isQuoteStale`) | the acknowledged total is not the total INVO would charge now | nothing was charged; quote again, show `err.expectedTotalUsd`, retry with the new total and a new `purchaseReference` |
627
+ | `400 AMOUNT_BELOW_FEE` (`err.isAmountBelowFee`) | unacknowledged, and the amount cannot carry the fee (well under a dollar) | nothing was charged; send a larger amount, or quote and acknowledge |
628
+
629
+ Only a `success` response carries the four fee fields; `requires_action` and `pending_payment` do not. Storefront rails bill no INVO card fee: the storefront takes its own cut.
630
+
631
+ ### Refunds of coin purchases
632
+
633
+ **Only coins that have not been spent are refundable. Spent coins are never refunded**, including when new coins have arrived in the balance since. A refund of a card purchase of coins returns the price of the unspent coins and takes those coins back; if every coin from the purchase has been spent, nothing is refunded. Refunds are issued by INVO: this SDK has no call that refunds a coin purchase, so ask INVO support.
634
+
573
635
  ---
574
636
 
575
637
  ## Item purchase (spend game currency)
@@ -607,7 +669,7 @@ const item = await server.purchaseItem({
607
669
 
608
670
  ## Platform Commerce (ecommerce)
609
671
 
610
- > **This is not [item purchase](#item-purchase-spend-game-currency).** Item purchase is a *game* tenant spending a player's *existing game currency* on an *in-game* item — always a balance debit, never a card, no refunds. **Platform Commerce is a _platform_ tenant (a non-game app: vertical video, creator merch, marketplace) running a storefront.** The buyer pays with **INVO balance** *or* a **real card** (new money), INVO is **merchant of record**, and **refunds** exist. Only platform tenants may call it — a game tenant gets `403` (`err.isNotPlatformTenant`).
672
+ > **This is not [item purchase](#item-purchase-spend-game-currency).** Item purchase is a *game* tenant spending a player's *existing game currency* on an *in-game* item — always a balance debit, never a card, no refunds. **Platform Commerce is a _platform_ tenant (a non-game app: vertical video, creator merch, marketplace) running a storefront.** The buyer pays with **INVO balance** *or* a **real card** (new money), and **refunds** exist. Who is the seller of record, and who handles tax, depends on your [tier](#tiers). Only platform tenants may call it — a game tenant gets `403` (`err.isNotPlatformTenant`).
611
673
 
612
674
  The funding source is resolved **server-side under lock** — the client can *request* `balance` or `card`, but the backend verifies the real balance before any value moves. Everything money-shaped is a server call (holds the secret, creates the purchase/refund); the browser's only job on the card leg is to **send the buyer to INVO's hosted checkout page**. Reached via the `platformCommerce` namespace on each entry point.
613
675
 
@@ -702,7 +764,7 @@ Each period INVO works out what the period is worth in coins (card: price × the
702
764
 
703
765
  - **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 7% by default plus $0.30, on the full price ($9.99 pays INVO $1.00 and you $8.99). Subscriptions are their own rate: item purchases stay at 10/90.
704
766
  - **Steam rail: unchanged.** INVO spends the member's wallet first and tops up from Steam for the shortfall only.
705
- - **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.
767
+ - **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. A [paid trial](#paid-trials) is stricter: without a usable saved card it is refused (`400 PAYMENT_METHOD_REQUIRED`) and nothing is created.
706
768
  - **`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.
707
769
 
708
770
  **Three rules to carry through everything below.**
@@ -800,7 +862,7 @@ switch (setup.status) {
800
862
  const { cards } = await server.cards.list("member@example.com"); // unexpired, newest first; `id` is the only handle
801
863
  ```
802
864
 
803
- **2. Create the subscription.** `create` **charges the first period before responding** (unless it is a trial), so expect it to take as long as a card charge.
865
+ **2. Create the subscription.** `create` **charges the first period before responding** (unless it is a free trial; a [paid trial](#paid-trials) charges its trial price), so expect it to take as long as a card charge.
804
866
 
805
867
  ```ts
806
868
  const r = await server.subscriptions.create({
@@ -813,10 +875,11 @@ const r = await server.subscriptions.create({
813
875
  interval: "month", // "month" (default) | "year"
814
876
  // intervalCount: 3, // quarterly; 1..36
815
877
  // trialDays: 7, // or trialEnd: "2026-10-01T00:00:00Z"
878
+ // trialAmountUsd: "1.00", // a PAID trial: see "Paid trials" below
816
879
  // playerCardId: cards[0].id, // omitted: INVO attaches the newest unexpired saved card
817
880
  // walletOnly: true, // DEPRECATED: never charges a card, so it can never be paid ("wallet_only")
818
881
  metadata: { guild_id: "42" }, // echoed on every read and event (`_invo` is reserved)
819
- consent: { // send it: INVO is merchant of record and a dispute is argued from this
882
+ consent: { // send it: a dispute over a recurring charge is argued from this
820
883
  consentAt: new Date().toISOString(),
821
884
  consentIp: memberIp, // the MEMBER's IP as your server saw it
822
885
  consentUserAgent: memberUserAgent,
@@ -838,7 +901,7 @@ switch (r.firstCharge.status) {
838
901
  case "requires_action": // NOTHING has been charged; status is awaiting_authentication
839
902
  relayToMember(r.firstCharge.confirmationUrl!, r.firstCharge.expiresAt!); // a single-use bearer link: never log it
840
903
  break; // access follows on subscription.renewed; if the link lapses INVO retries on its own
841
- case "skipped_trial": // status is trialing; the first charge runs at trialEnd
904
+ case "skipped_trial": // a FREE trial: status is trialing; the first charge runs at trialEnd
842
905
  grantTrialUntil(r.subscription.trialEnd!);
843
906
  break;
844
907
  case "failed": // status is past_due, in dunning; INVO retries at nextRetryAt
@@ -854,6 +917,41 @@ switch (r.firstCharge.status) {
854
917
 
855
918
  **4. Replay before retry.** `create` is idempotent on `clientRequestId`: a repeat returns HTTP 200 with the identical shape and `r.idempotentReplay === true`, nothing is charged again, and `firstCharge` is re-derived from what already happened (so a replay after the charge settled reports `paid`). The SDK auto-retries transient failures with the same key. **On any timeout or 5xx, replay the same key before you do anything else.** A fresh key inside a retry loop lands on `409 ACTIVE_SUBSCRIPTION_EXISTS` (`err.isActiveSubscriptionExists`, the live id on `err.existingSubscriptionId`) at best and a second subscription at worst; the same key with different terms is `err.isIdempotentReplayMismatch` (`err.mismatchedFields`).
856
919
 
920
+ ### Paid trials
921
+
922
+ Charge a small amount for the trial window, then the regular price, as **one subscription with one card**: for example **$1.00 for 7 days, then $29.00 a month**. Card subscriptions only.
923
+
924
+ ```ts
925
+ const r = await server.subscriptions.create({
926
+ clientRequestId: "member-7-pro",
927
+ playerEmail: "member@example.com",
928
+ playerName: "Member",
929
+ itemId: "pro-membership",
930
+ amountUsd: "29.00", // the regular price, charged from period 2
931
+ interval: "month",
932
+ trialDays: 7, // or trialEnd; a paid trial needs one of them
933
+ trialAmountUsd: "1.00", // at least 0.50 and less than amountUsd
934
+ consent: {
935
+ consentAt: new Date().toISOString(),
936
+ disclosedAmountUsd: "29.00",
937
+ disclosedInterval: "month",
938
+ disclosedTrialAmountUsd: "1.00", // what you showed the member
939
+ disclosedTrialDays: 7, // or disclosedTrialEnd
940
+ },
941
+ });
942
+ // On success: r.firstCharge.status "paid", r.firstCharge.amountUsd "1.00", r.firstCharge.paidPeriodSeq 1,
943
+ // r.subscription.status "trialing", r.subscription.amountUsd "29.00", r.subscription.trialAmountUsd "1.00",
944
+ // r.subscription.paidThrough === r.subscription.trialEnd, r.subscription.trialAmountCoinsEstimate "10.00"
945
+ ```
946
+
947
+ - **Period 1 is the trial window** and is charged `trialAmountUsd` inside the `create` call, through the same first charge as any subscription. `firstCharge` reports it as any first charge is reported (`paid`, `requires_action`, `failed`, `pending`) with the trial price; `skipped_trial` is never returned for a paid trial. `subscription.renewed` fires for period 1 with `is_trial: true` and `amount_usd: "1.00"`.
948
+ - **At the trial end INVO charges `amountUsd` as period 2** (`subscription.renewed` with `period_seq: 2`, `is_trial: false`) and billing continues as normal. This is not a price change: nothing is staged and the doubling rule does not apply.
949
+ - **Save the card first.** Without a usable saved card the create is refused with `400 PAYMENT_METHOD_REQUIRED` (`err.isPaymentMethodRequired`) and nothing is created.
950
+ - **A refused trial charge ends it.** The subscription goes straight to `expired`, `firstCharge.status` is `failed` with `nextRetryAt: null`, and you receive `subscription.payment_failed` then `subscription.expired` with `expire_cause: "trial_payment_failed"`. Subscribe again with a **new** `clientRequestId` once the member has a working card. A temporary processing error is not a refusal: that goes to ordinary dunning and is retried.
951
+ - **Events about the trial period** (`payment_failed`, `past_due`, `authentication_required`, `expired`) carry `is_trial: true` and `trial_amount_usd`; their `amount_usd` is still the regular price and `amount_due_usd` is the trial price. The keys are absent on every other event of those types.
952
+ - **Refusals:** `err.isTrialAmountRequiresTrial` (no `trialDays`/`trialEnd`), `err.isTrialAmountNotSupportedForFunding` (`walletOnly: true`, or the Steam rail), `err.isTrialAmountInvalid` (below $0.50 or not below `amountUsd`), `err.isConsentDisclosedTrialInvalid` (a malformed `disclosedTrial*` field). The first two, and a malformed amount, are also caught by the SDK before the network. A changed `trialAmountUsd` on a replay is `err.isIdempotentReplayMismatch` with `trial_amount_usd` in `err.mismatchedFields`.
953
+ - The trial period is refundable like any other period.
954
+
857
955
  ### The Steam road
858
956
 
859
957
  A Steam subscription is funded from the member's Steam wallet through a recurring agreement they authorise **once, in Steam**. INVO still owns the clock. Valve pays you through your Steamworks account; INVO mints the currency and settles with you afterwards. The title must be enabled for Steam in INVO (`err.isSteamRailNotEntitled` / `err.isSteamNotConfigured` otherwise), and the coins a period is worth depend on the member's country because Steam prices include VAT: **show `amountCoins` from the init response, never price × 10.**
@@ -1066,7 +1164,10 @@ Match on `err.code` (and on `body.status` where the body carries one), never on
1066
1164
  |---|---|
1067
1165
  | `.isGameNotLive` | (403) create refused; the game is `testing`. Make it live in the console |
1068
1166
  | `.isActiveSubscriptionExists` + `.existingSubscriptionId` | (409) the player already has a live subscription to this item. You regenerated `clientRequestId` in a retry loop |
1069
- | `.isIdempotentReplayMismatch` + `.mismatchedFields` | (409) same key, same player + item, different material terms. Use `changeAmount`/`setPaymentMethod`, or a new key |
1167
+ | `.isIdempotentReplayMismatch` + `.mismatchedFields` | (409) same key, same player + item, different material terms (`trial_amount_usd` included). Use `changeAmount`/`setPaymentMethod`, or a new key |
1168
+ | `.isPaymentMethodRequired` | (400) a paid trial with no usable saved card; nothing was created. Save a card first. (Also `setPaymentMethod` without a card id) |
1169
+ | `.isTrialAmountRequiresTrial` / `.isTrialAmountNotSupportedForFunding` / `.isTrialAmountInvalid` | (400) `trialAmountUsd` without a trial; with `walletOnly: true` or on Steam; below $0.50 or not below `amountUsd` |
1170
+ | `.isConsentDisclosedTrialInvalid` | (400) a malformed `disclosedTrialAmountUsd` / `disclosedTrialDays` / `disclosedTrialEnd`; `err.code` says which |
1070
1171
  | `.isFlowPaused` | (503) maintenance pause. Retry later with the **same** key |
1071
1172
  | `.isSubscriptionTerminal` | (409) the subscription is `canceled`/`expired`. Start a new one |
1072
1173
  | `.isSteamReauthorizationRequired` | (409) a price **increase** on Steam. Start a new Steam subscription at the new price |
@@ -1091,7 +1192,7 @@ Match on `err.code` (and on `body.status` where the body carries one), never on
1091
1192
  | `.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`) |
1092
1193
  | `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` |
1093
1194
 
1094
- 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.
1195
+ Client-side guards (missing key, a `sub_`-prefixed key, a bad amount, a non-E.164 `playerPhone`, a trial or card field on Steam, `trialAmountUsd` without a trial or with `walletOnly: true`, a web session without `playerIp`, a missing `sandboxClockKey`) throw `InvoError` with `.status === 0` **before** any network call.
1095
1196
 
1096
1197
  ### Traps
1097
1198
 
@@ -2067,6 +2168,8 @@ Helpers:
2067
2168
  | `.isNotPlatformTenant` | Platform Commerce called by a non-platform tenant (403) — use `purchaseItem`/`createCheckout` instead |
2068
2169
  | `.isAmountBelowMinimum` / `.isBelowCardMinimum` / `.isAboveCardMaximum` | amount too small for the fee to round up / card charge under $0.50 / card charge over INVO's maximum single card charge, which is a runtime setting (400) |
2069
2170
  | `.isAlreadyRefunded` | Platform Commerce refund of an already-refunded order (409) — treat as already done |
2171
+ | `.isQuoteStale` + `.expectedTotalUsd` | `purchaseCurrency` with an `acknowledgedTotalUsd` that is no longer the total (409); nothing charged: quote again |
2172
+ | `.isAmountBelowFee` | unacknowledged `purchaseCurrency` too small to carry INVO's card fee (400); nothing charged |
2070
2173
  | `.retryAfter` | seconds to back off on a 429 throttle |
2071
2174
  | `.isEnrollmentAuthorizationRequired` | first-enrollment needs the OTP grant → `enrollmentBegin`/`enrollmentVerify` |
2072
2175
  | `.isEnrollmentProofRequired` | another method exists → prove it via `linkDevice` |
@@ -2104,7 +2207,8 @@ try {
2104
2207
  | `initiateSend(input)` | `{ transactionId, verificationMethod, guardianApproval?, raw }` |
2105
2208
  | `initiateTransfer(input)` | `{ transactionId, verificationMethod, guardianApproval?, raw }` |
2106
2209
  | `createCheckout(input)` | `{ sessionId, checkoutUrl, sessionToken?, expiresAt, expiresInSeconds, raw }`, where `sessionToken` is INVO's own `session_token` field (falling back to the `checkoutUrl` query string on a backend that predates it) and is the credential for the [status read](#did-the-purchase-go-through-the-status-read) |
2107
- | `purchaseCurrency(input)` | `{ status, clientSecret?, paymentIntentId?, paymentUrl?, transactionId?, orderId?, newBalance?, raw }` |
2210
+ | `quoteCurrencyPurchase({ playerEmail, usdAmount, country?, subdivision? })` | `CurrencyPurchaseQuote`: `{ totalUsd, amountCents, subtotalUsd, processingFeeUsd, coins, currencyName, breakdown, ifUnacknowledged, raw }`; moves no money; send `totalUsd` back as `acknowledgedTotalUsd` (see [INVO's card fee](#invos-card-fee-quote-show-acknowledge)) |
2211
+ | `purchaseCurrency(input)` | `{ status, clientSecret?, paymentIntentId?, paymentUrl?, transactionId?, orderId?, newBalance?, processingFeeUsd?, feeTakenFrom?, coinsCredited?, chargeTotalUsd?, raw }`; optional `acknowledgedTotalUsd` input |
2108
2212
  | `confirmPayment({ paymentIntentId, orderId? })` | `{ status, transactionId?, newBalance?, raw }` |
2109
2213
  | `getOrderDetails({ orderId? \| transactionId? })` | `{ order, financialSummary, statusTimeline, raw }` |
2110
2214
  | `purchaseItem(input)` | `{ status, transactionId, orderId, newBalance, previousBalance, currencyName, financialBreakdown?, raw }` — **game** tenant spending game currency on an in-game item |
@@ -2113,7 +2217,7 @@ try {
2113
2217
  | `platformCommerce.purchase(input)` | `{ status, fundingSource, orderId?, transactionId?, newBalance?, financialBreakdown?, sessionId?, checkoutUrl?, expiresAt?, amountUsd?, idempotentReplay?, raw }` — **ecommerce** (platform tenant); `balance` settles now, `card` returns a hosted-checkout `checkoutUrl` |
2114
2218
  | `platformCommerce.getStatus(orderId)` | `{ orderId, status, gameCurrencyAmount?, usdAmount?, paymentMethod?, createdAt?, raw }` |
2115
2219
  | `platformCommerce.refund({ orderId? \| clientRequestId?, reason? })` | `{ status, orderId?, fundingSource?, refundedAmount?, amountUnit?, feeRetained?, raw }` — pass **exactly one** id; INVO keeps its fee |
2116
- | `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) |
2220
+ | `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`); `trialAmountUsd` makes a [paid trial](#paid-trials); idempotent on `clientRequestId` (a repeat is `idempotentReplay: true`, never thrown) |
2117
2221
  | `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) |
2118
2222
  | `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 |
2119
2223
  | `subscriptions.cancel(id, { atPeriodEnd?, reason? })` | `CancelResult` — `{ alreadyCanceled, cancelAtPeriodEnd, terminatedImmediately, effectiveAt, accessUntil, paidThrough, subscription, raw }`; an already-terminal row is a 200 with `alreadyCanceled: true` |
@@ -381,6 +381,34 @@ var InvoError = class _InvoError extends Error {
381
381
  get isAboveCardMaximum() {
382
382
  return this.code === "ABOVE_CARD_MAXIMUM";
383
383
  }
384
+ // ---- Coin purchase: INVO's card fee (2026-09-23) ----
385
+ /**
386
+ * True when an UNACKNOWLEDGED `purchaseCurrency` was refused because the amount is too
387
+ * small to carry INVO's card fee (`AMOUNT_BELOW_FEE`, 400). Nothing was charged. Send a
388
+ * larger amount, or quote it with `quoteCurrencyPurchase` and send `acknowledgedTotalUsd`
389
+ * so the fee is added on top.
390
+ */
391
+ get isAmountBelowFee() {
392
+ return this.code === "AMOUNT_BELOW_FEE";
393
+ }
394
+ /**
395
+ * True when `purchaseCurrency` was sent an `acknowledgedTotalUsd` that is not the total
396
+ * INVO would charge now (`QUOTE_STALE`, 409). Nothing was charged. Quote again, show the
397
+ * player the new total, and retry with it. {@link expectedTotalUsd} carries INVO's figure.
398
+ */
399
+ get isQuoteStale() {
400
+ return this.code === "QUOTE_STALE";
401
+ }
402
+ /** On `QUOTE_STALE`: the total INVO would charge (`expected_total_usd`), decimal string. */
403
+ get expectedTotalUsd() {
404
+ const v = this.bodyObject()["expected_total_usd"];
405
+ return typeof v === "string" && v ? v : void 0;
406
+ }
407
+ /** On `QUOTE_STALE`: the total you sent, as INVO read it (`acknowledged_total_usd`). */
408
+ get acknowledgedTotalUsd() {
409
+ const v = this.bodyObject()["acknowledged_total_usd"];
410
+ return typeof v === "string" && v ? v : void 0;
411
+ }
384
412
  /**
385
413
  * True if a Platform Commerce refund targeted an order that was already refunded
386
414
  * (409). Idempotent outcome — the original refund did happen, so treat this as
@@ -497,7 +525,8 @@ var InvoError = class _InvoError extends Error {
497
525
  * True when the same `clientRequestId` was replayed for the same player and item but
498
526
  * with DIFFERENT material terms (`IDEMPOTENT_REPLAY_MISMATCH`, 409). See
499
527
  * `mismatchedFields` (any of `amount_usd`, `interval`, `interval_count`, `wallet_only`,
500
- * `funding_rail`). To change terms use `changeAmount` / `setPaymentMethod`; to create a
528
+ * `funding_rail`, `trial_amount_usd`; for the last an omitted value counts, so a replay
529
+ * without it against a paid trial is a mismatch). To change terms use `changeAmount` / `setPaymentMethod`; to create a
501
530
  * new subscription use a new key.
502
531
  */
503
532
  get isIdempotentReplayMismatch() {
@@ -508,6 +537,46 @@ var InvoError = class _InvoError extends Error {
508
537
  const v = this.bodyObject()["mismatched_fields"];
509
538
  return Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
510
539
  }
540
+ // ---- Subscriptions: paid trials (2026-09-23) ----
541
+ /**
542
+ * True on `PAYMENT_METHOD_REQUIRED` (400). From `subscriptions.create`: a paid trial
543
+ * (`trialAmountUsd`) with no usable saved card; nothing was created. Save the member's card
544
+ * (`cards.createSetupSession`), then subscribe again. From `setPaymentMethod`: no
545
+ * `playerCardId` was sent.
546
+ */
547
+ get isPaymentMethodRequired() {
548
+ return this.code === "PAYMENT_METHOD_REQUIRED";
549
+ }
550
+ /**
551
+ * True when `trialAmountUsd` is not a usable trial price (`TRIAL_AMOUNT_INVALID`, 400): it
552
+ * must be a decimal of at least `0.50` (the card minimum) and less than `amountUsd`. The
553
+ * message names the rule.
554
+ */
555
+ get isTrialAmountInvalid() {
556
+ return this.code === "TRIAL_AMOUNT_INVALID";
557
+ }
558
+ /** True when `trialAmountUsd` was sent without `trialDays` or `trialEnd` (`TRIAL_AMOUNT_REQUIRES_TRIAL`, 400). */
559
+ get isTrialAmountRequiresTrial() {
560
+ return this.code === "TRIAL_AMOUNT_REQUIRES_TRIAL";
561
+ }
562
+ /**
563
+ * True when a paid trial was asked for where it cannot be charged
564
+ * (`TRIAL_AMOUNT_NOT_SUPPORTED_FOR_FUNDING`, 400): with `walletOnly: true`, or on the Steam
565
+ * rail. Paid trials are for card subscriptions only.
566
+ */
567
+ get isTrialAmountNotSupportedForFunding() {
568
+ return this.code === "TRIAL_AMOUNT_NOT_SUPPORTED_FOR_FUNDING";
569
+ }
570
+ /**
571
+ * True when one of the disclosed paid-trial consent fields is malformed (400):
572
+ * `CONSENT_DISCLOSED_TRIAL_AMOUNT_INVALID`, `CONSENT_DISCLOSED_TRIAL_DAYS_INVALID` (not an
573
+ * integer 1 to 365) or `CONSENT_DISCLOSED_TRIAL_END_INVALID` (not ISO 8601). `err.code`
574
+ * says which. A disclosed value that is well formed but disagrees with the trial is not
575
+ * refused; INVO records the disagreement.
576
+ */
577
+ get isConsentDisclosedTrialInvalid() {
578
+ return this.code === "CONSENT_DISCLOSED_TRIAL_AMOUNT_INVALID" || this.code === "CONSENT_DISCLOSED_TRIAL_DAYS_INVALID" || this.code === "CONSENT_DISCLOSED_TRIAL_END_INVALID";
579
+ }
511
580
  /**
512
581
  * True when `changeAmount` tried to RAISE the price of a Steam subscription
513
582
  * (`STEAM_REAUTHORIZATION_REQUIRED`, 409). The member consented to a ceiling; start a
@@ -984,5 +1053,5 @@ function toDestinationsResult(raw, direction) {
984
1053
  }
985
1054
 
986
1055
  export { Http, InvoError, assertSecureBaseUrl, toDestinationsResult };
987
- //# sourceMappingURL=chunk-5BMM5ZTW.js.map
988
- //# sourceMappingURL=chunk-5BMM5ZTW.js.map
1056
+ //# sourceMappingURL=chunk-NJIZMM4H.js.map
1057
+ //# sourceMappingURL=chunk-NJIZMM4H.js.map
package/dist/index.cjs CHANGED
@@ -383,6 +383,34 @@ var InvoError = class _InvoError extends Error {
383
383
  get isAboveCardMaximum() {
384
384
  return this.code === "ABOVE_CARD_MAXIMUM";
385
385
  }
386
+ // ---- Coin purchase: INVO's card fee (2026-09-23) ----
387
+ /**
388
+ * True when an UNACKNOWLEDGED `purchaseCurrency` was refused because the amount is too
389
+ * small to carry INVO's card fee (`AMOUNT_BELOW_FEE`, 400). Nothing was charged. Send a
390
+ * larger amount, or quote it with `quoteCurrencyPurchase` and send `acknowledgedTotalUsd`
391
+ * so the fee is added on top.
392
+ */
393
+ get isAmountBelowFee() {
394
+ return this.code === "AMOUNT_BELOW_FEE";
395
+ }
396
+ /**
397
+ * True when `purchaseCurrency` was sent an `acknowledgedTotalUsd` that is not the total
398
+ * INVO would charge now (`QUOTE_STALE`, 409). Nothing was charged. Quote again, show the
399
+ * player the new total, and retry with it. {@link expectedTotalUsd} carries INVO's figure.
400
+ */
401
+ get isQuoteStale() {
402
+ return this.code === "QUOTE_STALE";
403
+ }
404
+ /** On `QUOTE_STALE`: the total INVO would charge (`expected_total_usd`), decimal string. */
405
+ get expectedTotalUsd() {
406
+ const v = this.bodyObject()["expected_total_usd"];
407
+ return typeof v === "string" && v ? v : void 0;
408
+ }
409
+ /** On `QUOTE_STALE`: the total you sent, as INVO read it (`acknowledged_total_usd`). */
410
+ get acknowledgedTotalUsd() {
411
+ const v = this.bodyObject()["acknowledged_total_usd"];
412
+ return typeof v === "string" && v ? v : void 0;
413
+ }
386
414
  /**
387
415
  * True if a Platform Commerce refund targeted an order that was already refunded
388
416
  * (409). Idempotent outcome — the original refund did happen, so treat this as
@@ -499,7 +527,8 @@ var InvoError = class _InvoError extends Error {
499
527
  * True when the same `clientRequestId` was replayed for the same player and item but
500
528
  * with DIFFERENT material terms (`IDEMPOTENT_REPLAY_MISMATCH`, 409). See
501
529
  * `mismatchedFields` (any of `amount_usd`, `interval`, `interval_count`, `wallet_only`,
502
- * `funding_rail`). To change terms use `changeAmount` / `setPaymentMethod`; to create a
530
+ * `funding_rail`, `trial_amount_usd`; for the last an omitted value counts, so a replay
531
+ * without it against a paid trial is a mismatch). To change terms use `changeAmount` / `setPaymentMethod`; to create a
503
532
  * new subscription use a new key.
504
533
  */
505
534
  get isIdempotentReplayMismatch() {
@@ -510,6 +539,46 @@ var InvoError = class _InvoError extends Error {
510
539
  const v = this.bodyObject()["mismatched_fields"];
511
540
  return Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
512
541
  }
542
+ // ---- Subscriptions: paid trials (2026-09-23) ----
543
+ /**
544
+ * True on `PAYMENT_METHOD_REQUIRED` (400). From `subscriptions.create`: a paid trial
545
+ * (`trialAmountUsd`) with no usable saved card; nothing was created. Save the member's card
546
+ * (`cards.createSetupSession`), then subscribe again. From `setPaymentMethod`: no
547
+ * `playerCardId` was sent.
548
+ */
549
+ get isPaymentMethodRequired() {
550
+ return this.code === "PAYMENT_METHOD_REQUIRED";
551
+ }
552
+ /**
553
+ * True when `trialAmountUsd` is not a usable trial price (`TRIAL_AMOUNT_INVALID`, 400): it
554
+ * must be a decimal of at least `0.50` (the card minimum) and less than `amountUsd`. The
555
+ * message names the rule.
556
+ */
557
+ get isTrialAmountInvalid() {
558
+ return this.code === "TRIAL_AMOUNT_INVALID";
559
+ }
560
+ /** True when `trialAmountUsd` was sent without `trialDays` or `trialEnd` (`TRIAL_AMOUNT_REQUIRES_TRIAL`, 400). */
561
+ get isTrialAmountRequiresTrial() {
562
+ return this.code === "TRIAL_AMOUNT_REQUIRES_TRIAL";
563
+ }
564
+ /**
565
+ * True when a paid trial was asked for where it cannot be charged
566
+ * (`TRIAL_AMOUNT_NOT_SUPPORTED_FOR_FUNDING`, 400): with `walletOnly: true`, or on the Steam
567
+ * rail. Paid trials are for card subscriptions only.
568
+ */
569
+ get isTrialAmountNotSupportedForFunding() {
570
+ return this.code === "TRIAL_AMOUNT_NOT_SUPPORTED_FOR_FUNDING";
571
+ }
572
+ /**
573
+ * True when one of the disclosed paid-trial consent fields is malformed (400):
574
+ * `CONSENT_DISCLOSED_TRIAL_AMOUNT_INVALID`, `CONSENT_DISCLOSED_TRIAL_DAYS_INVALID` (not an
575
+ * integer 1 to 365) or `CONSENT_DISCLOSED_TRIAL_END_INVALID` (not ISO 8601). `err.code`
576
+ * says which. A disclosed value that is well formed but disagrees with the trial is not
577
+ * refused; INVO records the disagreement.
578
+ */
579
+ get isConsentDisclosedTrialInvalid() {
580
+ return this.code === "CONSENT_DISCLOSED_TRIAL_AMOUNT_INVALID" || this.code === "CONSENT_DISCLOSED_TRIAL_DAYS_INVALID" || this.code === "CONSENT_DISCLOSED_TRIAL_END_INVALID";
581
+ }
513
582
  /**
514
583
  * True when `changeAmount` tried to RAISE the price of a Steam subscription
515
584
  * (`STEAM_REAUTHORIZATION_REQUIRED`, 409). The member consented to a ceiling; start a
package/dist/index.d.cts CHANGED
@@ -1,5 +1,5 @@
1
- import { A as ApproveResult, C as ConfirmReceiptResult, P as PurchaseStatusResult, a as PurchaseCredited, b as PurchaseExpired, c as PurchaseRefunded, d as PurchaseRefused, e as CheckoutClientConfig, H as Http, f as PurchaseStatusInput, g as CallOptions, W as WaitForPurchaseInput, M as MountCheckoutOptions, h as CheckoutMountHandle, i as ClientConfig, L as LinkDeviceResult, j as PendingCollectResult, D as DestinationsQuery, k as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, l as EnrollmentVerifyResult, R as RecoveryBeginResult, m as RecoveryCompleteResult } from './types-CT0Ksonp.cjs';
2
- export { n as BalanceRow, o as CheckoutPurchaseStatus, p as DestinationGame, I as InvoError, q as InvoErrorInfo, r as InvoHooks, s as InvoRequestInfo, t as InvoResponseInfo, u as PendingCollectItem, v as PurchaseRefusalReason, w as Rail, V as VerificationMethod } from './types-CT0Ksonp.cjs';
1
+ import { A as ApproveResult, C as ConfirmReceiptResult, P as PurchaseStatusResult, a as PurchaseCredited, b as PurchaseExpired, c as PurchaseRefunded, d as PurchaseRefused, e as CheckoutClientConfig, H as Http, f as PurchaseStatusInput, g as CallOptions, W as WaitForPurchaseInput, M as MountCheckoutOptions, h as CheckoutMountHandle, i as ClientConfig, L as LinkDeviceResult, j as PendingCollectResult, D as DestinationsQuery, k as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, l as EnrollmentVerifyResult, R as RecoveryBeginResult, m as RecoveryCompleteResult } from './types-DUo5NAzj.cjs';
2
+ export { n as BalanceRow, o as CheckoutPurchaseStatus, p as DestinationGame, I as InvoError, q as InvoErrorInfo, r as InvoHooks, s as InvoRequestInfo, t as InvoResponseInfo, u as PendingCollectItem, v as PurchaseRefusalReason, w as Rail, V as VerificationMethod } from './types-DUo5NAzj.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, P as PurchaseStatusResult, a as PurchaseCredited, b as PurchaseExpired, c as PurchaseRefunded, d as PurchaseRefused, e as CheckoutClientConfig, H as Http, f as PurchaseStatusInput, g as CallOptions, W as WaitForPurchaseInput, M as MountCheckoutOptions, h as CheckoutMountHandle, i as ClientConfig, L as LinkDeviceResult, j as PendingCollectResult, D as DestinationsQuery, k as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, l as EnrollmentVerifyResult, R as RecoveryBeginResult, m as RecoveryCompleteResult } from './types-CT0Ksonp.js';
2
- export { n as BalanceRow, o as CheckoutPurchaseStatus, p as DestinationGame, I as InvoError, q as InvoErrorInfo, r as InvoHooks, s as InvoRequestInfo, t as InvoResponseInfo, u as PendingCollectItem, v as PurchaseRefusalReason, w as Rail, V as VerificationMethod } from './types-CT0Ksonp.js';
1
+ import { A as ApproveResult, C as ConfirmReceiptResult, P as PurchaseStatusResult, a as PurchaseCredited, b as PurchaseExpired, c as PurchaseRefunded, d as PurchaseRefused, e as CheckoutClientConfig, H as Http, f as PurchaseStatusInput, g as CallOptions, W as WaitForPurchaseInput, M as MountCheckoutOptions, h as CheckoutMountHandle, i as ClientConfig, L as LinkDeviceResult, j as PendingCollectResult, D as DestinationsQuery, k as DestinationsResult, B as BalanceResult, E as EnrollmentBeginResult, l as EnrollmentVerifyResult, R as RecoveryBeginResult, m as RecoveryCompleteResult } from './types-DUo5NAzj.js';
2
+ export { n as BalanceRow, o as CheckoutPurchaseStatus, p as DestinationGame, I as InvoError, q as InvoErrorInfo, r as InvoHooks, s as InvoRequestInfo, t as InvoResponseInfo, u as PendingCollectItem, v as PurchaseRefusalReason, w as Rail, V as VerificationMethod } from './types-DUo5NAzj.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-5BMM5ZTW.js';
2
- export { InvoError } from './chunk-5BMM5ZTW.js';
1
+ import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult } from './chunk-NJIZMM4H.js';
2
+ export { InvoError } from './chunk-NJIZMM4H.js';
3
3
 
4
4
  // src/shared/webauthn.ts
5
5
  function malformedOptions(field) {