@invonetwork/web-sdk 3.30.0 → 3.30.2

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,21 @@
1
1
  # Changelog
2
2
 
3
+ ## 3.30.2
4
+
5
+ ### Patch Changes
6
+
7
+ - Docs and docstrings follow the 2026-10-15 pricing: INVO card fee 3.5% + $0.15 on Open and 5.0% + $0.15 on Merchant of Record (was 3.5% + $0.30 and 5.5% + $0.50), plus 1.5% on cards issued outside the US; item purchases 5% (you keep 95%). Worked examples recomputed ($10.00 coin pack: $0.50 Open, $0.65 MoR). No code or API change.
8
+
9
+ ## 3.30.1
10
+
11
+ ### Patch Changes
12
+
13
+ - Demo key: `POST /transfers/{id}/approve` no longer returns the claim code to the sender's browser (`claimCode` is always `null`). The game server keeps it and collects for the recipient, so the browser never needed it.
14
+ - UI kit: moves to INVO Demo Arcade on the demo key are described as delivered automatically once approved, matching the backend, instead of refunded after 24 hours.
15
+ - Game server: a purchase is confirmed even when the signed webhook can't reach the server (for example a private `*.replit.dev` development preview, which refuses requests that don't come from a signed-in browser). While a purchase is pending, `GET /purchases/{ref}` reads the checkout's status from INVO server-side, with the session token kept on the server, and credits from INVO's answer. The webhook and the status read credit under the same ledger ref, so whichever lands first wins and the other is a no-op. The browser's word is never used.
16
+ - `InvoServer.getCheckoutStatus({ sessionId, sessionToken })`: the server-side read of a hosted checkout's status.
17
+ - Nothing removed or renamed.
18
+
3
19
  ## 3.30.0
4
20
 
5
21
  ### 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.23.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.23.0** types two optional fields on the `purchase.disputed` close: `dispute_fee_usd` and `dispute_fee_charged_to_partner` (from November 8, 2026 the card dispute fee on Open-tier card sales is passed through to you at cost); **3.22.0** follows INVO's 2026-10 pricing: the Open card fee is **3.5% + $0.30** (was 4.5%), Merchant of Record stays **5.5% + $0.50**; the **chargeback guarantee** is a Merchant of Record term (Open-tier card payments made before November 8, 2026 keep it); payouts to your bank carry a **1% fee, capped at $500 per payout**. New reads: `getPlayerActivity()` / `iteratePlayerActivity()` (one merged list of a player's purchases, sends and transfers) and `platformCommerce.getPurchaseHistory()` / `iteratePurchaseHistory()`; `expiryReason` on `getTransferStatus()` / `getSendStatus()`; typed `transfer.*` and `payout.status_changed` webhook fields; new additive `err.publicCode` (the neutral twin of a code), set to `"BELOW_CARD_MINIMUM"` on the local card-floor refusal, whose `err.code` is unchanged (see [Tiers](#tiers) for the pricing); and the **[player-confirmed phone change](#player-confirmed-phone-change)**: `requestPhoneChange()` / `getPhoneChange()` on the server, `listPhoneChangeApprovals()` / `approvePhoneChange()` on the player's enrolled device, the typed `player.phone_changed` webhook, `err.changeRequestEndpoint` and new phone change error helpers; **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).
