@invonetwork/web-sdk 3.17.0 → 3.19.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,36 @@
1
1
  # Changelog
2
2
 
3
+ ## 3.19.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 6940139: D-PRICE-012: a subscription card refund, and a lost chargeback not covered by the chargeback guarantee, now cost the partner the whole refunded amount, INVO's card fee included, exactly as a Platform Commerce card refund does. There is no separate payment processor fee on a refund any more: `processingFeeUsd` reads `"0.00"` and `processingFeeBasis` `"none"`.
8
+
9
+ Additive, optional fields:
10
+
11
+ - `RefundResult.cardFeeChargedToPartnerUsd` and `RefundResult.partnerDebitedUsd` on `subscriptions.refund` (the 200 receipt and the 202 `pending_approval` body). `undefined` on a receipt stored before this release.
12
+ - `card_fee_charged_to_partner_usd` and `partner_debited_usd` on the `refund` block of `subscription.refunded` (`SubscriptionRefundDetail`) and on `purchase.disputed` (`PurchaseEventData`, subscription and Platform Commerce losses; `null` where not applicable).
13
+
14
+ README: subscription refund costs, lost chargebacks and the "What did I earn?" answer updated.
15
+
16
+ ## 3.18.0
17
+
18
+ ### Minor Changes
19
+
20
+ - 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:
21
+
22
+ - `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"`.
23
+ - `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.
24
+ - `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.
25
+ - `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`).
26
+ - `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`.
27
+ - `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`.
28
+ - `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.
29
+ - 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).
30
+ - 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).
31
+ - 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.
32
+ - 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).
33
+
3
34
  ## 3.17.0
4
35
 
5
36
  ### 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 charges are now **4% + $0.30** on Open and **5% + $0.50** on Merchant of Record, international card and currency conversion costs on subscriptions pass through at cost, chargeback handling by tier, 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)** (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).
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 | 3.5% + $0.30 | 5% + $0.30 |
299
- | Subscriptions | 4% + $0.30 per card charge | 5% + $0.50 per card charge |
300
- | 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 |
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. On subscription card charges made on a card issued outside the United States, or needing a currency conversion, the extra processing cost is passed through to you at INVO's actual cost, reported separately from INVO's fee. 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 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/
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: $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)).
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 $0.50. The maximum is an INVO setting
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'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.
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 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:
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
- - **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.
630
- - **Send only `usdAmount`.** The card is charged **exactly `usdAmount`, never more**, and the fee comes out of the coins instead.
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.65" = q.totalUsd "10.65" (q.coins "100.00")
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.ifUnacknowledged: { chargeTotalUsd: "10.00", processingFeeUsd: "0.63", coins: "93.70", feeTakenFrom: "coins" }
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.65"). 3) Charge exactly what they saw:
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.65": the card is charged this, to the cent
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.65", purchase.processingFeeUsd "0.65",
652
- // purchase.feeTakenFrom "charge", purchase.coinsCredited "100.00"
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
- 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.
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 not the total INVO would charge now | nothing was charged; quote again, show `err.expectedTotalUsd`, retry with the new total and a new `purchaseReference` |
660
- | `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 |
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 four fee fields; `requires_action` and `pending_payment` do not. Storefront rails bill no INVO card fee: the storefront takes its own cut.
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 retains its fee (ref.feeRetained === true); the customer is made whole minus that fee.
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) · **3.5% + $0.30** (card). Too-small amounts throw `err.isAmountBelowMinimum` / `err.isBelowCardMinimum` (card < $0.50); a card total over INVO's maximum single card charge comes back as `err.isAboveCardMaximum` (400) with the live figure in `err.message`.
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.70 and you $9.29 on Open). Subscriptions are their own rate: item purchases stay at 10/90.
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.
@@ -1110,9 +1134,10 @@ export const POST = createWebhookHandler({
1110
1134
  case "subscription.expired": // the retry budget ran out (or a Steam row was never authorised)
1111
1135
  await revokeAt(event.data.subscription_id, event.data.final_period_end); // NOT ended_at; null if nothing was ever paid
1112
1136
  break; // failure_code "steam_containment" is no longer sent (spending is not restricted by origin)
1113
- case "subscription.refunded": { // your revenue is reversed, plus the processor fee on a card refund
1114
- const r = event.data.refund; // older events carry no partner_total_reversed_usd
1115
- await recordReversal(event.data.subscription_id, r.partner_total_reversed_usd ?? r.partner_revenue_reversed_usd);
1137
+ case "subscription.refunded": { // your revenue is reversed, plus INVO's card fee on a card refund
1138
+ const r = event.data.refund; // older events carry no partner_debited_usd / partner_total_reversed_usd
1139
+ await recordReversal(event.data.subscription_id,
1140
+ r.partner_debited_usd ?? r.partner_total_reversed_usd ?? r.partner_revenue_reversed_usd);
1116
1141
  break; // event.data.subscription_canceled: a full refund cancels (subscription.canceled is sent with it)
1117
1142
  }
1118
1143
  case "subscription.refund_requested": // a refund over your daily limit is waiting for INVO; nothing moved
@@ -1132,7 +1157,7 @@ export const POST = createWebhookHandler({
1132
1157
  |---|---|
1133
1158
  | Has the member paid for the period they are in? | `subscription.renewed` for that period, or `paidThrough` on `get` |
1134
1159
  | 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` |
1160
+ | 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_debited_usd` (revenue reversed plus INVO's card fee: the whole refunded price) on any `subscription.refunded`; on refunds before 2026-09-28, `refund.partner_total_reversed_usd`, and before 2026-09-17, which carry neither, `refund.partner_revenue_reversed_usd`; minus `partner_debited_usd` on a lost chargeback (`purchase.disputed`) |
1136
1161
  | 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
1162
  | 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
1163
 
@@ -1180,7 +1205,8 @@ if (isRefundPendingApproval(r)) { // narrows r; status =
1180
1205
  // r.status === "refunded". r.isFullRefund, r.fundingShape ("card" for every card period since 2026-09-17),
1181
1206
  // r.cardRefundedUsd (card-only periods: equals the amount, partial included), r.balanceDeltaCoins,
1182
1207
  // r.partnerRevenueReversedUsd (your revenue reversed; INVO's fee is retained),
1183
- // r.processingFeeUsd (the card processor fee you bear), r.partnerTotalReversedUsd (the two together),
1208
+ // r.cardFeeChargedToPartnerUsd (INVO's card fee on the refunded part, charged to you),
1209
+ // r.partnerDebitedUsd (the two together: the whole refunded price), r.processingFeeUsd ("0.00" since 2026-09-28),
1184
1210
  // r.subscriptionCanceled (a full refund cancels the subscription), r.idempotentReplay on a repeat,
1185
1211
  // r.revenueShareAttribution?.netAttributedAmountUsd (the corrected figure to pay your recipient).
1186
1212
  }
@@ -1192,7 +1218,8 @@ for (const w of r.warnings ?? []) log(w.code); // "REASON_RECOMMENDED"
1192
1218
  **What else happens.**
1193
1219
 
1194
1220
  - **A full refund cancels the subscription** immediately (`subscriptionCanceled: true`, `subscriptionStatus: "canceled"`), and you receive `subscription.canceled` (`canceled_by: "partner"`, `cancel_cause: "full_refund"`) together with `subscription.refunded`; the two are sent together and may arrive in any order. A partial refund leaves it live. Before 2026-09-17 a full refund did not cancel.
1195
- - **You bear the card processor fee** on any refund that returns money to a card: `processingFeeUsd` (`processingFeeBasis` `actual` or `estimated`, `processingFeeBorneBy: "partner"`) is deducted from your revenue as its own line. `partnerTotalReversedUsd` is your revenue reversed plus that fee. A coin refund has no fee.
1221
+ - **You bear the whole refunded amount, INVO's card fee included** (since 2026-09-28), on any refund that returns money to a card, exactly as on a Platform Commerce card refund: your revenue is reversed and INVO's card fee on the refunded part is deducted from your revenue as its own line (`cardFeeChargedToPartnerUsd`). Across partial refunds of one charge it adds up to exactly INVO's fee on it. `partnerDebitedUsd` (and `partnerTotalReversedUsd`, the same value) is the two together, which equals the refunded price before tax. There is no separate payment processor fee: `processingFeeUsd` reads `"0.00"` (`processingFeeBasis: "none"`). The 1.5% international card fee is not returned. A coin refund has no fee. Example, Open tier, US card: a $9.99 period refunded in full reverses $9.24 of revenue and charges the $0.75 card fee, a $9.99 debit; a $100 period leaves you at -$4.80 (-$6.30 on a card issued outside the US). A receipt stored before 2026-09-28 (a replay) carries neither new field.
1222
+ - **A lost chargeback costs what a refund does.** Not covered by the chargeback guarantee, it reverses your share and charges INVO's card fee on every charge (`purchase.disputed`: `card_fee_charged_to_partner_usd`, `partner_debited_usd`). A fraud chargeback the guarantee covers costs you nothing; the Open-tier dispute fee pass-through is unchanged.
1196
1223
  - **INVO emails the member** when a refund executes (the amount, where it went, and whether the subscription ended). Your `reason` is not in that email.
1197
1224
  - **Refunds of periods charged through Steam are not supported yet**: `409 STEAM_REFUND_NOT_SUPPORTED` (`err.isSteamRefundNotSupported`); periods of a Steam subscription that the wallet covered entirely are refundable in coins.
1198
1225
 
@@ -2151,9 +2178,9 @@ export const POST = createWebhookHandler({
2151
2178
 
2152
2179
  | Event | Fires for | Use it to |
2153
2180
  |---|---|---|
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`) — `metadata` echoes what you passed to `createCheckout`/`purchaseCurrency` (all rails); `order_id` is also on every webhook as a secondary reconciliation key (`getOrderDetails`). **Skip it when `metadata.source` is `"subscription_renewal"`**: those coins are spent by the renewal itself; grant on `subscription.renewed`. |
2181
+ | `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
2182
  | `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` |
2183
+ | `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: your share is reversed and INVO's card fee stays charged to you, on a Platform Commerce sale and on every subscription charge (`card_fee_charged_to_partner_usd`, and `partner_debited_usd` = share reversed plus that fee, since 2026-09-28). A subscription dispute also carries `processing_fee_usd`, which reads `"0.00"`. Coin purchase disputes carry none of these keys: 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
2184
  | `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
2185
  | `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
2186
  | `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`) |
@@ -2163,7 +2190,7 @@ export const POST = createWebhookHandler({
2163
2190
  | `subscription.authentication_required` | a card issuer wants the cardholder to authenticate (card rail) | **not a failure** — relay `confirmation_url` before `expires_at` |
2164
2191
  | `subscription.canceled` | a cancel request (yours, or the member's from Steam: `canceled_by`), or a full refund (`cancel_cause: "full_refund"`) | revoke at `access_until` |
2165
2192
  | `subscription.expired` | the retry budget ran out, or a Steam row was never authorised (`steam_authorization_abandoned`). `steam_containment` is **no longer returned**: spending is not restricted by which rail bought the currency | **revoke at `final_period_end`** (not `ended_at`; `null` if nothing was ever paid) |
2166
- | `subscription.refunded` | a period refund | record the reversal (`refund.partner_total_reversed_usd` = revenue reversed plus the card processor fee you bear, `refund.partner_revenue_reversed_usd`, `refund.processing_fee_usd`, `is_full_refund`, `subscription_canceled`, `initiation`, `refund_request_id`, `revenue_share_attribution`) |
2193
+ | `subscription.refunded` | a period refund | record the reversal (`refund.partner_debited_usd` = revenue reversed plus INVO's card fee, the whole refunded price; `refund.card_fee_charged_to_partner_usd`; `refund.partner_total_reversed_usd`, the same value as `partner_debited_usd`; `refund.partner_revenue_reversed_usd`, `refund.processing_fee_usd` (`"0.00"` since 2026-09-28), `is_full_refund`, `subscription_canceled`, `initiation`, `refund_request_id`, `revenue_share_attribution`) |
2167
2194
  | `subscription.refund_requested` / `subscription.refund_approved` / `subscription.refund_rejected` | a refund over the game's daily self-serve limit became a request / INVO approved it (sent together with `subscription.refunded`, and `subscription.canceled` on a full refund, in any order) / INVO rejected it | track the request (`request_id, status, subscription_id, item_id, period_seq, client_request_id, amount_usd, reason, requested_at, daily_cap_usd, executed_today_usd, player_email, identity_id, metadata`; approved adds `decided_at, transaction_id`; rejected adds `decided_at, decision_reason`) |
2168
2195
  | `transfer.received` / `transfer.claim_expired` / `transfer.refunded` | sends & transfers | reconcile claim state — credited to the recipient (by any claim path, the hosted claim page included) / not collected within 24h / returned to the sender |
2169
2196
 
@@ -2250,10 +2277,10 @@ Helpers:
2250
2277
  | `.isDuplicateClientRequestId` | Platform Commerce card purchase whose `clientRequestId` already has a payment (409); `order_id` + `order_status` on `.body` |
2251
2278
  | `.isIdentityCheckUnavailable` | a claim or confirm-receipt could not be checked just now (503); nothing moved, retry in a few seconds |
2252
2279
  | `.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) |
2280
+ | `.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
2281
  | `.isAlreadyRefunded` | Platform Commerce refund of an already-refunded order (409) — treat as already done |
2255
- | `.isQuoteStale` + `.expectedTotalUsd` | `purchaseCurrency` with an `acknowledgedTotalUsd` that is no longer the total (409); nothing charged: quote again |
2256
- | `.isAmountBelowFee` | unacknowledged `purchaseCurrency` too small to carry INVO's card fee (400); nothing charged |
2282
+ | `.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 |
2283
+ | `.isAmountBelowFee` | deprecated: `AMOUNT_BELOW_FEE` is no longer returned (the partner pays the card fee) |
2257
2284
  | `.retryAfter` | seconds to back off on a 429 throttle |
2258
2285
  | `.isEnrollmentAuthorizationRequired` | first-enrollment needs the OTP grant → `enrollmentBegin`/`enrollmentVerify` |
2259
2286
  | `.isEnrollmentProofRequired` | another method exists → prove it via `linkDevice` |
@@ -2290,9 +2317,9 @@ try {
2290
2317
  | `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
2318
  | `initiateSend(input)` | `{ transactionId, verificationMethod, guardianApproval?, raw }` |
2292
2319
  | `initiateTransfer(input)` | `{ transactionId, verificationMethod, guardianApproval?, raw }` |
2293
- | `createCheckout(input)` | `{ sessionId, checkoutUrl, sessionToken?, expiresAt, expiresInSeconds, warnings?, 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) |
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` input; `receiptNumber` / `receiptUrl` on Merchant of Record only |
2320
+ | `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) |
2321
+ | `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)) |
2322
+ | `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
2323
  | `confirmPayment({ paymentIntentId, orderId? })` | `{ status, transactionId?, newBalance?, credited?, reasonCode?, raw }`; report success only on `credited: true` |
2297
2324
  | `getOrderDetails({ orderId? \| transactionId? })` | `{ order, financialSummary, statusTimeline, receiptNumber?, receiptUrl?, raw }`; the receipt fields on a Merchant of Record currency purchase only |
2298
2325
  | `purchaseItem(input)` | `{ status, transactionId, orderId, newBalance, previousBalance, currencyName, financialBreakdown?, raw }` — **game** tenant spending game currency on an in-game item |
@@ -2300,7 +2327,7 @@ try {
2300
2327
  | `getItemOrderDetails({ orderId? \| transactionId? \| clientRequestId? })` | `{ order, financialSummary, statusTimeline, raw }` |
2301
2328
  | `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
2329
  | `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) |
2330
+ | `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
2331
  | `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
2332
  | `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
2333
  | `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
- /** True if a Platform Commerce CARD purchase was below the processor's floor of $0.50
379
- * (backend code `BELOW_STRIPE_MINIMUM`, 400). Neutral name; matches the wire code. */
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 is too
398
- * small to carry INVO's card fee (`AMOUNT_BELOW_FEE`, 400). Nothing was charged. Send a
399
- * larger amount, or quote it with `quoteCurrencyPurchase` and send `acknowledgedTotalUsd`
400
- * so the fee is added on top.
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` that is not the total
407
- * INVO would charge now (`QUOTE_STALE`, 409). Nothing was charged. Quote again, show the
408
- * player the new total, and retry with it. {@link expectedTotalUsd} carries INVO's figure.
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 (`acknowledged_total_usd`). */
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-JGDNPNQX.js.map
1138
- //# sourceMappingURL=chunk-JGDNPNQX.js.map
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
- /** True if a Platform Commerce CARD purchase was below the processor's floor of $0.50
381
- * (backend code `BELOW_STRIPE_MINIMUM`, 400). Neutral name; matches the wire code. */
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 is too
400
- * small to carry INVO's card fee (`AMOUNT_BELOW_FEE`, 400). Nothing was charged. Send a
401
- * larger amount, or quote it with `quoteCurrencyPurchase` and send `acknowledgedTotalUsd`
402
- * so the fee is added on top.
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` that is not the total
409
- * INVO would charge now (`QUOTE_STALE`, 409). Nothing was charged. Quote again, show the
410
- * player the new total, and retry with it. {@link expectedTotalUsd} carries INVO's figure.
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 (`acknowledged_total_usd`). */
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