@invonetwork/web-sdk 3.2.0 → 3.2.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +654 -610
- package/README.md +920 -850
- package/package.json +76 -76
package/README.md
CHANGED
|
@@ -1,850 +1,920 @@
|
|
|
1
|
-
# @invonetwork/web-sdk
|
|
2
|
-
|
|
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
|
-
|
|
5
|
-
> **Status:** `v3.1.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.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
|
-
> Canonical partner reference: **https://docs.invo.network/docs/currency-purchase** and **https://docs.invo.network/docs/game-developer-integration**.
|
|
7
|
-
|
|
8
|
-
## What it does
|
|
9
|
-
|
|
10
|
-
Five money flows plus passkey (WebAuthn) authentication, split across a trusted server entry and an untrusted browser entry:
|
|
11
|
-
|
|
12
|
-
| Flow | Direction | Real money? | Passkey? | Where |
|
|
13
|
-
|---|---|---|---|---|
|
|
14
|
-
| **Currency purchase** | real money **→** game currency | yes (card/rails) | no | server initiates, browser opens hosted checkout |
|
|
15
|
-
| **Item purchase** | game currency **→** in-game item | no (balance debit) | no | server only |
|
|
16
|
-
| **Platform Commerce** (ecommerce) | balance **or** card **→** a storefront item | card leg only | no | server creates; buyer pays on INVO's **hosted checkout** |
|
|
17
|
-
| **Send** | currency **→** another player (cross-game) | no | yes (sender approves) | server initiates, browser approves/claims |
|
|
18
|
-
| **Transfer** | currency **→** another player (transfer rail) | no | yes (sender approves) | server initiates, browser approves/claims |
|
|
19
|
-
|
|
20
|
-
> **Item purchase vs Platform Commerce — don't mix them up.** They share a body shape (`itemId`, `unitPrice`, `totalPrice`, `clientRequestId`) but are different products:
|
|
21
|
-
> - **[Item purchase](#item-purchase-spend-game-currency)** — a **game** tenant. A player spends **game currency they already hold** on an **in-game** item (a sword, a skin). Always a balance debit — **never a card, never new money, no refunds**. `server.purchaseItem(...)` → `/api/item-purchases`.
|
|
22
|
-
> - **[Platform Commerce](#platform-commerce-ecommerce)** — a **platform** tenant (a non-game app: vertical video, creator merch, marketplace). A **storefront** sale funded by **INVO balance or a real card** (new money), with **INVO as merchant of record** and **refunds**. `server.platformCommerce.purchase(...)` → `/api/platform-commerce`. A game tenant calling it gets `403 NOT_A_PLATFORM_TENANT`.
|
|
23
|
-
|
|
24
|
-
The **game secret stays on your server**; the browser only ever holds a short-lived, game-scoped **player token** (and, for the card leg, a per-purchase `checkoutUrl`).
|
|
25
|
-
|
|
26
|
-
## Passkeys are the gold standard — don't build on SMS
|
|
27
|
-
|
|
28
|
-
**If you take one thing from this README: authorize money movement with a passkey. Do not design your verification UX around the SMS PIN.**
|
|
29
|
-
|
|
30
|
-
A passkey is a WebAuthn assertion — phishing-resistant, bound to your origin, and backed by the device's secure hardware. An SMS PIN is a shared secret delivered over a channel exposed to **SIM swap**, SS7 interception, and social engineering. They are not two equivalent ways to approve a transfer; one is materially weaker, and INVO treats it that way (see the 24-hour money-out cooldown after a passkey recovery — that gate exists precisely because phone-based possession can be stolen).
|
|
31
|
-
|
|
32
|
-
So:
|
|
33
|
-
|
|
34
|
-
| | Do this | Not this |
|
|
35
|
-
|---|---|---|
|
|
36
|
-
| Sender approves a send/transfer | `client.enrollPasskey()` once, then `client.approveSend` / `approveTransfer` | a PIN pad as the default flow |
|
|
37
|
-
| `initiate*` returns `verificationMethod: "sms"` | read it as *"this user has no passkey"* → offer enrollment | route straight to PIN entry |
|
|
38
|
-
| Recipient collects | `client.confirmReceiptSend` / `confirmReceiptTransfer` (passkey) | claim code as the primary path |
|
|
39
|
-
|
|
40
|
-
### Prerequisite: passkeys are dark until your tenant verifies a domain
|
|
41
|
-
|
|
42
|
-
**Read this before you wire up `enrollPasskey()`.** Passkey step-up is enabled **per tenant** and stays off until you verify ownership of a domain (your RP ID) in the developer console. Until then every passkey endpoint returns `403 WEBAUTHN_NOT_ENABLED_FOR_TENANT`.
|
|
43
|
-
|
|
44
|
-
**This is the common case today, not an edge case.** As of 2026-08-05 only **4 of 23 sandbox tenants** and **0 of 3 production tenants** have a verified RP ID. If you skip this, your integration will 403 on its first `enrollPasskey()` call and you'll be debugging a configuration state as if it were a bug.
|
|
45
|
-
|
|
46
|
-
`WEBAUTHN_NOT_ENABLED_FOR_TENANT` is **configuration state, not an error** — the ceremony was never available to fail. Don't show the player a failure; fall back to the existing path:
|
|
47
|
-
|
|
48
|
-
```ts
|
|
49
|
-
try {
|
|
50
|
-
await client.enrollPasskey();
|
|
51
|
-
} catch (e) {
|
|
52
|
-
if (e instanceof InvoError && e.isWebauthnNotEnabledForTenant) {
|
|
53
|
-
// Not a failure — this tenant simply hasn't verified a domain yet.
|
|
54
|
-
// Fall back to the SMS/in-app path and (if this is YOUR tenant) go verify a domain.
|
|
55
|
-
usePinFallback();
|
|
56
|
-
} else throw e;
|
|
57
|
-
}
|
|
58
|
-
```
|
|
59
|
-
|
|
60
|
-
So the honest sequence is: **verify your domain → enroll passkeys → you're on the gold-standard path.** Until step one is done, the SMS path is carrying you whether you like it or not — which is exactly why the deprecation below has no removal date attached.
|
|
61
|
-
|
|
62
|
-
> ⚠️ **`verifySmsTransfer` / `verifySmsSend` are deprecated as of `3.1.0` and a future major version will remove them.** They still work exactly as before — this release changes documentation only, emits no runtime warning, and breaks nothing. Keep the PIN path as a genuine last resort for: users who **cannot** enroll (unsupported device, no platform authenticator), users who decline, and **tenants that haven't verified a domain yet** (see above). Just don't make it the road everyone walks down once passkeys are available to you.
|
|
63
|
-
|
|
64
|
-
**What is *not* discouraged.** These use a one-time code, but they are the on-ramp *to* a passkey — not a substitute for one. Use them freely:
|
|
65
|
-
|
|
66
|
-
- `enrollmentBegin` / `enrollmentVerify` — the first-enrollment grant. This is how a user **gets** a passkey.
|
|
67
|
-
- `recoveryBegin` / `recoveryComplete` — restores a passkey after the user loses or deletes it.
|
|
68
|
-
- `phoneShareInitiate` / `phoneShareApprove` — phone-**ownership consent**, not transaction authorization.
|
|
69
|
-
|
|
70
|
-
Beyond security, this is also an economics story: SMS costs real money per message at every scale, and INVO's architecture targets passkey/in-app verification as the primary path so the platform never depends on carrier delivery. A passkey-first integration is faster for your users, cheaper to run, and won't need migrating later.
|
|
71
|
-
|
|
72
|
-
## Contents
|
|
73
|
-
|
|
74
|
-
- [Passkeys are the gold standard — don't build on SMS](#passkeys-are-the-gold-standard--dont-build-on-sms)
|
|
75
|
-
- [Install](#install)
|
|
76
|
-
- [Architecture & the two entry points](#architecture--the-two-entry-points)
|
|
77
|
-
- [Before you go live](#before-you-go-live)
|
|
78
|
-
- [Configuration](#configuration)
|
|
79
|
-
- [Currency purchase (real money in)](#currency-purchase-real-money-in)
|
|
80
|
-
- [Item purchase (spend game currency)](#item-purchase-spend-game-currency)
|
|
81
|
-
- [Platform Commerce (ecommerce)](#platform-commerce-ecommerce)
|
|
82
|
-
- [Player balance](#player-balance)
|
|
83
|
-
- [Sends & transfers (move currency between players)](#sends--transfers-move-currency-between-players)
|
|
84
|
-
- [Passkeys (enroll, approve, link, recover)](#passkeys-enroll-approve-link-recover)
|
|
85
|
-
- [Webhooks](#webhooks)
|
|
86
|
-
- [Resilience & observability](#resilience--observability)
|
|
87
|
-
- [Errors](#errors)
|
|
88
|
-
- [API reference](#api-reference)
|
|
89
|
-
- [Scripts & versioning](#scripts--versioning)
|
|
90
|
-
|
|
91
|
-
## Install
|
|
92
|
-
|
|
93
|
-
```bash
|
|
94
|
-
npm install @invonetwork/web-sdk
|
|
95
|
-
```
|
|
96
|
-
|
|
97
|
-
Node ≥ 18 on the server (uses the global `fetch`). The browser build ships ESM + CJS + types.
|
|
98
|
-
|
|
99
|
-
## Get your account & game secret (INVO console)
|
|
100
|
-
|
|
101
|
-
Sign up, create your game, and copy its credentials (the **game secret**, plus your WebAuthn **RP ID / origins**) in the INVO console. Use the console that matches the environment you're building against:
|
|
102
|
-
|
|
103
|
-
| Environment | Console — sign up, manage games, copy your game secret | API `baseUrl` |
|
|
104
|
-
|---|---|---|
|
|
105
|
-
| **Testing / sandbox** | **https://dev.console.invo.network** | `https://sandbox.invo.network/sandbox` |
|
|
106
|
-
| **Production** | **https://console.invo.network** | `https://invo.network` |
|
|
107
|
-
|
|
108
|
-
Build and test against the **dev console + sandbox** first, then switch to the **production console + `https://invo.network`** for launch. **Each environment has its own game secret — never mix them**, and keep the secret server-side only.
|
|
109
|
-
|
|
110
|
-
## Architecture & the two entry points
|
|
111
|
-
|
|
112
|
-
```
|
|
113
|
-
┌──────────────────────────────┐ ┌──────────────────────────────┐
|
|
114
|
-
│ YOUR SERVER (trusted) │ │ THE BROWSER (untrusted) │
|
|
115
|
-
│ @invonetwork/web-sdk/server │ │ @invonetwork/web-sdk │
|
|
116
|
-
│ │ mint │ │
|
|
117
|
-
│ • holds X-Game-Secret-Key │ ──────► │ • holds short-lived token │
|
|
118
|
-
│ • mintPlayerToken() │ token │ (~15 min, game-scoped) │
|
|
119
|
-
│ • initiateSend/Transfer() │ │ • enrollPasskey() │
|
|
120
|
-
│ • createCheckout() │ │ • approveSend/Transfer() │
|
|
121
|
-
│ • purchaseCurrency() │ │ • confirmReceipt*() │
|
|
122
|
-
│ • purchaseItem() │ │ • linkDevice() │
|
|
123
|
-
└───────────────┬───────────────┘ └───────────────┬──────────────┘
|
|
124
|
-
└──────────────► INVO BACKEND ◄────────────┘
|
|
125
|
-
```
|
|
126
|
-
|
|
127
|
-
| Import | Runs on | Holds | Responsibilities |
|
|
128
|
-
|---|---|---|---|
|
|
129
|
-
| `@invonetwork/web-sdk/server` | your backend (Node ≥18) | the **game secret** | mint player tokens; initiate sends/transfers; currency purchase; item purchase |
|
|
130
|
-
| `@invonetwork/web-sdk` | the browser | a short-lived **player token** | passkey enroll, approve, self-claim, device link |
|
|
131
|
-
|
|
132
|
-
**Never import `/server` into browser code** — it carries the game secret. The two entries are built separately for exactly this reason.
|
|
133
|
-
|
|
134
|
-
## Integration modes
|
|
135
|
-
|
|
136
|
-
`InvoClient` needs a `token` and a `baseUrl` — which lets you adopt it **two ways**. Same SDK, same code in your components; only the config differs.
|
|
137
|
-
|
|
138
|
-
### Player token (session mint for an existing player)
|
|
139
|
-
|
|
140
|
-
`mintPlayerToken` mints a short-lived, game-scoped **session token** for a player who
|
|
141
|
-
**already exists** on your game. It is *not* a registration call — the backend looks the
|
|
142
|
-
player up by `playerEmail` and returns a token for their existing identity (or `404` if no
|
|
143
|
-
such player exists). It only needs `playerEmail`:
|
|
144
|
-
|
|
145
|
-
```ts
|
|
146
|
-
// your backend
|
|
147
|
-
const { token } = await invo.mintPlayerToken({ playerEmail: "player@example.com" });
|
|
148
|
-
```
|
|
149
|
-
|
|
150
|
-
`playerPhone` is **optional** here (validated as E.164 only if you pass it, and ignored by this
|
|
151
|
-
endpoint) — an existing email-only player still mints a token.
|
|
152
|
-
|
|
153
|
-
**Where phone actually matters.** A player's INVO identity encodes their phone, and cross-game
|
|
154
|
-
money routing keys off it — but that's enforced on the money calls, not the token mint:
|
|
155
|
-
|
|
156
|
-
- **`initiateSend` / `initiateTransfer`** require the **sender's** phone (E.164), and take the
|
|
157
|
-
**recipient's** phone. You can send by the recipient's **phone alone** — they supply their
|
|
158
|
-
email when they claim.
|
|
159
|
-
- An account with no phone can't receive cross-game money and can't take part in the
|
|
160
|
-
account-linking consent SMS, so make sure players have a phone at **creation / enrollment**
|
|
161
|
-
(in your own player system), before they transact.
|
|
162
|
-
|
|
163
|
-
### Token bootstrap (both modes)
|
|
164
|
-
|
|
165
|
-
Expose one small backend endpoint that calls `mintPlayerToken` (server-side, with the game secret) and hand the token to the browser:
|
|
166
|
-
|
|
167
|
-
```ts
|
|
168
|
-
// browser
|
|
169
|
-
const client = new InvoClient({
|
|
170
|
-
baseUrl: "https://api.invo.network",
|
|
171
|
-
token: await fetch("/your/sdk-token").then((r) => r.json()).then((j) => j.token),
|
|
172
|
-
// Called automatically on SDK_TOKEN_EXPIRED (~15 min TTL) — just re-fetch from your backend:
|
|
173
|
-
refreshToken: () => fetch("/your/sdk-token").then((r) => r.json()).then((j) => j.token),
|
|
174
|
-
});
|
|
175
|
-
```
|
|
176
|
-
|
|
177
|
-
### Mode A — browser-direct (default)
|
|
178
|
-
|
|
179
|
-
The browser holds the short-lived, game-scoped player token and calls INVO directly (`baseUrl` = the INVO API). Fewer moving parts. Requires INVO to **CORS-allow your web origin** and to have your **RP ID / origins** set up for passkeys (see [Before you go live](#before-you-go-live)).
|
|
180
|
-
|
|
181
|
-
### Mode B — behind your proxy (keep the token server-side)
|
|
182
|
-
|
|
183
|
-
If your architecture requires the INVO player token to **never reach the browser**, route the SDK through your own backend — **no CORS setup needed, and no security-posture change**:
|
|
184
|
-
|
|
185
|
-
- Set `baseUrl` to your proxy (e.g. `https://yourgame.com/invo`), which forwards to the INVO API and **injects the real `Authorization` header server-side**.
|
|
186
|
-
- Give the browser a short-lived **session/CSRF token** (not the INVO token) as `token`; your proxy validates it and swaps in the real player token. Or use cookie auth with a custom `fetch`:
|
|
187
|
-
|
|
188
|
-
```ts
|
|
189
|
-
const client = new InvoClient({
|
|
190
|
-
baseUrl: "https://yourgame.com/invo", // your proxy → INVO
|
|
191
|
-
token: sessionToken, // your token; the proxy swaps in the real one
|
|
192
|
-
fetch: (url, init) => fetch(url, { ...init, credentials: "include" }), // send your cookie
|
|
193
|
-
});
|
|
194
|
-
```
|
|
195
|
-
|
|
196
|
-
The WebAuthn ceremony still runs in the browser (it must — it's `navigator.credentials`), but transport/auth stays behind your proxy. You keep the SDK's ceremony handling, token-refresh, typed holds, and error classifiers either way.
|
|
197
|
-
|
|
198
|
-
**Running `InvoServer` in the proxy** (for the game-secret writes — initiate, checkout, purchase — so the secret leaves the browser): see the drop-in reference at [`examples/proxy-server.ts`](examples/proxy-server.ts). Its actor resolver is pluggable:
|
|
199
|
-
|
|
200
|
-
- **Real partner** (one login = one player) — derive the acting player from your **session**.
|
|
201
|
-
- **Trusted first-party rig** (an internal tool that impersonates arbitrary test players) — the caller names `playerEmail`, guarded by a shared-secret header (`INVO_PROXY_TRUSTED_SECRET`), the same trusted pattern as a `player_email` token minter. Never expose this mode to end-user browsers.
|
|
202
|
-
|
|
203
|
-
> **Lowest-risk first step:** adopt just `linkDevice` (passkey ↔ app device interchange) — it's purely additive and needs no refactor. See [Passkeys](#passkeys-enroll-approve-link-recover).
|
|
204
|
-
|
|
205
|
-
## Before you go live
|
|
206
|
-
|
|
207
|
-
INVO enables each flow for your tenant in the [console](#get-your-account--game-secret-invo-console). What you need to do:
|
|
208
|
-
|
|
209
|
-
- **Store the game secret server-side** and expose a small endpoint that calls `mintPlayerToken` so the browser can fetch/refresh its token. Never ship the secret to the browser.
|
|
210
|
-
- **Make sure players have a phone (E.164) at creation/enrollment** — it's required on the money calls (`initiateSend`/`initiateTransfer`) and for cross-game receive, though not on the token mint itself (see [Player token](#player-token-session-mint-for-an-existing-player)).
|
|
211
|
-
- **If you use browser-direct ([Mode A](#mode-a--browser-direct-default)):** ask INVO to **CORS-allow your web origin(s)** so the browser can call the API directly. (Not needed for [Mode B / proxy](#mode-b--behind-your-proxy-keep-the-token-server-side) — those requests are same-origin to your backend.)
|
|
212
|
-
- **For passkeys (sends/transfers):** give INVO the **RP ID + web origin(s)** you'll serve from. Passkeys only validate on approved origins — if a call returns `WEBAUTHN_NOT_ENABLED_FOR_TENANT`, your origins aren't set up yet; contact INVO. **Get this configured before launch:** until a sender is enrolled the backend falls back to the deprecated SMS-PIN path, which is the flow you don't want your users on (see [Passkeys are the gold standard](#passkeys-are-the-gold-standard--dont-build-on-sms)).
|
|
213
|
-
- **For currency purchase:** card checkout works out of the box; ask INVO to enable the `game`/`steam` rails if you need them.
|
|
214
|
-
- **For item purchase:** nothing extra — it's a currency-balance debit.
|
|
215
|
-
|
|
216
|
-
If a flow isn't enabled for your tenant yet, calls return a clear `InvoError` (e.g. `TENANT_NOT_MIGRATED`, `WEBAUTHN_NOT_ENABLED_FOR_TENANT`, or `flow_paused`) — coordinate with your INVO contact to turn it on.
|
|
217
|
-
|
|
218
|
-
## Configuration
|
|
219
|
-
|
|
220
|
-
```ts
|
|
221
|
-
import { InvoServer } from "@invonetwork/web-sdk/server";
|
|
222
|
-
import { InvoClient } from "@invonetwork/web-sdk";
|
|
223
|
-
|
|
224
|
-
const server = new InvoServer({
|
|
225
|
-
gameSecret: process.env.INVO_GAME_SECRET!, // server-side only
|
|
226
|
-
baseUrl: "https://sandbox.invo.network/sandbox", // prod: "https://invo.network"
|
|
227
|
-
timeoutMs: 30_000, // optional, default 30s
|
|
228
|
-
maxRetries: 2, // optional, default 2 (0 disables)
|
|
229
|
-
// retryBaseDelayMs: 250, // optional backoff base
|
|
230
|
-
// fetch: customFetch, // optional override
|
|
231
|
-
// hooks: { onRequest, onResponse, onError }, // optional observability (see below)
|
|
232
|
-
});
|
|
233
|
-
|
|
234
|
-
const client = new InvoClient({
|
|
235
|
-
token, // from your /mint endpoint
|
|
236
|
-
baseUrl: "https://sandbox.invo.network/sandbox",
|
|
237
|
-
refreshToken: () => // optional: auto re-mint + retry on token expiry
|
|
238
|
-
fetch("/invo/token", { method: "POST" }).then((r) => r.json()).then((j) => j.token),
|
|
239
|
-
});
|
|
240
|
-
```
|
|
241
|
-
|
|
242
|
-
**Base URLs** (manage each environment in its [console](#get-your-account--game-secret-invo-console))
|
|
243
|
-
- Production: `https://invo.network` — console: `https://console.invo.network`
|
|
244
|
-
- Sandbox / testing: `https://sandbox.invo.network/sandbox` — console: `https://dev.console.invo.network` (sandbox prepends the `/sandbox` prefix; the SDK absorbs it via `baseUrl`)
|
|
245
|
-
|
|
246
|
-
`baseUrl` must be `https://` — the game secret and player token travel in request headers, so plaintext is rejected. `http://localhost` is allowed for local dev only.
|
|
247
|
-
|
|
248
|
-
**Player tokens** live ~15 minutes and are game-scoped. Mint one per browser session. If you pass `refreshToken` to `InvoClient`, the SDK transparently re-mints and retries once on `SDK_TOKEN_EXPIRED` (it re-runs the whole passkey ceremony so it never replays a single-use challenge).
|
|
249
|
-
|
|
250
|
-
---
|
|
251
|
-
|
|
252
|
-
## Currency purchase (real money in)
|
|
253
|
-
|
|
254
|
-
Buy game currency with real money. Authenticated by the **payment rail**, not a passkey — there's no WebAuthn step. Two paths:
|
|
255
|
-
|
|
256
|
-
### Hosted checkout (recommended — PCI-light, you never touch card data)
|
|
257
|
-
|
|
258
|
-
```ts
|
|
259
|
-
// SERVER
|
|
260
|
-
const { checkoutUrl, sessionId, expiresAt, expiresInSeconds } = await server.createCheckout({
|
|
261
|
-
playerEmail: "p@example.com",
|
|
262
|
-
usdAmount: "20.00", // USD, 0 < x ≤ 999.99
|
|
263
|
-
rail: "platform", // optional: "platform" (default) | "game" | "steam"
|
|
264
|
-
successUrl: "https://you/buy/ok",
|
|
265
|
-
cancelUrl: "https://you/buy/cancel",
|
|
266
|
-
metadata: { yourOrderId: "ord_42" }, // echoed on the purchase.completed webhook (all rails); order_id also reconciles
|
|
267
|
-
});
|
|
268
|
-
// → send the browser to checkoutUrl. Token TTL is expiresInSeconds (~900s / 15 min).
|
|
269
|
-
// Reloading the URL after a completed payment is idempotent — it shows an already-complete
|
|
270
|
-
// success screen (no error), so you don't have to guard against a refresh.
|
|
271
|
-
```
|
|
272
|
-
|
|
273
|
-
Open `checkoutUrl` either way:
|
|
274
|
-
|
|
275
|
-
- **Full-page redirect / WebView** — works everywhere; on success the page redirects to your `successUrl`.
|
|
276
|
-
- **Embedded `<iframe>`** — works by default from any https origin (no allow-listing). The page does *not* redirect your top window; listen for the `INVO_CHECKOUT_COMPLETE` postMessage:
|
|
277
|
-
|
|
278
|
-
```ts
|
|
279
|
-
// BROWSER
|
|
280
|
-
const iframe = document.createElement("iframe");
|
|
281
|
-
iframe.src = checkoutUrl;
|
|
282
|
-
iframe.style.cssText = "width:440px;height:720px;border:0";
|
|
283
|
-
document.body.appendChild(iframe);
|
|
284
|
-
|
|
285
|
-
window.addEventListener("message", (e) => {
|
|
286
|
-
if (e.origin !== "https://invo.network") return; // sandbox: "https://sandbox.invo.network"
|
|
287
|
-
if (e.data?.type === "INVO_CHECKOUT_COMPLETE") {
|
|
288
|
-
// UX hint ONLY (unsigned). data = { status, new_balance, currency_name, transaction_id }
|
|
289
|
-
refreshBalanceOptimistically(e.data.data.new_balance);
|
|
290
|
-
}
|
|
291
|
-
});
|
|
292
|
-
```
|
|
293
|
-
|
|
294
|
-
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. Currency purchase has **no browser SDK method** — the browser only opens the URL.
|
|
295
|
-
|
|
296
|
-
### Payment rails (neutral names)
|
|
297
|
-
|
|
298
|
-
The `rail` selects the in-page experience — all branded INVO, no visible redirect:
|
|
299
|
-
- `"platform"` (default) — cards plus **Apple Pay / Google Pay / Link** (rendered automatically on supported devices) and international billing addresses. It's a web checkout, so there's no app-store commission.
|
|
300
|
-
- `"game"` — regional / game-store methods (may redirect to the regional hosted page).
|
|
301
|
-
- `"steam"` — Steam titles hand off to the in-client Steam flow.
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
//
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
//
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
//
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
//
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
//
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
//
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
//
|
|
502
|
-
|
|
503
|
-
//
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
```
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
- **
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
```
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
//
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
```
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
|
|
569
|
-
|
|
570
|
-
|
|
571
|
-
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
passkey
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
|
|
585
|
-
}
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
590
|
-
|
|
591
|
-
|
|
592
|
-
|
|
593
|
-
|
|
594
|
-
|
|
595
|
-
-
|
|
596
|
-
-
|
|
597
|
-
|
|
598
|
-
|
|
599
|
-
|
|
600
|
-
|
|
601
|
-
|
|
602
|
-
|
|
603
|
-
> `
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
|
|
611
|
-
|
|
612
|
-
|
|
613
|
-
|
|
614
|
-
|
|
615
|
-
|
|
616
|
-
|
|
617
|
-
|
|
618
|
-
|
|
619
|
-
|
|
620
|
-
|
|
621
|
-
|
|
622
|
-
|
|
623
|
-
|
|
624
|
-
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
|
|
629
|
-
|
|
630
|
-
|
|
631
|
-
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
|
|
635
|
-
|
|
636
|
-
|
|
637
|
-
|
|
638
|
-
|
|
639
|
-
|
|
640
|
-
|
|
641
|
-
}
|
|
642
|
-
|
|
643
|
-
|
|
644
|
-
|
|
645
|
-
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
|
|
650
|
-
|
|
651
|
-
|
|
652
|
-
|
|
653
|
-
|
|
654
|
-
|
|
655
|
-
|
|
656
|
-
|
|
657
|
-
|
|
658
|
-
|
|
659
|
-
|
|
660
|
-
|
|
661
|
-
|
|
662
|
-
|
|
663
|
-
|
|
664
|
-
|
|
665
|
-
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
|
|
672
|
-
|
|
673
|
-
|
|
674
|
-
|
|
675
|
-
|
|
676
|
-
|
|
677
|
-
|
|
678
|
-
|
|
679
|
-
-
|
|
680
|
-
-
|
|
681
|
-
|
|
682
|
-
|
|
683
|
-
|
|
684
|
-
|
|
685
|
-
|
|
686
|
-
|
|
687
|
-
|
|
688
|
-
|
|
689
|
-
|
|
690
|
-
|
|
691
|
-
|
|
692
|
-
|
|
693
|
-
|
|
694
|
-
|
|
695
|
-
|
|
696
|
-
|
|
697
|
-
|
|
698
|
-
|
|
699
|
-
|
|
700
|
-
|
|
701
|
-
|
|
702
|
-
|
|
703
|
-
|
|
704
|
-
|
|
705
|
-
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
|
|
709
|
-
|
|
710
|
-
|
|
711
|
-
|
|
712
|
-
|
|
713
|
-
|
|
714
|
-
|
|
715
|
-
|
|
716
|
-
|
|
717
|
-
|
|
718
|
-
|
|
719
|
-
|
|
720
|
-
|
|
721
|
-
|
|
722
|
-
|
|
723
|
-
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
|
|
727
|
-
|
|
728
|
-
|
|
729
|
-
|
|
730
|
-
|
|
731
|
-
|
|
732
|
-
|
|
733
|
-
|
|
734
|
-
|
|
735
|
-
|
|
736
|
-
|
|
737
|
-
|
|
738
|
-
|
|
739
|
-
|
|
740
|
-
|
|
741
|
-
|
|
742
|
-
|
|
743
|
-
|
|
744
|
-
|
|
745
|
-
|
|
746
|
-
|
|
747
|
-
|
|
748
|
-
|
|
749
|
-
|
|
750
|
-
|
|
751
|
-
|
|
752
|
-
|
|
753
|
-
|
|
754
|
-
|
|
755
|
-
|
|
756
|
-
|
|
757
|
-
|
|
758
|
-
|
|
759
|
-
|
|
760
|
-
|
|
761
|
-
|
|
762
|
-
|
|
763
|
-
|
|
764
|
-
|
|
765
|
-
|
|
766
|
-
|
|
767
|
-
|
|
768
|
-
|
|
769
|
-
|
|
770
|
-
|
|
771
|
-
|
|
772
|
-
|
|
773
|
-
|
|
774
|
-
|
|
775
|
-
|
|
776
|
-
|
|
777
|
-
|
|
778
|
-
|
|
779
|
-
|
|
780
|
-
|
|
781
|
-
|
|
782
|
-
|
|
783
|
-
|
|
784
|
-
|
|
|
785
|
-
|
|
786
|
-
| `
|
|
787
|
-
|
|
788
|
-
|
|
789
|
-
|
|
790
|
-
|
|
791
|
-
|
|
792
|
-
|
|
793
|
-
|
|
794
|
-
|
|
795
|
-
|
|
796
|
-
|
|
797
|
-
|
|
798
|
-
|
|
799
|
-
|
|
800
|
-
|
|
801
|
-
|
|
802
|
-
|
|
803
|
-
|
|
804
|
-
|
|
805
|
-
|
|
806
|
-
|
|
807
|
-
|
|
808
|
-
|
|
809
|
-
|
|
810
|
-
|
|
811
|
-
|
|
812
|
-
|
|
813
|
-
|
|
814
|
-
|
|
815
|
-
|
|
816
|
-
|
|
817
|
-
|
|
|
818
|
-
|
|
819
|
-
| `
|
|
820
|
-
| `
|
|
821
|
-
| `
|
|
822
|
-
| `
|
|
823
|
-
| `
|
|
824
|
-
| `
|
|
825
|
-
| `
|
|
826
|
-
| `
|
|
827
|
-
| `
|
|
828
|
-
| `
|
|
829
|
-
|
|
830
|
-
|
|
831
|
-
|
|
832
|
-
|
|
833
|
-
|
|
834
|
-
|
|
835
|
-
|
|
836
|
-
|
|
837
|
-
|
|
838
|
-
|
|
839
|
-
|
|
840
|
-
|
|
841
|
-
|
|
842
|
-
|
|
843
|
-
|
|
844
|
-
|
|
845
|
-
|
|
846
|
-
|
|
847
|
-
|
|
848
|
-
|
|
849
|
-
|
|
850
|
-
|
|
1
|
+
# @invonetwork/web-sdk
|
|
2
|
+
|
|
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
|
+
|
|
5
|
+
> **Status:** `v3.1.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.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
|
+
> Canonical partner reference: **https://docs.invo.network/docs/currency-purchase** and **https://docs.invo.network/docs/game-developer-integration**.
|
|
7
|
+
|
|
8
|
+
## What it does
|
|
9
|
+
|
|
10
|
+
Five money flows plus passkey (WebAuthn) authentication, split across a trusted server entry and an untrusted browser entry:
|
|
11
|
+
|
|
12
|
+
| Flow | Direction | Real money? | Passkey? | Where |
|
|
13
|
+
|---|---|---|---|---|
|
|
14
|
+
| **Currency purchase** | real money **→** game currency | yes (card/rails) | no | server initiates, browser opens hosted checkout |
|
|
15
|
+
| **Item purchase** | game currency **→** in-game item | no (balance debit) | no | server only |
|
|
16
|
+
| **Platform Commerce** (ecommerce) | balance **or** card **→** a storefront item | card leg only | no | server creates; buyer pays on INVO's **hosted checkout** |
|
|
17
|
+
| **Send** | currency **→** another player (cross-game) | no | yes (sender approves) | server initiates, browser approves/claims |
|
|
18
|
+
| **Transfer** | currency **→** another player (transfer rail) | no | yes (sender approves) | server initiates, browser approves/claims |
|
|
19
|
+
|
|
20
|
+
> **Item purchase vs Platform Commerce — don't mix them up.** They share a body shape (`itemId`, `unitPrice`, `totalPrice`, `clientRequestId`) but are different products:
|
|
21
|
+
> - **[Item purchase](#item-purchase-spend-game-currency)** — a **game** tenant. A player spends **game currency they already hold** on an **in-game** item (a sword, a skin). Always a balance debit — **never a card, never new money, no refunds**. `server.purchaseItem(...)` → `/api/item-purchases`.
|
|
22
|
+
> - **[Platform Commerce](#platform-commerce-ecommerce)** — a **platform** tenant (a non-game app: vertical video, creator merch, marketplace). A **storefront** sale funded by **INVO balance or a real card** (new money), with **INVO as merchant of record** and **refunds**. `server.platformCommerce.purchase(...)` → `/api/platform-commerce`. A game tenant calling it gets `403 NOT_A_PLATFORM_TENANT`.
|
|
23
|
+
|
|
24
|
+
The **game secret stays on your server**; the browser only ever holds a short-lived, game-scoped **player token** (and, for the card leg, a per-purchase `checkoutUrl`).
|
|
25
|
+
|
|
26
|
+
## Passkeys are the gold standard — don't build on SMS
|
|
27
|
+
|
|
28
|
+
**If you take one thing from this README: authorize money movement with a passkey. Do not design your verification UX around the SMS PIN.**
|
|
29
|
+
|
|
30
|
+
A passkey is a WebAuthn assertion — phishing-resistant, bound to your origin, and backed by the device's secure hardware. An SMS PIN is a shared secret delivered over a channel exposed to **SIM swap**, SS7 interception, and social engineering. They are not two equivalent ways to approve a transfer; one is materially weaker, and INVO treats it that way (see the 24-hour money-out cooldown after a passkey recovery — that gate exists precisely because phone-based possession can be stolen).
|
|
31
|
+
|
|
32
|
+
So:
|
|
33
|
+
|
|
34
|
+
| | Do this | Not this |
|
|
35
|
+
|---|---|---|
|
|
36
|
+
| Sender approves a send/transfer | `client.enrollPasskey()` once, then `client.approveSend` / `approveTransfer` | a PIN pad as the default flow |
|
|
37
|
+
| `initiate*` returns `verificationMethod: "sms"` | read it as *"this user has no passkey"* → offer enrollment | route straight to PIN entry |
|
|
38
|
+
| Recipient collects | `client.confirmReceiptSend` / `confirmReceiptTransfer` (passkey) | claim code as the primary path |
|
|
39
|
+
|
|
40
|
+
### Prerequisite: passkeys are dark until your tenant verifies a domain
|
|
41
|
+
|
|
42
|
+
**Read this before you wire up `enrollPasskey()`.** Passkey step-up is enabled **per tenant** and stays off until you verify ownership of a domain (your RP ID) in the developer console. Until then every passkey endpoint returns `403 WEBAUTHN_NOT_ENABLED_FOR_TENANT`.
|
|
43
|
+
|
|
44
|
+
**This is the common case today, not an edge case.** As of 2026-08-05 only **4 of 23 sandbox tenants** and **0 of 3 production tenants** have a verified RP ID. If you skip this, your integration will 403 on its first `enrollPasskey()` call and you'll be debugging a configuration state as if it were a bug.
|
|
45
|
+
|
|
46
|
+
`WEBAUTHN_NOT_ENABLED_FOR_TENANT` is **configuration state, not an error** — the ceremony was never available to fail. Don't show the player a failure; fall back to the existing path:
|
|
47
|
+
|
|
48
|
+
```ts
|
|
49
|
+
try {
|
|
50
|
+
await client.enrollPasskey();
|
|
51
|
+
} catch (e) {
|
|
52
|
+
if (e instanceof InvoError && e.isWebauthnNotEnabledForTenant) {
|
|
53
|
+
// Not a failure — this tenant simply hasn't verified a domain yet.
|
|
54
|
+
// Fall back to the SMS/in-app path and (if this is YOUR tenant) go verify a domain.
|
|
55
|
+
usePinFallback();
|
|
56
|
+
} else throw e;
|
|
57
|
+
}
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
So the honest sequence is: **verify your domain → enroll passkeys → you're on the gold-standard path.** Until step one is done, the SMS path is carrying you whether you like it or not — which is exactly why the deprecation below has no removal date attached.
|
|
61
|
+
|
|
62
|
+
> ⚠️ **`verifySmsTransfer` / `verifySmsSend` are deprecated as of `3.1.0` and a future major version will remove them.** They still work exactly as before — this release changes documentation only, emits no runtime warning, and breaks nothing. Keep the PIN path as a genuine last resort for: users who **cannot** enroll (unsupported device, no platform authenticator), users who decline, and **tenants that haven't verified a domain yet** (see above). Just don't make it the road everyone walks down once passkeys are available to you.
|
|
63
|
+
|
|
64
|
+
**What is *not* discouraged.** These use a one-time code, but they are the on-ramp *to* a passkey — not a substitute for one. Use them freely:
|
|
65
|
+
|
|
66
|
+
- `enrollmentBegin` / `enrollmentVerify` — the first-enrollment grant. This is how a user **gets** a passkey.
|
|
67
|
+
- `recoveryBegin` / `recoveryComplete` — restores a passkey after the user loses or deletes it.
|
|
68
|
+
- `phoneShareInitiate` / `phoneShareApprove` — phone-**ownership consent**, not transaction authorization.
|
|
69
|
+
|
|
70
|
+
Beyond security, this is also an economics story: SMS costs real money per message at every scale, and INVO's architecture targets passkey/in-app verification as the primary path so the platform never depends on carrier delivery. A passkey-first integration is faster for your users, cheaper to run, and won't need migrating later.
|
|
71
|
+
|
|
72
|
+
## Contents
|
|
73
|
+
|
|
74
|
+
- [Passkeys are the gold standard — don't build on SMS](#passkeys-are-the-gold-standard--dont-build-on-sms)
|
|
75
|
+
- [Install](#install)
|
|
76
|
+
- [Architecture & the two entry points](#architecture--the-two-entry-points)
|
|
77
|
+
- [Before you go live](#before-you-go-live)
|
|
78
|
+
- [Configuration](#configuration)
|
|
79
|
+
- [Currency purchase (real money in)](#currency-purchase-real-money-in)
|
|
80
|
+
- [Item purchase (spend game currency)](#item-purchase-spend-game-currency)
|
|
81
|
+
- [Platform Commerce (ecommerce)](#platform-commerce-ecommerce)
|
|
82
|
+
- [Player balance](#player-balance)
|
|
83
|
+
- [Sends & transfers (move currency between players)](#sends--transfers-move-currency-between-players)
|
|
84
|
+
- [Passkeys (enroll, approve, link, recover)](#passkeys-enroll-approve-link-recover)
|
|
85
|
+
- [Webhooks](#webhooks)
|
|
86
|
+
- [Resilience & observability](#resilience--observability)
|
|
87
|
+
- [Errors](#errors)
|
|
88
|
+
- [API reference](#api-reference)
|
|
89
|
+
- [Scripts & versioning](#scripts--versioning)
|
|
90
|
+
|
|
91
|
+
## Install
|
|
92
|
+
|
|
93
|
+
```bash
|
|
94
|
+
npm install @invonetwork/web-sdk
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Node ≥ 18 on the server (uses the global `fetch`). The browser build ships ESM + CJS + types.
|
|
98
|
+
|
|
99
|
+
## Get your account & game secret (INVO console)
|
|
100
|
+
|
|
101
|
+
Sign up, create your game, and copy its credentials (the **game secret**, plus your WebAuthn **RP ID / origins**) in the INVO console. Use the console that matches the environment you're building against:
|
|
102
|
+
|
|
103
|
+
| Environment | Console — sign up, manage games, copy your game secret | API `baseUrl` |
|
|
104
|
+
|---|---|---|
|
|
105
|
+
| **Testing / sandbox** | **https://dev.console.invo.network** | `https://sandbox.invo.network/sandbox` |
|
|
106
|
+
| **Production** | **https://console.invo.network** | `https://invo.network` |
|
|
107
|
+
|
|
108
|
+
Build and test against the **dev console + sandbox** first, then switch to the **production console + `https://invo.network`** for launch. **Each environment has its own game secret — never mix them**, and keep the secret server-side only.
|
|
109
|
+
|
|
110
|
+
## Architecture & the two entry points
|
|
111
|
+
|
|
112
|
+
```
|
|
113
|
+
┌──────────────────────────────┐ ┌──────────────────────────────┐
|
|
114
|
+
│ YOUR SERVER (trusted) │ │ THE BROWSER (untrusted) │
|
|
115
|
+
│ @invonetwork/web-sdk/server │ │ @invonetwork/web-sdk │
|
|
116
|
+
│ │ mint │ │
|
|
117
|
+
│ • holds X-Game-Secret-Key │ ──────► │ • holds short-lived token │
|
|
118
|
+
│ • mintPlayerToken() │ token │ (~15 min, game-scoped) │
|
|
119
|
+
│ • initiateSend/Transfer() │ │ • enrollPasskey() │
|
|
120
|
+
│ • createCheckout() │ │ • approveSend/Transfer() │
|
|
121
|
+
│ • purchaseCurrency() │ │ • confirmReceipt*() │
|
|
122
|
+
│ • purchaseItem() │ │ • linkDevice() │
|
|
123
|
+
└───────────────┬───────────────┘ └───────────────┬──────────────┘
|
|
124
|
+
└──────────────► INVO BACKEND ◄────────────┘
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
| Import | Runs on | Holds | Responsibilities |
|
|
128
|
+
|---|---|---|---|
|
|
129
|
+
| `@invonetwork/web-sdk/server` | your backend (Node ≥18) | the **game secret** | mint player tokens; initiate sends/transfers; currency purchase; item purchase |
|
|
130
|
+
| `@invonetwork/web-sdk` | the browser | a short-lived **player token** | passkey enroll, approve, self-claim, device link |
|
|
131
|
+
|
|
132
|
+
**Never import `/server` into browser code** — it carries the game secret. The two entries are built separately for exactly this reason.
|
|
133
|
+
|
|
134
|
+
## Integration modes
|
|
135
|
+
|
|
136
|
+
`InvoClient` needs a `token` and a `baseUrl` — which lets you adopt it **two ways**. Same SDK, same code in your components; only the config differs.
|
|
137
|
+
|
|
138
|
+
### Player token (session mint for an existing player)
|
|
139
|
+
|
|
140
|
+
`mintPlayerToken` mints a short-lived, game-scoped **session token** for a player who
|
|
141
|
+
**already exists** on your game. It is *not* a registration call — the backend looks the
|
|
142
|
+
player up by `playerEmail` and returns a token for their existing identity (or `404` if no
|
|
143
|
+
such player exists). It only needs `playerEmail`:
|
|
144
|
+
|
|
145
|
+
```ts
|
|
146
|
+
// your backend
|
|
147
|
+
const { token } = await invo.mintPlayerToken({ playerEmail: "player@example.com" });
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
`playerPhone` is **optional** here (validated as E.164 only if you pass it, and ignored by this
|
|
151
|
+
endpoint) — an existing email-only player still mints a token.
|
|
152
|
+
|
|
153
|
+
**Where phone actually matters.** A player's INVO identity encodes their phone, and cross-game
|
|
154
|
+
money routing keys off it — but that's enforced on the money calls, not the token mint:
|
|
155
|
+
|
|
156
|
+
- **`initiateSend` / `initiateTransfer`** require the **sender's** phone (E.164), and take the
|
|
157
|
+
**recipient's** phone. You can send by the recipient's **phone alone** — they supply their
|
|
158
|
+
email when they claim.
|
|
159
|
+
- An account with no phone can't receive cross-game money and can't take part in the
|
|
160
|
+
account-linking consent SMS, so make sure players have a phone at **creation / enrollment**
|
|
161
|
+
(in your own player system), before they transact.
|
|
162
|
+
|
|
163
|
+
### Token bootstrap (both modes)
|
|
164
|
+
|
|
165
|
+
Expose one small backend endpoint that calls `mintPlayerToken` (server-side, with the game secret) and hand the token to the browser:
|
|
166
|
+
|
|
167
|
+
```ts
|
|
168
|
+
// browser
|
|
169
|
+
const client = new InvoClient({
|
|
170
|
+
baseUrl: "https://api.invo.network",
|
|
171
|
+
token: await fetch("/your/sdk-token").then((r) => r.json()).then((j) => j.token),
|
|
172
|
+
// Called automatically on SDK_TOKEN_EXPIRED (~15 min TTL) — just re-fetch from your backend:
|
|
173
|
+
refreshToken: () => fetch("/your/sdk-token").then((r) => r.json()).then((j) => j.token),
|
|
174
|
+
});
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
### Mode A — browser-direct (default)
|
|
178
|
+
|
|
179
|
+
The browser holds the short-lived, game-scoped player token and calls INVO directly (`baseUrl` = the INVO API). Fewer moving parts. Requires INVO to **CORS-allow your web origin** and to have your **RP ID / origins** set up for passkeys (see [Before you go live](#before-you-go-live)).
|
|
180
|
+
|
|
181
|
+
### Mode B — behind your proxy (keep the token server-side)
|
|
182
|
+
|
|
183
|
+
If your architecture requires the INVO player token to **never reach the browser**, route the SDK through your own backend — **no CORS setup needed, and no security-posture change**:
|
|
184
|
+
|
|
185
|
+
- Set `baseUrl` to your proxy (e.g. `https://yourgame.com/invo`), which forwards to the INVO API and **injects the real `Authorization` header server-side**.
|
|
186
|
+
- Give the browser a short-lived **session/CSRF token** (not the INVO token) as `token`; your proxy validates it and swaps in the real player token. Or use cookie auth with a custom `fetch`:
|
|
187
|
+
|
|
188
|
+
```ts
|
|
189
|
+
const client = new InvoClient({
|
|
190
|
+
baseUrl: "https://yourgame.com/invo", // your proxy → INVO
|
|
191
|
+
token: sessionToken, // your token; the proxy swaps in the real one
|
|
192
|
+
fetch: (url, init) => fetch(url, { ...init, credentials: "include" }), // send your cookie
|
|
193
|
+
});
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
The WebAuthn ceremony still runs in the browser (it must — it's `navigator.credentials`), but transport/auth stays behind your proxy. You keep the SDK's ceremony handling, token-refresh, typed holds, and error classifiers either way.
|
|
197
|
+
|
|
198
|
+
**Running `InvoServer` in the proxy** (for the game-secret writes — initiate, checkout, purchase — so the secret leaves the browser): see the drop-in reference at [`examples/proxy-server.ts`](examples/proxy-server.ts). Its actor resolver is pluggable:
|
|
199
|
+
|
|
200
|
+
- **Real partner** (one login = one player) — derive the acting player from your **session**.
|
|
201
|
+
- **Trusted first-party rig** (an internal tool that impersonates arbitrary test players) — the caller names `playerEmail`, guarded by a shared-secret header (`INVO_PROXY_TRUSTED_SECRET`), the same trusted pattern as a `player_email` token minter. Never expose this mode to end-user browsers.
|
|
202
|
+
|
|
203
|
+
> **Lowest-risk first step:** adopt just `linkDevice` (passkey ↔ app device interchange) — it's purely additive and needs no refactor. See [Passkeys](#passkeys-enroll-approve-link-recover).
|
|
204
|
+
|
|
205
|
+
## Before you go live
|
|
206
|
+
|
|
207
|
+
INVO enables each flow for your tenant in the [console](#get-your-account--game-secret-invo-console). What you need to do:
|
|
208
|
+
|
|
209
|
+
- **Store the game secret server-side** and expose a small endpoint that calls `mintPlayerToken` so the browser can fetch/refresh its token. Never ship the secret to the browser.
|
|
210
|
+
- **Make sure players have a phone (E.164) at creation/enrollment** — it's required on the money calls (`initiateSend`/`initiateTransfer`) and for cross-game receive, though not on the token mint itself (see [Player token](#player-token-session-mint-for-an-existing-player)).
|
|
211
|
+
- **If you use browser-direct ([Mode A](#mode-a--browser-direct-default)):** ask INVO to **CORS-allow your web origin(s)** so the browser can call the API directly. (Not needed for [Mode B / proxy](#mode-b--behind-your-proxy-keep-the-token-server-side) — those requests are same-origin to your backend.)
|
|
212
|
+
- **For passkeys (sends/transfers):** give INVO the **RP ID + web origin(s)** you'll serve from. Passkeys only validate on approved origins — if a call returns `WEBAUTHN_NOT_ENABLED_FOR_TENANT`, your origins aren't set up yet; contact INVO. **Get this configured before launch:** until a sender is enrolled the backend falls back to the deprecated SMS-PIN path, which is the flow you don't want your users on (see [Passkeys are the gold standard](#passkeys-are-the-gold-standard--dont-build-on-sms)).
|
|
213
|
+
- **For currency purchase:** card checkout works out of the box; ask INVO to enable the `game`/`steam` rails if you need them.
|
|
214
|
+
- **For item purchase:** nothing extra — it's a currency-balance debit.
|
|
215
|
+
|
|
216
|
+
If a flow isn't enabled for your tenant yet, calls return a clear `InvoError` (e.g. `TENANT_NOT_MIGRATED`, `WEBAUTHN_NOT_ENABLED_FOR_TENANT`, or `flow_paused`) — coordinate with your INVO contact to turn it on.
|
|
217
|
+
|
|
218
|
+
## Configuration
|
|
219
|
+
|
|
220
|
+
```ts
|
|
221
|
+
import { InvoServer } from "@invonetwork/web-sdk/server";
|
|
222
|
+
import { InvoClient } from "@invonetwork/web-sdk";
|
|
223
|
+
|
|
224
|
+
const server = new InvoServer({
|
|
225
|
+
gameSecret: process.env.INVO_GAME_SECRET!, // server-side only
|
|
226
|
+
baseUrl: "https://sandbox.invo.network/sandbox", // prod: "https://invo.network"
|
|
227
|
+
timeoutMs: 30_000, // optional, default 30s
|
|
228
|
+
maxRetries: 2, // optional, default 2 (0 disables)
|
|
229
|
+
// retryBaseDelayMs: 250, // optional backoff base
|
|
230
|
+
// fetch: customFetch, // optional override
|
|
231
|
+
// hooks: { onRequest, onResponse, onError }, // optional observability (see below)
|
|
232
|
+
});
|
|
233
|
+
|
|
234
|
+
const client = new InvoClient({
|
|
235
|
+
token, // from your /mint endpoint
|
|
236
|
+
baseUrl: "https://sandbox.invo.network/sandbox",
|
|
237
|
+
refreshToken: () => // optional: auto re-mint + retry on token expiry
|
|
238
|
+
fetch("/invo/token", { method: "POST" }).then((r) => r.json()).then((j) => j.token),
|
|
239
|
+
});
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
**Base URLs** (manage each environment in its [console](#get-your-account--game-secret-invo-console))
|
|
243
|
+
- Production: `https://invo.network` — console: `https://console.invo.network`
|
|
244
|
+
- Sandbox / testing: `https://sandbox.invo.network/sandbox` — console: `https://dev.console.invo.network` (sandbox prepends the `/sandbox` prefix; the SDK absorbs it via `baseUrl`)
|
|
245
|
+
|
|
246
|
+
`baseUrl` must be `https://` — the game secret and player token travel in request headers, so plaintext is rejected. `http://localhost` is allowed for local dev only.
|
|
247
|
+
|
|
248
|
+
**Player tokens** live ~15 minutes and are game-scoped. Mint one per browser session. If you pass `refreshToken` to `InvoClient`, the SDK transparently re-mints and retries once on `SDK_TOKEN_EXPIRED` (it re-runs the whole passkey ceremony so it never replays a single-use challenge).
|
|
249
|
+
|
|
250
|
+
---
|
|
251
|
+
|
|
252
|
+
## Currency purchase (real money in)
|
|
253
|
+
|
|
254
|
+
Buy game currency with real money. Authenticated by the **payment rail**, not a passkey — there's no WebAuthn step. Two paths:
|
|
255
|
+
|
|
256
|
+
### Hosted checkout (recommended — PCI-light, you never touch card data)
|
|
257
|
+
|
|
258
|
+
```ts
|
|
259
|
+
// SERVER
|
|
260
|
+
const { checkoutUrl, sessionId, expiresAt, expiresInSeconds } = await server.createCheckout({
|
|
261
|
+
playerEmail: "p@example.com",
|
|
262
|
+
usdAmount: "20.00", // USD, 0 < x ≤ 999.99
|
|
263
|
+
rail: "platform", // optional: "platform" (default) | "game" | "steam"
|
|
264
|
+
successUrl: "https://you/buy/ok",
|
|
265
|
+
cancelUrl: "https://you/buy/cancel",
|
|
266
|
+
metadata: { yourOrderId: "ord_42" }, // echoed on the purchase.completed webhook (all rails); order_id also reconciles
|
|
267
|
+
});
|
|
268
|
+
// → send the browser to checkoutUrl. Token TTL is expiresInSeconds (~900s / 15 min).
|
|
269
|
+
// Reloading the URL after a completed payment is idempotent — it shows an already-complete
|
|
270
|
+
// success screen (no error), so you don't have to guard against a refresh.
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
Open `checkoutUrl` either way:
|
|
274
|
+
|
|
275
|
+
- **Full-page redirect / WebView** — works everywhere; on success the page redirects to your `successUrl`.
|
|
276
|
+
- **Embedded `<iframe>`** — works by default from any https origin (no allow-listing). The page does *not* redirect your top window; listen for the `INVO_CHECKOUT_COMPLETE` postMessage:
|
|
277
|
+
|
|
278
|
+
```ts
|
|
279
|
+
// BROWSER
|
|
280
|
+
const iframe = document.createElement("iframe");
|
|
281
|
+
iframe.src = checkoutUrl;
|
|
282
|
+
iframe.style.cssText = "width:440px;height:720px;border:0";
|
|
283
|
+
document.body.appendChild(iframe);
|
|
284
|
+
|
|
285
|
+
window.addEventListener("message", (e) => {
|
|
286
|
+
if (e.origin !== "https://invo.network") return; // sandbox: "https://sandbox.invo.network"
|
|
287
|
+
if (e.data?.type === "INVO_CHECKOUT_COMPLETE") {
|
|
288
|
+
// UX hint ONLY (unsigned). data = { status, new_balance, currency_name, transaction_id }
|
|
289
|
+
refreshBalanceOptimistically(e.data.data.new_balance);
|
|
290
|
+
}
|
|
291
|
+
});
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
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. Currency purchase has **no browser SDK method** — the browser only opens the URL.
|
|
295
|
+
|
|
296
|
+
### Payment rails (neutral names)
|
|
297
|
+
|
|
298
|
+
The `rail` selects the in-page experience — all branded INVO, no visible redirect:
|
|
299
|
+
- `"platform"` (default) — cards plus **Apple Pay / Google Pay / Link** (rendered automatically on supported devices) and international billing addresses. It's a web checkout, so there's no app-store commission.
|
|
300
|
+
- `"game"` — regional / game-store methods (may redirect to the regional hosted page).
|
|
301
|
+
- `"steam"` — Steam titles hand off to the in-client Steam flow.
|
|
302
|
+
|
|
303
|
+
> **Steam titles: currency must be bought through Steam, and INVO sets the packs.**
|
|
304
|
+
>
|
|
305
|
+
> A title distributed on Steam may only sell currency on the `steam` rail — any other
|
|
306
|
+
> rail is refused with `409 STEAM_PURCHASE_LAYER_REQUIRED`. This is a platform
|
|
307
|
+
> requirement, not an INVO preference, and it applies to every storefront the title
|
|
308
|
+
> ships on because a player's balance is shared across them.
|
|
309
|
+
>
|
|
310
|
+
> **You do not set Steam prices and you do not send an amount.** INVO defines the pack
|
|
311
|
+
> catalogue for every game on the network. Fetch it with `GET /steam/packs?steamid=...`,
|
|
312
|
+
> render it, and pass the `pack_id` back to the purchase call.
|
|
313
|
+
>
|
|
314
|
+
> **The price is the same everywhere; the currency inside is not.** Steam prices are
|
|
315
|
+
> VAT-inclusive wherever VAT is collected, so more of a fixed price goes to tax in a
|
|
316
|
+
> high-VAT country and less is left to buy currency with — the same $9.99 pack yields
|
|
317
|
+
> 69 units in the US and 58 in France. Always pass `steamid` when fetching the
|
|
318
|
+
> catalogue, or the amounts are quoted with no VAT deducted and your store promises
|
|
319
|
+
> more than the purchase delivers. Do not cache one catalogue for all players and do
|
|
320
|
+
> not hard-code amounts: pack prices and VAT rates are both configuration.
|
|
321
|
+
|
|
322
|
+
Provider/processor names are an internal detail and never appear in the API.
|
|
323
|
+
|
|
324
|
+
### Steam purchases (packs, not prices)
|
|
325
|
+
|
|
326
|
+
Steam is **not** an SDK method — it is a server-to-server REST flow, because the
|
|
327
|
+
purchase is authorised inside the Steam client and your game has to relay that.
|
|
328
|
+
`purchaseCurrency` rejects `rail: "steam"` with `WRONG_RAIL_ENDPOINT` for that reason.
|
|
329
|
+
|
|
330
|
+
**INVO owns the pack catalogue.** You never send a price. Fetch the packs, show them,
|
|
331
|
+
pass a `pack_id` back.
|
|
332
|
+
|
|
333
|
+
```ts
|
|
334
|
+
// 1. The catalogue, priced for THIS player. Always pass steamid.
|
|
335
|
+
const res = await fetch(
|
|
336
|
+
`${INVO_BASE}/api/enhanced-purchase/steam/packs?steamid=${steamId}`,
|
|
337
|
+
{ headers: { "X-Game-Secret": GAME_SECRET } },
|
|
338
|
+
);
|
|
339
|
+
const { country, vat_rate_pct, packs } = await res.json();
|
|
340
|
+
// packs: [{ pack_id, label, price_usd, currency_amount }, ...]
|
|
341
|
+
|
|
342
|
+
// 2. Start the purchase with the pack the player chose.
|
|
343
|
+
const init = await fetch(`${INVO_BASE}/api/enhanced-purchase/steam/init-purchase`, {
|
|
344
|
+
method: "POST",
|
|
345
|
+
headers: { "X-Game-Secret": GAME_SECRET, "Content-Type": "application/json" },
|
|
346
|
+
body: JSON.stringify({
|
|
347
|
+
player_email: "player@example.com",
|
|
348
|
+
steamid: steamId,
|
|
349
|
+
pack_id: "steam_medium", // NOT a price
|
|
350
|
+
purchase_reference: crypto.randomUUID(),
|
|
351
|
+
}),
|
|
352
|
+
});
|
|
353
|
+
// -> { order_id, steam_transid, pack_id, charged_usd, currency_amount }
|
|
354
|
+
|
|
355
|
+
// 3. Steam shows its overlay. Your game client receives
|
|
356
|
+
// MicroTxnAuthorizationResponse_t and tells your backend to finalize.
|
|
357
|
+
// 4. POST /steam/finalize-purchase { order_id } -> currency is credited.
|
|
358
|
+
```
|
|
359
|
+
|
|
360
|
+
**The price is identical everywhere; the currency inside is not.** Steam prices are
|
|
361
|
+
VAT-inclusive wherever VAT is collected, so more of a fixed price goes to tax in a
|
|
362
|
+
high-VAT country and less is left to buy currency with — the same `$9.99` pack yields
|
|
363
|
+
**69** units in the US and **58** in France.
|
|
364
|
+
|
|
365
|
+
- **Always pass `steamid`** to `/steam/packs`. Without it the amounts are quoted with
|
|
366
|
+
no VAT deducted — the most any pack yields — so your store promises more than the
|
|
367
|
+
purchase delivers.
|
|
368
|
+
- **Do not cache one catalogue for all players**, and do not hard-code amounts. Pack
|
|
369
|
+
prices and VAT rates are both configuration and change without an SDK release.
|
|
370
|
+
- **A Steam-distributed title may only sell on this rail.** Any other is refused with
|
|
371
|
+
`409 STEAM_PURCHASE_LAYER_REQUIRED`, across every storefront the title ships on,
|
|
372
|
+
because a player's balance is shared between them.
|
|
373
|
+
- A locked Steam account is refused up front with `409 STEAM_ACCOUNT_LOCKED`.
|
|
374
|
+
|
|
375
|
+
### Direct rail (advanced — you tokenize the card yourself)
|
|
376
|
+
|
|
377
|
+
```ts
|
|
378
|
+
const purchase = await server.purchaseCurrency({
|
|
379
|
+
playerEmail: "p@example.com",
|
|
380
|
+
usdAmount: "20.00",
|
|
381
|
+
purchaseReference: crypto.randomUUID(), // idempotency key, required
|
|
382
|
+
rail: "platform",
|
|
383
|
+
paymentMethodId: "pm_...", // a tokenized payment method
|
|
384
|
+
metadata: { yourOrderId: "ord_42" }, // echoed on the purchase.completed webhook (all rails); order_id also reconciles
|
|
385
|
+
});
|
|
386
|
+
// purchase.status:
|
|
387
|
+
// "success" → captured, purchase.newBalance updated
|
|
388
|
+
// "requires_action" → 3-D Secure: run the client action with purchase.clientSecret,
|
|
389
|
+
// then call server.confirmPayment({ paymentIntentId })
|
|
390
|
+
// "pending_payment" → redirect the browser to purchase.paymentUrl (game rail)
|
|
391
|
+
```
|
|
392
|
+
`rail: "steam"` is rejected here (`WRONG_RAIL_ENDPOINT`) — Steam uses its own in-client flow. Reconcile with `server.getOrderDetails({ orderId })`. Most browser integrations should use hosted checkout instead.
|
|
393
|
+
|
|
394
|
+
---
|
|
395
|
+
|
|
396
|
+
## Item purchase (spend game currency)
|
|
397
|
+
|
|
398
|
+
Spend the currency a player **already owns** to buy an in-game item. A balance debit — **no real money, no payment rail, no passkey** — server-side only. Amounts are in **game-currency units** (not USD).
|
|
399
|
+
|
|
400
|
+
```ts
|
|
401
|
+
const item = await server.purchaseItem({
|
|
402
|
+
clientRequestId: crypto.randomUUID(), // idempotency key, unique per game
|
|
403
|
+
playerEmail: "p@example.com",
|
|
404
|
+
playerName: "P",
|
|
405
|
+
itemId: "sword_001",
|
|
406
|
+
itemName: "Legendary Sword",
|
|
407
|
+
itemQuantity: 1, // integer 1..1000
|
|
408
|
+
unitPrice: "100.00", // > 0 and ≤ 999999.99
|
|
409
|
+
totalPrice: "100.00", // must equal unitPrice × itemQuantity (±0.01)
|
|
410
|
+
// optional: playerPhone, itemDescription, itemCategory
|
|
411
|
+
});
|
|
412
|
+
// item.status === "success"
|
|
413
|
+
// item.newBalance / item.previousBalance / item.currencyName
|
|
414
|
+
// item.transactionId / item.orderId
|
|
415
|
+
// item.financialBreakdown { total_paid, developer_revenue, platform_fee }
|
|
416
|
+
```
|
|
417
|
+
|
|
418
|
+
- **Grant the item off the `item.purchased` webhook**, not just this response. INVO debits currency and records the purchase; **your game owns the item catalog and grants the item.** The webhook fires atomically with the spend.
|
|
419
|
+
- **Idempotent** on `clientRequestId` — a duplicate throws `409` (`err.isDuplicateRequest`).
|
|
420
|
+
- **Insufficient balance** throws `400` (`err.isInsufficientBalance`; `required_amount` + `current_balance` on `err.body`).
|
|
421
|
+
- **Throttled** calls throw `429` with `err.retryAfter` (seconds).
|
|
422
|
+
- Client-side validation (missing fields, quantity outside `1..1000`, bad price, total ≠ unit×qty) throws `INVALID_INPUT` **before** any network call.
|
|
423
|
+
- Fee split: **90% developer / 10% INVO** by default (per-partner override). Not guardian-gated.
|
|
424
|
+
|
|
425
|
+
**Companion reads:** `server.getItemPurchaseHistory({ playerEmail, limit?, offset? })` and `server.getItemOrderDetails({ orderId | transactionId | clientRequestId })` (pass **exactly one** id — use `clientRequestId` for recovery: "did this purchase complete?"). To walk the full history, `for await (const row of server.iterateItemPurchaseHistory({ playerEmail }))` pages automatically.
|
|
426
|
+
|
|
427
|
+
---
|
|
428
|
+
|
|
429
|
+
## Platform Commerce (ecommerce)
|
|
430
|
+
|
|
431
|
+
> **This is not [item purchase](#item-purchase-spend-game-currency).** Item purchase is a *game* tenant spending a player's *existing game currency* on an *in-game* item — always a balance debit, never a card, no refunds. **Platform Commerce is a _platform_ tenant (a non-game app: vertical video, creator merch, marketplace) running a storefront.** The buyer pays with **INVO balance** *or* a **real card** (new money), INVO is **merchant of record**, and **refunds** exist. Only platform tenants may call it — a game tenant gets `403` (`err.isNotPlatformTenant`).
|
|
432
|
+
|
|
433
|
+
The funding source is resolved **server-side under lock** — the client can *request* `balance` or `card`, but the backend verifies the real balance before any value moves. Everything money-shaped is a server call (holds the secret, creates the purchase/refund); the browser's only job on the card leg is to **send the buyer to INVO's hosted checkout page**. Reached via the `platformCommerce` namespace on each entry point.
|
|
434
|
+
|
|
435
|
+
### Balance leg — one server call, settles now
|
|
436
|
+
|
|
437
|
+
```ts
|
|
438
|
+
const r = await server.platformCommerce.purchase({
|
|
439
|
+
clientRequestId: crypto.randomUUID(), // idempotency key, unique per tenant
|
|
440
|
+
fundingSource: "balance",
|
|
441
|
+
playerEmail: "user@example.com",
|
|
442
|
+
playerName: "Ada",
|
|
443
|
+
itemId: "sticker_pack_01",
|
|
444
|
+
itemName: "Sticker Pack",
|
|
445
|
+
itemQuantity: 1, // integer 1..1000
|
|
446
|
+
unitPrice: "5.00", // BALANCE leg: the tenant's network-currency amount
|
|
447
|
+
totalPrice: "5.00", // must equal unitPrice × itemQuantity (±0.01)
|
|
448
|
+
});
|
|
449
|
+
// r.status === "success" — settled synchronously
|
|
450
|
+
// r.newBalance / r.previousBalance / r.currencyName
|
|
451
|
+
// r.orderId / r.transactionId
|
|
452
|
+
// r.financialBreakdown { total_paid, developer_revenue, platform_fee } // INVO fee: 3.5% flat
|
|
453
|
+
```
|
|
454
|
+
|
|
455
|
+
### Card leg — server creates, INVO hosts the checkout
|
|
456
|
+
|
|
457
|
+
**INVO hosts the entire card checkout** — card fields, Apple Pay / Google Pay, the international billing-address collector, and 3-D Secure all live on INVO's page. There is **no billing address in the request, no card element, no processor dependency, and no client payment code to write**: the server call returns a `checkoutUrl` and you send the buyer there. `totalPrice` is **USD** ($0.50–$999.99).
|
|
458
|
+
|
|
459
|
+
```ts
|
|
460
|
+
// 1) server — returns a hosted-checkout session, NOT yet paid
|
|
461
|
+
const r = await server.platformCommerce.purchase({
|
|
462
|
+
clientRequestId: crypto.randomUUID(),
|
|
463
|
+
fundingSource: "card",
|
|
464
|
+
playerEmail: "user@example.com",
|
|
465
|
+
playerName: "Ada",
|
|
466
|
+
itemId: "sticker_pack_01",
|
|
467
|
+
itemName: "Sticker Pack",
|
|
468
|
+
itemQuantity: 1,
|
|
469
|
+
unitPrice: "5.00", // CARD leg: USD
|
|
470
|
+
totalPrice: "5.00",
|
|
471
|
+
successUrl: "https://app.example/thanks", // optional: where the buyer lands after paying
|
|
472
|
+
cancelUrl: "https://app.example/cart", // optional: where the buyer lands on cancel
|
|
473
|
+
metadata: { cartId: "c_9" }, // optional: echoed back on the webhook
|
|
474
|
+
});
|
|
475
|
+
// r.status === "requires_payment"
|
|
476
|
+
// r.checkoutUrl → send the buyer here r.sessionId / r.expiresAt (unix seconds)
|
|
477
|
+
```
|
|
478
|
+
|
|
479
|
+
```ts
|
|
480
|
+
// 2) browser — EITHER just redirect…
|
|
481
|
+
location.href = r.checkoutUrl;
|
|
482
|
+
|
|
483
|
+
// …OR embed the hosted page with the optional helper (iframe + completion listener):
|
|
484
|
+
const handle = invo.platformCommerce.mountCheckout("#checkout", checkoutUrl, {
|
|
485
|
+
onComplete: () => showProcessing(), // fires on the page's INVO_CHECKOUT_COMPLETE message
|
|
486
|
+
});
|
|
487
|
+
// later: handle.destroy();
|
|
488
|
+
```
|
|
489
|
+
|
|
490
|
+
`mountCheckout` accepts completion messages **only from the checkout page's own origin**, and `onComplete` is a UX signal — show "processing", then reconcile server-side.
|
|
491
|
+
|
|
492
|
+
> ⚠️ **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.
|
|
493
|
+
|
|
494
|
+
### Status & refunds
|
|
495
|
+
|
|
496
|
+
```ts
|
|
497
|
+
const s = await server.platformCommerce.getStatus(r.orderId);
|
|
498
|
+
// s.status: "completed" (balance immediately; card after the webhook) | "pending_payment" | "refunded"
|
|
499
|
+
|
|
500
|
+
const ref = await server.platformCommerce.refund({ orderId: r.orderId, reason: "customer request" });
|
|
501
|
+
// or refund({ clientRequestId }). Pass EXACTLY ONE id.
|
|
502
|
+
// INVO retains its fee (ref.feeRetained === true); the customer is made whole minus that fee.
|
|
503
|
+
// A second refund of the same order throws 409 (err.isAlreadyRefunded) — treat as already done.
|
|
504
|
+
```
|
|
505
|
+
|
|
506
|
+
- **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`.
|
|
507
|
+
- INVO fee: **3.5% flat** (balance) · **3.5% + $0.30** (card). Too-small amounts throw `err.isAmountBelowMinimum` / `err.isBelowCardMinimum` (card < $0.50); a card total over $999.99 throws `err.isAboveCardMaximum`.
|
|
508
|
+
- Client-side validation (missing fields, bad funding source, quantity outside `1..1000`, total ≠ unit×qty, card USD bounds, non-E.164 `playerPhone`) throws **before** any network call.
|
|
509
|
+
- Fulfill on the **`platform_commerce.purchased`** webhook; handle **`platform_commerce.refunded`** for reversals.
|
|
510
|
+
|
|
511
|
+
---
|
|
512
|
+
|
|
513
|
+
## Player balance
|
|
514
|
+
|
|
515
|
+
Read a player's currency balances (server-side, game-secret) **by email**:
|
|
516
|
+
|
|
517
|
+
```ts
|
|
518
|
+
const { balances, summary } = await server.getPlayerBalance({ playerEmail: "p@example.com" });
|
|
519
|
+
// balances: [{ currencyName, availableBalance, reservedBalance, totalBalance, currencySymbol, raw }]
|
|
520
|
+
```
|
|
521
|
+
|
|
522
|
+
Lookup is by email only — there is no by-`playerId` balance route (a `playerId` is a per-game
|
|
523
|
+
internal id). For a **client-side** read, use `InvoClient.getBalance()` (player-token; identity
|
|
524
|
+
comes from the token, no PII).
|
|
525
|
+
|
|
526
|
+
---
|
|
527
|
+
|
|
528
|
+
## Sends & transfers (move currency between players)
|
|
529
|
+
|
|
530
|
+
Move already-owned game currency from one player to another, authorized by the **sender's passkey** — the [gold standard](#passkeys-are-the-gold-standard--dont-build-on-sms). (A deprecated SMS-PIN fallback exists for senders who aren't enrolled; treat it as a last resort, not a design.) **Send** and **transfer** are parallel flows:
|
|
531
|
+
|
|
532
|
+
| | Send | Transfer |
|
|
533
|
+
|---|---|---|
|
|
534
|
+
| Initiate (server) | `initiateSend` | `initiateTransfer` |
|
|
535
|
+
| Parties | `sender*` / `receiver*` + `receivingGameId` | `source*` / `target*` + `targetGameId` |
|
|
536
|
+
| Approve (browser) | `approveSend` | `approveTransfer` — also returns the sender's **claim code** |
|
|
537
|
+
| Recipient claim (browser) | `confirmReceiptSend` | `confirmReceiptTransfer` |
|
|
538
|
+
|
|
539
|
+
**Where can I send? (browser, v0.7.0+)** — before a player can move value, populate the "pick a destination" UI with `client.getDestinations({ direction: "transfer" | "send" })`. One player-token call returns every reachable game with display metadata inline — no per-game lookup:
|
|
540
|
+
|
|
541
|
+
```ts
|
|
542
|
+
const { availableGames, sourceCurrencyName } = await client.getDestinations({ direction: "transfer" });
|
|
543
|
+
// each: { gameId, gameName, gameIcon, currencyName, currencySymbol, minimumTransfer, maximumTransfer, … }
|
|
544
|
+
```
|
|
545
|
+
|
|
546
|
+
**What do I have? (browser, v0.8.0+)** — `client.getBalance()` returns the player's balances for this game (amounts are decimal strings; rows carry `currencySymbol`/`currencySymbolUrl`). A player who hasn't transacted here yet returns an empty `balances` array (show 0.00) — not an error:
|
|
547
|
+
|
|
548
|
+
```ts
|
|
549
|
+
const { balances, hasFunds, totalValue } = await client.getBalance();
|
|
550
|
+
// each: { currencyId, currencyName, currencySymbol, availableBalance, reservedBalance, totalBalance }
|
|
551
|
+
```
|
|
552
|
+
|
|
553
|
+
```ts
|
|
554
|
+
// 1. SERVER — initiate, then branch on how the sender must verify
|
|
555
|
+
const t = await server.initiateTransfer({
|
|
556
|
+
clientRequestId: crypto.randomUUID(),
|
|
557
|
+
sourcePlayerName: "P", sourcePlayerEmail: "p@example.com", sourcePlayerPhone: "+15555550100",
|
|
558
|
+
targetPlayerEmail: "q@example.com", targetPlayerPhone: "+15555550111",
|
|
559
|
+
targetGameId: 123456, amount: "50",
|
|
560
|
+
});
|
|
561
|
+
// (initiateSend uses sender*/receiver* + receivingGameId instead)
|
|
562
|
+
|
|
563
|
+
// Check guardianApproval FIRST — the guardian path takes precedence.
|
|
564
|
+
switch (true) {
|
|
565
|
+
case !!t.guardianApproval: // minor/guardian path (HTTP 202) → pending approval, no PIN UI
|
|
566
|
+
case t.verificationMethod === "in_app": // sender HAS a passkey → approve in the browser. The good path.
|
|
567
|
+
case t.verificationMethod === "sms": // sender has NO passkey → offer enrollPasskey() and approve;
|
|
568
|
+
// show the PIN pad only if they can't or won't enroll.
|
|
569
|
+
}
|
|
570
|
+
|
|
571
|
+
// 2. BROWSER — the sender approves with their passkey (give them t.transactionId + the player token)
|
|
572
|
+
const approved = await client.approveTransfer(t.transactionId); // or approveSend(...)
|
|
573
|
+
// approved.claimCode + approved.claimCodeExpiresAt (transfer only) — deliver if the recipient can't self-claim
|
|
574
|
+
|
|
575
|
+
// 3. BROWSER — the recipient claims with their passkey; fall back to the claim code if not enrolled
|
|
576
|
+
try {
|
|
577
|
+
await client.confirmReceiptTransfer(t.transactionId); // or confirmReceiptSend(...)
|
|
578
|
+
} catch (e) {
|
|
579
|
+
if (e instanceof InvoError && e.isReceiverNotEnrolled) {
|
|
580
|
+
// recipient has no passkey here → show claim-code entry using approved.claimCode
|
|
581
|
+
} else if (e instanceof InvoError && e.isPhoneShareApprovalRequired) {
|
|
582
|
+
// receiver phone is contested → funds held, phone owner texted to approve.
|
|
583
|
+
showPending(e.message, e.phoneShareLast4); // show e.message verbatim; last4 names the phone
|
|
584
|
+
// …then RETRY the same confirmReceipt*/claim call once approved (succeeds idempotently).
|
|
585
|
+
} else throw e;
|
|
586
|
+
}
|
|
587
|
+
```
|
|
588
|
+
|
|
589
|
+
- **`verificationMethod`** (from initiate): `"in_app"` → the sender has a passkey, go approve (the recommended path); `"sms"` → **the sender has no passkey** and a PIN was sent as a deprecated fallback — the best response is to offer `enrollPasskey()` and then `approveSend`/`approveTransfer`, showing the PIN pad only if they can't or won't enroll; `undefined` + `guardianApproval` → minor/guardian (HTTP 202), do **not** show the PIN UI. On the guardian path the SDK reports `verificationMethod: undefined` (even though the raw 202 body also carries `"sms"`) so `guardianApproval` wins — but branch on it first to be safe.
|
|
590
|
+
- **Claim codes** are returned only by `approveTransfer`; they're the out-of-band fallback when the recipient isn't enrolled.
|
|
591
|
+
- **`err.isReceiverNotEnrolled`** on `confirmReceipt*` is the explicit signal to switch to claim-code entry.
|
|
592
|
+
- **`err.isPhoneShareApprovalRequired` on `confirmReceipt*` / `claimTransfer` / `claimCurrency`** (409): the receiver phone is contested, so INVO **holds the money** and texts the phone owner to approve. Not a failure — show `err.message` verbatim (`err.phoneShareLast4` names the phone), then **retry the same call** once approved (it succeeds idempotently); on denial/expiry the sender is refunded. Same handling as the initiate-time phone-share 409.
|
|
593
|
+
- **Both games must be Live.** `initiateSend`/`initiateTransfer` throw `403` if either side is still in testing, and the two cases are **deliberately separate** because the fix differs: `err.isSourceGameNotLive` is **your** game (self-serve — switch it to Live in the console under Game Settings → Status), `err.isTargetGameNotLive` is the **destination** game, usually owned by another developer, so you can't flip it — show `err.message` and steer the player elsewhere via `getDestinations`. `err.gameStatus` carries the current state. Don't merge these into one "not live" branch; it produces a "go fix it" button that leads nowhere half the time.
|
|
594
|
+
- **Steam titles** (dark until a title is Steam-distributed): `initiateSend`/`initiateTransfer` can throw `err.isSteamValueNonTransferable` (moving more than the non-Steam balance to a non-Steam destination — show `err.message`, cap the amount at `err.steamTransferableMax`; `err.steamOriginAmount` is the Steam-locked portion) or `err.isNonSteamValueIntoSteamBlocked` (non-Steam value into a Steam title). Prevent both up front: `getDestinations` rows carry **`acceptsSteamOriginValue`** — disable non-Steam destinations for a player holding Steam-purchased currency.
|
|
595
|
+
- Transfer self-claim may be disabled for your tenant; if it is, surface the claim-code path instead.
|
|
596
|
+
- **Holds:** an approve/claim can return an HTTP 202 hold instead of success — inspect `result.holdReason` (`"RISK_HOLD"`, `"GUARDIAN_APPROVAL_PENDING"`, and on confirm-receipt `"RECIPIENT_IDENTITY_PENDING"`); success has no `holdReason` (and `next: "pending_claim"`). Terminal guardian outcomes throw (`GUARDIAN_APPROVAL_REJECTED`/`_EXPIRED`).
|
|
597
|
+
|
|
598
|
+
**"You have X to collect"**
|
|
599
|
+
|
|
600
|
+
- **Browser (player-token):** `client.getPendingCollect()` returns the player's own pending items. Each row's `kind` tells you the action:
|
|
601
|
+
- `"receiving_confirm"` → a peer/another game **sent value TO this player** (incoming) → call `confirmReceiptSend`/`confirmReceiptTransfer`.
|
|
602
|
+
- `"identity_gate"` → **this player initiated** and it's awaiting them → call `approveSend`/`approveTransfer`.
|
|
603
|
+
> **Seeing incoming transfers from other games?** They come back as **`kind: "receiving_confirm"`** — render **both** kinds (a UI that only shows `identity_gate` will miss all inbound). The list is scoped to the token's player, so mint the token for the **recipient**. PII-free (no claim code / phone).
|
|
604
|
+
- **Server (game-secret):** `server.getInboundPending({ playerEmail | playerPhone })` — richer, includes `toPhone`/`toIdentityId` for routing a notification to the right account. Match `toPhone` to the player (`toIdentityId` is null when the phone maps to >1 of your players).
|
|
605
|
+
|
|
606
|
+
---
|
|
607
|
+
|
|
608
|
+
## Passkeys (enroll, approve, link, recover)
|
|
609
|
+
|
|
610
|
+
Passkeys (WebAuthn) are **the** way to approve sends/transfers — see [Passkeys are the gold standard](#passkeys-are-the-gold-standard--dont-build-on-sms) for why the SMS PIN they replace is deprecated. The browser SDK wraps `navigator.credentials.create/get`, base64url encoding, challenge round-trips, and error mapping.
|
|
611
|
+
|
|
612
|
+
**Enroll early.** The best moment is right after a player first signs in — not at the moment they're trying to move money, when a WebAuthn prompt reads as friction. A player enrolled up front never touches the PIN path at all.
|
|
613
|
+
|
|
614
|
+
```ts
|
|
615
|
+
// Enroll once per user (no-op to call again — the backend excludes already-enrolled credentials)
|
|
616
|
+
await client.enrollPasskey();
|
|
617
|
+
|
|
618
|
+
// Interchangeable methods (optional): prove an already-enrolled method (e.g. the INVO app
|
|
619
|
+
// device key) to authorize adding THIS passkey, then enroll. Without this, enrolling a second
|
|
620
|
+
// method is blocked with ENROLLMENT_REQUIRES_PROOF.
|
|
621
|
+
await client.linkDevice(linkId); // → { status: "authorized" }
|
|
622
|
+
await client.enrollPasskey();
|
|
623
|
+
```
|
|
624
|
+
|
|
625
|
+
**First-enrollment OTP grant.** For tenants that require it, the first `enrollPasskey()`
|
|
626
|
+
throws `ENROLLMENT_REQUIRES_AUTHORIZATION`. Send a one-time code (to the player's phone +
|
|
627
|
+
email on file), verify it, then **retry the same `enrollPasskey()`** — the server-side
|
|
628
|
+
grant is consumed automatically:
|
|
629
|
+
|
|
630
|
+
```ts
|
|
631
|
+
try {
|
|
632
|
+
await client.enrollPasskey();
|
|
633
|
+
} catch (e) {
|
|
634
|
+
if (e instanceof InvoError && e.isEnrollmentAuthorizationRequired) {
|
|
635
|
+
await client.enrollmentBegin(); // → { status: "sent", channels: ["sms","email"] }
|
|
636
|
+
await client.enrollmentVerify(codeFromUser); // 6-digit OTP
|
|
637
|
+
await client.enrollPasskey(); // retry — grant auto-consumed
|
|
638
|
+
} else if (e instanceof InvoError && e.isEnrollmentProofRequired) {
|
|
639
|
+
await client.linkDevice(linkId); // a different method already exists
|
|
640
|
+
await client.enrollPasskey();
|
|
641
|
+
} else throw e;
|
|
642
|
+
}
|
|
643
|
+
```
|
|
644
|
+
|
|
645
|
+
### Lost or replaced passkey (recovery)
|
|
646
|
+
|
|
647
|
+
Deleting a passkey on the device **never tells the server the key is gone**, so the next
|
|
648
|
+
`enrollPasskey()` is blocked by the anti-takeover gate with `ENROLLMENT_REQUIRES_PROOF` —
|
|
649
|
+
and the player has nothing left to prove possession with. Offer a **"Lost or replaced your
|
|
650
|
+
passkey?"** action that runs the possession-proofed recovery flow:
|
|
651
|
+
|
|
652
|
+
```ts
|
|
653
|
+
try {
|
|
654
|
+
await client.enrollPasskey();
|
|
655
|
+
} catch (e) {
|
|
656
|
+
if (e instanceof InvoError && e.isEnrollmentProofRequired) {
|
|
657
|
+
// Player still HAS the other method → linkDevice (above). Lost/deleted it → recover:
|
|
658
|
+
await client.recoveryBegin(); // → { status:"sent", channels:["sms","email"] }
|
|
659
|
+
await client.recoveryComplete(codeFromUser); // → { status:"recovered", deactivatedCount }
|
|
660
|
+
await client.enrollPasskey(); // same call — now succeeds
|
|
661
|
+
} else throw e;
|
|
662
|
+
}
|
|
663
|
+
```
|
|
664
|
+
|
|
665
|
+
- `recoveryBegin()` errors: `no_channel_on_file` (422), `rate_limited` (429 — max 5 codes / 10 min).
|
|
666
|
+
- `recoveryComplete(code)` errors: `ENROLLMENT_CODE_INVALID` (wrong/expired, attempt-capped — let the user retry or resend), `RECOVERY_FAILED` (500, transient).
|
|
667
|
+
- A recovery also sends the owner an out-of-band "your passkey was reset" SMS/email — that's the intended tamper alert; surface nothing special.
|
|
668
|
+
- If the **OS fails to save** a new passkey ("there is a problem saving your passkey"), have the user delete the stale entry in their password manager first (iPhone: Settings → Passwords; Android: Google Password Manager; Windows: Settings → Accounts → Passkeys).
|
|
669
|
+
|
|
670
|
+
> ⚠️ **24-hour money cooldown after recovery.** A recovery-enrolled passkey logs in and
|
|
671
|
+
> **collects funds immediately**, but `approveSend`/`approveTransfer` return **403
|
|
672
|
+
> `PASSKEY_RECOVERY_COOLDOWN`** for 24 hours (SIM-swap protection). Branch on
|
|
673
|
+
> `err.isPasskeyRecoveryCooldown` and show — *"For your security, transfers are paused for
|
|
674
|
+
> 24 hours after a passkey reset. You can still receive funds. Try again after
|
|
675
|
+
> `err.retryAfterAt`."* — do **not** treat it as a generic failure or retry-loop it.
|
|
676
|
+
> Unaffected: login, `getPendingCollect`, inbound `confirmReceipt*`.
|
|
677
|
+
|
|
678
|
+
- **User verification is required** on every approve/claim (a missing-UV assertion fails closed).
|
|
679
|
+
- Challenges are single-use and bound to `{flow}:{transactionId}`.
|
|
680
|
+
- The SDK passes the backend's WebAuthn options through unchanged (it does not hard-code `pubKeyCredParams`/`timeout`/`attestation`).
|
|
681
|
+
|
|
682
|
+
---
|
|
683
|
+
|
|
684
|
+
## Webhooks
|
|
685
|
+
|
|
686
|
+
The synchronous responses are for UX; **reconcile and grant value off webhooks.** They're HMAC-signed; **dedupe on the `X-Invo-Idempotency-Key` header** (stable across retries/replays — *not* `X-Invo-Event-Id`, which changes per delivery).
|
|
687
|
+
|
|
688
|
+
### Verify a webhook (server)
|
|
689
|
+
|
|
690
|
+
The SDK ships the signature check so you don't hand-roll HMAC. Pass the **raw** request bytes (never a re-serialized object) and the `X-Invo-Signature` header:
|
|
691
|
+
|
|
692
|
+
```ts
|
|
693
|
+
import { verifyWebhook, InvoError } from "@invonetwork/web-sdk/server";
|
|
694
|
+
|
|
695
|
+
// e.g. Express: app.post("/invo/webhooks", express.raw({ type: "application/json" }), handler)
|
|
696
|
+
function handler(req, res) {
|
|
697
|
+
let event;
|
|
698
|
+
try {
|
|
699
|
+
event = verifyWebhook(req.body, req.get("X-Invo-Signature"), process.env.INVO_WEBHOOK_SECRET!);
|
|
700
|
+
} catch (e) {
|
|
701
|
+
return res.status(400).send((e as InvoError).code); // bad signature / stale / malformed
|
|
702
|
+
}
|
|
703
|
+
if (alreadyProcessed(req.get("X-Invo-Idempotency-Key"))) return res.status(200).end(); // dedupe
|
|
704
|
+
|
|
705
|
+
switch (event.event_type) {
|
|
706
|
+
case "purchase.completed": grantCurrency(event.data); break; // event.data is typed
|
|
707
|
+
case "item.purchased": grantItem(event.data); break;
|
|
708
|
+
// transfer.* , payout.status_changed , …
|
|
709
|
+
}
|
|
710
|
+
res.status(200).end(); // 2xx fast; offload slow work
|
|
711
|
+
}
|
|
712
|
+
```
|
|
713
|
+
|
|
714
|
+
`verifyWebhook` does constant-time HMAC-SHA256 over `${t}.${rawBody}`, enforces a 5-minute replay window, and accepts an **array of secrets** during rotation (`verifyWebhook(body, sig, [oldSecret, newSecret])`). It returns a typed `InvoWebhookEvent` (discriminate on `event_type`) and throws `InvoError` (`WEBHOOK_SIGNATURE_INVALID` / `WEBHOOK_TIMESTAMP_EXPIRED` / `WEBHOOK_MALFORMED` / `WEBHOOK_SECRET_MISSING`) on any failure. **De-dupe yourself on `X-Invo-Idempotency-Key`** — the SDK verifies, it doesn't track delivery.
|
|
715
|
+
|
|
716
|
+
**Edge / serverless** (Cloudflare Workers, Deno, Vercel/Netlify Edge, Bun): `verifyWebhook` uses `node:crypto`, so use **`verifyWebhookAsync`** (Web Crypto) — same args/result, just `await` it — or the ready-made Fetch-API handler:
|
|
717
|
+
|
|
718
|
+
```ts
|
|
719
|
+
import { createWebhookHandler } from "@invonetwork/web-sdk/server";
|
|
720
|
+
|
|
721
|
+
// Next.js App Router — app/invo/webhooks/route.ts
|
|
722
|
+
export const POST = createWebhookHandler({
|
|
723
|
+
secret: process.env.INVO_WEBHOOK_SECRET!,
|
|
724
|
+
onEvent: async (event, { idempotencyKey }) => {
|
|
725
|
+
// de-dupe on idempotencyKey, then grant value. Throw to return 500 (Invo retries).
|
|
726
|
+
},
|
|
727
|
+
});
|
|
728
|
+
```
|
|
729
|
+
|
|
730
|
+
`createWebhookHandler` returns `(request: Request) => Promise<Response>` and runs in Next.js, Workers, Deno, Hono, and Bun. Bad signature → `400`; a throwing `onEvent` → `500`.
|
|
731
|
+
|
|
732
|
+
### Event types
|
|
733
|
+
|
|
734
|
+
| Event | Fires for | Use it to |
|
|
735
|
+
|---|---|---|
|
|
736
|
+
| `purchase.completed` | every currency-purchase rail | 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`). |
|
|
737
|
+
| `purchase.failed` / `purchase.disputed` | `platform` rail only | handle failures/disputes |
|
|
738
|
+
| `purchase.refunded` | `game` / `steam` rails | handle refunds |
|
|
739
|
+
| `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`) |
|
|
740
|
+
| `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`) |
|
|
741
|
+
| `platform_commerce.refunded` | a Platform Commerce refund | handle the reversal (payload: `order_id, funding_source, player_email, refunded_amount, amount_unit, fee_retained`) |
|
|
742
|
+
|
|
743
|
+
Don't block waiting on `purchase.failed` for the `game`/`steam` rails — they only emit `completed`/`refunded`. Reconcile off `*.completed` + the status endpoints. For Platform Commerce **card** orders, fulfill on `platform_commerce.purchased`, not the browser confirmation.
|
|
744
|
+
|
|
745
|
+
---
|
|
746
|
+
|
|
747
|
+
## Resilience & observability
|
|
748
|
+
|
|
749
|
+
- **Automatic retries.** Transient failures — network errors/timeouts, `429` (honoring `retry_after`), and `5xx` — are retried with exponential backoff + jitter. Configure with `maxRetries` (default `2`, set `0` to disable) and `retryBaseDelayMs` (default `250`). Mutating calls carry idempotency keys, so retries are safe; set `maxRetries: 0` if you'd rather handle `429` abuse-throttles yourself.
|
|
750
|
+
- **Hooks.** Pass `hooks` to either client for tracing/metrics — all best-effort (a throwing hook never breaks a request):
|
|
751
|
+
|
|
752
|
+
```ts
|
|
753
|
+
new InvoServer({
|
|
754
|
+
/* … */,
|
|
755
|
+
hooks: {
|
|
756
|
+
onRequest: ({ method, url, attempt }) => {},
|
|
757
|
+
onResponse: ({ status, durationMs, requestId, attempt }) => {},
|
|
758
|
+
onError: ({ error, willRetry, attempt }) => {},
|
|
759
|
+
},
|
|
760
|
+
});
|
|
761
|
+
```
|
|
762
|
+
|
|
763
|
+
> Note: hook payloads include the request `url`, which for some calls embeds a player email (e.g. balance-by-email). Tokens and the game secret are sent as headers and are **never** passed to hooks — but redact the `url` if you log hook payloads.
|
|
764
|
+
|
|
765
|
+
- **Request ids.** `InvoError.requestId` carries the backend request id (from `x-invo-request-id` / `x-request-id`) — quote it in support tickets.
|
|
766
|
+
- **Cancellation.** Every method takes an optional `{ signal }` (an `AbortSignal`) as its last argument — `server.getPlayerBalance({ playerEmail }, { signal })`. Aborting throws `InvoError` with `.code === "ABORTED"`, and an aborted call is never retried.
|
|
767
|
+
|
|
768
|
+
---
|
|
769
|
+
|
|
770
|
+
## Errors
|
|
771
|
+
|
|
772
|
+
Every failure throws **`InvoError`** with:
|
|
773
|
+
- `.code` — stable machine code when present (some txn-state errors have none — branch on `.message` for those)
|
|
774
|
+
- `.status` — HTTP status (`0` for client-side validation and network errors)
|
|
775
|
+
- `.message` — human-readable
|
|
776
|
+
- `.body` — the raw parsed response
|
|
777
|
+
|
|
778
|
+
### `.status === 0` means "no HTTP response" — and nothing else
|
|
779
|
+
|
|
780
|
+
This is the single most important thing to get right when handling INVO errors, so it's worth stating precisely:
|
|
781
|
+
|
|
782
|
+
| `err.status` | What actually happened | What to tell the developer |
|
|
783
|
+
|---|---|---|
|
|
784
|
+
| `0` | **No HTTP response** — DNS failure, connection refused, TLS failure, timeout, or a client-side guard that ran before any network call | "couldn't reach INVO" |
|
|
785
|
+
| `4xx` | The API **answered**, with a precise refusal. `.code` and `.message` are populated | show `.message` — it says what to do |
|
|
786
|
+
| `5xx` | The API answered with a server fault | retry; escalate if it persists |
|
|
787
|
+
|
|
788
|
+
**The SDK never collapses a non-2xx into a transport error.** A `403` arrives as `status: 403` with `.code` and `.message` intact; only a genuine absence of a response produces `status: 0`. Both entry points and both SDKs behave this way, and it's covered by regression tests.
|
|
789
|
+
|
|
790
|
+
The failure mode to avoid is in **your** catch block:
|
|
791
|
+
|
|
792
|
+
```ts
|
|
793
|
+
// ✗ Loses everything the API told you. A 403 with a precise, actionable refusal
|
|
794
|
+
// renders as a network outage, and the developer debugs a 500 that never happened.
|
|
795
|
+
try { await server.initiateTransfer(input); }
|
|
796
|
+
catch (e) { showToast("Could not reach the server"); }
|
|
797
|
+
|
|
798
|
+
// ✓ Distinguish "no response" from "answered with a refusal".
|
|
799
|
+
try { await server.initiateTransfer(input); }
|
|
800
|
+
catch (e) {
|
|
801
|
+
if (!(e instanceof InvoError)) throw e;
|
|
802
|
+
if (e.status === 0) showToast("Couldn't reach INVO — check your connection.");
|
|
803
|
+
else showToast(e.message); // the API already wrote the actionable text
|
|
804
|
+
}
|
|
805
|
+
```
|
|
806
|
+
|
|
807
|
+
> This is not hypothetical. A developer once spent a debugging session hunting a 500 that didn't exist — the logs showed two clean `403`s carrying exact remediation steps, and a catch-all in the integration layer had rendered them as "could not reach the server."
|
|
808
|
+
|
|
809
|
+
### 409 is usually "not ready" or "already done", not a failure
|
|
810
|
+
|
|
811
|
+
INVO uses `409` for **retryable not-ready states**, not errors: a duplicate `clientRequestId`, an already-refunded order, an unverified domain. Branch on them (`.isDuplicateRequest`, `.isAlreadyRefunded`, `.isPhoneShareApprovalRequired`, `.isPhoneShareAlreadyApproved`) and treat them as "retry" or "already done" — surfacing them as red error states misrepresents what happened.
|
|
812
|
+
|
|
813
|
+
Helpers:
|
|
814
|
+
|
|
815
|
+
| Helper | Meaning |
|
|
816
|
+
|---|---|
|
|
817
|
+
| `.isTokenExpired` | player token expired — re-mint + retry (automatic if `refreshToken` is set) |
|
|
818
|
+
| `.isReceiverNotEnrolled` | recipient has no passkey → switch to claim-code entry |
|
|
819
|
+
| `.isInsufficientBalance` | item purchase failed (400); `required_amount` + `current_balance` on `.body` |
|
|
820
|
+
| `.isDuplicateRequest` | idempotency-keyed request was a duplicate (409) |
|
|
821
|
+
| `.isNotPlatformTenant` | Platform Commerce called by a non-platform tenant (403) — use `purchaseItem`/`createCheckout` instead |
|
|
822
|
+
| `.isAmountBelowMinimum` / `.isBelowCardMinimum` / `.isAboveCardMaximum` | Platform Commerce amount too small for the fee to round up / card charge under $0.50 / card charge over $999.99 (400) |
|
|
823
|
+
| `.isAlreadyRefunded` | Platform Commerce refund of an already-refunded order (409) — treat as already done |
|
|
824
|
+
| `.retryAfter` | seconds to back off on a 429 throttle |
|
|
825
|
+
| `.isEnrollmentAuthorizationRequired` | first-enrollment needs the OTP grant → `enrollmentBegin`/`enrollmentVerify` |
|
|
826
|
+
| `.isEnrollmentProofRequired` | another method exists → prove it via `linkDevice` |
|
|
827
|
+
| `.isPhoneShareApprovalRequired` | phone needs owner approval — at register/mint **or** at claim/`confirmReceipt*` (contested receiver phone) → show `.message` (+ `.phoneShareLast4`), retry the same call after approval |
|
|
828
|
+
| `.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) |
|
|
829
|
+
| `.isNonSteamValueIntoSteamBlocked` | initiate blocked (409): non-Steam value can't move into a Steam title → show `.message`, pick a non-Steam destination |
|
|
830
|
+
| `.isPhoneShareAlreadyApproved` | phone-share was already approved (e.g. from a `/reject`) |
|
|
831
|
+
| `.isSourceGameNotLive` | **(403)** the caller's OWN game is in testing → **self-serve**: switch it to Live in the console (Game Settings → Status). Show `.message`; `.gameStatus` has the current state |
|
|
832
|
+
| `.isTargetGameNotLive` | **(403)** the DESTINATION game is in testing → the caller usually **can't fix this** (someone else's game). Show `.message`; steer to another destination via `getDestinations`. Deliberately **distinct** from `.isSourceGameNotLive` — don't collapse them, the remediation differs |
|
|
833
|
+
| `.isWebauthnNotEnabledForTenant` | **(403)** tenant has no verified RP ID → **configuration state, not a failure**. Fall back to the SMS/in-app path; see [passkey prerequisites](#prerequisite-passkeys-are-dark-until-your-tenant-verifies-a-domain) |
|
|
834
|
+
|
|
835
|
+
Client-side guards (bad amount, missing idempotency key, `rail:"steam"` on `purchaseCurrency`, item validation) throw `InvoError` with `.status === 0` **before** any network call. Notable backend codes: `SDK_TOKEN_EXPIRED`, `TENANT_NOT_MIGRATED`, `WEBAUTHN_NOT_ENABLED_FOR_TENANT`, `WEBAUTHN_UV_REQUIRED`, `ENROLLMENT_REQUIRES_PROOF`, `ENROLLMENT_CODE_INVALID`, `PASSKEY_RECOVERY_COOLDOWN` (403, `retryAfterAt`), `no_channel_on_file`, `rate_limited`, `WRONG_RAIL_ENDPOINT`, `flow_paused`.
|
|
836
|
+
|
|
837
|
+
```ts
|
|
838
|
+
import { InvoError } from "@invonetwork/web-sdk"; // or "@invonetwork/web-sdk/server"
|
|
839
|
+
try {
|
|
840
|
+
await server.purchaseItem(/* … */);
|
|
841
|
+
} catch (e) {
|
|
842
|
+
if (e instanceof InvoError && e.isInsufficientBalance) {
|
|
843
|
+
showTopUp(e.body); // { required_amount, current_balance }
|
|
844
|
+
} else throw e;
|
|
845
|
+
}
|
|
846
|
+
```
|
|
847
|
+
|
|
848
|
+
---
|
|
849
|
+
|
|
850
|
+
## API reference
|
|
851
|
+
|
|
852
|
+
### `InvoServer` (`@invonetwork/web-sdk/server`)
|
|
853
|
+
|
|
854
|
+
| Method | Returns |
|
|
855
|
+
|---|---|
|
|
856
|
+
| `mintPlayerToken({ playerEmail, playerPhone? })` | `{ token, expiresAt, identityId }` — session mint for an **existing** player (404 if unknown); `playerPhone` optional/validated-if-present (see [Player token](#player-token-session-mint-for-an-existing-player)) |
|
|
857
|
+
| `initiateSend(input)` | `{ transactionId, verificationMethod, guardianApproval?, raw }` |
|
|
858
|
+
| `initiateTransfer(input)` | `{ transactionId, verificationMethod, guardianApproval?, raw }` |
|
|
859
|
+
| `createCheckout(input)` | `{ sessionId, checkoutUrl, expiresAt, expiresInSeconds, raw }` |
|
|
860
|
+
| `purchaseCurrency(input)` | `{ status, clientSecret?, paymentIntentId?, paymentUrl?, transactionId?, orderId?, newBalance?, raw }` |
|
|
861
|
+
| `confirmPayment({ paymentIntentId, orderId? })` | `{ status, transactionId?, newBalance?, raw }` |
|
|
862
|
+
| `getOrderDetails({ orderId? \| transactionId? })` | `{ order, financialSummary, statusTimeline, raw }` |
|
|
863
|
+
| `purchaseItem(input)` | `{ status, transactionId, orderId, newBalance, previousBalance, currencyName, financialBreakdown?, raw }` — **game** tenant spending game currency on an in-game item |
|
|
864
|
+
| `getItemPurchaseHistory({ playerEmail, limit?, offset? })` | `{ history, pagination, raw }` |
|
|
865
|
+
| `getItemOrderDetails({ orderId? \| transactionId? \| clientRequestId? })` | `{ order, financialSummary, statusTimeline, raw }` |
|
|
866
|
+
| `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` |
|
|
867
|
+
| `platformCommerce.getStatus(orderId)` | `{ orderId, status, gameCurrencyAmount?, usdAmount?, paymentMethod?, createdAt?, raw }` |
|
|
868
|
+
| `platformCommerce.refund({ orderId? \| clientRequestId?, reason? })` | `{ status, orderId?, fundingSource?, refundedAmount?, amountUnit?, feeRetained?, raw }` — pass **exactly one** id; INVO keeps its fee |
|
|
869
|
+
| `getPlayerBalance({ playerEmail })` | `{ player, balances, summary, raw }` — **by email only** (no by-id route; use `InvoClient.getBalance()` client-side) |
|
|
870
|
+
| `getInboundPending({ playerEmail? \| playerPhone? })` | `{ inboundPending, raw }` — live unclaimed inbound sends/transfers |
|
|
871
|
+
| `getLinkedIdentities({ playerEmail? \| playerPhone? })` | `{ walletUserId, primaryEmail, primaryPhone, isMinor, emails, notFound, raw }` — **server-only** (returns PII) |
|
|
872
|
+
| ~~`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. |
|
|
873
|
+
| `claimTransfer(input)` / `claimCurrency(input)` | `ClaimResult` — redeem a claim code (`needsAccountSelection` + `candidates` on a multi-account phone) |
|
|
874
|
+
| `getTransferStatus(txnId)` / `getSendStatus(txnId)` | `TransactionStatusResult` — poll outbound state (`verificationState`) |
|
|
875
|
+
| `getGuardianApprovalStatus(txnId)` | `GuardianApprovalStatusResult` — poll a guardian hold to resolution (`state`) |
|
|
876
|
+
| `getDestinations({ sourceGameId, direction? })` | `DestinationsResult` — server-side (game-secret) destinations; same rows as the browser variant |
|
|
877
|
+
| `phoneShareInitiate({ phone, email })` / `phoneShareApprove({ approvalId, otp })` / `phoneShareStatus({ phone, email })` | phone-share OTP handshake (unauthenticated) to resolve a `PHONE_SHARE_APPROVAL_REQUIRED` (409); then re-issue the original request |
|
|
878
|
+
| `iterateItemPurchaseHistory({ playerEmail, pageSize? })` | async iterator over all history rows |
|
|
879
|
+
| `verifyWebhook(rawBody, signatureHeader, secret \| secrets, opts?)` | typed `InvoWebhookEvent` (throws on bad signature) |
|
|
880
|
+
| `verifyWebhookAsync(...)` | same as `verifyWebhook`, Web Crypto (edge/Workers/Deno/Bun) |
|
|
881
|
+
| `createWebhookHandler({ secret, onEvent })` | `(Request) => Promise<Response>` webhook route handler |
|
|
882
|
+
|
|
883
|
+
Every method also accepts an optional final `{ signal }` (`AbortSignal`) for cancellation.
|
|
884
|
+
|
|
885
|
+
### `InvoClient` (`@invonetwork/web-sdk`)
|
|
886
|
+
|
|
887
|
+
| Method | Returns |
|
|
888
|
+
|---|---|
|
|
889
|
+
| `enrollPasskey()` | `{ status, device, raw }` |
|
|
890
|
+
| `enrollmentBegin()` / `enrollmentVerify(code)` | OTP grant for `ENROLLMENT_REQUIRES_AUTHORIZATION` (then retry `enrollPasskey`) |
|
|
891
|
+
| `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`) |
|
|
892
|
+
| `approveSend(txnId)` / `approveTransfer(txnId)` | `{ status, next, transactionId, claimCode?, claimCodeExpiresAt?, holdReason?, risk?, guardianApproval?, pollEndpoint?, raw }` |
|
|
893
|
+
| `confirmReceiptSend(txnId)` / `confirmReceiptTransfer(txnId)` | `{ status, holdReason?, raw }` |
|
|
894
|
+
| `linkDevice(linkId)` | `{ status, raw }` |
|
|
895
|
+
| `getPendingCollect()` | `{ pending, raw }` — the player's own pending-to-collect list (player-token) |
|
|
896
|
+
| `getDestinations({ direction? })` | `{ availableGames, sourceGameName, transferMode, … }` — where the player can send/transfer, metadata inline |
|
|
897
|
+
| `getBalance()` | `{ gameId, gameName, balances, totalValue, currencyCount, hasFunds, raw }` — the player's balances for this game |
|
|
898
|
+
| `platformCommerce.mountCheckout(el, checkoutUrl, { onComplete? })` | `{ iframe, destroy() }` — optional embed of INVO's hosted checkout (or just `location.href = checkoutUrl`); `onComplete` fires on the page's origin-checked `INVO_CHECKOUT_COMPLETE` message |
|
|
899
|
+
|
|
900
|
+
Every method throws `InvoError` on failure and takes an optional final `{ signal }`. Full inline types ship with the package. The Platform Commerce card leg needs **no keys and no payment code in the browser** — INVO's hosted page owns the card form.
|
|
901
|
+
|
|
902
|
+
---
|
|
903
|
+
|
|
904
|
+
## Scripts & versioning
|
|
905
|
+
|
|
906
|
+
```bash
|
|
907
|
+
npm run build # tsup → dist (ESM + CJS + d.ts)
|
|
908
|
+
npm run typecheck # tsc --noEmit
|
|
909
|
+
npm test # vitest
|
|
910
|
+
```
|
|
911
|
+
|
|
912
|
+
### Stability
|
|
913
|
+
|
|
914
|
+
Since **`1.0.0`** the public API is **stable**: it follows [semver](https://semver.org/), and **no breaking change ships without a major version bump + a migration note**. Patch = fixes, minor = additive surface (new methods/fields, backward-compatible — e.g. `2.1.0`'s passkey recovery, `2.4.0`'s Steam-policy classifiers), major = breaking changes (rare — two to date: `2.0.0` required `playerPhone` at the token mint, which `2.2.0` later relaxed back to optional, and `3.0.0` replaced the Platform Commerce card-element surface with INVO's hosted checkout). Deprecations get a documentation-only notice in a minor release first — `verifySmsTransfer`/`verifySmsSend` are deprecated as of `3.1.0` and keep working until a future major removes them. The wire contract is the same live INVO API you'd call directly, and it's backward-compatible within a major — so a pinned SDK keeps working. Safe to depend on in production; pin a version and watch [releases](https://github.com/Invo-Technologies/invo-web-sdk/releases) for security updates.
|
|
915
|
+
|
|
916
|
+
Full history: [CHANGELOG](https://github.com/Invo-Technologies/invo-web-sdk/blob/main/CHANGELOG.md) · [release notes](https://github.com/Invo-Technologies/invo-web-sdk/blob/main/docs/RELEASES.md) (absolute links to `main`).
|
|
917
|
+
|
|
918
|
+
## License
|
|
919
|
+
|
|
920
|
+
Proprietary — © Invo Tech Inc. See [`LICENSE`](LICENSE).
|