@invonetwork/web-sdk 3.21.0 → 3.23.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,57 @@
1
1
  # Changelog
2
2
 
3
+ ## 3.23.0
4
+
5
+ ### Minor Changes
6
+
7
+ - Webhook types: `PurchaseEventData` gains `dispute_fee_usd` (`string | null`, USD decimal such as `"15.00"`, `"0.00"` when INVO bears the fee) and `dispute_fee_charged_to_partner` (`boolean | null`), carried on a card `purchase.disputed` when the dispute closes. From November 8, 2026 the card dispute fee on Open-tier card sales (coin purchases, Platform Commerce card sales and subscription charges) is passed through to you at cost. A lost dispute is `purchase.disputed` with `dispute_status: "lost"`, not a separate event. README updated. Both fields optional; nothing removed or renamed.
8
+
9
+ ## 3.22.0
10
+
11
+ ### Minor Changes
12
+
13
+ - e3895ab: 2026-10 pricing and new reads. Server: `getPlayerActivity({ playerEmail, limit?, cursor?, types? })`
14
+ (`GET /api/sdk/players/activity`), one merged, newest-first page of a player's currency purchases,
15
+ item purchases, Platform Commerce purchases, sends and transfers, and `iteratePlayerActivity`, which
16
+ follows `nextCursor`. `platformCommerce.getPurchaseHistory({ playerEmail, limit?, cursor? })`
17
+ (`GET /api/platform-commerce/purchase-history`, entries shaped like `getStatus`) and
18
+ `platformCommerce.iteratePurchaseHistory`. `getTransferStatus` / `getSendStatus` results carry
19
+ `expiryReason` once expired. Webhook types: `TransferEventData` gains `order_id`,
20
+ `net_transfer_amount`, `claim_code_expires_at`, `from_game_id`, `to_game_id`, `from_player_id`,
21
+ `expired_at`, `reason`, `expiry_reason` and `refunded_amount`; `payout.status_changed` is typed as
22
+ `PayoutStatusChangedData`, with the payout fee fields `offboarding_fee_pct`, `offboarding_fee_usd`,
23
+ `offboarding_fee_cap_usd` and `net_payout_usd`. New additive `err.publicCode`: the
24
+ provider-neutral twin of a code (INVO's `error_code_public` on errors from the API). The SDK's own
25
+ pre-network refusal of a Platform Commerce card total under $0.50 keeps `err.code` exactly as
26
+ before and now also carries `err.publicCode === "BELOW_CARD_MINIMUM"` and `err.minUsd === "0.50"`;
27
+ `err.isBelowCardMinimum` is true as before and accepts both spellings. Nothing removed or renamed. README: the
28
+ Open card fee is 3.5% + $0.30 (was 4.5%); the chargeback guarantee is a Merchant of Record term
29
+ (Open-tier card payments made before November 8, 2026 keep it); transfers are 10% (3.5% / 3.5% /
30
+ 3%); payouts carry a 1% fee capped at $500 per payout; the hosted checkout reports a finished
31
+ purchase as status `"completed"`; on `phoneMismatch`, call `updatePlayerPhone`. Additive only.
32
+ - Player-confirmed phone change. Server: `requestPhoneChange({ playerEmail, newPhone })`
33
+ (`POST /api/sdk/players/phone/change-requests`, 202, never auto-retried) returns
34
+ `changeRequestId`, `status`, `expiresAt`, `delivery`, `confirmation` and `message`; INVO emails
35
+ the player, who confirms on INVO's page (plus their passkey or enrolled device when they have
36
+ one). `getPhoneChange(changeRequestId)` reads the request. Browser, with the player token, on
37
+ the player's enrolled device: `listPhoneChangeApprovals()` and
38
+ `approvePhoneChange(changeRequestId, { deviceFingerprint, decision?, sign | deviceSignal })`,
39
+ which sends a `device_signal` over `phone-change|<id>|<nonce>|<timestamp>` (or
40
+ `phone-change-deny|...`); new `phoneChangeSignalMessage()` builds that message. No method sends
41
+ a confirmation code: games never collect it. `err.changeRequestEndpoint` on
42
+ `PHONE_CHANGE_REQUIRES_VERIFICATION`; new error predicates `isConfirmOnInvoPage`,
43
+ `isChangeRequestNotFound`, `isChangeRequestNotReady`, `isChangeRequestNotPending` (with
44
+ `changeRequestStatus`), `isChangeRequestInProgress`, `isPhoneChangeLocked`,
45
+ `isTooManyChangeRequests`, `isPhoneChangeUnavailable`, `isDeviceSignalRejected`,
46
+ `isPhoneChangeRecoveryCooldown` (`PHONE_CHANGE_RECOVERY_COOLDOWN`, 409 on create and approve:
47
+ a recent sign-in recovery; retry later, declining still works) and
48
+ `isDeviceEnrolledAfterRequest` (`DEVICE_ENROLLED_AFTER_REQUEST`, 409 on approve). New
49
+ `isPendingTransfersToOldPhone` / `isPendingTransfersToNewPhone`, which `updatePlayerPhone`
50
+ now also answers (409, no counts) as well as the change request routes. Webhook
51
+ type: `player.phone_changed` as `PlayerPhoneChangedData` (`new_phone` only for the requesting
52
+ game). README section "Player-confirmed phone change": on `phoneMismatch` or
53
+ `player.phone_changed`, never push a stored number back; ask the player. Additive only.
54
+
3
55
  ## 3.21.0
4
56
 