5
+ > **Status:** `v3.23.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.23.0** types two optional fields on the `purchase.disputed` close: `dispute_fee_usd` and `dispute_fee_charged_to_partner` (from November 8, 2026 the card dispute fee on Open-tier card sales is passed through to you at cost); **3.22.0** follows INVO's 2026-10 pricing: the Open card fee is **3.5% + $0.15** (was 4.5%), Merchant of Record stays **5.0% + $0.15**; the **chargeback guarantee** is a Merchant of Record term (Open-tier card payments made before November 8, 2026 keep it); payouts to your bank carry a **1% fee, capped at $500 per payout**. New reads: `getPlayerActivity()` / `iteratePlayerActivity()` (one merged list of a player's purchases, sends and transfers) and `platformCommerce.getPurchaseHistory()` / `iteratePurchaseHistory()`; `expiryReason` on `getTransferStatus()` / `getSendStatus()`; typed `transfer.*` and `payout.status_changed` webhook fields; new additive `err.publicCode` (the neutral twin of a code), set to `"BELOW_CARD_MINIMUM"` on the local card-floor refusal, whose `err.code` is unchanged (see [Tiers](#tiers) for the pricing); and the **[player-confirmed phone change](#player-confirmed-phone-change)**: `requestPhoneChange()` / `getPhoneChange()` on the server, `listPhoneChangeApprovals()` / `approvePhoneChange()` on the player's enrolled device, the typed `player.phone_changed` webhook, `err.changeRequestEndpoint` and new phone change error helpers; **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.0% + $0.15** 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
@@ -482,21 +482,21 @@ Every INVO developer account is on one of two tiers. The SDK calls are the same
482
482
  | Who it is for | every account, including all current ones | accounts INVO has approved |
483
483
  | Who the seller is | **you** | **INVO** |
484
484
  | Tax on sales | **you** are responsible for it; INVO collects none | **INVO** calculates, collects and remits it |
485
- | Card purchase of coins | 3.5% + $0.30 | 5.5% + $0.50 |
486
- | Platform Commerce card sales | 3.5% + $0.30 | 5.5% + $0.50 |
487
- | Subscriptions | 3.5% + $0.30 per card charge | 5.5% + $0.50 per card charge |
485
+ | Card purchase of coins | 3.5% + $0.15 | 5.0% + $0.15 |
486
+ | Platform Commerce card sales | 3.5% + $0.15 | 5.0% + $0.15 |
487
+ | Subscriptions | 3.5% + $0.15 per card charge | 5.0% + $0.15 per card charge |
488
488
  | Card issued outside the US | plus 1.5% of the listed price (before tax) | plus 1.5% of the listed price (before tax) |
489
489
  | 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 |
490
490
  | Fraud screening | included on every card payment | included on every card payment |
491
491
  | Chargebacks disputed as fraud (card sales) | card payments made **before November 8, 2026** keep the **chargeback guarantee**; from that date a lost one is your responsibility, passed through at cost | **chargeback guarantee**: INVO absorbs a lost one; your share is not reversed or held, and no dispute fee is passed to you |
492
492
  | Other chargebacks | the disputed amount comes out of your share; on subscription charges the dispute fee is passed through too, and from November 8, 2026 on every card sale (coin purchases, Platform Commerce card sales and subscription charges), at cost | INVO manages the dispute and pays the dispute fee; the disputed amount comes out of your share and is restored if INVO wins |
493
493
  | Minimum card purchase (coins, Platform Commerce card sales) | $2.99, enforced from 2026-10-27 | $2.99, enforced from 2026-10-27 |
494
- | Item purchases (coins spent on an item) | 10% (you keep 90%) | 10% (you keep 90%) |
494
+ | Item purchases (coins spent on an item) | 5% (you keep 95%) | 5% (you keep 95%) |
495
495
  | Platform Commerce balance purchases | 3.5% | 3.5% |
496
496
  | Sends and transfers between players | 10% of the amount: 3.5% to the sending title, 3.5% to the receiving title, 3% to INVO | same |
497
497
  | Payouts to your bank | 1% per payout, capped at $500 | 1% per payout, capped at $500 |
498
498
 
499
- 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 $3.80 on Open or $6.00 on Merchant of Record; on a card issued outside the US, $5.30 or $7.50. On a $10.00 sale: $0.65 or $1.05. The Open card fee was 4.5% + $0.30 until 2026-10-09. 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/
499
+ 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 $3.65 on Open or $5.15 on Merchant of Record; on a card issued outside the US, $5.15 or $6.65. On a $10.00 sale: $0.50 or $0.65. The Open card fee was 4.5% + $0.30 until 2026-10-09 and 3.5% + $0.30 until 2026-10-15; Merchant of Record was 5.5% + $0.50 until 2026-10-15. 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/
500
500
 
501
501
  **Chargeback guarantee by tier.** The guarantee (INVO absorbs a lost fraud chargeback on a card sale) is a Merchant of Record term. On Open, card payments made before November 8, 2026 keep it; for card payments from that date, a lost fraud chargeback is your responsibility and is passed through at cost, like any other lost chargeback. Fraud screening stays included on every card payment on both tiers. On a lost dispute, `guarantee_covered` on `purchase.disputed` says which case applies. When a card dispute closes, `purchase.disputed` also carries `dispute_fee_usd` (the dispute fee charged to you for that dispute, `"0.00"` when INVO bears it) and `dispute_fee_charged_to_partner`. A lost dispute is `purchase.disputed` with `dispute_status: "lost"`; there is no separate lost-dispute event.
502
502
 
@@ -827,7 +827,7 @@ Show "purchase complete" only when `credited` is `true`. `alreadyProcessed` is a
827
827
 
828
828
  ### INVO's card fee: quote, show, acknowledge
829
829
 
830
- 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: **3.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 on every card payment. On Merchant of Record a fraud chargeback on a card sale is covered by INVO's [chargeback guarantee](#tiers); on Open only card payments made before November 8, 2026 keep it. These terms apply to card purchases only; purchases through a third-party storefront or payment rail are unaffected.
830
+ 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: **3.5% + $0.15** on the Open [tier](#tiers), **5.0% + $0.15** 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 on every card payment. On Merchant of Record a fraud chargeback on a card sale is covered by INVO's [chargeback guarantee](#tiers); on Open only card payments made before November 8, 2026 keep it. These terms apply to card purchases only; purchases through a third-party storefront or payment rail are unaffected.
831
831
 
832
832
  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:
833
833
 
@@ -842,7 +842,7 @@ const q = await server.quoteCurrencyPurchase({
842
842
  // country: "US", subdivision: "NY", // optional: the buyer's billing place, for any tax
843
843
  });
844
844
  // q.subtotalUsd "10.00" + q.processingFeeUsd "0.00" = q.totalUsd "10.00" (q.coins "100.00")
845
- // q.partnerFeeUsd "0.65" when INVO sends it: YOUR fee (Open, US card), never the player's
845
+ // q.partnerFeeUsd "0.50" when INVO sends it: YOUR fee (Open, US card), never the player's
846
846
  // q.breakdown: every line, with taxNote / processingFeeNote sentences you can show as is
847
847
  // q.minPurchaseWarning: set while an amount under the minimum card purchase is still accepted
848
848
 
@@ -856,7 +856,7 @@ const purchase = await server.purchaseCurrency({
856
856
  });
857
857
  // On "success": purchase.chargeTotalUsd "10.00", purchase.coinsCredited "100.00",
858
858
  // purchase.processingFeeUsd "0.00", purchase.feeTakenFrom "partner",
859
- // purchase.partnerFeeUsd "0.65" (Open; "1.05" on Merchant of Record),
859
+ // purchase.partnerFeeUsd "0.50" (Open; "0.65" on Merchant of Record),
860
860
  // purchase.internationalCardFeeUsd "0.00" ("0.15" on a card issued outside the US)
861
861
  ```
