@invonetwork/web-sdk 3.20.0 → 3.22.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 +63 -0
- package/README.md +289 -34
- package/dist/{chunk-6IY4473A.js → chunk-BOD4WOWO.js} +257 -7
- package/dist/index.cjs +347 -6
- package/dist/index.d.cts +58 -5
- package/dist/index.d.ts +58 -5
- package/dist/index.js +119 -4
- package/dist/server.cjs +598 -41
- package/dist/server.d.cts +233 -28
- package/dist/server.d.ts +233 -28
- package/dist/server.js +380 -27
- package/dist/{types-BwgkJoM6.d.cts → types-C7vpPqsF.d.cts} +425 -6
- package/dist/{types-BwgkJoM6.d.ts → types-C7vpPqsF.d.ts} +425 -6
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
First-party TypeScript SDK for integrating **INVO** into partner **web** platforms (storefronts, web games, dashboards). It wraps INVO's web money flows behind a typed, versioned API — the web analog of the Unity/Unreal plugins.
|
|
4
4
|
|
|
5
|
-
> **Status:** `v3.
|
|
5
|
+
> **Status:** `v3.22.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.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
|
|
@@ -93,6 +93,8 @@ The right approval method is a property of the **client the player is sitting in
|
|
|
93
93
|
- [Passkeys are the gold standard — don't build on SMS](#passkeys-are-the-gold-standard--dont-build-on-sms)
|
|
94
94
|
- [Install](#install)
|
|
95
95
|
- [Architecture & the two entry points](#architecture--the-two-entry-points)
|
|
96
|
+
- [Registering players and changing their phone](#registering-players-and-changing-their-phone)
|
|
97
|
+
- [Player-confirmed phone change](#player-confirmed-phone-change)
|
|
96
98
|
- [Before you go live](#before-you-go-live)
|
|
97
99
|
- [Configuration](#configuration)
|
|
98
100
|
- [Tiers](#tiers)
|
|
@@ -108,6 +110,7 @@ The right approval method is a property of the **client the player is sitting in
|
|
|
108
110
|
- [Paid trials](#paid-trials)
|
|
109
111
|
- [Subscription packages](#subscription-packages)
|
|
110
112
|
- [Player balance](#player-balance)
|
|
113
|
+
- [Player activity (one list of everything)](#player-activity-one-list-of-everything)
|
|
111
114
|
- [Sends & transfers (move currency between players)](#sends--transfers-move-currency-between-players)
|
|
112
115
|
- [Legacy fallback: the SMS PIN (being retired)](#legacy-fallback-the-sms-pin-being-retired)
|
|
113
116
|
- [Sends and transfers, stage by stage](#sends-and-transfers-stage-by-stage)
|
|
@@ -173,28 +176,209 @@ Build and test against the **dev console + sandbox** first, then switch to the *
|
|
|
173
176
|
|
|
174
177
|
### Player token (session mint for an existing player)
|
|
175
178
|
|
|
176
|
-
`mintPlayerToken` mints a short-lived, game-scoped **session token** for a player
|
|
177
|
-
**already exists**
|
|
178
|
-
|
|
179
|
-
such player exists). It only needs `playerEmail`:
|
|
179
|
+
`mintPlayerToken` mints a short-lived, game-scoped **session token** for a player. For a
|
|
180
|
+
player who **already exists** in your title it looks them up by `playerEmail` and returns a
|
|
181
|
+
token for their identity; it only needs `playerEmail`:
|
|
180
182
|
|
|
181
183
|
```ts
|
|
182
184
|
// your backend
|
|
183
185
|
const { token } = await invo.mintPlayerToken({ playerEmail: "player@example.com" });
|
|
184
186
|
```
|
|
185
187
|
|
|
186
|
-
|
|
187
|
-
|
|
188
|
+
For a player who is **not in your title yet**, the answer depends on `playerPhone`:
|
|
189
|
+
|
|
190
|
+
- without `playerPhone`: `404`, `err.isPlayerNotFound` (unchanged behaviour);
|
|
191
|
+
- with `playerPhone` (E.164) and optionally `playerName`: INVO **creates** the player and
|
|
192
|
+
the result carries `created: true`. A first-time receiver can then collect in-game without
|
|
193
|
+
buying first.
|
|
194
|
+
|
|
195
|
+
```ts
|
|
196
|
+
const t = await invo.mintPlayerToken({
|
|
197
|
+
playerEmail: "player@example.com",
|
|
198
|
+
playerPhone: "+15555550100",
|
|
199
|
+
playerName: "Pat",
|
|
200
|
+
});
|
|
201
|
+
if (t.created) { /* the player was new to your title */ }
|
|
202
|
+
if (t.phoneMismatch) { /* they exist with a different phone; see updatePlayerPhone */ }
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
An existing player's phone is **never changed** by this call. When it differs from the
|
|
206
|
+
`playerPhone` you passed, the token is still minted for that player and the result carries
|
|
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.
|
|
188
215
|
|
|
189
216
|
**Where phone actually matters.** A player's INVO identity encodes their phone, and cross-game
|
|
190
|
-
money routing keys off it
|
|
217
|
+
money routing keys off it:
|
|
191
218
|
|
|
192
219
|
- **`initiateSend` / `initiateTransfer`** require the **sender's** phone (E.164), and take the
|
|
193
|
-
**recipient's** phone. You can send by the recipient's **phone alone
|
|
220
|
+
**recipient's** phone. You can send by the recipient's **phone alone**; they supply their
|
|
194
221
|
email when they claim.
|
|
195
222
|
- An account with no phone can't receive cross-game money and can't take part in the
|
|
196
|
-
account-linking consent
|
|
197
|
-
(
|
|
223
|
+
account-linking consent, so make sure players have a phone at **creation / enrollment**
|
|
224
|
+
(`registerPlayer`, or `mintPlayerToken` with `playerPhone`), before they transact.
|
|
225
|
+
|
|
226
|
+
### Registering players and changing their phone
|
|
227
|
+
|
|
228
|
+
Two server calls, both authenticated with your game secret, neither moves money nor sends the
|
|
229
|
+
player a message.
|
|
230
|
+
|
|
231
|
+
**`registerPlayer({ playerEmail, playerPhone, playerName? })`** creates the player in your
|
|
232
|
+
title. It returns `status: "created"` (new) or `status: "exists"` (already in your title with
|
|
233
|
+
that phone), the `identityId`, and a `playerToken` / `playerTokenExpiresAt` when INVO can issue
|
|
234
|
+
one for your title, so you can hand the browser a token straight away.
|
|
235
|
+
|
|
236
|
+
```ts
|
|
237
|
+
const reg = await invo.registerPlayer({
|
|
238
|
+
playerEmail: "player@example.com",
|
|
239
|
+
playerPhone: "+15555550100",
|
|
240
|
+
playerName: "Pat",
|
|
241
|
+
});
|
|
242
|
+
// reg.status: "created" | "exists"; reg.playerToken may be present
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
**`updatePlayerPhone({ playerEmail, newPhone })`** sets the phone of a player already in your
|
|
246
|
+
title. It returns `status: "updated"` or `status: "unchanged"`, and `identityRekeyed`. A phone
|
|
247
|
+
change can give the player a **new INVO identity**: when `identityRekeyed` is `true`, every
|
|
248
|
+
player token minted before the change is out of date, so use the `playerToken` in the result
|
|
249
|
+
(or mint a new one). This call is never retried automatically.
|
|
250
|
+
|
|
251
|
+
```ts
|
|
252
|
+
const upd = await invo.updatePlayerPhone({ playerEmail: "player@example.com", newPhone: "+15555550111" });
|
|
253
|
+
if (upd.identityRekeyed && upd.playerToken) handTokenToBrowser(upd.playerToken);
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
| Refusal | HTTP | Means | Do |
|
|
257
|
+
|---|---|---|---|
|
|
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. |
|
|
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. |
|
|
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)). |
|
|
261
|
+
| `err.isPlayerNotFound` | 404 | `updatePlayerPhone` (or `mintPlayerToken` without `playerPhone`): no player with that email in your title. | Create the player first (`registerPlayer`). |
|
|
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`). |
|
|
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. |
|
|
266
|
+
| `PHONE_UPDATE_UNAVAILABLE` | 503 | `updatePlayerPhone` could not be checked right now. Nothing changed. | Try again shortly. |
|
|
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`.
|
|
198
382
|
|
|
199
383
|
### Token bootstrap (both modes)
|
|
200
384
|
|
|
@@ -296,18 +480,27 @@ Every INVO developer account is on one of two tiers. The SDK calls are the same
|
|
|
296
480
|
| Who it is for | every account, including all current ones | accounts INVO has approved |
|
|
297
481
|
| Who the seller is | **you** | **INVO** |
|
|
298
482
|
| Tax on sales | **you** are responsible for it; INVO collects none | **INVO** calculates, collects and remits it |
|
|
299
|
-
| Card purchase of coins |
|
|
300
|
-
| Platform Commerce card sales |
|
|
301
|
-
| Subscriptions |
|
|
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 |
|
|
302
486
|
| Card issued outside the US | plus 1.5% of the listed price (before tax) | plus 1.5% of the listed price (before tax) |
|
|
303
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 |
|
|
304
|
-
| Fraud screening | included | included |
|
|
305
|
-
| Chargebacks disputed as fraud (card sales) |
|
|
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 |
|
|
306
490
|
| 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 |
|
|
307
491
|
| Minimum card purchase (coins, Platform Commerce card sales) | $2.99, enforced from 2026-10-27 | $2.99, enforced from 2026-10-27 |
|
|
308
|
-
| 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.
|
|
500
|
+
|
|
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.
|
|
309
502
|
|
|
310
|
-
|
|
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.
|
|
311
504
|
|
|
312
505
|
**What the tier changes in what the SDK returns** (all additive):
|
|
313
506
|
|
|
@@ -384,12 +577,13 @@ window.addEventListener("message", (e) => {
|
|
|
384
577
|
if (e.origin !== "https://invo.network") return; // sandbox: "https://sandbox.invo.network"
|
|
385
578
|
if (e.data?.type === "INVO_CHECKOUT_COMPLETE") {
|
|
386
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.
|
|
387
581
|
refreshBalanceOptimistically(e.data.data.new_balance);
|
|
388
582
|
}
|
|
389
583
|
});
|
|
390
584
|
```
|
|
391
585
|
|
|
392
|
-
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.
|
|
393
587
|
|
|
394
588
|
### Did the purchase go through? (the status read)
|
|
395
589
|
|
|
@@ -631,7 +825,7 @@ Show "purchase complete" only when `credited` is `true`. `alreadyProcessed` is a
|
|
|
631
825
|
|
|
632
826
|
### INVO's card fee: quote, show, acknowledge
|
|
633
827
|
|
|
634
|
-
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: **
|
|
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.
|
|
635
829
|
|
|
636
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:
|
|
637
831
|
|
|
@@ -646,7 +840,7 @@ const q = await server.quoteCurrencyPurchase({
|
|
|
646
840
|
// country: "US", subdivision: "NY", // optional: the buyer's billing place, for any tax
|
|
647
841
|
});
|
|
648
842
|
// q.subtotalUsd "10.00" + q.processingFeeUsd "0.00" = q.totalUsd "10.00" (q.coins "100.00")
|
|
649
|
-
// q.partnerFeeUsd "0.
|
|
843
|
+
// q.partnerFeeUsd "0.65" when INVO sends it: YOUR fee (Open, US card), never the player's
|
|
650
844
|
// q.breakdown: every line, with taxNote / processingFeeNote sentences you can show as is
|
|
651
845
|
// q.minPurchaseWarning: set while an amount under the minimum card purchase is still accepted
|
|
652
846
|
|
|
@@ -660,7 +854,7 @@ const purchase = await server.purchaseCurrency({
|
|
|
660
854
|
});
|
|
661
855
|
// On "success": purchase.chargeTotalUsd "10.00", purchase.coinsCredited "100.00",
|
|
662
856
|
// purchase.processingFeeUsd "0.00", purchase.feeTakenFrom "partner",
|
|
663
|
-
// purchase.partnerFeeUsd "0.
|
|
857
|
+
// purchase.partnerFeeUsd "0.65" (Open; "1.05" on Merchant of Record),
|
|
664
858
|
// purchase.internationalCardFeeUsd "0.00" ("0.15" on a card issued outside the US)
|
|
665
859
|
```
|
|
666
860
|
|
|
@@ -784,7 +978,7 @@ const handle = invo.platformCommerce.mountCheckout("#checkout", checkoutUrl, {
|
|
|
784
978
|
// later: handle.destroy();
|
|
785
979
|
```
|
|
786
980
|
|
|
787
|
-
`mountCheckout` accepts completion messages **only from the checkout page's own origin
|
|
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.
|
|
788
982
|
|
|
789
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.
|
|
790
984
|
|
|
@@ -803,6 +997,17 @@ const ref = await server.platformCommerce.refund({ orderId: r.orderId, reason: "
|
|
|
803
997
|
// A second refund of the same order throws 409 (err.isAlreadyRefunded) — treat as already done.
|
|
804
998
|
```
|
|
805
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
|
+
|
|
806
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.
|
|
807
1012
|
|
|
808
1013
|
```ts
|
|
@@ -817,7 +1022,7 @@ await server.platformCommerce.refund({ orderId, refundRemaining: true });
|
|
|
817
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.
|
|
818
1023
|
|
|
819
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.
|
|
820
|
-
- INVO fee: **3.5% flat** (balance) · **
|
|
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`.
|
|
821
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).
|
|
822
1027
|
- Fulfill on the **`platform_commerce.purchased`** webhook; handle **`platform_commerce.refunded`** for reversals.
|
|
823
1028
|
|
|
@@ -834,7 +1039,7 @@ A subscription is a standing agreement, created by **your server**, under which
|
|
|
834
1039
|
|
|
835
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.
|
|
836
1041
|
|
|
837
|
-
- **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
|
|
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.
|
|
838
1043
|
- **Steam rail: unchanged.** INVO spends the member's wallet first and tops up from Steam for the shortfall only.
|
|
839
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.
|
|
840
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.
|
|
@@ -1219,8 +1424,8 @@ for (const w of r.warnings ?? []) log(w.code); // "REASON_RECOMMENDED"
|
|
|
1219
1424
|
**What else happens.**
|
|
1220
1425
|
|
|
1221
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.
|
|
1222
|
-
- **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.
|
|
1223
|
-
- **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.
|
|
1224
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.
|
|
1225
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.
|
|
1226
1431
|
|
|
@@ -1368,6 +1573,39 @@ Lookup is by email only — there is no by-`playerId` balance route (a `playerId
|
|
|
1368
1573
|
internal id). For a **client-side** read, use `InvoClient.getBalance()` (player-token; identity
|
|
1369
1574
|
comes from the token, no PII).
|
|
1370
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
|
+
|
|
1371
1609
|
---
|
|
1372
1610
|
|
|
1373
1611
|
## Sends & transfers (move currency between players)
|
|
@@ -1587,6 +1825,7 @@ the same one: a grant approved for `transfer` settles nothing else.
|
|
|
1587
1825
|
| `TRANSACTION_NOT_PENDING` | 400 | The transaction is not at this step. Three different situations: your earlier attempt **already landed**; the transaction is **dead** (expired / refunded); or — on a receipt flow — it has **not got here yet**, because the sender's own approval is still pending or held at a guardian. | **Not thrown by `approveWithDeviceCode`** — it comes back as `{ status: "not_pending", alreadySettled, currentStatus }`. `alreadySettled` separates the first case from the other two. When it is `false`, go read `getTransferStatus` / `getSendStatus` rather than assuming; never retry-loop. |
|
|
1588
1826
|
| `DEVICE_APPROVAL_NOT_APPROVED` | 400 | The `device_code` was unknown, another player's, bound to a different transaction, bound to a different **flow**, or the player has not approved yet. One answer for all five, deliberately — distinguishing them would leak which transactions have a live approval. | `err.isDeviceApprovalNotApproved`. Check the `flow` matches the `begin`, and that the poll actually said `approved`. |
|
|
1589
1827
|
| `DEVICE_APPROVAL_ALREADY_PENDING` | 409 | An **approved** grant for this transaction and flow is still inside its window. The player already approved. | `err.isDeviceApprovalAlreadyPending`, `err.deviceApprovalExpiresAt`. You are missing stage 4, not a new code — call `approveWithDeviceCode` with the code you have. (A merely *pending* earlier grant does **not** 409; `begin` supersedes it.) |
|
|
1828
|
+
| `PLAYER_TOKEN_STALE` | 403 | The player token predates a change to the sender's identity: their phone was added (often on this very initiate), which gives them a new identity. Nothing moved; the old token stays refused. | `err.isPlayerTokenStale`. The SDK does not retry money calls itself: re-mint the player token (or use `playerToken` from the initiate result, present when `identityRekeyed` is `true`) and retry the approve **once**. |
|
|
1590
1829
|
| `PASSKEY_RECOVERY_COOLDOWN` | 403 | Money **out** is paused for 24 h after a passkey recovery (SIM-swap protection). Receiving and collecting are unaffected. | `err.isPasskeyRecoveryCooldown`, `err.retryAfterAt` (ISO; the body also carries `retry_after_seconds`). Expect a fresh initiate later — do not retry-loop. |
|
|
1591
1830
|
| `SEND_APPROVE_FAILED`, `TRANSFER_APPROVE_FAILED`, `CONFIRM_RECEIPT_FAILED` | 400 | A **fault** on INVO's side, not a rule. `err.isSettleFault`; the body carries **`error_ref`** (`err.errorRef`). | Never retryable. See the ambiguity note below — do **not** tell the player it failed until you have read the transaction. Quote `errorRef` to INVO support; it names the exact server log line. |
|
|
1592
1831
|
| guardian hold | 202 | A minor's transaction is waiting on a guardian. **The money is held, not refused.** | Returned as a result with `holdReason`; poll `getGuardianApprovalStatus`. Terminal outcomes (`GUARDIAN_APPROVAL_REJECTED` / `_EXPIRED`) throw as 410. |
|
|
@@ -2277,7 +2516,10 @@ export const POST = createWebhookHandler({
|
|
|
2277
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) |
|
|
2278
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`) |
|
|
2279
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`) |
|
|
2280
|
-
| `transfer.received` / `transfer.claim_expired` / `transfer.refunded` | sends & transfers | reconcile claim state
|
|
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) |
|
|
2281
2523
|
|
|
2282
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).
|
|
2283
2525
|
|
|
@@ -2362,7 +2604,7 @@ Helpers:
|
|
|
2362
2604
|
| `.isDuplicateClientRequestId` | Platform Commerce card purchase whose `clientRequestId` already has a payment (409); `order_id` + `order_status` on `.body` |
|
|
2363
2605
|
| `.isIdentityCheckUnavailable` | a claim or confirm-receipt could not be checked just now (503); nothing moved, retry in a few seconds |
|
|
2364
2606
|
| `.isNotPlatformTenant` | Platform Commerce called by a non-platform tenant (403) — use `purchaseItem`/`createCheckout` instead |
|
|
2365
|
-
| `.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) |
|
|
2366
2608
|
| `.isAlreadyRefunded` | Platform Commerce refund of an already-refunded order (409) — treat as already done |
|
|
2367
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 |
|
|
2368
2610
|
| `.isAmountBelowFee` | deprecated: `AMOUNT_BELOW_FEE` is no longer returned (the partner pays the card fee) |
|
|
@@ -2370,6 +2612,9 @@ Helpers:
|
|
|
2370
2612
|
| `.isEnrollmentAuthorizationRequired` | first-enrollment needs the OTP grant → `enrollmentBegin`/`enrollmentVerify` |
|
|
2371
2613
|
| `.isEnrollmentProofRequired` | another method exists → prove it via `linkDevice` |
|
|
2372
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 |
|
|
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) |
|
|
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 |
|
|
2373
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) |
|
|
2374
2619
|
| `.isNonSteamValueIntoSteamBlocked` | initiate blocked (409): non-Steam value can't move into a Steam title → show `.message`, pick a non-Steam destination |
|
|
2375
2620
|
| `.isPhoneShareAlreadyApproved` | phone-share was already approved (e.g. from a `/reject`) |
|
|
@@ -2399,9 +2644,13 @@ try {
|
|
|
2399
2644
|
|
|
2400
2645
|
| Method | Returns |
|
|
2401
2646
|
|---|---|
|
|
2402
|
-
| `mintPlayerToken({ playerEmail, playerPhone? })` | `{ token, expiresAt, identityId }
|
|
2403
|
-
| `
|
|
2404
|
-
| `
|
|
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) |
|
|
2648
|
+
| `registerPlayer({ playerEmail, playerPhone, playerName? })` | `{ status: "created" \| "exists", identityId, playerToken?, playerTokenExpiresAt?, raw }`; moves no money. `isPhoneMismatch` / `isPhoneShareRefused` |
|
|
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 }` |
|
|
2652
|
+
| `initiateSend(input)` | `{ transactionId, verificationMethod, guardianApproval?, identityRekeyed?, playerToken?, playerTokenExpiresAt?, identityId?, claimDeliveryPlanned?, raw }`; when `identityRekeyed` is `true`, hand the browser `playerToken` before it approves |
|
|
2653
|
+
| `initiateTransfer(input)` | same as `initiateSend` |
|
|
2405
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) |
|
|
2406
2655
|
| `quoteCurrencyPurchase({ playerEmail, usdAmount, country?, subdivision? })` | `CurrencyPurchaseQuote`: `{ totalUsd, amountCents, subtotalUsd, processingFeeUsd, partnerFeeUsd?, internationalCardFeeUsd?, feeTakenFrom?, minPurchaseWarning?, coins, currencyName, breakdown, ifUnacknowledged, raw }`; moves no money; send `totalUsd` back as `acknowledgedTotalUsd` (see [INVO's card fee](#invos-card-fee-quote-show-acknowledge)) |
|
|
2407
2656
|
| `purchaseCurrency(input)` | `{ status, clientSecret?, paymentIntentId?, paymentUrl?, transactionId?, orderId?, newBalance?, processingFeeUsd?, feeTakenFrom?, partnerFeeUsd?, internationalCardFeeUsd?, minPurchaseWarning?, coinsCredited?, chargeTotalUsd?, receiptNumber?, receiptUrl?, raw }`; optional `acknowledgedTotalUsd`, `country` and `subdivision` inputs; `receiptNumber` / `receiptUrl` on Merchant of Record only |
|
|
@@ -2409,9 +2658,13 @@ try {
|
|
|
2409
2658
|
| `getOrderDetails({ orderId? \| transactionId? })` | `{ order, financialSummary, statusTimeline, receiptNumber?, receiptUrl?, raw }`; the receipt fields on a Merchant of Record currency purchase only |
|
|
2410
2659
|
| `purchaseItem(input)` | `{ status, transactionId, orderId, newBalance, previousBalance, currencyName, financialBreakdown?, raw }` — **game** tenant spending game currency on an in-game item |
|
|
2411
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` |
|
|
2412
2663
|
| `getItemOrderDetails({ orderId? \| transactionId? \| clientRequestId? })` | `{ order, financialSummary, statusTimeline, raw }` |
|
|
2413
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` |
|
|
2414
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` |
|
|
2415
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) |
|
|
2416
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) |
|
|
2417
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) |
|
|
@@ -2433,7 +2686,7 @@ try {
|
|
|
2433
2686
|
| `getLinkedIdentities({ playerEmail? \| playerPhone? })` | `{ walletUserId, primaryEmail, primaryPhone, isMinor, emails, notFound, raw }` — **server-only** (returns PII) |
|
|
2434
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. |
|
|
2435
2688
|
| `claimTransfer(input)` / `claimCurrency(input)` | `ClaimResult` — redeem a claim code (`needsAccountSelection` + `candidates` on a multi-account phone) |
|
|
2436
|
-
| `getTransferStatus(txnId)` / `getSendStatus(txnId)` | `TransactionStatusResult
|
|
2689
|
+
| `getTransferStatus(txnId)` / `getSendStatus(txnId)` | `TransactionStatusResult`: poll outbound state (`verificationState`); `expiryReason` once expired |
|
|
2437
2690
|
| `getGuardianApprovalStatus(txnId)` | `GuardianApprovalStatusResult` — poll a guardian hold to resolution (`state`) |
|
|
2438
2691
|
| `getDestinations({ sourceGameId, direction? })` | `DestinationsResult` — server-side (game-secret) destinations; same rows as the browser variant |
|
|
2439
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 |
|
|
@@ -2456,8 +2709,10 @@ Every method also accepts an optional final `{ signal }` (`AbortSignal`) for can
|
|
|
2456
2709
|
| `enrollPasskey()` | `{ status, device, raw }` |
|
|
2457
2710
|
| `enrollmentBegin()` / `enrollmentVerify(code)` | OTP grant for `ENROLLMENT_REQUIRES_AUTHORIZATION` (then retry `enrollPasskey`) |
|
|
2458
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`) |
|
|
2459
|
-
| `approveSend(txnId)` / `approveTransfer(txnId)` | `{ status, next, transactionId, claimCode?, claimCodeExpiresAt?, holdReason?, risk?, guardianApproval?, pollEndpoint?, raw }` |
|
|
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) |
|
|
2460
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 |
|
|
2461
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) |
|
|
2462
2717
|
| `getPendingCollect()` | `{ pending, raw }` — the player's own pending-to-collect list (player-token) |
|
|
2463
2718
|
| `getDestinations({ direction? })` | `{ availableGames, sourceGameName, transferMode, … }` — where the player can send/transfer, metadata inline |
|