@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 +21 -0
- package/README.md +117 -13
- package/dist/{chunk-5BMM5ZTW.js → chunk-NJIZMM4H.js} +72 -3
- package/dist/index.cjs +70 -1
- package/dist/index.d.cts +2 -2
- package/dist/index.d.ts +2 -2
- package/dist/index.js +2 -2
- package/dist/server.cjs +218 -3
- package/dist/server.d.cts +75 -10
- package/dist/server.d.ts +75 -10
- package/dist/server.js +150 -4
- package/dist/{types-CT0Ksonp.d.cts → types-DUo5NAzj.d.cts} +212 -10
- package/dist/{types-CT0Ksonp.d.ts → types-DUo5NAzj.d.ts} +212 -10
- package/package.json +1 -1
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.
|
|
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 **
|
|
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
|
|
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
|
|
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),
|
|
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:
|
|
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
|
-
| `
|
|
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`
|
|
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-
|
|
988
|
-
//# sourceMappingURL=chunk-
|
|
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`
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
2
|
-
export { InvoError } from './chunk-
|
|
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) {
|