5
57
  ### 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.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.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).
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
@@ -94,6 +94,7 @@ The right approval method is a property of the **client the player is sitting in
94
94
  - [Install](#install)
95
95
  - [Architecture & the two entry points](#architecture--the-two-entry-points)
96
96
  - [Registering players and changing their phone](#registering-players-and-changing-their-phone)
97
+ - [Player-confirmed phone change](#player-confirmed-phone-change)
97
98
  - [Before you go live](#before-you-go-live)
98
99
  - [Configuration](#configuration)
99
100
  - [Tiers](#tiers)
@@ -109,6 +110,7 @@ The right approval method is a property of the **client the player is sitting in
109
110
  - [Paid trials](#paid-trials)
110
111
  - [Subscription packages](#subscription-packages)
111
112
  - [Player balance](#player-balance)
113
+ - [Player activity (one list of everything)](#player-activity-one-list-of-everything)
112
114
  - [Sends & transfers (move currency between players)](#sends--transfers-move-currency-between-players)
113
115
  - [Legacy fallback: the SMS PIN (being retired)](#legacy-fallback-the-sms-pin-being-retired)
114
116
  - [Sends and transfers, stage by stage](#sends-and-transfers-stage-by-stage)
@@ -202,8 +204,14 @@ if (t.phoneMismatch) { /* they exist with a different phone; see updatePlayerPho
202
204
 
203
205
  An existing player's phone is **never changed** by this call. When it differs from the
204
206
  `playerPhone` you passed, the token is still minted for that player and the result carries
205
- `phoneMismatch: true`. A phone that already belongs to another email is a `409`
206
- (`err.isPhoneShareRefused`).
207
+ `phoneMismatch: true`. When the new phone is genuine, call
208
+ `updatePlayerPhone({ playerEmail, newPhone })` to change it (see
209
+ [Registering players and changing their phone](#registering-players-and-changing-their-phone)).
210
+ A phone that already belongs to another email is a `409` (`err.isPhoneShareRefused`).
211
+
212
+ If the player changed their number with INVO (a `player.phone_changed` webhook, or a
213
+ `phoneMismatch` you did not cause), INVO's number is the current one: **never push the number
214
+ you have stored back** to INVO. Ask the player if you need the full new number.
207
215
 
208
216
  **Where phone actually matters.** A player's INVO identity encodes their phone, and cross-game
209
217
  money routing keys off it:
@@ -249,12 +257,129 @@ if (upd.identityRekeyed && upd.playerToken) handTokenToBrowser(upd.playerToken);
249
257
  |---|---|---|---|
250
258
  | `err.isPhoneMismatch` (`PHONE_MISMATCH`) | 409 | `registerPlayer`: the player is already in your title with a **different** phone. Nothing changed. | Call `updatePlayerPhone` if the change is genuine. |
251
259
  | `err.isPhoneShareRefused` (`PHONE_SHARE_APPROVAL_REQUIRED`) | 409 | The phone belongs to another email. Nothing was created or changed. Same code as `err.isPhoneShareApprovalRequired`. | Show `err.message`; ask the player to check the number. |
252
- | `err.isPhoneChangeRequiresVerification` (`PHONE_CHANGE_REQUIRES_VERIFICATION`) | 409 | `updatePlayerPhone`: the player has secured this account, so the change needs the player's own confirmation. Nothing changed. | Until that flow is available, contact INVO support to change it. |
260
+ | `err.isPhoneChangeRequiresVerification` (`PHONE_CHANGE_REQUIRES_VERIFICATION`) | 409 | `updatePlayerPhone`: the player has secured this account, so the change needs the player's own confirmation. Nothing changed. `err.changeRequestEndpoint` names the route to use instead. | Call `requestPhoneChange` (see [Player-confirmed phone change](#player-confirmed-phone-change)). |
253
261
  | `err.isPlayerNotFound` | 404 | `updatePlayerPhone` (or `mintPlayerToken` without `playerPhone`): no player with that email in your title. | Create the player first (`registerPlayer`). |
254
262
  | `INVALID_INPUT` / `INVALID_PHONE` | 400 | A missing email or phone, or a phone INVO does not accept. | Fix the input. The SDK also refuses a non-E.164 phone before the network (`status === 0`). |
255
263
  | rate limited | 429 | Too many registrations or phone changes for this player. | Back off by `err.retryAfter`. |
264
+ | `err.isPendingTransfersToOldPhone` (`PENDING_TRANSFERS_TO_OLD_PHONE`) | 409 | `updatePlayerPhone`: sends or transfers to the player's current number are still waiting to be collected; changing the number now would strand them. Nothing changed. | Ask the player to collect them first (or wait until they expire), then retry. |
265
+ | `err.isPendingTransfersToNewPhone` (`PENDING_TRANSFERS_TO_NEW_PHONE`) | 409 | `updatePlayerPhone`: sends or transfers to the new number are still waiting to be collected. Nothing changed. | Retry after they are collected or expire. |
256
266
  | `PHONE_UPDATE_UNAVAILABLE` | 503 | `updatePlayerPhone` could not be checked right now. Nothing changed. | Try again shortly. |
257
267
 
268
+ ### Player-confirmed phone change
269
+
270
+ When `updatePlayerPhone` answers `409` `err.isPhoneChangeRequiresVerification`, the player
271
+ confirms the change themselves:
272
+
273
+ 1. Your server calls `requestPhoneChange({ playerEmail, newPhone })`.
274
+ 2. INVO emails the address on the player's account a confirmation code and a link to a page on
275
+ INVO's site.
276
+ 3. The player opens the link and confirms on INVO's page. If they have a passkey or an enrolled
277
+ device with INVO, they also approve with it, on the page or on that device.
278
+
279
+ Nothing changes until the player confirms. **Your game never collects the code and never
280
+ receives the link.** Do not build a code field for this and do not ask the player for the code:
281
+ the email tells them to enter it only on INVO's page. The SDK has no method that sends a code;
282
+ INVO's confirm route answers `409` `err.isConfirmOnInvoPage` to any game that tries.
283
+
284
+ ```ts
285
+ // your backend
286
+ try {
287
+ await invo.updatePlayerPhone({ playerEmail, newPhone });
288
+ } catch (err) {
289
+ if (!(err instanceof InvoError) || !err.isPhoneChangeRequiresVerification) throw err;
290
+ const req = await invo.requestPhoneChange({ playerEmail, newPhone });
291
+ // req.changeRequestId, req.status ("pending_confirmation"), req.expiresAt,
292
+ // req.delivery ("email"), req.confirmation, req.message
293
+ tellPlayer("Check your email and confirm the new number on INVO's page.");
294
+ }
295
+
296
+ // later, optional (or wait for the player.phone_changed webhook)
297
+ const cr = await invo.getPhoneChange(changeRequestId);
298
+ // cr.status: "pending" | "confirmed" | "expired" | "cancelled" | "refused" | "denied"
299
+ ```
300
+
301
+ `confirmation` says what the player will be asked for: `"email_code"` (the code alone),
302
+ `"email_code_and_passkey"` (the code and their passkey, on INVO's page) or
303
+ `"email_code_and_device"` (the code on INVO's page, then an approval on their enrolled device).
304
+ A new request from your game for the same player replaces your earlier pending one.
305
+ `requestPhoneChange` is never retried automatically, since each request sends the player an
306
+ email.
307
+
308
+ `getPhoneChange(changeRequestId)` reads a request your game created: `status`, `confirmation`,
309
+ `delivery`, `newPhoneMasked`, `createdAt`, `expiresAt`, `confirmedAt` and `confirmedVia`
310
+ (`"hosted_page"` or `"hosted_page_device"`). Create returns `"pending_confirmation"`; the read
311
+ calls the same state `"pending"`. `expired`, `cancelled` and `refused` need a new request if
312
+ the player still wants the change; `denied` means the player declined on their device.
313
+
314
+ | Refusal | HTTP | Means | Do |
315
+ |---|---|---|---|
316
+ | `PHONE_SAME` | 409 | That number is already on file. | Nothing. |
317
+ | `PHONE_IN_USE_BY_ANOTHER_PLAYER` | 409 | Another player uses that number. INVO does not contact them. | Ask your player for a different number. |
318
+ | `err.isPendingTransfersToNewPhone` (`PENDING_TRANSFERS_TO_NEW_PHONE`) | 409 | Transfers to the new number are still waiting to be collected. | Retry after they are collected or expire. |
319
+ | `err.isPendingTransfersToOldPhone` (`PENDING_TRANSFERS_TO_OLD_PHONE`) | 409 | Transfers to the player's current number are still waiting to be collected. Changing the number now would strand them. | Ask the player to collect them first (or wait until they expire), then retry. |
320
+ | `err.isChangeRequestInProgress` (`CHANGE_REQUEST_IN_PROGRESS`) | 409 | Another game's change request for this player is waiting for the player. | Retry after it is confirmed or expires. |
321
+ | `err.isPhoneChangeLocked` (`PHONE_CHANGE_LOCKED`) | 409 | Phone changes for this player are paused after failed confirmations. The player has been emailed. | Retry later. |
322
+ | `err.isPhoneChangeRecoveryCooldown` (`PHONE_CHANGE_RECOVERY_COOLDOWN`) | 409 | The player's account recently went through a sign-in recovery, so the number cannot be changed yet. | Retry later. |
323
+ | `STEP_UP_UNAVAILABLE`, `IDENTITY_COLLISION`, `AMBIGUOUS_IDENTITY` | 409 | The account cannot be changed this way. | The player contacts INVO support. |
324
+ | `WALLET_SECURED` | 409 | The player manages this number in the INVO Wallet app. | The player changes it there, or through INVO support. |
325
+ | `PHONE_NOT_SET` | 409 | No phone on file yet. | Set it with `updatePlayerPhone`. |
326
+ | `err.isTooManyChangeRequests` (`TOO_MANY_CHANGE_REQUESTS`) | 429 | Too many change requests for this player. | Try again later; do not loop. |
327
+ | `err.isPlayerNotFound` | 404 | No player with that email in your title. | Create the player first. |
328
+ | `err.isChangeRequestNotFound` (`CHANGE_REQUEST_NOT_FOUND`) | 404 | `getPhoneChange`: unknown id, or a request another game created. | Use the id your game received. |
329
+ | `err.isPhoneChangeUnavailable` (`PHONE_CHANGE_UNAVAILABLE`, `CONFIRMATION_EMAIL_UNAVAILABLE`) | 503 | Temporarily unavailable, or the email could not be sent (that request is closed). | Retry shortly. |
330
+ | `INVALID_INPUT` / `INVALID_PHONE` | 400 | A missing email, or a phone INVO does not accept. | Fix the input. The SDK refuses a non-E.164 phone before the network (`status === 0`). |
331
+
332
+ **Device approval** (only when `confirmation` is `"email_code_and_device"`). After the player
333
+ enters the code on INVO's page, their enrolled device approves the change. On that device, with
334
+ the player token:
335
+
336
+ ```ts
337
+ const { approvals } = await invo.listPhoneChangeApprovals();
338
+ // [{ changeRequestId, gameName, oldPhoneMasked, newPhoneMasked, expiresAt }]
339
+ // Show each one: "Approve changing your number to ***-***-0123?"
340
+
341
+ const res = await invo.approvePhoneChange(approvals[0].changeRequestId, {
342
+ deviceFingerprint, // the enrolled device's fingerprint
343
+ decision: "approve", // or "deny"
344
+ sign: (message) => signWithDeviceKey(message), // returns the base64 signature
345
+ });
346
+ if (res.status === "confirmed") {
347
+ saveIdentityId(res.identityId);
348
+ if (res.playerToken) useToken(res.playerToken); // tokens minted before the change are stale
349
+ }
350
+ ```
351
+
352
+ The device key registered with INVO signs `phone-change|<changeRequestId>|<nonce>|<timestamp>`
353
+ to approve, or `phone-change-deny|<changeRequestId>|<nonce>|<timestamp>` to decline, where
354
+ `timestamp` is epoch seconds. With `sign`, the SDK makes the nonce and timestamp, builds that
355
+ message and sends `device_signal` with `transfer_id` set to the change request id. If you sign
356
+ elsewhere, pass `deviceSignal: { nonce, timestamp, signature }` instead and build the message
357
+ with `phoneChangeSignalMessage(changeRequestId, nonce, timestamp, decision)`. This is a device
358
+ key, not a passkey: a player with a passkey approves on INVO's page.
359
+
360
+ | Refusal | HTTP | Means |
361
+ |---|---|---|
362
+ | `err.isChangeRequestNotReady` | 409 | The player has not entered the code on INVO's page yet. |
363
+ | `err.isChangeRequestNotPending` (`err.changeRequestStatus`) | 409 | Already confirmed, expired, cancelled, refused or declined. |
364
+ | `err.isDeviceEnrolledAfterRequest` (`DEVICE_ENROLLED_AFTER_REQUEST`) | 409 | This device (or its key) was set up after the change was requested, so it cannot approve it. The player approves on their earlier device, or your game creates a new request. |
365
+ | `err.isPhoneChangeRecoveryCooldown` (`PHONE_CHANGE_RECOVERY_COOLDOWN`) | 409 | The player's account recently went through a sign-in recovery; approving is paused, retry later. Declining (`decision: "deny"`) still works. |
366
+ | `err.isChangeRequestNotFound` | 404 | Unknown id, or a token for another player. |
367
+ | `err.isDeviceSignalRejected` | 401 | The signature did not verify. Nothing changed. |
368
+ | `DEVICE_REQUIRES_ELEVATION` | 403 | This device cannot approve sensitive changes yet. |
369
+ | `no_registered_device_key` (in `err.body.error`) / `INVALID_INPUT` | 400 | This device has no key enrolled for the player, or fields are missing. |
370
+ | a creation refusal above | 409 | The change cannot be applied now (for example `PENDING_TRANSFERS_TO_OLD_PHONE`). |
371
+
372
+ **After a change**, every game the player is in receives `player.phone_changed`
373
+ (`PlayerPhoneChangedData`): `player_email`, `previous_phone_masked`, `new_phone_masked`,
374
+ `new_phone_included`, `changed_at`, `source` (`"player"` or `"support"`), `identity_id` and
375
+ `previous_identity_id`. `new_phone` is present only for the game that requested the change
376
+ (`new_phone_included: true`). In every case: store the new `identity_id` and re-mint the
377
+ player's token. **Never push the number you have stored back to INVO** with
378
+ `updatePlayerPhone`: INVO's number is the current one and yours is the old one. If your game
379
+ needs the full new number and did not receive it, ask the player. After a player-confirmed
380
+ change, `updatePlayerPhone` answers `err.isPhoneChangeRequiresVerification` for that player, so
381
+ further changes go through `requestPhoneChange`.
382
+
258
383
  ### Token bootstrap (both modes)
259
384
 
260
385
  Expose one small backend endpoint that calls `mintPlayerToken` (server-side, with the game secret) and hand the token to the browser:
@@ -355,18 +480,27 @@ Every INVO developer account is on one of two tiers. The SDK calls are the same
355
480
  | Who it is for | every account, including all current ones | accounts INVO has approved |
356
481
  | Who the seller is | **you** | **INVO** |
357
482
  | Tax on sales | **you** are responsible for it; INVO collects none | **INVO** calculates, collects and remits it |
358
- | Card purchase of coins | 4.5% + $0.30 | 5.5% + $0.50 |
359
- | Platform Commerce card sales | 4.5% + $0.30 | 5.5% + $0.50 |
360
- | Subscriptions | 4.5% + $0.30 per card charge | 5.5% + $0.50 per card charge |
483
+ | Card purchase of coins | 3.5% + $0.30 | 5.5% + $0.50 |
484
+ | Platform Commerce card sales | 3.5% + $0.30 | 5.5% + $0.50 |
485
+ | Subscriptions | 3.5% + $0.30 per card charge | 5.5% + $0.50 per card charge |
361
486
  | Card issued outside the US | plus 1.5% of the listed price (before tax) | plus 1.5% of the listed price (before tax) |
362
487
  | 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 |
363
- | Fraud screening | included | included |
364
- | 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 |
365
- | 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 |
488
+ | Fraud screening | included on every card payment | included on every card payment |
489
+ | 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 |
490
+ | 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 |
366
491
  | Minimum card purchase (coins, Platform Commerce card sales) | $2.99, enforced from 2026-10-27 | $2.99, enforced from 2026-10-27 |
367
- | Item purchases (coins spent on an item) | 10% | 10% |
492
+ | Item purchases (coins spent on an item) | 10% (you keep 90%) | 10% (you keep 90%) |
493
+ | Platform Commerce balance purchases | 3.5% | 3.5% |
494
+ | 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 |
495
+ | Payouts to your bank | 1% per payout, capped at $500 | 1% per payout, capped at $500 |
496
+
497
+ 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/
498
+
499
+ **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.
368
500
 
369
- 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/
501
+ **Sends and transfers.** The fee is 10% of the amount moved, a network standard that is the same for every title: 3.5% to the sending title, 3.5% to the receiving title and 3% to INVO. Moving 100.00: the fee is 10.00 (3.50 to the sending title, 3.50 to the receiving title, 3.00 to INVO) and the recipient gets 90.00. A move inside one title earns that title both shares, 7.00, and INVO 3.00. Reconcile from the webhook figures rather than recomputing.
502
+
503
+ **Payouts.** INVO pays you, the partner, and you pay your own players from your own funds; INVO does not pay players. Every payout of your balance to your bank (developer withdrawals and partner payouts) carries a payout fee of 1% of the amount, capped at $500 per payout; negotiated rates may apply. The fee is deducted from the payout: `payout.status_changed` carries `offboarding_fee_pct`, `offboarding_fee_usd`, `offboarding_fee_cap_usd` and `net_payout_usd` (what reaches your bank). Negotiated or custom rates for any fee here are available on request.
370
504
 
371
505
  **What the tier changes in what the SDK returns** (all additive):
372
506
 
@@ -443,12 +577,13 @@ window.addEventListener("message", (e) => {
443
577
  if (e.origin !== "https://invo.network") return; // sandbox: "https://sandbox.invo.network"
444
578
  if (e.data?.type === "INVO_CHECKOUT_COMPLETE") {
445
579
  // UX hint ONLY (unsigned). data = { status, new_balance, currency_name, transaction_id }
580
+ // A finished purchase reads status "completed" (not "success"): compare against that.
446
581
  refreshBalanceOptimistically(e.data.data.new_balance);
447
582
  }
448
583
  });
449
584
  ```
450
585
 
451
- The hosted page handles card entry, saved cards, and 3-D Secure (with a top-level break-out when framed). **Grant currency off the `purchase.completed` webhook**, not the postMessage hint. No browser SDK method *charges* (the browser only opens the URL), but it can now **read what happened**, below.
586
+ On a finished purchase the message's `data.status` is `"completed"`, never `"success"`; a listener that waits for `"success"` never fires. The hosted page handles card entry, saved cards, and 3-D Secure (with a top-level break-out when framed). **Grant currency off the `purchase.completed` webhook**, not the postMessage hint. No browser SDK method *charges* (the browser only opens the URL), but it can now **read what happened**, below.
452
587
 
453
588
  ### Did the purchase go through? (the status read)
454
589
 
@@ -690,7 +825,7 @@ Show "purchase complete" only when `credited` is `true`. `alreadyProcessed` is a
690
825
 
691
826
  ### INVO's card fee: quote, show, acknowledge
692
827
 
693
- 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.
828
+ 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.
694
829
 
695
830
  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:
696
831
 
@@ -705,7 +840,7 @@ const q = await server.quoteCurrencyPurchase({
705
840
  // country: "US", subdivision: "NY", // optional: the buyer's billing place, for any tax
706
841
  });
707
842
  // q.subtotalUsd "10.00" + q.processingFeeUsd "0.00" = q.totalUsd "10.00" (q.coins "100.00")
708
- // q.partnerFeeUsd "0.75" when INVO sends it: YOUR fee (Open, US card), never the player's
843
+ // q.partnerFeeUsd "0.65" when INVO sends it: YOUR fee (Open, US card), never the player's
709
844
  // q.breakdown: every line, with taxNote / processingFeeNote sentences you can show as is
710
845
  // q.minPurchaseWarning: set while an amount under the minimum card purchase is still accepted
711
846
 
@@ -719,7 +854,7 @@ const purchase = await server.purchaseCurrency({
719
854
  });
720
855
  // On "success": purchase.chargeTotalUsd "10.00", purchase.coinsCredited "100.00",
721
856
  // purchase.processingFeeUsd "0.00", purchase.feeTakenFrom "partner",
722
- // purchase.partnerFeeUsd "0.75" (Open; "1.05" on Merchant of Record),
857
+ // purchase.partnerFeeUsd "0.65" (Open; "1.05" on Merchant of Record),
723
858
  // purchase.internationalCardFeeUsd "0.00" ("0.15" on a card issued outside the US)
724
859
  ```
725
860
 
@@ -843,7 +978,7 @@ const handle = invo.platformCommerce.mountCheckout("#checkout", checkoutUrl, {
843
978
  // later: handle.destroy();
844
979
  ```
845
980
 
846
- `mountCheckout` accepts completion messages **only from the checkout page's own origin**, and `onComplete` is a UX signal — show "processing", then reconcile server-side.
981
+ `mountCheckout` accepts completion messages **only from the checkout page's own origin** (a finished purchase reports status `"completed"`, not `"success"`), and `onComplete` is a UX signal: show "processing", then reconcile server-side.
847
982
 
848
983
  > ⚠️ **The card sale is real only on the `platform_commerce.purchased` webhook — never on the client return or the in-frame completion event** (a client can be tampered with). Fulfill on the webhook.
849
984
 
@@ -862,6 +997,17 @@ const ref = await server.platformCommerce.refund({ orderId: r.orderId, reason: "
862
997
  // A second refund of the same order throws 409 (err.isAlreadyRefunded) — treat as already done.
863
998
  ```
864
999
 
1000
+ **Purchase history.** `getPurchaseHistory` lists one player's Platform Commerce purchases, newest first, one page at a time (`GET /api/platform-commerce/purchase-history`). Each entry has exactly the fields `getStatus` returns for that order. Pass `nextCursor` back as `cursor`; it is `null` on the last page. `iteratePurchaseHistory` walks every page for you.
1001
+
1002
+ ```ts
1003
+ const page = await server.platformCommerce.getPurchaseHistory({ playerEmail: "user@example.com", limit: 50 });
1004
+ // page.purchases: PlatformOrderStatusResult[] page.hasMore page.nextCursor
1005
+ for await (const order of server.platformCommerce.iteratePurchaseHistory({ playerEmail: "user@example.com" })) {
1006
+ // order.orderId, order.status, order.usdAmount, order.receiptNumber (Merchant of Record) ...
1007
+ }
1008
+ // 400 INVALID_CURSOR (a cursor from another player), 404 PLAYER_NOT_FOUND (err.isPlayerNotFound)
1009
+ ```
1010
+
865
1011
  **Card sales refunded in parts.** A card refund normally returns the whole charge in one go, and the result is as above. A sale ends up refunded in parts only when part of the charge was already refunded outside INVO's API: the next `refund()` records that existing refund and moves no new money (`ref.adopted === true`, `ref.partialRefund === true`, `ref.refundedTotalUsd`, `ref.chargeTotalUsd`, `ref.remainingUsd`; the order stays `completed`). Every figure is then that refund's own share, and `partialRefund` / `refundedTotalUsd` / `chargeTotalUsd` appear on each part (`partialRefund: false` on the last); on a one-shot full refund none of the parts keys appear; `adopted: true` can still appear if the call recorded an existing full refund.
866
1012
 
867
1013
  ```ts
@@ -876,7 +1022,7 @@ await server.platformCommerce.refund({ orderId, refundRemaining: true });
876
1022
  - `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.
877
1023
 
878
1024
  - **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.
879
- - 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`.
1025
+ - 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`.
880
1026
  - 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).
881
1027
  - Fulfill on the **`platform_commerce.purchased`** webhook; handle **`platform_commerce.refunded`** for reversals.
882
1028
 
@@ -893,7 +1039,7 @@ A subscription is a standing agreement, created by **your server**, under which
893
1039
 
894
1040
  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.
895
1041
 
896
- - **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.
1042
+ - **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.
897
1043
  - **Steam rail: unchanged.** INVO spends the member's wallet first and tops up from Steam for the shortfall only.
898
1044
  - **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.
899
1045
  - **`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.
@@ -1278,8 +1424,8 @@ for (const w of r.warnings ?? []) log(w.code); // "REASON_RECOMMENDED"
1278
1424
  **What else happens.**
1279
1425
 
1280
1426
  - **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.
1281
- - **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.
1282
- - **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.
1427
+ - **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.
1428
+ - **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.
1283
1429
  - **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.
1284
1430
  - **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.
1285
1431
 
@@ -1427,6 +1573,39 @@ Lookup is by email only — there is no by-`playerId` balance route (a `playerId
1427
1573
  internal id). For a **client-side** read, use `InvoClient.getBalance()` (player-token; identity
1428
1574
  comes from the token, no PII).
1429
1575
 
1576
+ ### Player activity (one list of everything)
1577
+
1578
+ `getPlayerActivity` returns one merged, newest-first list of a player's money activity in your
1579
+ game (`GET /api/sdk/players/activity`, game secret): currency purchases, item purchases,
1580
+ Platform Commerce purchases, sends and transfers, in both directions. Only rows where your game
1581
+ is a party through this player are listed; the other side of a cross-game send or transfer is
1582
+ named by game only (`counterpartyGame`).
1583
+
1584
+ ```ts
1585
+ const page = await server.getPlayerActivity({
1586
+ playerEmail: "p@example.com",
1587
+ limit: 50, // 1 to 100, default 50
1588
+ types: ["send", "transfer"], // optional: currency_purchase, item_purchase, platform_commerce, send, transfer
1589
+ });
1590
+ // page.activity[0] = { id, type, direction: "in" | "out" | "self", amount, amountUnit, currency,
1591
+ // status, statusDetail, expiryReason, counterpartyGame, createdAt, completedAt, orderId, raw }
1592
+ // page.nextCursor: pass back as `cursor` (with the same types); null on the last page
1593
+
1594
+ for await (const row of server.iteratePlayerActivity({ playerEmail: "p@example.com" })) {
1595
+ // every page, one row at a time
1596
+ }
1597
+ ```
1598
+
1599
+ - **An `"in"` send or transfer is listed as soon as it names this player, in any status**
1600
+ (awaiting collection, completed, expired, refunded). Read `status` and `statusDetail` before
1601
+ treating it as credited. `expiryReason` says why an expired one lapsed.
1602
+ - `direction` is `"in"`, `"out"` or `"self"` (a send or transfer where the player is both sender
1603
+ and recipient in your game). It is not the `"incoming"` / `"outgoing"` of the per-type history
1604
+ reads. `amountUnit` is `"usd"` only on the card leg of a Platform Commerce purchase.
1605
+ - Errors: `400 INVALID_INPUT` (for example an unknown kind in `types`), `400 INVALID_CURSOR` (a
1606
+ cursor from another player or other `types`), `404 PLAYER_NOT_FOUND` (`err.isPlayerNotFound`),
1607
+ `500 PLAYER_ACTIVITY_FAILED` (retry later), `429` (back off by `err.retryAfter`).
1608
+
1430
1609
  ---
1431
1610
 
1432
1611
  ## Sends & transfers (move currency between players)
@@ -2325,7 +2504,7 @@ export const POST = createWebhookHandler({
2325
2504
  |---|---|---|
2326
2505
  | `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`. |
2327
2506
  | `purchase.failed` | `platform` rail only | handle failures |
2328
- | `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` |
2507
+ | `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`. A card dispute close also carries `dispute_fee_usd` (string decimal, `"0.00"` when INVO bears the fee, `null` when undecided) and `dispute_fee_charged_to_partner` (boolean or `null`); from November 8, 2026 the dispute fee on an Open-tier card sale is passed through to you at cost. **If you revoke on `purchase.refunded`, handle this too:** a Steam chargeback no longer arrives as `purchase.refunded` |
2329
2508
  | `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` |
2330
2509
  | `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`) |
2331
2510
  | `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`) |
@@ -2337,7 +2516,10 @@ export const POST = createWebhookHandler({
2337
2516
  | `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) |
2338
2517
  | `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`) |
2339
2518
  | `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`) |
2340
- | `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 |
2519
+ | `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. `transfer.claim_expired` and an expiry `transfer.refunded` carry `expiry_reason` (`"approval_expired"`, `"pin_expired"` or `"claim_expired"`); read it rather than `reason` for the precise cause |
2520
+ | `transfer.claim_pending` / `transfer.claim_expired` | sends & transfers | an `"outbound"` copy goes to the sending title and an `"inbound"` copy to the receiving title (`direction`); a move inside one title sends that title **both**, each with its own `event_id`. Dedupe on `event_id`, not `transaction_id`, and act on `direction`. `claim_pending` carries `transaction_id, order_id, amount, net_transfer_amount, claim_code_expires_at, from_game_id, to_game_id, from_player_id, direction` (+ `to_phone, to_identity_id` inbound) |
2521
+ | `player.phone_changed` | a player's phone changed (confirmed by the player, or by INVO support); sent to every game the player is in | store the new `identity_id` and re-mint the token (`player_email, previous_phone_masked, new_phone_masked, new_phone_included, changed_at, source, identity_id, previous_identity_id`; `new_phone` only for the game that requested the change). Never push your stored number back; ask the player. See [Player-confirmed phone change](#player-confirmed-phone-change) |
2522
+ | `payout.status_changed` | a payout of your balance to your bank | track the payout (`payout_id, status, previous_status, requested_amount_usd`, plus the payout fee: `offboarding_fee_pct, offboarding_fee_usd, offboarding_fee_cap_usd, net_payout_usd`, `null` on a payout recorded before the fee existed) |
2341
2523
 
2342
2524
  On a Merchant of Record account, `purchase.completed`, `platform_commerce.purchased` and `subscription.renewed` for a card sale also carry `receipt_number` and `receipt_url` (the receipt INVO issued to the buyer), and `purchase.refunded`, `platform_commerce.refunded` and `subscription.refunded` carry the refund receipt's. Absent on Open. `purchase.completed` also carries `tax_treatment` (`"partner_responsible"` on Open).
2343
2525
 
@@ -2422,7 +2604,7 @@ Helpers:
2422
2604
  | `.isDuplicateClientRequestId` | Platform Commerce card purchase whose `clientRequestId` already has a payment (409); `order_id` + `order_status` on `.body` |
2423
2605
  | `.isIdentityCheckUnavailable` | a claim or confirm-receipt could not be checked just now (503); nothing moved, retry in a few seconds |
2424
2606
  | `.isNotPlatformTenant` | Platform Commerce called by a non-platform tenant (403) — use `purchaseItem`/`createCheckout` instead |
2425
- | `.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) |
2607
+ | `.isAmountBelowMinimum` / `.isBelowCardMinimum` / `.isAboveCardMaximum` | amount too small for the fee to round up / card charge under $0.50 at any date (`.code` `BELOW_CARD_MINIMUM`, `.minUsd` `"0.50"`, no `.enforcedFrom`; the SDK's own pre-network refusal on the Platform Commerce card leg keeps its earlier `.code` and carries `.publicCode` `BELOW_CARD_MINIMUM`), 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) |
2426
2608
  | `.isAlreadyRefunded` | Platform Commerce refund of an already-refunded order (409) — treat as already done |
2427
2609
  | `.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 |
2428
2610
  | `.isAmountBelowFee` | deprecated: `AMOUNT_BELOW_FEE` is no longer returned (the partner pays the card fee) |
@@ -2430,7 +2612,8 @@ Helpers:
2430
2612
  | `.isEnrollmentAuthorizationRequired` | first-enrollment needs the OTP grant → `enrollmentBegin`/`enrollmentVerify` |
2431
2613
  | `.isEnrollmentProofRequired` | another method exists → prove it via `linkDevice` |
2432
2614
  | `.isPhoneShareApprovalRequired` | phone needs owner approval — at register/mint **or** at claim/`confirmReceipt*` (contested receiver phone) → show `.message` (+ `.phoneShareLast4`), retry the same call after approval |
2433
- | `.isPhoneShareRefused` / `.isPhoneMismatch` / `.isPhoneChangeRequiresVerification` | `mintPlayerToken` / `registerPlayer` / `updatePlayerPhone` refusals (409); see [Registering players and changing their phone](#registering-players-and-changing-their-phone) |
2615
+ | `.isPhoneShareRefused` / `.isPhoneMismatch` / `.isPhoneChangeRequiresVerification` | `mintPlayerToken` / `registerPlayer` / `updatePlayerPhone` refusals (409); see [Registering players and changing their phone](#registering-players-and-changing-their-phone). On `.isPhoneChangeRequiresVerification`, `.changeRequestEndpoint` names the change request route |
2616
+ | `.isConfirmOnInvoPage` / `.isChangeRequestNotFound` / `.isChangeRequestNotReady` / `.isChangeRequestNotPending` (+ `.changeRequestStatus`) / `.isChangeRequestInProgress` / `.isPhoneChangeLocked` / `.isTooManyChangeRequests` / `.isPhoneChangeUnavailable` / `.isDeviceSignalRejected` / `.isPhoneChangeRecoveryCooldown` / `.isDeviceEnrolledAfterRequest` / `.isPendingTransfersToOldPhone` / `.isPendingTransfersToNewPhone` | the phone change refusals (the last two also on `updatePlayerPhone`); see [Player-confirmed phone change](#player-confirmed-phone-change) |
2434
2617
  | `.isPlayerTokenStale` | approve refused (403 `PLAYER_TOKEN_STALE`): the token predates the sender's phone being added. Re-mint (or use the initiate's `playerToken`) and retry once; never auto-retried |
2435
2618
  | `.isSteamValueNonTransferable` | initiate blocked (409): would move more than the non-Steam balance to a non-Steam destination → show `.message`, cap input at `.steamTransferableMax` (`.steamOriginAmount` = Steam-locked portion) |
2436
2619
  | `.isNonSteamValueIntoSteamBlocked` | initiate blocked (409): non-Steam value can't move into a Steam title → show `.message`, pick a non-Steam destination |
@@ -2463,7 +2646,9 @@ try {
2463
2646
  |---|---|
2464
2647
  | `mintPlayerToken({ playerEmail, playerPhone?, playerName? })` | `{ token, expiresAt, identityId, created?, phoneMismatch? }`: session mint; an unknown player is a 404 without `playerPhone` and is created with it (`created: true`); an existing player's phone is never changed (`phoneMismatch: true` when it differs). See [Player token](#player-token-session-mint-for-an-existing-player) |
2465
2648
  | `registerPlayer({ playerEmail, playerPhone, playerName? })` | `{ status: "created" \| "exists", identityId, playerToken?, playerTokenExpiresAt?, raw }`; moves no money. `isPhoneMismatch` / `isPhoneShareRefused` |
2466
- | `updatePlayerPhone({ playerEmail, newPhone })` | `{ status: "updated" \| "unchanged", identityRekeyed, identityId, playerToken?, playerTokenExpiresAt?, raw }`; never auto-retried. `isPhoneChangeRequiresVerification` / `isPhoneShareRefused` / `isPlayerNotFound` |
2649
+ | `updatePlayerPhone({ playerEmail, newPhone })` | `{ status: "updated" \| "unchanged", identityRekeyed, identityId, playerToken?, playerTokenExpiresAt?, raw }`; never auto-retried. `isPhoneChangeRequiresVerification` / `isPhoneShareRefused` / `isPendingTransfersToOldPhone` / `isPendingTransfersToNewPhone` / `isPlayerNotFound` |
2650
+ | `requestPhoneChange({ playerEmail, newPhone })` | `{ changeRequestId, status: "pending_confirmation", expiresAt, delivery, confirmation, message, raw }` (HTTP 202); INVO emails the player, who confirms on INVO's page; never auto-retried. See [Player-confirmed phone change](#player-confirmed-phone-change) |
2651
+ | `getPhoneChange(changeRequestId)` | `{ changeRequestId, status, confirmation, delivery, newPhoneMasked, createdAt, expiresAt, confirmedAt, confirmedVia, raw }` |
2467
2652
  | `initiateSend(input)` | `{ transactionId, verificationMethod, guardianApproval?, identityRekeyed?, playerToken?, playerTokenExpiresAt?, identityId?, claimDeliveryPlanned?, raw }`; when `identityRekeyed` is `true`, hand the browser `playerToken` before it approves |
2468
2653
  | `initiateTransfer(input)` | same as `initiateSend` |
2469
2654
  | `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) |
@@ -2473,9 +2658,13 @@ try {
2473
2658
  | `getOrderDetails({ orderId? \| transactionId? })` | `{ order, financialSummary, statusTimeline, receiptNumber?, receiptUrl?, raw }`; the receipt fields on a Merchant of Record currency purchase only |
2474
2659
  | `purchaseItem(input)` | `{ status, transactionId, orderId, newBalance, previousBalance, currencyName, financialBreakdown?, raw }` — **game** tenant spending game currency on an in-game item |
2475
2660
  | `getItemPurchaseHistory({ playerEmail, limit?, offset? })` | `{ history, pagination, raw }` |
2661
+ | `getPlayerActivity({ playerEmail, limit?, cursor?, types? })` | `PlayerActivityResult`: `{ playerEmail, gameId, types, activity, limit, hasMore, nextCursor, raw }`, one merged, newest-first page of purchases, sends and transfers. See [Player activity](#player-activity-one-list-of-everything) |
2662
+ | `iteratePlayerActivity({ playerEmail, types?, pageSize? })` | async iterator over every `PlayerActivityEntry`, following `nextCursor` |
2476
2663
  | `getItemOrderDetails({ orderId? \| transactionId? \| clientRequestId? })` | `{ order, financialSummary, statusTimeline, raw }` |
2477
2664
  | `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` |
2478
2665
  | `platformCommerce.getStatus(orderId)` | `{ orderId, status, gameCurrencyAmount?, usdAmount?, paymentMethod?, createdAt?, receiptNumber?, receiptUrl?, raw }` |
2666
+ | `platformCommerce.getPurchaseHistory({ playerEmail, limit?, cursor? })` | `{ playerEmail, gameId, purchases, limit, hasMore, nextCursor, raw }`; each purchase is what `getStatus` returns, newest first |
2667
+ | `platformCommerce.iteratePurchaseHistory({ playerEmail, pageSize? })` | async iterator over every purchase, following `nextCursor` |
2479
2668
  | `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) |
2480
2669
  | `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) |
2481
2670
  | `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) |
@@ -2497,7 +2686,7 @@ try {
2497
2686
  | `getLinkedIdentities({ playerEmail? \| playerPhone? })` | `{ walletUserId, primaryEmail, primaryPhone, isMinor, emails, notFound, raw }` — **server-only** (returns PII) |
2498
2687
  | ~~`verifySmsTransfer(txnId, smsPin)`~~ / ~~`verifySmsSend(txnId, smsPin)`~~ | **Deprecated (3.1.0), removal at a future major.** `SmsVerifyResult` — completes the SMS-PIN path when `verificationMethod: "sms"`. Prefer passkey enrollment + `approveTransfer`/`approveSend`; keep this only for users who can't enroll. Still fully functional. |
2499
2688
  | `claimTransfer(input)` / `claimCurrency(input)` | `ClaimResult` — redeem a claim code (`needsAccountSelection` + `candidates` on a multi-account phone) |
2500
- | `getTransferStatus(txnId)` / `getSendStatus(txnId)` | `TransactionStatusResult` — poll outbound state (`verificationState`) |
2689
+ | `getTransferStatus(txnId)` / `getSendStatus(txnId)` | `TransactionStatusResult`: poll outbound state (`verificationState`); `expiryReason` once expired |
2501
2690
  | `getGuardianApprovalStatus(txnId)` | `GuardianApprovalStatusResult` — poll a guardian hold to resolution (`state`) |
2502
2691
  | `getDestinations({ sourceGameId, direction? })` | `DestinationsResult` — server-side (game-secret) destinations; same rows as the browser variant |
2503
2692
  | `beginDeviceApproval({ playerToken, transactionId, flow, channel? })` | `DeviceApprovalGrant` — `{ deviceCode, userCode, verificationUri, verificationUriComplete, expiresIn, interval, channel, raw }`. **Player token**, never the game secret. Show `verificationUriComplete` as a QR |
@@ -2522,6 +2711,8 @@ Every method also accepts an optional final `{ signal }` (`AbortSignal`) for can
2522
2711
  | `recoveryBegin()` / `recoveryComplete(code)` | passkey recovery for `ENROLLMENT_REQUIRES_PROOF` when the passkey was lost/deleted (then retry `enrollPasskey`) — recovered keys can't move money OUT for 24h (`PASSKEY_RECOVERY_COOLDOWN`) |
2523
2712
  | `approveSend(txnId)` / `approveTransfer(txnId)` | `{ status, next, transactionId, claimCode?, claimCodeExpiresAt?, holdReason?, risk?, guardianApproval?, pollEndpoint?, claimDelivery?, raw }`; `claimDelivery` is `"email"`, `"none"` or legacy `"sms"`. 403 `err.isPlayerTokenStale`: re-mint and retry once (never auto-retried) |
2524
2713
  | `confirmReceiptSend(txnId)` / `confirmReceiptTransfer(txnId)` | `{ status, holdReason?, raw }` |
2714
+ | `listPhoneChangeApprovals()` | `{ approvals: [{ changeRequestId, gameName, oldPhoneMasked, newPhoneMasked, expiresAt }], raw }`: phone changes waiting for this player's enrolled device |
2715
+ | `approvePhoneChange(changeRequestId, { deviceFingerprint, decision?, sign \| deviceSignal })` | `{ status: "confirmed", changeRequestId, identityId, previousIdentityId, playersUpdated, verifiedPhone, playerToken?, playerTokenExpiresAt?, raw }` or `{ status: "denied", changeRequestId, raw }`; the device key signs `phone-change\|<id>\|<nonce>\|<timestamp>` (`phone-change-deny\|...` to decline); `phoneChangeSignalMessage()` builds it |
2525
2716
  | `linkDevice()` | `{ status, raw }` — call with no arguments; the server mints the link id (a value passed by 3.10-era code is still accepted and ignored) |
2526
2717
  | `getPendingCollect()` | `{ pending, raw }` — the player's own pending-to-collect list (player-token) |
2527
2718
  | `getDestinations({ direction? })` | `{ availableGames, sourceGameName, transferMode, … }` — where the player can send/transfer, metadata inline |