862
862
 
@@ -913,7 +913,7 @@ const item = await server.purchaseItem({
913
913
  - **Insufficient balance** throws `400` (`err.isInsufficientBalance`; `required_amount` + `current_balance` on `err.body`).
914
914
  - **Throttled** calls throw `429` with `err.retryAfter` (seconds).
915
915
  - Client-side validation (missing fields, quantity outside `1..1000`, bad price, total ≠ unit×qty) throws `INVALID_INPUT` **before** any network call.
916
- - Fee split: **90% developer / 10% INVO** by default (per-partner override). Not guardian-gated.
916
+ - Fee split: **95% developer / 5% INVO** by default (per-partner override). Not guardian-gated.
917
917
 
918
918
  **Companion reads:** `server.getItemPurchaseHistory({ playerEmail, limit?, offset? })` and `server.getItemOrderDetails({ orderId | transactionId | clientRequestId })` (pass **exactly one** id — use `clientRequestId` for recovery: "did this purchase complete?"). To walk the full history, `for await (const row of server.iterateItemPurchaseHistory({ playerEmail }))` pages automatically.
919
919
 
@@ -1024,7 +1024,7 @@ await server.platformCommerce.refund({ orderId, refundRemaining: true });
1024
1024
  - `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.
1025
1025
 
1026
1026
  - **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.
1027
- - INVO fee: **3.5% flat** (balance) · **3.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`.
1027
+ - INVO fee: **3.5% flat** (balance) · **3.5% + $0.15** on Open, **5.0% + $0.15** 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`.
1028
1028
  - 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).
1029
1029
  - Fulfill on the **`platform_commerce.purchased`** webhook; handle **`platform_commerce.refunded`** for reversals.
1030
1030
 
@@ -1041,7 +1041,7 @@ A subscription is a standing agreement, created by **your server**, under which
1041
1041
 
1042
1042
  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.
1043
1043
 
1044
- - **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 3.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.65 and you $9.34 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.
1044
+ - **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 3.5% plus $0.15 on Open (5.0% plus $0.15 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.50 and you $9.49 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.
1045
1045
  - **Steam rail: unchanged.** INVO spends the member's wallet first and tops up from Steam for the shortfall only.
1046
1046
  - **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.
1047
1047
  - **`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.
@@ -1426,7 +1426,7 @@ for (const w of r.warnings ?? []) log(w.code); // "REASON_RECOMMENDED"
1426
1426
  **What else happens.**
1427
1427
 
1428
1428
  - **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.
1429
- - **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.34 of revenue and charges the $0.65 card fee, a $9.99 debit; a $100 period leaves you at -$3.80 (-$5.30 on a card issued outside the US). A receipt stored before 2026-09-28 (a replay) carries neither new field.
1429
+ - **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.49 of revenue and charges the $0.50 card fee, a $9.99 debit; a $100 period leaves you at -$3.65 (-$5.15 on a card issued outside the US). A receipt stored before 2026-09-28 (a replay) carries neither new field.
1430
1430
  - **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 guarantee is a Merchant of Record term; on Open it covers card payments made before November 8, 2026); the Open-tier dispute fee pass-through is unchanged.
1431
1431
  - **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.
1432
1432
  - **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.
@@ -2585,7 +2585,7 @@ On the demo key, send only `recipientEmail`. The server maps it to the friend's
2585
2585
  - `approveTransfer(start)` asks the game server, which approves in INVO's demo sandbox (`approval: "sandbox"`) and keeps the claim code.
2586
2586
  - The friend's `pendingTransfers()` and `collectTransfer(item, "sandbox")` collect it through the game server.
2587
2587
 
2588
- Within one game, use a **send**. The transfer rail refuses a move to your own game, and `transferDestinations()` lists this game first for that reason. On the demo, a send to INVO Demo Arcade can't be collected from your copy, so it's refunded after 24 hours.
2588
+ Within one game, use a **send**. The transfer rail refuses a move to your own game, and `transferDestinations()` lists this game first for that reason. On the demo, a move to INVO Demo Arcade is collected there automatically once it's approved.
2589
2589
 
2590
2590
  On a real key, `recipientPhone` (E.164) is required and the email is optional.
2591
2591
 
@@ -1,4 +1,4 @@
1
- import { InvoError, assertSecureBaseUrl, Http, toPhoneChangeApprovalsResult, phoneChangeSignalMessage, toApprovePhoneChangeResult, toDestinationsResult, toLoyaltyCardsResult, toLoyaltyVaultResult, toRedeemRewardResult, toRewardsPageLink, buildGameEventBody, toReportGameEventResult, receiptFields } from './chunk-TSTP2CWA.js';
1
+ import { InvoError, assertSecureBaseUrl, Http, toPurchaseStatusResult, toPhoneChangeApprovalsResult, phoneChangeSignalMessage, toApprovePhoneChangeResult, toDestinationsResult, toLoyaltyCardsResult, toLoyaltyVaultResult, toRedeemRewardResult, toRewardsPageLink, buildGameEventBody, toReportGameEventResult } from './chunk-TCT2QSVB.js';
2
2
 
3
3
  // src/shared/webauthn.ts
4
4
  function malformedOptions(field) {
@@ -684,50 +684,6 @@ async function runHostedApproval(opts, api, deps = {}) {
684
684
  });
685
685
  }
