@invonetwork/web-sdk 3.17.0 → 3.18.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 +18 -0
- package/README.md +59 -35
- package/dist/{chunk-JGDNPNQX.js → chunk-YW2PYARQ.js} +60 -12
- package/dist/index.cjs +58 -10
- package/dist/index.d.cts +2 -2
- package/dist/index.d.ts +2 -2
- package/dist/index.js +2 -2
- package/dist/server.cjs +143 -30
- package/dist/server.d.cts +131 -24
- package/dist/server.d.ts +131 -24
- package/dist/server.js +87 -22
- package/dist/{types-CjJARoLk.d.cts → types-BnnVi5ws.d.cts} +210 -48
- package/dist/{types-CjJARoLk.d.ts → types-BnnVi5ws.d.ts} +210 -48
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,23 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 3.18.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- 432fb75: INVO's 2026-09 card pricing. On card purchases the partner now pays INVO's card fee (4.5% + $0.30 on Open, 5.5% + $0.50 on Merchant of Record, plus 1.5% of the listed price (before tax) on a card issued outside the US); the player pays the listed price (plus tax where owed) and receives the listed coins. Fraud screening and a chargeback guarantee (a fraud chargeback on a card sale is covered by INVO) are included. Minimum card purchase $2.99 on coin purchases and Platform Commerce card sales, enforced from 2026-10-27. Card purchases only; purchases through a third-party storefront or payment rail are unaffected. All additive:
|
|
8
|
+
|
|
9
|
+
- `PurchaseResult` and `CurrencyPurchaseQuote` gain `partnerFeeUsd`, `internationalCardFeeUsd` and `minPurchaseWarning` (`MinPurchaseWarning`: `{ code, minUsd, enforcedFrom, message?, enforced?, raw }`), each set only when INVO sends it. `processingFeeUsd` stays and reads `"0.00"`.
|
|
10
|
+
- `FeeTakenFrom` gains `"partner"`. `UnacknowledgedPurchaseOutcome.feeTakenFrom` stays required; INVO always sends it, and should it ever be missing the SDK reads `"partner"` when the quote carries `partner_fee_usd`, otherwise `"coins"` as before.
|
|
11
|
+
- `err.minUsd` and `err.enforcedFrom` on `BELOW_CARD_MINIMUM` (`err.isBelowCardMinimum`, which now also covers INVO's minimum card purchase). `err.isAmountBelowFee` is deprecated: `AMOUNT_BELOW_FEE` is no longer returned.
|
|
12
|
+
- `acknowledgedTotalUsd` is still honored: INVO never charges more than it, and an older, higher fee-inclusive total is accepted with the true, lower total charged. Only a total below the true total is refused (`QUOTE_STALE`).
|
|
13
|
+
- `partnerFeeUsd` and `internationalCardFeeUsd` are `string | null`: `null` only when the fee could not be booked when the purchase completed (the purchase succeeded; INVO books the fee shortly after). `internationalCardFeeUsd` is `"0.00"` on a US card or one whose country is unknown, and always `null` on a quote (no card yet). The quote also carries `feeTakenFrom`, and `ifUnacknowledged.partnerFeeUsd`.
|
|
14
|
+
- `createCheckout()` and the Platform Commerce card leg of `platformCommerce.purchase()` return `minPurchaseWarning` while an amount under the minimum card purchase is still accepted. `BELOW_CARD_MINIMUM` also answers a card charge under the $0.50 card floor at any date, on coin purchases, hosted checkout and Platform Commerce: `err.minUsd` reads `"0.50"` there, with no `err.enforcedFrom`.
|
|
15
|
+
- `purchaseCurrency()` accepts `country` and `subdivision`, the place you quoted with. On Merchant of Record INVO uses it only when it cannot read the buyer's tax location from the card; without it such a purchase is refused with `409 TAX_PLACE_UNAVAILABLE` (new `err.isTaxPlaceUnavailable`, `err.untaxedTotalUsd`), nothing charged.
|
|
16
|
+
- Platform Commerce card refunds: `cardFeeChargedToPartnerUsd` and `partnerDebitedUsd` on the refund result and `card_fee_charged_to_partner_usd` / `partner_debited_usd` on `platform_commerce.refunded` (the card fee is not returned on a refund; it stays charged to you).
|
|
17
|
+
- Webhook types: `purchase.completed` gains `partner_fee_usd` and `international_card_fee_usd` (nullable); `purchase.disputed` gains `guarantee_covered` (lost Platform Commerce card sale and subscription disputes only; never on a coin purchase dispute), `order_type`, `developer_revenue_reversed_usd`, `subscription_id`, `period_seq` and `processing_fee_usd` (the processor fee a non-fraud lost subscription chargeback charges you, as a refund does); `platform_commerce.purchased` gains `international_card_fee_usd` (already included in `fee_breakdown.platform_fee`); `subscription.renewed`'s split gains `international_card_fee_usd` (the same figure as `pass_through_fees_usd`, never add them; `partner_revenue_usd` stays gross).
|
|
18
|
+
- Behaviour to notice: an unacknowledged $10.00 coin purchase now credits the full 100.00 coins (93.70 under the earlier pricing); an older fee-inclusive acknowledged total is accepted and the lower true total charged; `AMOUNT_BELOW_FEE` is no longer returned.
|
|
19
|
+
- README and doc comments: every card fee figure, the Tiers table (card rates, international fee, who pays, fraud screening, chargeback guarantee, minimum card purchase) and the quote example ($10.00 charges the player $10.00; your fee is $0.75 on Open).
|
|
20
|
+
|
|
3
21
|
## 3.17.0
|
|
4
22
|
|
|
5
23
|
### Minor Changes
|
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
First-party TypeScript SDK for integrating **INVO** into partner **web** platforms (storefronts, web games, dashboards). It wraps INVO's web money flows behind a typed, versioned API — the web analog of the Unity/Unreal plugins.
|
|
4
4
|
|
|
5
|
-
> **Status:** `v3.17.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.17.0** types the Steam fields on `purchase.refunded` / `purchase.disputed` (`rail`, `steam_transid`, nullable card-only ids): Steam chargebacks now arrive as `purchase.disputed`; **3.16.0** adds `warnings` on `createCheckout()` (item metadata on a coin session), `err.isDuplicateClientRequestId`, `err.isTrialAmountBelowFeeFloor` and `err.isIdentityCheckUnavailable`; **3.14.0** adds `credited` / `reasonCode` on `confirmPayment()` and `steamFinalizePurchase()`, Merchant of Record receipt fields, Platform Commerce card refunds in parts, and updates the **[tiers](#tiers)**: subscription card
|
|
5
|
+
> **Status:** `v3.17.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.18.0** follows INVO's 2026-09 card pricing: on card purchases **you pay INVO's card fee** (**4.5% + $0.30** on Open, **5.5% + $0.50** on Merchant of Record, plus **1.5%** on a card issued outside the US) and the player pays the listed price and gets the listed coins; fraud screening and a **chargeback guarantee** are included; minimum card purchase **$2.99** from 2026-10-27. New `partnerFeeUsd`, `internationalCardFeeUsd`, `minPurchaseWarning`, `feeTakenFrom: "partner"`, `err.minUsd` / `err.enforcedFrom` on `err.isBelowCardMinimum`, `minPurchaseWarning` on `createCheckout()`, `country` / `subdivision` on `purchaseCurrency()` with `err.isTaxPlaceUnavailable`, `cardFeeChargedToPartnerUsd` / `partnerDebitedUsd` on Platform Commerce card refunds, and the `partner_fee_usd` / `international_card_fee_usd` / `guarantee_covered` / `card_fee_charged_to_partner_usd` / `partner_debited_usd` webhook fields, all additive; an unacknowledged $10.00 coin purchase now credits 100.00 coins, not 93.70 (see **[Tiers](#tiers)**); **3.17.0** types the Steam fields on `purchase.refunded` / `purchase.disputed` (`rail`, `steam_transid`, nullable card-only ids): Steam chargebacks now arrive as `purchase.disputed`; **3.16.0** adds `warnings` on `createCheckout()` (item metadata on a coin session), `err.isDuplicateClientRequestId`, `err.isTrialAmountBelowFeeFloor` and `err.isIdentityCheckUnavailable`; **3.14.0** adds `credited` / `reasonCode` on `confirmPayment()` and `steamFinalizePurchase()`, Merchant of Record receipt fields, Platform Commerce card refunds in parts, and updates the **[tiers](#tiers)**: subscription card rates and chargeback handling by tier (the rates are superseded by 3.18.0), and Merchant of Record is applied for from the console; **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)** (rates superseded by 3.18.0): `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 (it is its own rate; item purchases stay at 10/90; see [Tiers](#tiers) for the current rate); **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
|
|
@@ -295,12 +295,18 @@ Every INVO developer account is on one of two tiers. The SDK calls are the same
|
|
|
295
295
|
| Who it is for | every account, including all current ones | accounts INVO has approved |
|
|
296
296
|
| Who the seller is | **you** | **INVO** |
|
|
297
297
|
| Tax on sales | **you** are responsible for it; INVO collects none | **INVO** calculates, collects and remits it |
|
|
298
|
-
| Card purchase of coins |
|
|
299
|
-
|
|
|
300
|
-
|
|
|
298
|
+
| Card purchase of coins | 4.5% + $0.30 | 5.5% + $0.50 |
|
|
299
|
+
| Platform Commerce card sales | 4.5% + $0.30 | 5.5% + $0.50 |
|
|
300
|
+
| Subscriptions | 4.5% + $0.30 per card charge | 5.5% + $0.50 per card charge |
|
|
301
|
+
| Card issued outside the US | plus 1.5% of the listed price (before tax) | plus 1.5% of the listed price (before tax) |
|
|
302
|
+
| Who pays the card fee | **you**; the buyer pays the listed price and gets the listed coins or item | **you**; the buyer pays the listed price plus tax |
|
|
303
|
+
| Fraud screening | included | included |
|
|
304
|
+
| Chargebacks disputed as fraud (card sales) | **chargeback guarantee**: INVO absorbs a lost one; your share is not reversed or held, and no dispute fee is passed to you | **chargeback guarantee**: INVO absorbs a lost one; your share is not reversed or held, and no dispute fee is passed to you |
|
|
305
|
+
| Other chargebacks | the disputed amount comes out of your share; on subscription charges the dispute fee is passed through too | INVO manages the dispute and pays the dispute fee; the disputed amount comes out of your share and is restored if INVO wins |
|
|
306
|
+
| Minimum card purchase (coins, Platform Commerce card sales) | $2.99, enforced from 2026-10-27 | $2.99, enforced from 2026-10-27 |
|
|
301
307
|
| Item purchases (coins spent on an item) | 10% | 10% |
|
|
302
308
|
|
|
303
|
-
On both tiers every card charge runs on INVO's card rail and INVO pays you out, as today.
|
|
309
|
+
The card terms above (card fee, international fee, minimum and chargeback guarantee) apply to card purchases only; purchases through a third-party storefront or payment rail are unaffected and keep their current terms. On both tiers every card charge runs on INVO's card rail and INVO pays you out, as today. The card fee is charged to you, never to the buyer: the buyer pays the listed price (plus tax on Merchant of Record) and receives the listed coins or item. It nets against your earnings at purchase time and is not returned on a refund. The 1.5% on a card issued outside the United States applies on both tiers to every card charge and is reported as `international_card_fee_usd` (on a Platform Commerce sale it is already included in `fee_breakdown.platform_fee`); it replaces the earlier pass-through of international and currency conversion costs on subscriptions. Worked example, a $100.00 card sale: the buyer pays $100.00 (plus tax on Merchant of Record) and your fee is $4.80 on Open or $6.00 on Merchant of Record; on a card issued outside the US, $6.30 or $7.50. On a $10.00 sale: $0.75 or $1.05. On Merchant of Record, if your chargeback rate for the previous calendar month (disputes opened, excluding inquiries, divided by card charges completed, in UTC months) was above 0.75%, the dispute fee on subscription charges disputed this month for a reason the chargeback guarantee does not cover is charged to you as on Open, and INVO reviews your approval. Merchant of Record is applied for per developer account, not per game, from the Selling & Tax page in your INVO console, and INVO reviews each application. Full details: https://docs.invo.network/docs/tiers/
|
|
304
310
|
|
|
305
311
|
**What the tier changes in what the SDK returns** (all additive):
|
|
306
312
|
|
|
@@ -314,7 +320,7 @@ Buy game currency with real money. Authenticated by the **payment rail**, not a
|
|
|
314
320
|
|
|
315
321
|
### The card maximum is INVO's, not the SDK's
|
|
316
322
|
|
|
317
|
-
**Minimum: $
|
|
323
|
+
**Minimum card purchase: $2.99** on coin purchases and Platform Commerce card sales (not subscriptions), enforced by INVO from **2026-10-27**. From that date a smaller card purchase is refused before anything is charged (`400 BELOW_CARD_MINIMUM`, `err.isBelowCardMinimum`, with `err.minUsd` and `err.enforcedFrom`); until then it is accepted and the coin purchase quote and result carry `minPurchaseWarning`. The amount and the date are INVO settings, so this package does not pin them. Card purchases only; purchases through a third-party storefront or payment rail are unaffected. Below that sits the card rail's own floor of $0.50, where a charge cannot settle at all (the SDK checks it locally on the Platform Commerce card leg). See [INVO's card fee](#invos-card-fee-quote-show-acknowledge).
|
|
318
324
|
|
|
319
325
|
**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.
|
|
320
326
|
|
|
@@ -345,7 +351,7 @@ Per-customer velocity limits sit underneath the per-charge maximum (hourly, dail
|
|
|
345
351
|
// SERVER
|
|
346
352
|
const { checkoutUrl, sessionId, sessionToken, expiresAt, expiresInSeconds } = await server.createCheckout({
|
|
347
353
|
playerEmail: "p@example.com",
|
|
348
|
-
usdAmount: "20.00", // USD. Minimum $
|
|
354
|
+
usdAmount: "20.00", // USD. Minimum $2.99 from 2026-10-27. The maximum is an INVO setting
|
|
349
355
|
// ($100,000.00 by default) and is enforced on the request.
|
|
350
356
|
rail: "platform", // optional: "platform" (default) | "game" | "steam"
|
|
351
357
|
successUrl: "https://you/buy/ok",
|
|
@@ -432,7 +438,7 @@ Rules worth taking literally:
|
|
|
432
438
|
- **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`).
|
|
433
439
|
- **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.
|
|
434
440
|
- **`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.
|
|
435
|
-
- **`amountChargedUsd` minus `listedUsd`** is INVO
|
|
441
|
+
- **`amountChargedUsd` minus `listedUsd`** is the tax, where INVO collects it (Merchant of Record). The buyer pays no card fee: a 200.00 pack charges 200.00 plus any tax, and INVO's card fee is charged to you. A purchase settled under the earlier pricing may also include the card fee the buyer paid then; both numbers are here.
|
|
436
442
|
- **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.
|
|
437
443
|
- `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.
|
|
438
444
|
|
|
@@ -624,10 +630,12 @@ Show "purchase complete" only when `credited` is `true`. `alreadyProcessed` is a
|
|
|
624
630
|
|
|
625
631
|
### INVO's card fee: quote, show, acknowledge
|
|
626
632
|
|
|
627
|
-
A card purchase of coins
|
|
633
|
+
A card purchase of coins costs the player **the listed price** (plus tax where INVO collects it, on Merchant of Record) and credits **the listed coins**. INVO's card fee is charged to **you**, the developer of the game the coins were bought in: **4.5% + $0.30** on the Open [tier](#tiers), **5.5% + $0.50** on Merchant of Record, plus **1.5% of the listed price (before tax)** on a card issued outside the US. It nets against your earnings at purchase time and is not returned on a refund. Fraud screening is included, and a fraud chargeback on a card sale is covered by INVO's [chargeback guarantee](#tiers). These terms apply to card purchases only; purchases through a third-party storefront or payment rail are unaffected.
|
|
628
634
|
|
|
629
|
-
|
|
630
|
-
|
|
635
|
+
The hosted checkout shows the buyer the listed price (plus any tax), so there is nothing to do there. `purchaseCurrency` charges in the same request it is called, so it cannot show the buyer anything first:
|
|
636
|
+
|
|
637
|
+
- **Quote, show, acknowledge (recommended where tax may apply).** Ask `quoteCurrencyPurchase()` for the total, show the player that total, then send the same figure back as `acknowledgedTotalUsd`. The card is never charged more than that total and the player gets the listed coins.
|
|
638
|
+
- **Send only `usdAmount`.** The card is charged **exactly `usdAmount`, never more**, and the player gets the listed coins.
|
|
631
639
|
|
|
632
640
|
```ts
|
|
633
641
|
// 1) SERVER: quote. Moves no money and creates nothing: safe on every price render.
|
|
@@ -636,30 +644,43 @@ const q = await server.quoteCurrencyPurchase({
|
|
|
636
644
|
usdAmount: "10.00",
|
|
637
645
|
// country: "US", subdivision: "NY", // optional: the buyer's billing place, for any tax
|
|
638
646
|
});
|
|
639
|
-
// q.subtotalUsd "10.00" + q.processingFeeUsd "0.
|
|
647
|
+
// q.subtotalUsd "10.00" + q.processingFeeUsd "0.00" = q.totalUsd "10.00" (q.coins "100.00")
|
|
648
|
+
// q.partnerFeeUsd "0.75" when INVO sends it: YOUR fee (Open, US card), never the player's
|
|
640
649
|
// q.breakdown: every line, with taxNote / processingFeeNote sentences you can show as is
|
|
641
|
-
// q.
|
|
650
|
+
// q.minPurchaseWarning: set while an amount under the minimum card purchase is still accepted
|
|
642
651
|
|
|
643
|
-
// 2) Show the player q.totalUsd ("$10.
|
|
652
|
+
// 2) Show the player q.totalUsd ("$10.00"). 3) Charge what they saw:
|
|
644
653
|
const purchase = await server.purchaseCurrency({
|
|
645
654
|
playerEmail: "p@example.com",
|
|
646
|
-
usdAmount: "10.00", // the price; the coins are priced off this
|
|
647
|
-
acknowledgedTotalUsd: q.totalUsd, // "10.
|
|
655
|
+
usdAmount: "10.00", // the listed price; the coins are priced off this
|
|
656
|
+
acknowledgedTotalUsd: q.totalUsd, // "10.00": the card is never charged more than this
|
|
648
657
|
purchaseReference: crypto.randomUUID(),
|
|
649
658
|
paymentMethodId: "pm_...",
|
|
650
659
|
});
|
|
651
|
-
// On "success": purchase.chargeTotalUsd "10.
|
|
652
|
-
// purchase.
|
|
660
|
+
// On "success": purchase.chargeTotalUsd "10.00", purchase.coinsCredited "100.00",
|
|
661
|
+
// purchase.processingFeeUsd "0.00", purchase.feeTakenFrom "partner",
|
|
662
|
+
// purchase.partnerFeeUsd "0.75" (Open; "1.05" on Merchant of Record),
|
|
663
|
+
// purchase.internationalCardFeeUsd "0.00" ("0.15" on a card issued outside the US)
|
|
653
664
|
```
|
|
654
665
|
|
|
655
|
-
|
|
666
|
+
**What changed for an existing integration (2026-09 pricing).**
|
|
667
|
+
|
|
668
|
+
- **Not acknowledging:** a $10.00 purchase now credits the full **100.00** coins (it credited 93.70 under the earlier pricing, when the card fee was deducted from the coins). The card is still charged exactly `usdAmount`.
|
|
669
|
+
- **Already acknowledging the old total? It keeps working.** An integration written for the earlier pricing (where a $10.00 purchase quoted $10.65) may still send a higher, fee-inclusive `acknowledgedTotalUsd`. INVO accepts any acknowledged total at or above the true total and charges the true, lower total; the player is never charged more than they saw. Only an acknowledged total **below** the true total is refused. Quote again when you can, so the figure you show is the figure charged.
|
|
670
|
+
- **`AMOUNT_BELOW_FEE` is no longer returned:** the card fee is not in the player's charge, so no amount is too small to carry it. Small purchases are governed by the minimum card purchase below.
|
|
671
|
+
|
|
672
|
+
**Pass the place you quoted with (Merchant of Record).** Send the same `country` (and `subdivision`) you gave `quoteCurrencyPurchase()` on `purchaseCurrency()`. INVO uses it only when it cannot read the buyer's tax location from the card, so a buyer who was shown tax is charged it. Without it such a purchase is refused with `409 TAX_PLACE_UNAVAILABLE` and nothing is charged.
|
|
673
|
+
|
|
674
|
+
**Minimum card purchase: $2.99**, enforced by INVO from **2026-10-27** on coin purchases and Platform Commerce card sales (not subscriptions). Until then a smaller card purchase is accepted and the quote and result carry `minPurchaseWarning` (`{ code, minUsd, enforcedFrom }`). The amount and the date are INVO settings, so this package does not pin them: read them from the warning or the error.
|
|
656
675
|
|
|
657
676
|
| Error | When | What to do |
|
|
658
677
|
|---|---|---|
|
|
659
|
-
| `409 QUOTE_STALE` (`err.isQuoteStale`) | the acknowledged total is
|
|
660
|
-
| `400
|
|
678
|
+
| `409 QUOTE_STALE` (`err.isQuoteStale`) | the acknowledged total is below the total INVO would charge now | nothing was charged; quote again, show `err.expectedTotalUsd`, retry with the new total and a new `purchaseReference` |
|
|
679
|
+
| `400 BELOW_CARD_MINIMUM` (`err.isBelowCardMinimum`) | from 2026-10-27, a card purchase under the minimum card purchase (`err.minUsd`, `err.enforcedFrom`) | nothing was charged; raise the amount to at least `err.minUsd` |
|
|
680
|
+
| `409 TAX_PLACE_UNAVAILABLE` (`err.isTaxPlaceUnavailable`) | Merchant of Record only: you acknowledged a taxed total, INVO could not read the buyer's tax location from the card, and the request carried no `country` | nothing was charged; retry (a new attempt usually reads the card), or send the `country` / `subdivision` you quoted with. `err.untaxedTotalUsd` is the total without tax |
|
|
681
|
+
| `400 AMOUNT_BELOW_FEE` (`err.isAmountBelowFee`, deprecated) | no longer returned: the card fee is not in the player's charge | keep the branch if you have one; it will not fire |
|
|
661
682
|
|
|
662
|
-
Only a `success` response carries the
|
|
683
|
+
Only a `success` response carries the fee fields (`processingFeeUsd`, `feeTakenFrom`, `partnerFeeUsd`, `internationalCardFeeUsd`); `requires_action` and `pending_payment` do not. `internationalCardFeeUsd` is `"0.00"` on a US card and on a card whose country cannot be determined (it counts as domestic). `partnerFeeUsd` and `internationalCardFeeUsd` are `null` only if the fee could not be booked when the purchase completed: the purchase succeeded and INVO books the fee shortly after. On a quote `internationalCardFeeUsd` is always `null`, since no card is known yet. Each field is exactly what INVO sent, or `undefined`: the SDK never fills one in. A purchase settled under the earlier pricing may read `feeTakenFrom: "charge"` or `"coins"`. Storefront rails bill no INVO card fee: the storefront takes its own cut.
|
|
663
684
|
|
|
664
685
|
### Refunds of coin purchases
|
|
665
686
|
|
|
@@ -774,7 +795,10 @@ const s = await server.platformCommerce.getStatus(r.orderId);
|
|
|
774
795
|
|
|
775
796
|
const ref = await server.platformCommerce.refund({ orderId: r.orderId, reason: "customer request" });
|
|
776
797
|
// or refund({ clientRequestId }). Pass EXACTLY ONE id.
|
|
777
|
-
// INVO
|
|
798
|
+
// INVO's fee is not returned (ref.feeRetained === true); the buyer gets the refunded amount back.
|
|
799
|
+
// Card leg: the card fee stays charged to you. ref.cardFeeChargedToPartnerUsd is this refund's
|
|
800
|
+
// card fee part and ref.partnerDebitedUsd everything it takes from your earnings (your share
|
|
801
|
+
// reversed plus that fee part). The same two keys are on platform_commerce.refunded.
|
|
778
802
|
// A second refund of the same order throws 409 (err.isAlreadyRefunded) — treat as already done.
|
|
779
803
|
```
|
|
780
804
|
|
|
@@ -792,7 +816,7 @@ await server.platformCommerce.refund({ orderId, refundRemaining: true });
|
|
|
792
816
|
- `platform_commerce.refunded` for a sale refunded in parts also carries `partial_refund`, `refunded_total_usd` and `charge_total_usd` (`refunded_amount` is that refund's own amount); a one-shot full refund sends none of them.
|
|
793
817
|
|
|
794
818
|
- **Idempotency on `clientRequestId`:** a duplicate BALANCE purchase throws `409` (`err.isDuplicateRequest`); a duplicate CARD purchase **replays the same checkout session** (`r.idempotentReplay === true`, same URL — never a second charge), so a lost card-leg response is safely recovered by retrying with the *same* `clientRequestId`. A card purchase whose `clientRequestId` already has a payment can also throw `409` `err.isDuplicateClientRequestId` (`err.isDuplicateRequest` is also true) with `order_id` and `order_status` on `err.body`; read that order with `getStatus` instead of starting another payment. A refund by `clientRequestId` finds card orders as well as balance orders.
|
|
795
|
-
- INVO fee: **3.5% flat** (balance) · **
|
|
819
|
+
- INVO fee: **3.5% flat** (balance) · **4.5% + $0.30** on Open, **5.5% + $0.50** on Merchant of Record (card, charged to you; plus 1.5% of the listed price (before tax) on a card issued outside the US). On `platform_commerce.purchased`, `fee_breakdown.platform_fee` is INVO's whole fee and already includes the international card fee (also reported as `international_card_fee_usd`, top level and in `fee_breakdown`): `platform_fee + developer_revenue = total_paid`, and the card rate part is `platform_fee - international_card_fee_usd`. Too-small amounts throw `err.isAmountBelowMinimum` / `err.isBelowCardMinimum` (card < $0.50, and from 2026-10-27 card < $2.99, INVO's minimum card purchase; `err.minUsd`); a card total over INVO's maximum single card charge comes back as `err.isAboveCardMaximum` (400) with the live figure in `err.message`.
|
|
796
820
|
- Client-side validation (missing fields, bad funding source, quantity outside `1..1000`, total ≠ unit×qty, card total under $0.50, non-E.164 `playerPhone`) throws **before** any network call. The card **maximum** is deliberately not among them: see [The card maximum is INVO's, not the SDK's](#the-card-maximum-is-invos-not-the-sdks).
|
|
797
821
|
- Fulfill on the **`platform_commerce.purchased`** webhook; handle **`platform_commerce.refunded`** for reversals.
|
|
798
822
|
|
|
@@ -809,7 +833,7 @@ A subscription is a standing agreement, created by **your server**, under which
|
|
|
809
833
|
|
|
810
834
|
Each period INVO works out what the period is worth in coins (card: price × the currency's coins-per-USD rate, 10 per USD by default; Steam: what the price buys through Steam for the member's country) and splits it between INVO's platform fee and your revenue. Every figure is reported on the `subscription.renewed` event.
|
|
811
835
|
|
|
812
|
-
- **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 4% plus $0.30 on Open (5% plus $0.50 on Merchant of Record), on the full price ($9.99 pays INVO $0.
|
|
836
|
+
- **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 4.5% plus $0.30 on Open (5.5% plus $0.50 on Merchant of Record), on the full price, plus 1.5% of the listed price (before tax) on a card issued outside the US ($9.99 on a US card pays INVO $0.75 and you $9.24 on Open). On `subscription.renewed`, `split.partner_revenue_usd` stays the gross figure; the international card fee is billed on top of it and reported as `split.international_card_fee_usd`, and `split.pass_through_fees_usd` carries the same figure (one charge reported twice: never add them). Subscriptions are their own rate: item purchases stay at 10/90.
|
|
813
837
|
- **Steam rail: unchanged.** INVO spends the member's wallet first and tops up from Steam for the shortfall only.
|
|
814
838
|
- **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.
|
|
815
839
|
- **`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.
|
|
@@ -1132,7 +1156,7 @@ export const POST = createWebhookHandler({
|
|
|
1132
1156
|
|---|---|
|
|
1133
1157
|
| Has the member paid for the period they are in? | `subscription.renewed` for that period, or `paidThrough` on `get` |
|
|
1134
1158
|
| Should I revoke access? | only on `subscription.expired` (at `final_period_end`) or `subscription.canceled` (at `access_until`); **never** on `payment_failed`, `past_due` or `authentication_required` |
|
|
1135
|
-
| What did I earn? | `split.partner_revenue_usd` on `subscription.renewed`, minus `refund.partner_total_reversed_usd` (revenue reversed plus the card processor fee you bear) on any `subscription.refunded`; on refunds before 2026-09-17, which carry no such field, `refund.partner_revenue_reversed_usd` |
|
|
1159
|
+
| What did I earn? | `split.partner_revenue_usd` on `subscription.renewed`, minus `split.international_card_fee_usd` (the same figure as `split.pass_through_fees_usd`; subtract it once), minus `refund.partner_total_reversed_usd` (revenue reversed plus the card processor fee you bear) on any `subscription.refunded`; on refunds before 2026-09-17, which carry no such field, `refund.partner_revenue_reversed_usd` |
|
|
1136
1160
|
| Should I grant anything on a renewal's `purchase.completed`? | **No.** Every paid card renewal also sends `purchase.completed` (`data.metadata.source === "subscription_renewal"`) for the coins its charge minted, and the renewal spends them in the same step. Act on `subscription.renewed`. The two share the mint order id: `order_id` there is `mint_order_id` here |
|
|
1137
1161
|
| Did a refund end the subscription? | `subscription_canceled` on `subscription.refunded`, and the `subscription.canceled` sent with it (`cancel_cause: "full_refund"`; the two are sent together and may arrive in any order) |
|
|
1138
1162
|
|
|
@@ -2151,9 +2175,9 @@ export const POST = createWebhookHandler({
|
|
|
2151
2175
|
|
|
2152
2176
|
| Event | Fires for | Use it to |
|
|
2153
2177
|
|---|---|---|
|
|
2154
|
-
| `purchase.completed` | every currency-purchase rail, **and every paid card subscription renewal** | grant currency (payload: `transaction_id, order_id, player_email, identity_id, usd_amount, currency_amount, currency_name, new_balance, rail`, `metadata`)
|
|
2178
|
+
| `purchase.completed` | every currency-purchase rail, **and every paid card subscription renewal** | grant currency (payload: `transaction_id, order_id, player_email, identity_id, usd_amount, currency_amount, currency_name, new_balance, rail`, `metadata`). `metadata` echoes what you passed to `createCheckout`/`purchaseCurrency` (all rails); `order_id` is also on every webhook as a secondary reconciliation key (`getOrderDetails`). Card purchases also carry `partner_fee_usd` and `international_card_fee_usd`, the card fees charged to you (the player paid the listed price). **Skip it when `metadata.source` is `"subscription_renewal"`**: those coins are spent by the renewal itself; grant on `subscription.renewed`. |
|
|
2155
2179
|
| `purchase.failed` | `platform` rail only | handle failures |
|
|
2156
|
-
| `purchase.disputed` | `platform` rail, and `steam` chargebacks | handle disputes. A lost chargeback takes back up to the purchase's coins from the available balance, never below zero. A Steam chargeback carries the same keys as a lost card dispute with `payment_intent_id`, `charge_id` and `dispute_id` `null`, plus `rail: "steam"` and `steam_transid`. **If you revoke on `purchase.refunded`, handle this too:** a Steam chargeback no longer arrives as `purchase.refunded` |
|
|
2180
|
+
| `purchase.disputed` | `platform` rail, and `steam` chargebacks | handle disputes. A lost chargeback takes back up to the purchase's coins from the available balance, never below zero. On a lost Platform Commerce card sale or subscription charge dispute (`order_type`), `guarantee_covered: true` means INVO's chargeback guarantee covers it (a fraud chargeback): your share is not reversed or held and no dispute fee is passed to you. Otherwise a lost dispute costs you what a refund would: the card fee stays charged to you on a Platform Commerce sale, and a subscription charge carries `processing_fee_usd`, the processor fee a refund of that period charges (charges made under the 2026-09 pricing). Coin purchase disputes carry neither key: a lost one takes back the player's coins, not your share. A Steam chargeback carries the same keys as a lost card dispute with `payment_intent_id`, `charge_id` and `dispute_id` `null`, plus `rail: "steam"` and `steam_transid`. **If you revoke on `purchase.refunded`, handle this too:** a Steam chargeback no longer arrives as `purchase.refunded` |
|
|
2157
2181
|
| `purchase.refunded` | `game` / `steam` rails | handle refunds. Only coins the player still has from that purchase are taken back, never below zero. A Steam partial refund carries `fully_refunded: false` |
|
|
2158
2182
|
| `item.purchased` | every item purchase | **grant the in-game item** (payload includes `transaction_id, order_id, player_email, identity_id, item_id, item_name, item_quantity, unit_price, total_price, currency_name, new_balance, fee_breakdown`) |
|
|
2159
2183
|
| `platform_commerce.purchased` | every Platform Commerce purchase (balance immediately; **card after payment settles**) | **fulfill the ecommerce order** — never on the browser confirm (payload: `transaction_id, order_id, funding_source, player_email, identity_id, item_id, item_name, item_quantity, total_price`; + `unit_price, currency_name, new_balance` on balance; `total_price_usd` on card; `fee_breakdown`) |
|
|
@@ -2250,10 +2274,10 @@ Helpers:
|
|
|
2250
2274
|
| `.isDuplicateClientRequestId` | Platform Commerce card purchase whose `clientRequestId` already has a payment (409); `order_id` + `order_status` on `.body` |
|
|
2251
2275
|
| `.isIdentityCheckUnavailable` | a claim or confirm-receipt could not be checked just now (503); nothing moved, retry in a few seconds |
|
|
2252
2276
|
| `.isNotPlatformTenant` | Platform Commerce called by a non-platform tenant (403) — use `purchaseItem`/`createCheckout` instead |
|
|
2253
|
-
| `.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) |
|
|
2277
|
+
| `.isAmountBelowMinimum` / `.isBelowCardMinimum` / `.isAboveCardMaximum` | amount too small for the fee to round up / card charge under $0.50 at any date (`.minUsd` `"0.50"`, no `.enforcedFrom`), or from 2026-10-27 under INVO's minimum card purchase of $2.99 (`.minUsd` `"2.99"`, `.enforcedFrom`) / card charge over INVO's maximum single card charge, which is a runtime setting (400) |
|
|
2254
2278
|
| `.isAlreadyRefunded` | Platform Commerce refund of an already-refunded order (409) — treat as already done |
|
|
2255
|
-
| `.isQuoteStale` + `.expectedTotalUsd` | `purchaseCurrency` with an `acknowledgedTotalUsd`
|
|
2256
|
-
| `.isAmountBelowFee` |
|
|
2279
|
+
| `.isQuoteStale` + `.expectedTotalUsd` | `purchaseCurrency` with an `acknowledgedTotalUsd` below the total INVO would charge now (409); nothing charged: quote again. A higher total is accepted and the true total charged |
|
|
2280
|
+
| `.isAmountBelowFee` | deprecated: `AMOUNT_BELOW_FEE` is no longer returned (the partner pays the card fee) |
|
|
2257
2281
|
| `.retryAfter` | seconds to back off on a 429 throttle |
|
|
2258
2282
|
| `.isEnrollmentAuthorizationRequired` | first-enrollment needs the OTP grant → `enrollmentBegin`/`enrollmentVerify` |
|
|
2259
2283
|
| `.isEnrollmentProofRequired` | another method exists → prove it via `linkDevice` |
|
|
@@ -2290,9 +2314,9 @@ try {
|
|
|
2290
2314
|
| `mintPlayerToken({ playerEmail, playerPhone? })` | `{ token, expiresAt, identityId }` — session mint for an **existing** player (404 if unknown); `playerPhone` optional/validated-if-present (see [Player token](#player-token-session-mint-for-an-existing-player)) |
|
|
2291
2315
|
| `initiateSend(input)` | `{ transactionId, verificationMethod, guardianApproval?, raw }` |
|
|
2292
2316
|
| `initiateTransfer(input)` | `{ transactionId, verificationMethod, guardianApproval?, raw }` |
|
|
2293
|
-
| `createCheckout(input)` | `{ sessionId, checkoutUrl, sessionToken?, expiresAt, expiresInSeconds, warnings?, raw }
|
|
2294
|
-
| `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)) |
|
|
2295
|
-
| `purchaseCurrency(input)` | `{ status, clientSecret?, paymentIntentId?, paymentUrl?, transactionId?, orderId?, newBalance?, processingFeeUsd?, feeTakenFrom?, coinsCredited?, chargeTotalUsd?, receiptNumber?, receiptUrl?, raw }`; optional `acknowledgedTotalUsd`
|
|
2317
|
+
| `createCheckout(input)` | `{ sessionId, checkoutUrl, sessionToken?, expiresAt, expiresInSeconds, warnings?, minPurchaseWarning?, raw }` (`minPurchaseWarning` while an amount under INVO's minimum card purchase is still accepted), 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) |
|
|
2318
|
+
| `quoteCurrencyPurchase({ playerEmail, usdAmount, country?, subdivision? })` | `CurrencyPurchaseQuote`: `{ totalUsd, amountCents, subtotalUsd, processingFeeUsd, partnerFeeUsd?, internationalCardFeeUsd?, feeTakenFrom?, minPurchaseWarning?, coins, currencyName, breakdown, ifUnacknowledged, raw }`; moves no money; send `totalUsd` back as `acknowledgedTotalUsd` (see [INVO's card fee](#invos-card-fee-quote-show-acknowledge)) |
|
|
2319
|
+
| `purchaseCurrency(input)` | `{ status, clientSecret?, paymentIntentId?, paymentUrl?, transactionId?, orderId?, newBalance?, processingFeeUsd?, feeTakenFrom?, partnerFeeUsd?, internationalCardFeeUsd?, minPurchaseWarning?, coinsCredited?, chargeTotalUsd?, receiptNumber?, receiptUrl?, raw }`; optional `acknowledgedTotalUsd`, `country` and `subdivision` inputs; `receiptNumber` / `receiptUrl` on Merchant of Record only |
|
|
2296
2320
|
| `confirmPayment({ paymentIntentId, orderId? })` | `{ status, transactionId?, newBalance?, credited?, reasonCode?, raw }`; report success only on `credited: true` |
|
|
2297
2321
|
| `getOrderDetails({ orderId? \| transactionId? })` | `{ order, financialSummary, statusTimeline, receiptNumber?, receiptUrl?, raw }`; the receipt fields on a Merchant of Record currency purchase only |
|
|
2298
2322
|
| `purchaseItem(input)` | `{ status, transactionId, orderId, newBalance, previousBalance, currencyName, financialBreakdown?, raw }` — **game** tenant spending game currency on an in-game item |
|
|
@@ -2300,7 +2324,7 @@ try {
|
|
|
2300
2324
|
| `getItemOrderDetails({ orderId? \| transactionId? \| clientRequestId? })` | `{ order, financialSummary, statusTimeline, raw }` |
|
|
2301
2325
|
| `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` |
|
|
2302
2326
|
| `platformCommerce.getStatus(orderId)` | `{ orderId, status, gameCurrencyAmount?, usdAmount?, paymentMethod?, createdAt?, receiptNumber?, receiptUrl?, raw }` |
|
|
2303
|
-
| `platformCommerce.refund({ orderId? \| clientRequestId?, reason?, refundRemaining?, confirmAdditionalRefund? })` | `{ status, orderId?, fundingSource?, refundedAmount?, amountUnit?, feeRetained?, partialRefund?, adopted?, refundedTotalUsd?, chargeTotalUsd?, remainingUsd?, raw }`; pass **exactly one** id; INVO keeps its fee; `partialRefund`, `refundedTotalUsd`, `chargeTotalUsd`, `remainingUsd` only on a card sale refunded in parts; `adopted` whenever the call recorded an existing refund (a full one included) |
|
|
2327
|
+
| `platformCommerce.refund({ orderId? \| clientRequestId?, reason?, refundRemaining?, confirmAdditionalRefund? })` | `{ status, orderId?, fundingSource?, refundedAmount?, amountUnit?, feeRetained?, partialRefund?, adopted?, refundedTotalUsd?, chargeTotalUsd?, remainingUsd?, cardFeeChargedToPartnerUsd?, partnerDebitedUsd?, raw }`; pass **exactly one** id; INVO keeps its fee (on the card leg it stays charged to you: `cardFeeChargedToPartnerUsd`, `partnerDebitedUsd`); `partialRefund`, `refundedTotalUsd`, `chargeTotalUsd`, `remainingUsd` only on a card sale refunded in parts; `adopted` whenever the call recorded an existing refund (a full one included) |
|
|
2304
2328
|
| `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) |
|
|
2305
2329
|
| `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) |
|
|
2306
2330
|
| `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 |
|
|
@@ -375,11 +375,38 @@ var InvoError = class _InvoError extends Error {
|
|
|
375
375
|
const st = String(b["steam_status"] ?? "").toLowerCase();
|
|
376
376
|
return st !== "init" && st !== "";
|
|
377
377
|
}
|
|
378
|
-
/**
|
|
379
|
-
*
|
|
378
|
+
/**
|
|
379
|
+
* True if a CARD purchase was below the card minimum (`BELOW_CARD_MINIMUM`, 400). Nothing
|
|
380
|
+
* was charged. Two floors answer with this code:
|
|
381
|
+
* - INVO's minimum card purchase, $2.99 by default, on coin purchases and Platform Commerce
|
|
382
|
+
* card sales (not subscriptions), enforced from 2026-10-27. Until that date a smaller
|
|
383
|
+
* purchase is accepted and the response carries `minPurchaseWarning` instead.
|
|
384
|
+
* {@link minUsd} and {@link enforcedFrom} carry the figures in force; the amount and the
|
|
385
|
+
* date are INVO settings, so read them from the error rather than hard-coding them.
|
|
386
|
+
* - the card rail's own floor of $0.50, at any date, on coin purchases (the direct route and
|
|
387
|
+
* hosted checkout session create, complete and create-intent) and Platform Commerce card
|
|
388
|
+
* purchases ({@link minUsd} reads `"0.50"` there, with no {@link enforcedFrom}).
|
|
389
|
+
* {@link minUsd} tells you which floor refused it.
|
|
390
|
+
*
|
|
391
|
+
* Card purchases only; purchases through a third-party storefront or payment rail are
|
|
392
|
+
* unaffected. Raise the amount; do not retry it unchanged.
|
|
393
|
+
*/
|
|
380
394
|
get isBelowCardMinimum() {
|
|
381
395
|
return this.code === "BELOW_CARD_MINIMUM" || this.rawCode === "BELOW_STRIPE_MINIMUM";
|
|
382
396
|
}
|
|
397
|
+
/** On `BELOW_CARD_MINIMUM`: the minimum card purchase in force (`min_usd`), USD decimal
|
|
398
|
+
* string, for example `"2.99"`. `undefined` when the body does not carry it. */
|
|
399
|
+
get minUsd() {
|
|
400
|
+
const v = this.bodyObject()["min_usd"];
|
|
401
|
+
if (typeof v === "number" && Number.isFinite(v)) return v.toFixed(2);
|
|
402
|
+
return typeof v === "string" && v ? v : void 0;
|
|
403
|
+
}
|
|
404
|
+
/** On `BELOW_CARD_MINIMUM`: the date INVO started enforcing the minimum card purchase
|
|
405
|
+
* (`enforced_from`), ISO 8601, for example `"2026-10-27"`. `undefined` when absent. */
|
|
406
|
+
get enforcedFrom() {
|
|
407
|
+
const v = this.bodyObject()["enforced_from"];
|
|
408
|
+
return typeof v === "string" && v ? v : void 0;
|
|
409
|
+
}
|
|
383
410
|
/** True if a CARD purchase exceeded INVO's maximum single card charge
|
|
384
411
|
* (`ABOVE_CARD_MAXIMUM`, 400) — split the sale or lower the amount. Do not retry it
|
|
385
412
|
* unchanged; nothing was charged.
|
|
@@ -394,18 +421,22 @@ var InvoError = class _InvoError extends Error {
|
|
|
394
421
|
}
|
|
395
422
|
// ---- Coin purchase: INVO's card fee (2026-09-23) ----
|
|
396
423
|
/**
|
|
397
|
-
* True when an UNACKNOWLEDGED `purchaseCurrency` was refused because the amount
|
|
398
|
-
* small to carry INVO's card fee (`AMOUNT_BELOW_FEE`, 400). Nothing was charged.
|
|
399
|
-
*
|
|
400
|
-
*
|
|
424
|
+
* True when an UNACKNOWLEDGED `purchaseCurrency` was refused because the amount was too
|
|
425
|
+
* small to carry INVO's card fee (`AMOUNT_BELOW_FEE`, 400). Nothing was charged.
|
|
426
|
+
*
|
|
427
|
+
* @deprecated No longer returned: under the 2026-09 pricing the partner pays the card fee,
|
|
428
|
+
* so it is never in the buyer's charge. Kept so existing code still compiles; a small card
|
|
429
|
+
* purchase now answers `BELOW_CARD_MINIMUM` ({@link isBelowCardMinimum}).
|
|
401
430
|
*/
|
|
402
431
|
get isAmountBelowFee() {
|
|
403
432
|
return this.code === "AMOUNT_BELOW_FEE";
|
|
404
433
|
}
|
|
405
434
|
/**
|
|
406
|
-
* True when `purchaseCurrency` was sent an `acknowledgedTotalUsd`
|
|
407
|
-
*
|
|
408
|
-
*
|
|
435
|
+
* True when `purchaseCurrency` was sent an `acknowledgedTotalUsd` BELOW the total INVO would
|
|
436
|
+
* charge now (`QUOTE_STALE`, 409). Nothing was charged. Quote again, show the player the new
|
|
437
|
+
* total, and retry with it. {@link expectedTotalUsd} carries INVO's figure. A higher
|
|
438
|
+
* acknowledged total (for example an older fee-inclusive one) is not refused: INVO charges
|
|
439
|
+
* the true, lower total.
|
|
409
440
|
*/
|
|
410
441
|
get isQuoteStale() {
|
|
411
442
|
return this.code === "QUOTE_STALE";
|
|
@@ -415,11 +446,28 @@ var InvoError = class _InvoError extends Error {
|
|
|
415
446
|
const v = this.bodyObject()["expected_total_usd"];
|
|
416
447
|
return typeof v === "string" && v ? v : void 0;
|
|
417
448
|
}
|
|
418
|
-
/** On `QUOTE_STALE`: the total you sent, as INVO read it
|
|
449
|
+
/** On `QUOTE_STALE` or `TAX_PLACE_UNAVAILABLE`: the total you sent, as INVO read it
|
|
450
|
+
* (`acknowledged_total_usd`). */
|
|
419
451
|
get acknowledgedTotalUsd() {
|
|
420
452
|
const v = this.bodyObject()["acknowledged_total_usd"];
|
|
421
453
|
return typeof v === "string" && v ? v : void 0;
|
|
422
454
|
}
|
|
455
|
+
/**
|
|
456
|
+
* True when a Merchant of Record `purchaseCurrency` acknowledged a taxed total but INVO could
|
|
457
|
+
* not read the buyer's tax location from the card on this attempt, and the request carried no
|
|
458
|
+
* `country` to fall back on (`TAX_PLACE_UNAVAILABLE`, 409). Nothing was charged. Retry the
|
|
459
|
+
* purchase (a fresh attempt usually reads the card), or send the `country` (and
|
|
460
|
+
* `subdivision`) you quoted with. INVO never drops the tax a buyer was shown, so it refuses
|
|
461
|
+
* rather than charging a different figure. The body carries `retryable: true`.
|
|
462
|
+
*/
|
|
463
|
+
get isTaxPlaceUnavailable() {
|
|
464
|
+
return this.code === "TAX_PLACE_UNAVAILABLE";
|
|
465
|
+
}
|
|
466
|
+
/** On `TAX_PLACE_UNAVAILABLE`: the total without tax (`untaxed_total_usd`), decimal string. */
|
|
467
|
+
get untaxedTotalUsd() {
|
|
468
|
+
const v = this.bodyObject()["untaxed_total_usd"];
|
|
469
|
+
return typeof v === "string" && v ? v : void 0;
|
|
470
|
+
}
|
|
423
471
|
/**
|
|
424
472
|
* True if a Platform Commerce refund targeted an order that was already refunded
|
|
425
473
|
* (409). Idempotent outcome — the original refund did happen, so treat this as
|
|
@@ -1134,5 +1182,5 @@ function receiptFields(raw) {
|
|
|
1134
1182
|
}
|
|
1135
1183
|
|
|
1136
1184
|
export { Http, InvoError, assertSecureBaseUrl, creditFields, receiptFields, toDestinationsResult };
|
|
1137
|
-
//# sourceMappingURL=chunk-
|
|
1138
|
-
//# sourceMappingURL=chunk-
|
|
1185
|
+
//# sourceMappingURL=chunk-YW2PYARQ.js.map
|
|
1186
|
+
//# sourceMappingURL=chunk-YW2PYARQ.js.map
|
package/dist/index.cjs
CHANGED
|
@@ -377,11 +377,38 @@ var InvoError = class _InvoError extends Error {
|
|
|
377
377
|
const st = String(b["steam_status"] ?? "").toLowerCase();
|
|
378
378
|
return st !== "init" && st !== "";
|
|
379
379
|
}
|
|
380
|
-
/**
|
|
381
|
-
*
|
|
380
|
+
/**
|
|
381
|
+
* True if a CARD purchase was below the card minimum (`BELOW_CARD_MINIMUM`, 400). Nothing
|
|
382
|
+
* was charged. Two floors answer with this code:
|
|
383
|
+
* - INVO's minimum card purchase, $2.99 by default, on coin purchases and Platform Commerce
|
|
384
|
+
* card sales (not subscriptions), enforced from 2026-10-27. Until that date a smaller
|
|
385
|
+
* purchase is accepted and the response carries `minPurchaseWarning` instead.
|
|
386
|
+
* {@link minUsd} and {@link enforcedFrom} carry the figures in force; the amount and the
|
|
387
|
+
* date are INVO settings, so read them from the error rather than hard-coding them.
|
|
388
|
+
* - the card rail's own floor of $0.50, at any date, on coin purchases (the direct route and
|
|
389
|
+
* hosted checkout session create, complete and create-intent) and Platform Commerce card
|
|
390
|
+
* purchases ({@link minUsd} reads `"0.50"` there, with no {@link enforcedFrom}).
|
|
391
|
+
* {@link minUsd} tells you which floor refused it.
|
|
392
|
+
*
|
|
393
|
+
* Card purchases only; purchases through a third-party storefront or payment rail are
|
|
394
|
+
* unaffected. Raise the amount; do not retry it unchanged.
|
|
395
|
+
*/
|
|
382
396
|
get isBelowCardMinimum() {
|
|
383
397
|
return this.code === "BELOW_CARD_MINIMUM" || this.rawCode === "BELOW_STRIPE_MINIMUM";
|
|
384
398
|
}
|
|
399
|
+
/** On `BELOW_CARD_MINIMUM`: the minimum card purchase in force (`min_usd`), USD decimal
|
|
400
|
+
* string, for example `"2.99"`. `undefined` when the body does not carry it. */
|
|
401
|
+
get minUsd() {
|
|
402
|
+
const v = this.bodyObject()["min_usd"];
|
|
403
|
+
if (typeof v === "number" && Number.isFinite(v)) return v.toFixed(2);
|
|
404
|
+
return typeof v === "string" && v ? v : void 0;
|
|
405
|
+
}
|
|
406
|
+
/** On `BELOW_CARD_MINIMUM`: the date INVO started enforcing the minimum card purchase
|
|
407
|
+
* (`enforced_from`), ISO 8601, for example `"2026-10-27"`. `undefined` when absent. */
|
|
408
|
+
get enforcedFrom() {
|
|
409
|
+
const v = this.bodyObject()["enforced_from"];
|
|
410
|
+
return typeof v === "string" && v ? v : void 0;
|
|
411
|
+
}
|
|
385
412
|
/** True if a CARD purchase exceeded INVO's maximum single card charge
|
|
386
413
|
* (`ABOVE_CARD_MAXIMUM`, 400) — split the sale or lower the amount. Do not retry it
|
|
387
414
|
* unchanged; nothing was charged.
|
|
@@ -396,18 +423,22 @@ var InvoError = class _InvoError extends Error {
|
|
|
396
423
|
}
|
|
397
424
|
// ---- Coin purchase: INVO's card fee (2026-09-23) ----
|
|
398
425
|
/**
|
|
399
|
-
* True when an UNACKNOWLEDGED `purchaseCurrency` was refused because the amount
|
|
400
|
-
* small to carry INVO's card fee (`AMOUNT_BELOW_FEE`, 400). Nothing was charged.
|
|
401
|
-
*
|
|
402
|
-
*
|
|
426
|
+
* True when an UNACKNOWLEDGED `purchaseCurrency` was refused because the amount was too
|
|
427
|
+
* small to carry INVO's card fee (`AMOUNT_BELOW_FEE`, 400). Nothing was charged.
|
|
428
|
+
*
|
|
429
|
+
* @deprecated No longer returned: under the 2026-09 pricing the partner pays the card fee,
|
|
430
|
+
* so it is never in the buyer's charge. Kept so existing code still compiles; a small card
|
|
431
|
+
* purchase now answers `BELOW_CARD_MINIMUM` ({@link isBelowCardMinimum}).
|
|
403
432
|
*/
|
|
404
433
|
get isAmountBelowFee() {
|
|
405
434
|
return this.code === "AMOUNT_BELOW_FEE";
|
|
406
435
|
}
|
|
407
436
|
/**
|
|
408
|
-
* True when `purchaseCurrency` was sent an `acknowledgedTotalUsd`
|
|
409
|
-
*
|
|
410
|
-
*
|
|
437
|
+
* True when `purchaseCurrency` was sent an `acknowledgedTotalUsd` BELOW the total INVO would
|
|
438
|
+
* charge now (`QUOTE_STALE`, 409). Nothing was charged. Quote again, show the player the new
|
|
439
|
+
* total, and retry with it. {@link expectedTotalUsd} carries INVO's figure. A higher
|
|
440
|
+
* acknowledged total (for example an older fee-inclusive one) is not refused: INVO charges
|
|
441
|
+
* the true, lower total.
|
|
411
442
|
*/
|
|
412
443
|
get isQuoteStale() {
|
|
413
444
|
return this.code === "QUOTE_STALE";
|
|
@@ -417,11 +448,28 @@ var InvoError = class _InvoError extends Error {
|
|
|
417
448
|
const v = this.bodyObject()["expected_total_usd"];
|
|
418
449
|
return typeof v === "string" && v ? v : void 0;
|
|
419
450
|
}
|
|
420
|
-
/** On `QUOTE_STALE`: the total you sent, as INVO read it
|
|
451
|
+
/** On `QUOTE_STALE` or `TAX_PLACE_UNAVAILABLE`: the total you sent, as INVO read it
|
|
452
|
+
* (`acknowledged_total_usd`). */
|
|
421
453
|
get acknowledgedTotalUsd() {
|
|
422
454
|
const v = this.bodyObject()["acknowledged_total_usd"];
|
|
423
455
|
return typeof v === "string" && v ? v : void 0;
|
|
424
456
|
}
|
|
457
|
+
/**
|
|
458
|
+
* True when a Merchant of Record `purchaseCurrency` acknowledged a taxed total but INVO could
|
|
459
|
+
* not read the buyer's tax location from the card on this attempt, and the request carried no
|
|
460
|
+
* `country` to fall back on (`TAX_PLACE_UNAVAILABLE`, 409). Nothing was charged. Retry the
|
|
461
|
+
* purchase (a fresh attempt usually reads the card), or send the `country` (and
|
|
462
|
+
* `subdivision`) you quoted with. INVO never drops the tax a buyer was shown, so it refuses
|
|
463
|
+
* rather than charging a different figure. The body carries `retryable: true`.
|
|
464
|
+
*/
|
|
465
|
+
get isTaxPlaceUnavailable() {
|
|
466
|
+
return this.code === "TAX_PLACE_UNAVAILABLE";
|
|
467
|
+
}
|
|
468
|
+
/** On `TAX_PLACE_UNAVAILABLE`: the total without tax (`untaxed_total_usd`), decimal string. */
|
|
469
|
+
get untaxedTotalUsd() {
|
|
470
|
+
const v = this.bodyObject()["untaxed_total_usd"];
|
|
471
|
+
return typeof v === "string" && v ? v : void 0;
|
|
472
|
+
}
|
|
425
473
|
/**
|
|
426
474
|
* True if a Platform Commerce refund targeted an order that was already refunded
|
|
427
475
|
* (409). Idempotent outcome — the original refund did happen, so treat this as
|
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-BnnVi5ws.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-BnnVi5ws.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-BnnVi5ws.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-BnnVi5ws.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, receiptFields } from './chunk-
|
|
2
|
-
export { InvoError } from './chunk-
|
|
1
|
+
import { InvoError, assertSecureBaseUrl, Http, toDestinationsResult, receiptFields } from './chunk-YW2PYARQ.js';
|
|
2
|
+
export { InvoError } from './chunk-YW2PYARQ.js';
|
|
3
3
|
|
|
4
4
|
// src/shared/webauthn.ts
|
|
5
5
|
function malformedOptions(field) {
|