686
686
 
687
- // src/shared/purchase-status.ts
688
- function str(v) {
689
- return typeof v === "string" ? v : v === null || v === void 0 ? null : String(v);
690
- }
691
- function toPurchaseStatusResult(raw, sessionId) {
692
- return {
693
- status: String(raw["status"] ?? ""),
694
- // INVO SAYS, AND ONLY AN EXPLICIT `true` SAYS IT. A missing or malformed field reads
695
- // false, which keeps a poll running; the alternative, guessing terminality from
696
- // `status`, is how an old SDK declares a future status finished.
697
- terminal: raw["terminal"] === true,
698
- orderId: str(raw["order_id"]),
699
- sessionId: String(raw["session_id"] ?? sessionId),
700
- coinsCredited: str(raw["coins_credited"]),
701
- transactionId: str(raw["transaction_id"]),
702
- newBalance: str(raw["new_balance"]),
703
- reasonCode: str(raw["reason_code"]),
704
- message: str(raw["message"]),
705
- amountChargedUsd: str(raw["amount_charged_usd"]),
706
- listedUsd: str(raw["listed_usd"]),
707
- currencyName: str(raw["currency_name"]),
708
- ...receiptFields(raw),
709
- raw
710
- };
711
- }
712
- function isPurchaseCredited(r) {
713
- return r.status === "credited";
714
- }
715
- function isPurchaseRefused(r) {
716
- return r.status === "refused";
717
- }
718
- function isPurchaseRefunded(r) {
719
- return r.status === "refunded";
720
- }
721
- function isPurchaseExpired(r) {
722
- return r.status === "expired";
723
- }
724
- var NOTHING_CHARGED_REASONS = /* @__PURE__ */ new Set(["PAYMENT_DECLINED", "PAYMENT_CANCELLED"]);
725
- function nothingWasCharged(r) {
726
- if (r.status === "expired") return true;
727
- if (r.status !== "refused") return false;
728
- return r.reasonCode !== null && NOTHING_CHARGED_REASONS.has(r.reasonCode);
729
- }
730
-
731
687
  // src/index.ts
732
688
  function clientInvalidInput(message) {
733
689
  return new InvoError({ message, code: "INVALID_INPUT", status: 0 });
@@ -1629,6 +1585,6 @@ var InvoClient = class {
1629
1585
  }
1630
1586
  };
1631
1587
 
1632
- export { CheckoutClient, InvoClient, PlatformCommerceClient, isPurchaseCredited, isPurchaseExpired, isPurchaseRefunded, isPurchaseRefused, nothingWasCharged };
1633
- //# sourceMappingURL=chunk-QDHOPJFL.js.map
1634
- //# sourceMappingURL=chunk-QDHOPJFL.js.map
1588
+ export { CheckoutClient, InvoClient, PlatformCommerceClient };
1589
+ //# sourceMappingURL=chunk-7O5JT3LK.js.map
1590
+ //# sourceMappingURL=chunk-7O5JT3LK.js.map
@@ -0,0 +1,6 @@
1
+ // src/version.ts
2
+ var SDK_VERSION = "3.30.2";
3
+
4
+ export { SDK_VERSION };
5
+ //# sourceMappingURL=chunk-EJR7SOQK.js.map
6
+ //# sourceMappingURL=chunk-EJR7SOQK.js.map
@@ -1,5 +1,5 @@
1
- import { SDK_VERSION } from './chunk-BIK6UXY7.js';
2
- import { InvoError, assertSecureBaseUrl, Http, toRequestPhoneChangeResult, toPhoneChangeRequest, receiptFields, creditFields, toLoyaltyCardsResult, buildGameEventBody, toReportGameEventResult, toDestinationsResult } from './chunk-TSTP2CWA.js';
1
+ import { SDK_VERSION } from './chunk-EJR7SOQK.js';
2
+ import { InvoError, assertSecureBaseUrl, Http, toRequestPhoneChangeResult, toPhoneChangeRequest, toPurchaseStatusResult, receiptFields, creditFields, toLoyaltyCardsResult, buildGameEventBody, toReportGameEventResult, toDestinationsResult } from './chunk-TCT2QSVB.js';
3
3
  import { createHmac, timingSafeEqual } from 'crypto';
4
4
 
5
5
  // src/payouts.ts
@@ -2529,6 +2529,25 @@ var InvoServer = class {
2529
2529
  raw
2530
2530
  };
2531
2531
  }
2532
+ /**
2533
+ * Read a hosted checkout's status from INVO, server-side, with the session token that
2534
+ * {@link createCheckout} returned. Same answer as the browser's
2535
+ * `invo.checkout.getPurchaseStatus`. A game server uses it to confirm a purchase when
2536
+ * the signed webhook cannot reach it (for example a private development preview).
2537
+ * It is INVO's own record, read over TLS with the session credential, never the buyer's word.
2538
+ */
2539
+ async getCheckoutStatus(input, opts) {
2540
+ const sessionId = String(input?.sessionId ?? "").trim();
2541
+ const sessionToken = String(input?.sessionToken ?? "").trim();
2542
+ if (!sessionId) throw invalidInput2("sessionId", input?.sessionId, "is required");
2543
+ if (!sessionToken) throw invalidInput2("sessionToken", "(hidden)", "is required");
2544
+ const raw = await this.http.get(
2545
+ `/api/checkout/sessions/${encodeURIComponent(sessionId)}`,
2546
+ { kind: "bearer", token: sessionToken },
2547
+ { signal: opts?.signal }
2548
+ );
2549
+ return toPurchaseStatusResult(raw, sessionId);
2550
+ }
2532
2551
  /**
2533
2552
  * Direct purchase via the rail selector. Use when you need a specific rail.
2534
2553
  * - rail "platform" (default): standard card. May return status "requires_action"
@@ -2536,7 +2555,7 @@ var InvoServer = class {
2536
2555
  * - rail "game": returns status "pending_payment" + paymentUrl (redirect the browser).
2537
2556
  * - rail "steam": NOT a browser flow — the backend returns WRONG_RAIL_ENDPOINT.
2538
2557
  *
2539
- * INVO's card fee (3.5% + $0.30 on Open, 5.5% + $0.50 on Merchant of Record, plus 1.5% of
2558
+ * INVO's card fee (3.5% + $0.15 on Open, 5.0% + $0.15 on Merchant of Record, plus 1.5% of
2540
2559
  * the listed price (before tax) on a card issued outside the US) is charged to you, the partner. The player
2541
2560
  * pays the listed price (plus any tax) and receives the listed coins. Card purchases only;
2542
2561
  * purchases through a third-party storefront or payment rail are unaffected. Two shapes,
@@ -2625,7 +2644,7 @@ var InvoServer = class {
2625
2644
  *
2626
2645
  * The player pays the listed price plus any tax (when you pass `country`) and receives the
2627
2646
  * listed coins: `totalUsd` carries no card fee, and `processingFeeUsd` is `"0.00"`. INVO's
2628
- * card fee (3.5% + $0.30 on Open, 5.5% + $0.50 on Merchant of Record) is charged to you;
2647
+ * card fee (3.5% + $0.15 on Open, 5.0% + $0.15 on Merchant of Record) is charged to you;
2629
2648
  * `partnerFeeUsd` carries it when INVO sends it. $10.00 quotes a $10.00 total, 100.00 coins
2630
2649
  * at the default 10 per USD, and a $0.65 partner fee on Open. Show the player `totalUsd`,
2631
2650
  * then send the same figure back as `acknowledgedTotalUsd` on {@link purchaseCurrency}; the
@@ -3768,5 +3787,5 @@ var InvoServer = class {
3768
3787
  };
3769
3788
 
3770
3789
  export { CardsServer, DEMO_KEY_PREFIX, EnvironmentUnknownError, InvoServer, PRODUCTION_BASE_URL, PayoutsServer, PlatformCommerceServer, SANDBOX_BASE_URL, SandboxServer, SandboxSubscriptionsServer, SubscriptionsServer, baseUrlForKey, createWebhookHandler, isDemoKey, isRefundPendingApproval, resolveEnvironment, verifyInvoSignature, verifyWebhook, verifyWebhookAsync };
3771
- //# sourceMappingURL=chunk-664RAO2T.js.map
3772
- //# sourceMappingURL=chunk-664RAO2T.js.map
3790
+ //# sourceMappingURL=chunk-PED5RLYP.js.map
3791
+ //# sourceMappingURL=chunk-PED5RLYP.js.map
@@ -1399,10 +1399,54 @@ function receiptFields(raw) {
1399
1399
  return typeof u === "string" && u !== "" ? { receiptNumber: n, receiptUrl: u } : { receiptNumber: n };
1400
1400
  }
1401
1401
 
1402
+ // src/shared/purchase-status.ts
1403
+ function str(v) {
1404
+ return typeof v === "string" ? v : v === null || v === void 0 ? null : String(v);
1405
+ }
1406
+ function toPurchaseStatusResult(raw, sessionId) {
1407
+ return {
1408
+ status: String(raw["status"] ?? ""),
1409
+ // INVO SAYS, AND ONLY AN EXPLICIT `true` SAYS IT. A missing or malformed field reads
1410
+ // false, which keeps a poll running; the alternative, guessing terminality from
1411
+ // `status`, is how an old SDK declares a future status finished.
1412
+ terminal: raw["terminal"] === true,
1413
+ orderId: str(raw["order_id"]),
1414
+ sessionId: String(raw["session_id"] ?? sessionId),
1415
+ coinsCredited: str(raw["coins_credited"]),
1416
+ transactionId: str(raw["transaction_id"]),
1417
+ newBalance: str(raw["new_balance"]),
1418
+ reasonCode: str(raw["reason_code"]),
1419
+ message: str(raw["message"]),
1420
+ amountChargedUsd: str(raw["amount_charged_usd"]),
1421
+ listedUsd: str(raw["listed_usd"]),
1422
+ currencyName: str(raw["currency_name"]),
1423
+ ...receiptFields(raw),
1424
+ raw
1425
+ };
1426
+ }
1427
+ function isPurchaseCredited(r) {
1428
+ return r.status === "credited";
1429
+ }
1430
+ function isPurchaseRefused(r) {
1431
+ return r.status === "refused";
1432
+ }
1433
+ function isPurchaseRefunded(r) {
1434
+ return r.status === "refunded";
1435
+ }
1436
+ function isPurchaseExpired(r) {
1437
+ return r.status === "expired";
1438
+ }
1439
+ var NOTHING_CHARGED_REASONS = /* @__PURE__ */ new Set(["PAYMENT_DECLINED", "PAYMENT_CANCELLED"]);
1440
+ function nothingWasCharged(r) {
1441
+ if (r.status === "expired") return true;
1442
+ if (r.status !== "refused") return false;
1443
+ return r.reasonCode !== null && NOTHING_CHARGED_REASONS.has(r.reasonCode);
1444
+ }
1445
+
1402
1446
  // src/shared/loyalty.ts
1403
1447
  var obj = (v) => v && typeof v === "object" && !Array.isArray(v) ? v : {};
1404
1448
  var rows = (v) => Array.isArray(v) ? v.filter((r) => r && typeof r === "object" && !Array.isArray(r)) : [];
1405
- var str = (v) => v === void 0 || v === null ? "" : String(v);
1449
+ var str2 = (v) => v === void 0 || v === null ? "" : String(v);
1406
1450
  var strOrNull = (v) => v === void 0 || v === null ? null : String(v);
1407
1451
  var numOrNull = (v) => typeof v === "number" && Number.isFinite(v) ? v : null;
1408
1452
  var int = (v, fallback = 0) => typeof v === "number" && Number.isFinite(v) ? v : fallback;
@@ -1419,22 +1463,22 @@ function toStep(row) {
1419
1463
  return {
1420
1464
  stepId: strOrNull(row["step_id"]),
1421
1465
  index: int(row["index"]),
1422
- action: str(row["action"]),
1423
- label: str(row["label"]),
1424
- summary: str(row["summary"]),
1466
+ action: str2(row["action"]),
1467
+ label: str2(row["label"]),
1468
+ summary: str2(row["summary"]),
1425
1469
  windowHours: numOrNull(row["window_hours"]),
1426
- state: str(row["state"]),
1470
+ state: str2(row["state"]),
1427
1471
  progress: toLoyaltyStepProgress(row["progress"]),
1428
1472
  raw: row
1429
1473
  };
1430
1474
  }
1431
1475
  function toCardReward(row) {
1432
1476
  return {
1433
- vaultEntryId: str(row["vault_entry_id"]),
1434
- rewardId: str(row["reward_id"]),
1435
- state: str(row["state"]),
1436
- unlockedAt: str(row["unlocked_at"]),
1437
- expiresAt: str(row["expires_at"]),
1477
+ vaultEntryId: str2(row["vault_entry_id"]),
1478
+ rewardId: str2(row["reward_id"]),
1479
+ state: str2(row["state"]),
1480
+ unlockedAt: str2(row["unlocked_at"]),
1481
+ expiresAt: str2(row["expires_at"]),
1438
1482
  redeemedAt: strOrNull(row["redeemed_at"]),
1439
1483
  codeMasked: strOrNull(row["code_masked"]),
1440
1484
  canRedeem: row["can_redeem"] === true,
@@ -1449,18 +1493,18 @@ function toLoyaltyCard(row) {
1449
1493
  const steps = rows(row["steps"]).map(toStep);
1450
1494
  return {
1451
1495
  cardVersion: passThrough(row["card_version"]),
1452
- mode: str(row["mode"]),
1496
+ mode: str2(row["mode"]),
1453
1497
  programId: strOrNull(row["program_id"]),
1454
1498
  questId: strOrNull(row["quest_id"]),
1455
1499
  questVersion: numOrNull(row["quest_version"]),
1456
1500
  campaignId: strOrNull(row["campaign_id"]),
1457
- title: str(row["title"]),
1458
- description: str(row["description"]),
1501
+ title: str2(row["title"]),
1502
+ description: str2(row["description"]),
1459
1503
  brand: { name: strOrNull(brand["name"]), logoUrl: strOrNull(brand["logo_url"]) },
1460
1504
  artUrl: strOrNull(row["art_url"]),
1461
1505
  reward: { rewardId: strOrNull(reward["reward_id"]), name: strOrNull(reward["name"]) },
1462
- orderMode: str(row["order_mode"]),
1463
- status: str(row["status"]),
1506
+ orderMode: str2(row["order_mode"]),
1507
+ status: str2(row["status"]),
1464
1508
  startsAt: strOrNull(row["starts_at"]),
1465
1509
  endsAt: strOrNull(row["ends_at"]),
1466
1510
  completionHours: numOrNull(row["completion_hours"]),
@@ -1483,12 +1527,12 @@ function toLoyaltyCardsResult(raw) {
1483
1527
  }
1484
1528
  function toVaultEntry(row) {
1485
1529
  return {
1486
- vaultEntryId: str(row["vault_entry_id"]),
1487
- rewardRef: str(row["reward_ref"]),
1488
- programId: str(row["program_id"]),
1530
+ vaultEntryId: str2(row["vault_entry_id"]),
1531
+ rewardRef: str2(row["reward_ref"]),
1532
+ programId: str2(row["program_id"]),
1489
1533
  questId: strOrNull(row["quest_id"]),
1490
- units: str(row["units"]),
1491
- state: str(row["state"]),
1534
+ units: str2(row["units"]),
1535
+ state: str2(row["state"]),
1492
1536
  unlockedAt: strOrNull(row["unlocked_at"]),
1493
1537
  expiresAt: strOrNull(row["expires_at"]),
1494
1538
  redeemedAt: strOrNull(row["redeemed_at"]),
@@ -1501,9 +1545,9 @@ function toLoyaltyVaultResult(raw) {
1501
1545
  }
1502
1546
  function toRedeemRewardResult(raw, vaultEntryId) {
1503
1547
  return {
1504
- vaultEntryId: str(raw["vault_entry_id"] ?? vaultEntryId),
1505
- rewardRef: str(raw["reward_ref"]),
1506
- state: str(raw["state"]),
1548
+ vaultEntryId: str2(raw["vault_entry_id"] ?? vaultEntryId),
1549
+ rewardRef: str2(raw["reward_ref"]),
1550
+ state: str2(raw["state"]),
1507
1551
  redeemedAt: strOrNull(raw["redeemed_at"]),
1508
1552
  code: strOrNull(raw["code"]),
1509
1553
  codeMasked: strOrNull(raw["code_masked"]),
@@ -1513,7 +1557,7 @@ function toRedeemRewardResult(raw, vaultEntryId) {
1513
1557
  };
1514
1558
  }
1515
1559
  function toRewardsPageLink(raw) {
1516
- return { url: str(raw["url"]), expiresAt: str(raw["expires_at"]), raw };
1560
+ return { url: str2(raw["url"]), expiresAt: str2(raw["expires_at"]), raw };
1517
1561
  }
1518
1562
 
1519
1563
  // src/shared/loyalty-events.ts
@@ -1598,16 +1642,16 @@ function requireField(value, field, raw) {
1598
1642
  }
1599
1643
  return s;
1600
1644
  }
1601
- var str2 = (v) => v == null ? "" : String(v);
1645
+ var str3 = (v) => v == null ? "" : String(v);
1602
1646
  var strOrNull2 = (v) => typeof v === "string" ? v : v == null ? null : String(v);
1603
1647
  function toRequestPhoneChangeResult(raw) {
1604
1648
  return {
1605
1649
  changeRequestId: requireField(raw["change_request_id"], "change_request_id", raw),
1606
1650
  status: requireField(raw["status"], "status", raw),
1607
- expiresAt: str2(raw["expires_at"]),
1608
- delivery: str2(raw["delivery"]),
1609
- confirmation: str2(raw["confirmation"]),
1610
- message: str2(raw["message"]),
1651
+ expiresAt: str3(raw["expires_at"]),
1652
+ delivery: str3(raw["delivery"]),
1653
+ confirmation: str3(raw["confirmation"]),
1654
+ message: str3(raw["message"]),
1611
1655
  raw
1612
1656
  };
1613
1657
  }
@@ -1615,8 +1659,8 @@ function toPhoneChangeRequest(raw) {
1615
1659
  return {
1616
1660
  changeRequestId: requireField(raw["change_request_id"], "change_request_id", raw),
1617
1661
  status: requireField(raw["status"], "status", raw),
1618
- confirmation: str2(raw["confirmation"]),
1619
- delivery: str2(raw["delivery"]),
1662
+ confirmation: str3(raw["confirmation"]),
1663
+ delivery: str3(raw["delivery"]),
1620
1664
  newPhoneMasked: strOrNull2(raw["new_phone_masked"]),
1621
1665
  createdAt: strOrNull2(raw["created_at"]),
1622
1666
  expiresAt: strOrNull2(raw["expires_at"]),
@@ -1628,7 +1672,7 @@ function toPhoneChangeRequest(raw) {
1628
1672
  function toPhoneChangeApprovalsResult(raw) {
1629
1673
  const rows2 = Array.isArray(raw["approvals"]) ? raw["approvals"] : [];
1630
1674
  const approvals = rows2.filter((r) => r && typeof r === "object").map((r) => ({
1631
- changeRequestId: str2(r["change_request_id"]),
1675
+ changeRequestId: str3(r["change_request_id"]),
1632
1676
  gameName: strOrNull2(r["game_name"]),
1633
1677
  oldPhoneMasked: strOrNull2(r["old_phone_masked"]),
1634
1678
  newPhoneMasked: strOrNull2(r["new_phone_masked"]),
@@ -1637,7 +1681,7 @@ function toPhoneChangeApprovalsResult(raw) {
1637
1681
  return { approvals, raw };
1638
1682
  }
1639
1683
  function toApprovePhoneChangeResult(raw, changeRequestId) {
1640
- const id = str2(raw["change_request_id"] ?? changeRequestId);
1684
+ const id = str3(raw["change_request_id"] ?? changeRequestId);
1641
1685
  const status = requireField(raw["status"], "status", raw);
1642
1686
  if (status === "denied") {
1643
1687
  return { status: "denied", changeRequestId: id, raw };
@@ -1653,8 +1697,8 @@ function toApprovePhoneChangeResult(raw, changeRequestId) {
1653
1697
  const out = {
1654
1698
  status: "confirmed",
1655
1699
  changeRequestId: id,
1656
- identityId: str2(raw["identity_id"]),
1657
- previousIdentityId: str2(raw["previous_identity_id"]),
1700
+ identityId: str3(raw["identity_id"]),
1701
+ previousIdentityId: str3(raw["previous_identity_id"]),
1658
1702
  playersUpdated: Number(raw["players_updated"] ?? 0) || 0,
1659
1703
  verifiedPhone: raw["verified_phone"] === true,
1660
1704
  raw
@@ -1668,6 +1712,6 @@ function toApprovePhoneChangeResult(raw, changeRequestId) {
1668
1712
  return out;
1669
1713
  }
1670
1714
 
1671
- export { Http, InvoError, assertSecureBaseUrl, buildGameEventBody, creditFields, newEventId, phoneChangeSignalMessage, receiptFields, toApprovePhoneChangeResult, toDestinationsResult, toLoyaltyCardsResult, toLoyaltyVaultResult, toPhoneChangeApprovalsResult, toPhoneChangeRequest, toRedeemRewardResult, toReportGameEventResult, toRequestPhoneChangeResult, toRewardsPageLink };
1672
- //# sourceMappingURL=chunk-TSTP2CWA.js.map
1673
- //# sourceMappingURL=chunk-TSTP2CWA.js.map
1715
+ export { Http, InvoError, assertSecureBaseUrl, buildGameEventBody, creditFields, isPurchaseCredited, isPurchaseExpired, isPurchaseRefunded, isPurchaseRefused, newEventId, nothingWasCharged, phoneChangeSignalMessage, receiptFields, toApprovePhoneChangeResult, toDestinationsResult, toLoyaltyCardsResult, toLoyaltyVaultResult, toPhoneChangeApprovalsResult, toPhoneChangeRequest, toPurchaseStatusResult, toRedeemRewardResult, toReportGameEventResult, toRequestPhoneChangeResult, toRewardsPageLink };
1716
+ //# sourceMappingURL=chunk-TCT2QSVB.js.map
1717
+ //# sourceMappingURL=chunk-TCT2QSVB.js.map