@invonetwork/web-sdk 3.5.0 → 3.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +194 -14
- package/README.md +619 -60
- package/dist/{chunk-MBKE6ULW.js → chunk-23TGMTII.js} +90 -3
- package/dist/index.cjs +760 -20
- package/dist/index.d.cts +135 -3
- package/dist/index.d.ts +135 -3
- package/dist/index.js +674 -21
- package/dist/server.cjs +508 -1
- package/dist/server.d.cts +109 -3
- package/dist/server.d.ts +109 -3
- package/dist/server.js +422 -2
- package/dist/{types-Dxo3IsYq.d.cts → types-CspPkmK9.d.cts} +265 -11
- package/dist/{types-Dxo3IsYq.d.ts → types-CspPkmK9.d.ts} +265 -11
- package/package.json +2 -1
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
First-party TypeScript SDK for integrating **INVO** into partner **web** platforms (storefronts, web games, dashboards). It wraps INVO's web money flows behind a typed, versioned API — the web analog of the Unity/Unreal plugins.
|
|
4
4
|
|
|
5
|
-
> **Status:** `v3.
|
|
5
|
+
> **Status:** `v3.7.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.7.0** makes the **device approval grant a first-class SDK surface** — `beginDeviceApproval`, `pollDeviceApproval`, `confirmDeviceEnrollment` and, the step that actually moves the money, **`approveWithDeviceCode`** (plus the optional `completeDeviceApproval` loop); a grant that is polled to `approved` and left there settles **nothing**, which is the failure this release exists to make impossible, and `TRANSACTION_NOT_PENDING` now comes back as a typed `status: "not_pending"` result with `alreadySettled` rather than a thrown error you would have to string-match; **3.4.0** documents that a Steam title now bills through **its own Steam application** — the studio registers their appid + publisher Web API key and keeps a payment method on file, because Valve pays the studio and INVO settles afterwards (new `isSteamNotConfigured`, `isPartnerBillingNotSetUp`, `isPartnerSettlementUnavailable`, `isSteamAppChanged` error helpers); **3.2.3** corrects the base path and auth header in the Steam snippets (`/api/currency-purchases`, `X-Game-Secret-Key`) — 3.2.2 published both wrong, and copying them returned a 404; **3.2.x** documents **Steam currency purchases on a pack model** — INVO owns the catalogue, you pass a `pack_id` and never a price, and the currency inside a pack varies by country because Steam prices are VAT-inclusive; **3.1.0** makes the authentication guidance explicit — **[passkeys are the gold standard](#passkeys-are-the-gold-standard-dont-build-on-sms)** and the SMS-PIN completion (`verifySmsTransfer`/`verifySmsSend`) is **deprecated and being phased out** (documentation only — no behavior change, no runtime warnings); **3.0.0** moves the Platform Commerce card leg to **INVO's hosted checkout** — the server `purchase()` now returns a `checkoutUrl` and the browser just sends the buyer there (redirect or `mountCheckout` iframe); the 2.5.x card-element surface (`confirmCardPayment`/`mountCardPayment`, `billingAddress`, `commercePublishableKey`) is **removed** — see the [CHANGELOG](CHANGELOG.md) migration note; **2.5.0** added **Platform Commerce** (ecommerce) — a platform tenant selling items funded by balance **or** card, with `invo.platformCommerce.purchase/getStatus/refund` (server) and the `platform_commerce.*` webhooks; **2.4.0** adds Steam transfer-policy handling (`isSteamValueNonTransferable`/`isNonSteamValueIntoSteamBlocked` + `DestinationGame.acceptsSteamOriginValue`); **2.3.0** surfaces the claim-time phone-share `409` on `confirmReceipt*`/`claim*` (+ `err.phoneShareLast4`). Full history in the [CHANGELOG](CHANGELOG.md).
|
|
6
6
|
> Canonical partner reference: **https://docs.invo.network/docs/currency-purchase** and **https://docs.invo.network/docs/game-developer-integration**.
|
|
7
7
|
|
|
8
8
|
## What it does
|
|
@@ -35,31 +35,33 @@ So:
|
|
|
35
35
|
|---|---|---|
|
|
36
36
|
| Sender approves a send/transfer | `client.enrollPasskey()` once, then `client.approveSend` / `approveTransfer` | a PIN pad as the default flow |
|
|
37
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 |
|
|
38
|
+
| Recipient collects | `client.confirmReceiptSend` / `confirmReceiptTransfer` (passkey), or the QR flow with `flow: "send_receipt"` / `"transfer_receipt"` | claim code as the primary path |
|
|
39
|
+
| Console / TV / native client | the QR device-approval grant, **then `server.approveWithDeviceCode`** | polling to `approved` and stopping — that settles nothing |
|
|
39
40
|
|
|
40
|
-
### Prerequisite:
|
|
41
|
+
### Prerequisite: which passkey path serves your tenant
|
|
41
42
|
|
|
42
|
-
**Read this before you wire up `enrollPasskey()`.**
|
|
43
|
+
**Read this before you wire up `enrollPasskey()`.** There are two places a passkey ceremony can run, and which one serves your title is decided by whether you hold a partner passkey domain:
|
|
43
44
|
|
|
44
|
-
**
|
|
45
|
+
- **No partner domain (every new title):** INVO runs the ceremony **on its own domain** — the hosted approval page — for every platform. There is **no domain to verify and nothing to configure**; submitting one is refused (`409 PARTNER_RP_FROZEN`). On the web the path is [`approveHosted()`](#web-games--approving-on-invos-hosted-page); on consoles it is the QR flow; on iOS/Android the mobile plugins open the same page. The in-app `enrollPasskey()` / `approveSend` / `approveTransfer` calls return `403 WEBAUTHN_NOT_ENABLED_FOR_TENANT` for you — that is the **expected state, not a setup gap** (the body's `hosted_flow` says so and points at `device_code`).
|
|
46
|
+
- **A domain verified before the freeze (existing tenants):** your passkeys are bound to that RP ID for life, so `enrollPasskey()` and the in-app approves keep working exactly as documented below. You may still change or re-verify the domain. Removing it is **irreversible** — it can never be re-added, and the hosted flow serves the game from then on.
|
|
45
47
|
|
|
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;
|
|
48
|
+
`WEBAUTHN_NOT_ENABLED_FOR_TENANT` is **configuration state, not an error** — the in-app ceremony was never available to fail. Don't show the player a failure; use the hosted page:
|
|
47
49
|
|
|
48
50
|
```ts
|
|
49
51
|
try {
|
|
50
52
|
await client.enrollPasskey();
|
|
51
53
|
} catch (e) {
|
|
52
54
|
if (e instanceof InvoError && e.isWebauthnNotEnabledForTenant) {
|
|
53
|
-
// Not a failure — this tenant
|
|
54
|
-
//
|
|
55
|
-
|
|
55
|
+
// Not a failure — this tenant has no partner passkey domain, which is now the norm.
|
|
56
|
+
// Approve on INVO's hosted page instead (nothing to configure):
|
|
57
|
+
await client.approveHosted({ transactionId, flow: "transfer" });
|
|
56
58
|
} else throw e;
|
|
57
59
|
}
|
|
58
60
|
```
|
|
59
61
|
|
|
60
|
-
So the honest sequence is: **
|
|
62
|
+
So the honest sequence is: **start the transfer → `approveHosted()` (or the in-app approve if you hold a domain) → you're on the gold-standard path.** The SMS PIN is what carries a player who cannot or will not enrol — which is exactly why the deprecation below has no removal date attached.
|
|
61
63
|
|
|
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 **
|
|
64
|
+
> ⚠️ **`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 **players who will not use the hosted page** (see above). Just don't make it the road everyone walks down once passkeys are available to you.
|
|
63
65
|
|
|
64
66
|
**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
67
|
|
|
@@ -69,6 +71,20 @@ So the honest sequence is: **verify your domain → enroll passkeys → you're o
|
|
|
69
71
|
|
|
70
72
|
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
73
|
|
|
74
|
+
### Which method fits which platform
|
|
75
|
+
|
|
76
|
+
The right approval method is a property of the **client the player is sitting in front of**, not of your title. Pick it per platform:
|
|
77
|
+
|
|
78
|
+
| Where the player is | Approve with | Why |
|
|
79
|
+
|---|---|---|
|
|
80
|
+
| Mobile app & mobile web (iOS 16+ / Android 9+) | **a passkey, directly** | the platform authenticator (Face ID / Touch ID / fingerprint) is available in-client — strongest option, zero messaging cost |
|
|
81
|
+
| Desktop web (browser) | **a passkey, directly** | Touch ID / Windows Hello are available to the browser |
|
|
82
|
+
| Web, player has no in-app passkey yet | **INVO's hosted page in a popup** ([`approveHosted`](#web-games--approving-on-invos-hosted-page), below) | the same page a console scans, opened by the SDK from the browser; the player enrols an INVO passkey on INVO's own domain and the SDK polls and approves — one call, nothing new on your server |
|
|
83
|
+
| Consoles (PlayStation / Xbox / Switch) | **the QR device-approval flow** ([RFC 8628](#consoles-and-tvs--approving-without-a-browser-rfc-8628), below) | no browser and no WebAuthn in-client — show the QR, the player scans it and completes the passkey on their phone, your server polls, and **your server then calls `approveWithDeviceCode`** — the poll proves who, that call moves the money |
|
|
84
|
+
| Native Steam / desktop game clients (Mac & Windows) | **the QR device-approval flow** ([RFC 8628](#consoles-and-tvs--approving-without-a-browser-rfc-8628), below) | the OS supports passkeys, but the embedded game client can't invoke the platform authenticator from inside the engine — it is the **client**, not the OS, that forces QR here |
|
|
85
|
+
|
|
86
|
+
**When there is no passkey path at all** — a remote approval that can't run a ceremony (a guardian, a phone's existing owner) — INVO goes **email first, SMS on request**: a signed link to a hosted page to the oldest verified address, and a text only when there is no verified email, the email could not be delivered, or the player asks for one. SMS is the last resort, not the primary channel.
|
|
87
|
+
|
|
72
88
|
## Contents
|
|
73
89
|
|
|
74
90
|
- [Passkeys are the gold standard — don't build on SMS](#passkeys-are-the-gold-standard--dont-build-on-sms)
|
|
@@ -81,7 +97,14 @@ Beyond security, this is also an economics story: SMS costs real money per messa
|
|
|
81
97
|
- [Platform Commerce (ecommerce)](#platform-commerce-ecommerce)
|
|
82
98
|
- [Player balance](#player-balance)
|
|
83
99
|
- [Sends & transfers (move currency between players)](#sends--transfers-move-currency-between-players)
|
|
100
|
+
- [Legacy fallback: the SMS PIN (being retired)](#legacy-fallback-the-sms-pin-being-retired)
|
|
101
|
+
- [Sends and transfers, stage by stage](#sends-and-transfers-stage-by-stage)
|
|
102
|
+
- [What your server must call, in order](#what-your-server-must-call-in-order)
|
|
103
|
+
- [Errors on the money path](#errors-on-the-money-path)
|
|
104
|
+
- [Common mistakes](#common-mistakes)
|
|
84
105
|
- [Passkeys (enroll, approve, link, recover)](#passkeys-enroll-approve-link-recover)
|
|
106
|
+
- [Web games — approving on INVO's hosted page](#web-games--approving-on-invos-hosted-page)
|
|
107
|
+
- [Consoles and TVs — approving without a browser (RFC 8628)](#consoles-and-tvs--approving-without-a-browser-rfc-8628)
|
|
85
108
|
- [Webhooks](#webhooks)
|
|
86
109
|
- [Resilience & observability](#resilience--observability)
|
|
87
110
|
- [Errors](#errors)
|
|
@@ -209,7 +232,7 @@ INVO enables each flow for your tenant in the [console](#get-your-account--game-
|
|
|
209
232
|
- **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
233
|
- **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
234
|
- **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):**
|
|
235
|
+
- **For passkeys (sends/transfers):** nothing to configure — new titles approve on INVO's hosted page ([`approveHosted()`](#web-games--approving-on-invos-hosted-page)); there is no partner domain to verify. Only a tenant that verified an **RP ID + web origin(s)** before the freeze uses the in-app `enrollPasskey()` / `approveSend` path, and those passkeys only validate on the approved origins. **Wire the approve step 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
236
|
- **For currency purchase:** card checkout works out of the box; ask INVO to enable the `game`/`steam` rails if you need them. **The `steam` rail additionally requires the studio to register their own Steam app id + publisher Web API key and put a payment method on file** — see [Steam purchases](#steam-purchases-packs-not-prices).
|
|
214
237
|
- **For item purchase:** nothing extra — it's a currency-balance debit.
|
|
215
238
|
|
|
@@ -592,7 +615,16 @@ comes from the token, no PII).
|
|
|
592
615
|
|
|
593
616
|
## Sends & transfers (move currency between players)
|
|
594
617
|
|
|
595
|
-
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).
|
|
618
|
+
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).
|
|
619
|
+
|
|
620
|
+
**There are exactly two approval paths, and both are passkeys:**
|
|
621
|
+
|
|
622
|
+
- **In-app passkey** — wherever WebAuthn can run in the client: a browser, or a web game on INVO's [hosted approval page](#web-games--approving-on-invos-hosted-page). `approveSend` / `approveTransfer` / `approveHosted`.
|
|
623
|
+
- **Device approval (QR)** — wherever it cannot: consoles, TVs, native Steam and desktop clients. The player approves on their phone; **your server then makes the call that moves the money**. See [Consoles and TVs](#consoles-and-tvs--approving-without-a-browser-rfc-8628) and [Sends and transfers, stage by stage](#sends-and-transfers-stage-by-stage).
|
|
624
|
+
|
|
625
|
+
A legacy SMS-PIN fallback still exists for a sender who cannot use either — it is [being retired](#legacy-fallback-the-sms-pin-being-retired) and new integrations should not build on it.
|
|
626
|
+
|
|
627
|
+
**Send** and **transfer** are parallel flows:
|
|
596
628
|
|
|
597
629
|
| | Send | Transfer |
|
|
598
630
|
|---|---|---|
|
|
@@ -627,14 +659,17 @@ const t = await server.initiateTransfer({
|
|
|
627
659
|
|
|
628
660
|
// Check guardianApproval FIRST — the guardian path takes precedence.
|
|
629
661
|
switch (true) {
|
|
630
|
-
case !!t.guardianApproval: // minor/guardian path (HTTP 202) →
|
|
631
|
-
|
|
632
|
-
case t.verificationMethod === "
|
|
633
|
-
|
|
662
|
+
case !!t.guardianApproval: // minor/guardian path (HTTP 202) → a guardian is emailed a
|
|
663
|
+
// signed approve/decline link; poll, show no approval UI.
|
|
664
|
+
case t.verificationMethod === "in_app": // sender HAS a passkey → approve in the client. The good path.
|
|
665
|
+
default: // sender has NO passkey yet → enrol one (enrollPasskey() or
|
|
666
|
+
// approveHosted()), or run the QR flow on a console.
|
|
634
667
|
}
|
|
635
668
|
|
|
636
669
|
// 2. BROWSER — the sender approves with their passkey (give them t.transactionId + the player token)
|
|
637
670
|
const approved = await client.approveTransfer(t.transactionId); // or approveSend(...)
|
|
671
|
+
// On a console / TV / native client there is no browser: run the device approval grant
|
|
672
|
+
// instead — begin → show QR → poll → approveWithDeviceCode. See "stage by stage".
|
|
638
673
|
// approved.claimCode + approved.claimCodeExpiresAt (transfer only) — deliver if the recipient can't self-claim
|
|
639
674
|
|
|
640
675
|
// 3. BROWSER — the recipient claims with their passkey; fall back to the claim code if not enrolled
|
|
@@ -651,14 +686,57 @@ try {
|
|
|
651
686
|
}
|
|
652
687
|
```
|
|
653
688
|
|
|
654
|
-
- **`verificationMethod`** (from initiate): `"in_app"` → the sender has a passkey, go approve
|
|
689
|
+
- **`verificationMethod`** (from initiate): `"in_app"` → the sender has a passkey, go approve — the path you want. `"sms"` → read it as **"this sender has no passkey yet"**: offer enrollment (`enrollPasskey()`, or `approveHosted()` where you hold no verified domain), or run the [device approval grant](#consoles-and-tvs--approving-without-a-browser-rfc-8628) on a console. `undefined` + `guardianApproval` → minor/guardian (HTTP 202), show no approval 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.
|
|
655
690
|
- **Claim codes** are returned only by `approveTransfer`; they're the out-of-band fallback when the recipient isn't enrolled.
|
|
656
691
|
- **`err.isReceiverNotEnrolled`** on `confirmReceipt*` is the explicit signal to switch to claim-code entry.
|
|
692
|
+
- **The one message that is still a text: the claim link to a phone-only recipient.** A
|
|
693
|
+
send can be addressed to someone INVO has never met — the sender knows their phone number
|
|
694
|
+
and nothing else, so there is no email to write to and no session to notify. That is the
|
|
695
|
+
only remaining place INVO sends an SMS by default; everything else that needs a human
|
|
696
|
+
(guardian consent, enrolment backup, phone-share) goes by **email first**. The claim text a send's receiver gets
|
|
697
|
+
now ends with a link to a hosted INVO page ("Or collect here: …"). They see who sent what in
|
|
698
|
+
which game, enter **one email** (the same thing in-game claim already requires), confirm it
|
|
699
|
+
with an emailed 6-digit code, and their phone's fingerprint / face / screen lock creates an
|
|
700
|
+
INVO passkey — a recipient who already has one just confirms with it. The currency lands in
|
|
701
|
+
their balance for the receiving game; the page shows the new balance and tells them to sign
|
|
702
|
+
in to the game with that email + phone. In-game claim (`claimCurrency` / `confirmReceiptSend`)
|
|
703
|
+
is unchanged — point a player at the link when they don't have the game open, at in-game
|
|
704
|
+
claim when they do; both are the same claim with one lifetime. `transfer.received` fires
|
|
705
|
+
the same either way, and you change nothing.
|
|
706
|
+
- **Resend the claim SMS — a REST call, not an SDK method.**
|
|
707
|
+
`POST /api/sdk/send/{transactionId}/resend-claim` with the **sender's** player token, no
|
|
708
|
+
body. It re-sends the identical message (same code, same link); nothing new is minted.
|
|
709
|
+
30-second cooldown (`429 RESEND_COOLDOWN` + `retry_after`), at most 10 per transaction per
|
|
710
|
+
hour; `400 CLAIM_EXPIRED` / `NOT_CLAIMABLE` once the send can no longer be claimed; `403`
|
|
711
|
+
for anyone but the sender. `200 { status: "resent", transaction_id, retry_after }`.
|
|
712
|
+
- **Uncollected after 24 hours → refunded, and both parties are told.** The refund to the
|
|
713
|
+
sender is as before; what's new is that the sender gets an email and the recipient a single
|
|
714
|
+
text saying the currency was returned, instead of silence. `transfer.claim_expired` +
|
|
715
|
+
`transfer.refunded` remain the source of truth — reconcile off those, not the messages.
|
|
657
716
|
- **`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.
|
|
658
717
|
- **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.
|
|
659
718
|
- **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.
|
|
660
719
|
- Transfer self-claim may be disabled for your tenant; if it is, surface the claim-code path instead.
|
|
661
720
|
- **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`).
|
|
721
|
+
- **Guardian approval goes by email first.** When a minor's initiate returns the 202, the guardian gets a
|
|
722
|
+
signed, single-use link to a hosted INVO page with Approve / Decline — not a text. A reply-YES text goes
|
|
723
|
+
out only when the guardian has no verified email or the email could not be delivered. The raw 202
|
|
724
|
+
`guardian_approval` block (`t.raw`) now carries **`consent_channel`** (`"email"` | `"sms"`) — use it for
|
|
725
|
+
your waiting copy — and **`resend_endpoint`**. Poll `getGuardianApprovalStatus` exactly as before; the
|
|
726
|
+
approval object's `consent_channel` says how it went out and `decision_source` is `email_link` for a
|
|
727
|
+
page decision.
|
|
728
|
+
- **"Text my parent instead" — a REST call, not an SDK method.** `POST /api/sdk/approvals/guardian/{approvalId}/resend`
|
|
729
|
+
with the **minor's** player token (the session that started the transaction) and body `{ "channel": "sms" }`
|
|
730
|
+
— the only accepted value. Once per approval. `200 { status: "sent", channel: "sms" }`; `403 NOT_INITIATOR`;
|
|
731
|
+
`409 CHANNEL_WAS_SMS` (it already went by text — hide the button when `consent_channel` is `"sms"`);
|
|
732
|
+
`409 ALREADY_RESENT`; `410 APPROVAL_GONE` (decided or expired); `503 DELIVERY_FAILED` (retryable — does not
|
|
733
|
+
use up the one allowance). The emailed link keeps working alongside the text.
|
|
734
|
+
- **Phone-share and recipient-identity consents use the same hosted page.** On `err.isPhoneShareApprovalRequired`
|
|
735
|
+
the phone's existing owner gets an emailed link (Allow / Decline) when INVO has itself proven an address for
|
|
736
|
+
them — at most three holders, one email per request — and the 409 body carries `consent_channel: "email"`;
|
|
737
|
+
the OTP text goes out instead only when no proven holder exists (`consent_channel: "sms"`). The
|
|
738
|
+
`RECIPIENT_IDENTITY_PENDING` hold emails the phone owner's oldest verified address the same way. **Nothing
|
|
739
|
+
changes for you:** same 409 / 202 codes, same poll-and-retry, and the typed-code and in-app approves still work.
|
|
662
740
|
|
|
663
741
|
**"You have X to collect"**
|
|
664
742
|
|
|
@@ -668,6 +746,186 @@ try {
|
|
|
668
746
|
> **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).
|
|
669
747
|
- **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).
|
|
670
748
|
|
|
749
|
+
### Legacy fallback: the SMS PIN (being retired)
|
|
750
|
+
|
|
751
|
+
**This is the legacy path. It is being retired, and new integrations should not build on
|
|
752
|
+
it.** It is kept working only for a sender who genuinely cannot approve with a passkey:
|
|
753
|
+
an unsupported device with no platform authenticator, or a player who declines both the
|
|
754
|
+
in-app ceremony and the QR flow.
|
|
755
|
+
|
|
756
|
+
When a sender has no enrolled approver, `initiateSend` / `initiateTransfer` return
|
|
757
|
+
`verificationMethod: "sms"` and a one-time PIN is texted. The completion calls are
|
|
758
|
+
`server.verifySmsTransfer(txnId, pin)` / `verifySmsSend(txnId, pin)` — **deprecated since
|
|
759
|
+
3.1.0**, still fully functional, no runtime warning. They will be removed at some future
|
|
760
|
+
major; no date is being promised.
|
|
761
|
+
|
|
762
|
+
Why it is going away: a PIN in a text is a shared secret on a channel exposed to SIM swap,
|
|
763
|
+
SS7 interception and social engineering, it costs real money per message at every scale,
|
|
764
|
+
and it depends on carrier delivery INVO does not control. A passkey — in the client where
|
|
765
|
+
WebAuthn can run, on the player's phone by QR where it cannot — is stronger, faster and
|
|
766
|
+
free. Read `verificationMethod: "sms"` as *"this sender has no passkey yet"* and offer them
|
|
767
|
+
one; show a PIN pad only when there is no other way to serve that specific player.
|
|
768
|
+
|
|
769
|
+
|
|
770
|
+
---
|
|
771
|
+
|
|
772
|
+
## Sends and transfers, stage by stage
|
|
773
|
+
|
|
774
|
+
One reference for the whole money path — **both flows** (send and transfer) and **both
|
|
775
|
+
sides** (the sender who authorises, the recipient who collects). It exists because the
|
|
776
|
+
stages are easy to read as three when there are four, and the fourth one is the money.
|
|
777
|
+
|
|
778
|
+
> Companion page, same title, on the docs site:
|
|
779
|
+
> [**Sends and transfers, stage by stage**](https://docs.invo.network/docs/sends-and-transfers-stage-by-stage)
|
|
780
|
+
> — the same walkthrough with the raw REST calls, for stacks that don't use this package.
|
|
781
|
+
|
|
782
|
+
**The four stages.**
|
|
783
|
+
|
|
784
|
+
1. **Initiate** (your server). Nothing has moved; a transaction now exists, pending the
|
|
785
|
+
sender's approval.
|
|
786
|
+
2. **Prove who is approving.** A passkey ceremony in the browser, on INVO's hosted page,
|
|
787
|
+
or — where no browser exists — a device approval grant on the player's phone.
|
|
788
|
+
3. **Settle** (your server, for the grant path). **A proof is not a payment.** The
|
|
789
|
+
approval says *who*; a separate call moves the value and runs every gate (guardian,
|
|
790
|
+
risk, recovery cooldown). In the browser `approveSend` / `approveTransfer` does both
|
|
791
|
+
at once, which is why the split only becomes visible on the grant path.
|
|
792
|
+
4. **Collect.** The recipient confirms receipt (their own passkey, or the grant), or
|
|
793
|
+
redeems the claim code. Reconcile off webhooks, never off stage 3's response alone.
|
|
794
|
+
|
|
795
|
+
### What your server must call, in order
|
|
796
|
+
|
|
797
|
+
| # | Stage | Send | Transfer | Auth |
|
|
798
|
+
|---|---|---|---|---|
|
|
799
|
+
| 1 | Initiate | `server.initiateSend(...)` | `server.initiateTransfer(...)` | game secret |
|
|
800
|
+
| 2 | Mint the player's session | `server.mintPlayerToken({ playerEmail })` | same | game secret |
|
|
801
|
+
| 3a | Sender approves — **browser** | `client.approveSend(txnId)` | `client.approveTransfer(txnId)` | player token |
|
|
802
|
+
| 3b | Sender approves — **web, hosted page** | `client.approveHosted({ transactionId, flow: "send" })` | `… flow: "transfer"` | player token |
|
|
803
|
+
| 3c | Sender approves — **console / TV / native** | `server.beginDeviceApproval({ flow: "send" })` → `pollDeviceApproval` | `… flow: "transfer"` | **player** token |
|
|
804
|
+
| 4 | **Settle the grant** (3c only) | **`server.approveWithDeviceCode({ flow: "send", deviceCode })`** | **`… flow: "transfer"`** | **player** token |
|
|
805
|
+
| 5a | Recipient collects — browser | `client.confirmReceiptSend(txnId)` | `client.confirmReceiptTransfer(txnId)` | player token |
|
|
806
|
+
| 5b | Recipient collects — console | `begin`/`poll` `flow: "send_receipt"` → **`approveWithDeviceCode`** | `… flow: "transfer_receipt"` → **`approveWithDeviceCode`** | **player** token |
|
|
807
|
+
| 5c | Recipient collects — claim code | `server.claimCurrency({ claimCode, … })` | `server.claimTransfer({ claimCode, … })` | game secret |
|
|
808
|
+
| 6 | Reconcile | `transfer.claim_pending` → `transfer.received` webhooks | same | webhook secret |
|
|
809
|
+
|
|
810
|
+
Steps 3c, 4 and 5b take the **player token explicitly** — on a console the game *server*
|
|
811
|
+
holds the token it minted, and the game secret is never sent on any of them.
|
|
812
|
+
|
|
813
|
+
### The four device-approval flows
|
|
814
|
+
|
|
815
|
+
`flow` picks which endpoint stage 4 settles against. Begin with one flow and settle with
|
|
816
|
+
the same one: a grant approved for `transfer` settles nothing else.
|
|
817
|
+
|
|
818
|
+
| Side | `flow` | What `approveWithDeviceCode` calls | Success looks like |
|
|
819
|
+
|---|---|---|---|
|
|
820
|
+
| Sender, send | `send` | `POST /api/sdk/send/{id}/approve` | `status: "approved"`, `next: "pending_claim"` |
|
|
821
|
+
| Sender, transfer | `transfer` | `POST /api/sdk/transfers/{id}/approve` | `status: "approved"`, `next: "pending_claim"`, `claimCode` |
|
|
822
|
+
| Recipient, send | `send_receipt` | `POST /api/sdk/send/{id}/confirm-receipt` | `status: "completed"`, `amountReceived` |
|
|
823
|
+
| Recipient, transfer | `transfer_receipt` | `POST /api/sdk/transfers/{id}/confirm-receipt` | `status: "completed"`, `amountReceived` |
|
|
824
|
+
|
|
825
|
+
### Errors on the money path
|
|
826
|
+
|
|
827
|
+
| Code | HTTP | Means | Do |
|
|
828
|
+
|---|---|---|---|
|
|
829
|
+
| `TRANSACTION_NOT_PENDING` | 400 | The transaction is not at this step. Three different situations: your earlier attempt **already landed**; the transaction is **dead** (expired / refunded); or — on a receipt flow — it has **not got here yet**, because the sender's own approval is still pending or held at a guardian. | **Not thrown by `approveWithDeviceCode`** — it comes back as `{ status: "not_pending", alreadySettled, currentStatus }`. `alreadySettled` separates the first case from the other two. When it is `false`, go read `getTransferStatus` / `getSendStatus` rather than assuming; never retry-loop. |
|
|
830
|
+
| `DEVICE_APPROVAL_NOT_APPROVED` | 400 | The `device_code` was unknown, another player's, bound to a different transaction, bound to a different **flow**, or the player has not approved yet. One answer for all five, deliberately — distinguishing them would leak which transactions have a live approval. | `err.isDeviceApprovalNotApproved`. Check the `flow` matches the `begin`, and that the poll actually said `approved`. |
|
|
831
|
+
| `DEVICE_APPROVAL_ALREADY_PENDING` | 409 | An **approved** grant for this transaction and flow is still inside its window. The player already approved. | `err.isDeviceApprovalAlreadyPending`, `err.deviceApprovalExpiresAt`. You are missing stage 4, not a new code — call `approveWithDeviceCode` with the code you have. (A merely *pending* earlier grant does **not** 409; `begin` supersedes it.) |
|
|
832
|
+
| `PASSKEY_RECOVERY_COOLDOWN` | 403 | Money **out** is paused for 24 h after a passkey recovery (SIM-swap protection). Receiving and collecting are unaffected. | `err.isPasskeyRecoveryCooldown`, `err.retryAfterAt` (ISO; the body also carries `retry_after_seconds`). Expect a fresh initiate later — do not retry-loop. |
|
|
833
|
+
| `SEND_APPROVE_FAILED`, `TRANSFER_APPROVE_FAILED`, `CONFIRM_RECEIPT_FAILED` | 400 | A **fault** on INVO's side, not a rule. `err.isSettleFault`; the body carries **`error_ref`** (`err.errorRef`). | Never retryable. See the ambiguity note below — do **not** tell the player it failed until you have read the transaction. Quote `errorRef` to INVO support; it names the exact server log line. |
|
|
834
|
+
| guardian hold | 202 | A minor's transaction is waiting on a guardian. **The money is held, not refused.** | Returned as a result with `holdReason`; poll `getGuardianApprovalStatus`. Terminal outcomes (`GUARDIAN_APPROVAL_REJECTED` / `_EXPIRED`) throw as 410. |
|
|
835
|
+
|
|
836
|
+
**Also reachable from a receipt settle** (`send_receipt` / `transfer_receipt`) — a console
|
|
837
|
+
recipient built only from the table above ships with no fallback for these:
|
|
838
|
+
|
|
839
|
+
| Code | HTTP | Means | Do |
|
|
840
|
+
|---|---|---|---|
|
|
841
|
+
| `receiver_not_enrolled_use_claim_code` | 409 | The recipient has no passkey in this game, so there is no in-app confirm to run. | `err.isReceiverNotEnrolled`. Fall back to the claim code — show it, or point them at the hosted claim link from their text. |
|
|
842
|
+
| `not_intended_receiver` | 403 | The token's identity is not the addressed recipient. | Not retryable. You minted the token for the wrong player, or the send was addressed to a different phone. |
|
|
843
|
+
| `PHONE_SHARE_APPROVAL_REQUIRED` | 409 | The receiver phone is contested, so INVO **holds the money** and asks its owner to approve. | `err.isPhoneShareApprovalRequired`. Not a failure: show `err.message` verbatim (`err.phoneShareLast4` names the phone), then **retry the same call** once approved — it then succeeds idempotently. On denial/expiry the sender is refunded. |
|
|
844
|
+
| `RECIPIENT_IDENTITY_PENDING` | 202 | Same shape, on the identity check: **money held**, the phone's owner emailed. | Comes back as a result with `holdReason`, not a throw. Keep the collect pending and retry later. |
|
|
845
|
+
| `RECIPIENT_IDENTITY_DECLINED` | 403 | The phone's owner said no. | Terminal. The sender is refunded; do not retry. |
|
|
846
|
+
|
|
847
|
+
> ⚠️ **A settle FAILURE is ambiguous about the money.** INVO commits the transfer and
|
|
848
|
+
> *then* builds its `200` by reading the transaction back — so a fault raised after that
|
|
849
|
+
> commit answers `400 *_FAILED` for money that **already moved**. A `err.status === 0`
|
|
850
|
+
> (timeout, dropped connection) is ambiguous for exactly the same reason, and this call is
|
|
851
|
+
> deliberately never auto-retried. On either: read `getTransferStatus` / `getSendStatus`,
|
|
852
|
+
> or wait for the `transfer.claim_pending` webhook, **before** you tell the player it
|
|
853
|
+
> failed — and never auto-start a replacement transaction.
|
|
854
|
+
|
|
855
|
+
### "Already settled" is not a refusal
|
|
856
|
+
|
|
857
|
+
The integrator question this section was written for: *did the guard stop me, or is her
|
|
858
|
+
gold stuck?* You must be able to answer that without matching on message text.
|
|
859
|
+
|
|
860
|
+
`approveWithDeviceCode` **does not throw** for `TRANSACTION_NOT_PENDING`. It returns:
|
|
861
|
+
|
|
862
|
+
```ts
|
|
863
|
+
const r = await server.approveWithDeviceCode({ playerToken, transactionId, flow: "transfer", deviceCode });
|
|
864
|
+
if (r.status === "not_pending") {
|
|
865
|
+
if (r.alreadySettled) {
|
|
866
|
+
// This step already happened — typically your first attempt landed and the response
|
|
867
|
+
// was lost. r.currentStatus says where it is now (pending_claim, completed…).
|
|
868
|
+
} else {
|
|
869
|
+
// NOT settled. Either dead (expired / failed / refunded), or — on a receipt flow —
|
|
870
|
+
// not there YET: the sender has not approved, or their approval is held at a
|
|
871
|
+
// guardian. It is also what an unrecognised status returns, deliberately.
|
|
872
|
+
// Go and read it; do not guess and do not start a replacement transaction:
|
|
873
|
+
const t = await server.getTransferStatus(transactionId);
|
|
874
|
+
}
|
|
875
|
+
} else {
|
|
876
|
+
// status "approved" (+ next: "pending_claim", claimCode on a transfer)
|
|
877
|
+
// or "completed" (+ amountReceived) on the receipt flows
|
|
878
|
+
// or a 202 hold — r.holdReason names it.
|
|
879
|
+
}
|
|
880
|
+
```
|
|
881
|
+
|
|
882
|
+
Every other refusal is a normal thrown `InvoError` with a typed predicate, so a
|
|
883
|
+
`try`/`catch` around this call still means "something is wrong". Nothing in your code has
|
|
884
|
+
to read an English sentence to tell the two apart.
|
|
885
|
+
|
|
886
|
+
**`alreadySettled` fails closed.** It is `true` only for a status INVO knows to be past
|
|
887
|
+
this flow's step — and the two receipt flows have a *different* set from the two sender
|
|
888
|
+
flows, because the four endpoints gate on different statuses. Anything else, including a
|
|
889
|
+
status this SDK version has never seen, answers `false` with `currentStatus` set. Cautious
|
|
890
|
+
and wrong costs you a status lookup; confident and wrong credits goods for money that
|
|
891
|
+
never arrived.
|
|
892
|
+
|
|
893
|
+
*(Older INVO deployments answered this case with only a message — "Transaction not pending
|
|
894
|
+
PIN verification…", "…cannot be confirmed…" — and no machine code. The SDK matches those
|
|
895
|
+
shapes too, so `alreadySettled` is correct against an older backend without any
|
|
896
|
+
string-matching in your code. That fallback requires HTTP 400, one of those two phrases,
|
|
897
|
+
**and** a readable `(current status: …)` / `(status: …)` clause: "cannot be confirmed" is
|
|
898
|
+
ordinary English, so a phrase match alone is never allowed to assert that money moved.)*
|
|
899
|
+
|
|
900
|
+
### Common mistakes
|
|
901
|
+
|
|
902
|
+
> **1. Polling to `approved` and stopping.** The one that costs real money. A device
|
|
903
|
+
> approval grant is a **factor**, not a payment: `approved` means the player proved who
|
|
904
|
+
> they are, and the transaction is still sitting at `pending_pin_verification`. **You must
|
|
905
|
+
> call `approveWithDeviceCode`.** Nothing else in this SDK settles it, and no webhook does
|
|
906
|
+
> it for you — `device_approval.approved` is the *cue* to call it. Left alone, the
|
|
907
|
+
> transaction expires on its own window and is refunded.
|
|
908
|
+
>
|
|
909
|
+
> **2. Treating "already settled" as a failure.** A repeat call after a crash or a lost
|
|
910
|
+
> response answers `TRANSACTION_NOT_PENDING`. That is your earlier attempt succeeding, not
|
|
911
|
+
> a refusal. Branch on `r.alreadySettled` — never on the message.
|
|
912
|
+
>
|
|
913
|
+
> **3. Sending the game secret on the grant calls.** Every device-approval call
|
|
914
|
+
> authenticates with the **player token**. A game secret in a console build is a game
|
|
915
|
+
> secret in a disassembler.
|
|
916
|
+
>
|
|
917
|
+
> **4. Beginning a second grant instead of settling the first.** If `begin` answers
|
|
918
|
+
> `409 DEVICE_APPROVAL_ALREADY_PENDING`, the player has already approved; you need stage
|
|
919
|
+
> 4, not another QR.
|
|
920
|
+
>
|
|
921
|
+
> **5. Polling faster than `interval`.** You get `slow_down`; add 5 seconds and resume.
|
|
922
|
+
>
|
|
923
|
+
> **6. Using the wrong `flow` at stage 4.** The sender's grant (`transfer`) cannot settle
|
|
924
|
+
> the recipient's step (`transfer_receipt`) — it answers `DEVICE_APPROVAL_NOT_APPROVED`,
|
|
925
|
+
> which reads like a broken code and is really a wrong flow.
|
|
926
|
+
>
|
|
927
|
+
> **7. Granting value off stage 3's HTTP response.** Reconcile off webhooks.
|
|
928
|
+
|
|
671
929
|
---
|
|
672
930
|
|
|
673
931
|
## Passkeys (enroll, approve, link, recover)
|
|
@@ -688,8 +946,8 @@ await client.enrollPasskey();
|
|
|
688
946
|
```
|
|
689
947
|
|
|
690
948
|
**First-enrollment OTP grant.** For tenants that require it, the first `enrollPasskey()`
|
|
691
|
-
throws `ENROLLMENT_REQUIRES_AUTHORIZATION`. Send a one-time code (to the player's
|
|
692
|
-
|
|
949
|
+
throws `ENROLLMENT_REQUIRES_AUTHORIZATION`. Send a one-time code (to the player's email on
|
|
950
|
+
file first; by text only on request or when there is no email), verify it, then **retry the same `enrollPasskey()`** — the server-side
|
|
693
951
|
grant is consumed automatically:
|
|
694
952
|
|
|
695
953
|
```ts
|
|
@@ -697,7 +955,7 @@ try {
|
|
|
697
955
|
await client.enrollPasskey();
|
|
698
956
|
} catch (e) {
|
|
699
957
|
if (e instanceof InvoError && e.isEnrollmentAuthorizationRequired) {
|
|
700
|
-
await client.enrollmentBegin(); // → { status: "sent", channels: ["
|
|
958
|
+
await client.enrollmentBegin(); // → { status: "sent", channels: ["email"] } — email first; { channel: "sms" } to text instead
|
|
701
959
|
await client.enrollmentVerify(codeFromUser); // 6-digit OTP
|
|
702
960
|
await client.enrollPasskey(); // retry — grant auto-consumed
|
|
703
961
|
} else if (e instanceof InvoError && e.isEnrollmentProofRequired) {
|
|
@@ -720,7 +978,7 @@ try {
|
|
|
720
978
|
} catch (e) {
|
|
721
979
|
if (e instanceof InvoError && e.isEnrollmentProofRequired) {
|
|
722
980
|
// Player still HAS the other method → linkDevice (above). Lost/deleted it → recover:
|
|
723
|
-
await client.recoveryBegin(); // → { status:"sent", channels:["
|
|
981
|
+
await client.recoveryBegin(); // → { status:"sent", channels:["email"] } — email first; { channel: "sms" } to text instead
|
|
724
982
|
await client.recoveryComplete(codeFromUser); // → { status:"recovered", deactivatedCount }
|
|
725
983
|
await client.enrollPasskey(); // same call — now succeeds
|
|
726
984
|
} else throw e;
|
|
@@ -744,62 +1002,356 @@ try {
|
|
|
744
1002
|
- Challenges are single-use and bound to `{flow}:{transactionId}`.
|
|
745
1003
|
- The SDK passes the backend's WebAuthn options through unchanged (it does not hard-code `pubKeyCredParams`/`timeout`/`attestation`).
|
|
746
1004
|
|
|
1005
|
+
### Web games — approving on INVO's hosted page
|
|
1006
|
+
|
|
1007
|
+
A player on the **web** who has no INVO passkey yet — or whose passkey lives on your domain
|
|
1008
|
+
and so cannot approve on INVO's — uses the same hosted page a console player scans. On the
|
|
1009
|
+
web the **browser is the client**: one SDK call runs the whole device-approval grant with
|
|
1010
|
+
the player token it already holds, exactly as the in-app passkey calls do. Your **server does
|
|
1011
|
+
nothing new** — it initiates the transfer/send as today and its `device_approval.approved`
|
|
1012
|
+
webhook still fires.
|
|
1013
|
+
|
|
1014
|
+
**This is the path for every new title** — there is no partner passkey domain to verify any
|
|
1015
|
+
more (see [which passkey path serves your tenant](#prerequisite-which-passkey-path-serves-your-tenant)).
|
|
1016
|
+
In-app passkeys on your own domain (`enrollPasskey`, `approveSend`, `approveTransfer`) remain
|
|
1017
|
+
fully supported for tenants that verified a domain before the freeze.
|
|
1018
|
+
|
|
1019
|
+
```ts
|
|
1020
|
+
import { InvoClient, InvoError } from "@invonetwork/web-sdk";
|
|
1021
|
+
|
|
1022
|
+
const client = new InvoClient({ token: playerToken, baseUrl: INVO_BASE });
|
|
1023
|
+
|
|
1024
|
+
// Call from a click handler: the popup is opened synchronously, before any network call.
|
|
1025
|
+
approveButton.onclick = async () => {
|
|
1026
|
+
try {
|
|
1027
|
+
const result = await client.approveHosted({
|
|
1028
|
+
transactionId: transferId, // the transfer/send your server initiated
|
|
1029
|
+
flow: "transfer", // "transfer" | "send" | "send_receipt" | "transfer_receipt"
|
|
1030
|
+
// onEnrollment: (e, respond) => …, // optional: observe / draw your own prompt (renderPrompt:false)
|
|
1031
|
+
});
|
|
1032
|
+
switch (result.status) {
|
|
1033
|
+
case "approved": // money moved (or is held: result.approval.holdReason) — same shape as approveTransfer()
|
|
1034
|
+
showClaimCode(result.approval?.claimCode); break;
|
|
1035
|
+
case "denied": // the player said no on INVO's page (or denied the enrolment)
|
|
1036
|
+
case "expired": // start a new approval
|
|
1037
|
+
case "closed": // the player closed the popup
|
|
1038
|
+
break;
|
|
1039
|
+
case "blocked": // popup blocked or severed — nothing started; show a button and call again
|
|
1040
|
+
showRetry(result.message); break;
|
|
1041
|
+
}
|
|
1042
|
+
} catch (e) {
|
|
1043
|
+
if (e instanceof InvoError) handleBackendRefusal(e); // begin 400, invalid_grant, approve gates (e.g. PASSKEY_RECOVERY_COOLDOWN)
|
|
1044
|
+
}
|
|
1045
|
+
};
|
|
1046
|
+
```
|
|
1047
|
+
|
|
1048
|
+
What the one call does, in order — the same REST flow as the console section below, driven
|
|
1049
|
+
from the browser:
|
|
1050
|
+
|
|
1051
|
+
1. `POST /api/sdk/approvals/device/begin` with `{ transaction_id, flow, channel: "popup" }`.
|
|
1052
|
+
INVO records this page's `Origin` as the popup's opener. **The SDK holds the returned
|
|
1053
|
+
`device_code` for the duration of the call** — it is never on the result and never
|
|
1054
|
+
logged; your code never sees it.
|
|
1055
|
+
2. Opens `verification_uri_complete` in a popup (480×720). The player enrols or uses their
|
|
1056
|
+
INVO passkey there, on INVO's own domain.
|
|
1057
|
+
3. Polls `POST /api/sdk/approvals/device/poll` at the server's `interval`, backing off by
|
|
1058
|
+
5 s on `slow_down`.
|
|
1059
|
+
4. First-time enrolment: while the page waits on your screen, the poll carries
|
|
1060
|
+
`enrollment { state: "awaiting_screen", device_label, match_code }` and the SDK shows
|
|
1061
|
+
the INVO match-code prompt — *"Set up INVO on iPhone? Code 48-27. Say Yes only if the
|
|
1062
|
+
phone you just scanned/opened shows this code."* — with **Yes, it shows this code** /
|
|
1063
|
+
**No, that is not my phone** (focus-trapped dialog; Escape = No). The answer goes to
|
|
1064
|
+
`POST /api/sdk/approvals/device/confirm-enrollment`; `confirmed` shows a quiet
|
|
1065
|
+
"Finishing on iPhone… / Stop it, wrong code" row; a 409 already-decided (the backup
|
|
1066
|
+
email answered first) takes the prompt down quietly.
|
|
1067
|
+
5. When the poll says `approved`, the SDK calls the flow's approve endpoint with the
|
|
1068
|
+
`device_code` — `transfers/{id}/approve`, `send/{id}/approve`,
|
|
1069
|
+
`send/{id}/confirm-receipt` or `transfers/{id}/confirm-receipt` — through every gate your
|
|
1070
|
+
in-app approve already runs, and resolves `{ status: "approved", approval }`.
|
|
1071
|
+
|
|
1072
|
+
Security notes, in plain language:
|
|
1073
|
+
|
|
1074
|
+
- **The page's message is a wake-up, not a result.** When INVO's page finishes it posts a
|
|
1075
|
+
status-only message to the window that opened it; the SDK uses it to poll *right now*
|
|
1076
|
+
and nothing else. The outcome always comes from the poll and the approve call.
|
|
1077
|
+
- **Origin check.** The SDK accepts that message only from the hosted page's own https
|
|
1078
|
+
origin (parsed from `verification_uri_complete`; pass `platformOrigin` to pin it — the
|
|
1079
|
+
URL must then match it exactly) and only from the popup it opened. Anything else is
|
|
1080
|
+
ignored. The page posts only to its opener — the origin your `begin` request carried —
|
|
1081
|
+
never to `*`.
|
|
1082
|
+
- **No redirect parameter.** The hosted page never navigates to your site; there is no
|
|
1083
|
+
`return`/`redirect` URL to supply or to spoof. The popup is closed on `approved` and left
|
|
1084
|
+
readable on denied/expired. If the browser blocks the popup the default is to resolve
|
|
1085
|
+
`blocked` *before anything is started*, so you can show a button and call again from its
|
|
1086
|
+
click; `popupBlocked: "redirect"` opts in to sending this tab to the hosted page instead
|
|
1087
|
+
(your page unloads; the `device_approval.approved` webhook is then your server's signal).
|
|
1088
|
+
- **COOP.** Do not send `Cross-Origin-Opener-Policy: same-origin` on the page that calls
|
|
1089
|
+
`approveHosted` — it severs the popup from its opener and the wake-up can never arrive.
|
|
1090
|
+
Use `same-origin-allow-popups`. The SDK detects a severed popup and resolves `blocked`
|
|
1091
|
+
with a hint.
|
|
1092
|
+
- **Cancel with `signal`** (resolves `closed` and closes the popup). Nothing is called after
|
|
1093
|
+
the promise settles.
|
|
1094
|
+
|
|
747
1095
|
### Consoles and TVs — approving without a browser (RFC 8628)
|
|
748
1096
|
|
|
749
1097
|
A console has no browser, so it cannot run a passkey ceremony at all. **Device
|
|
750
1098
|
Approval** moves the ceremony to a device that can: your game shows a short code, the
|
|
751
|
-
player approves on their phone, your server polls until it hears back
|
|
1099
|
+
player approves on their phone, your server polls until it hears back — **and then your
|
|
1100
|
+
server makes the call that actually moves the money.** It is the
|
|
752
1101
|
[OAuth 2.0 Device Authorization Grant, RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628)
|
|
753
1102
|
— the same flow every console and TV app uses — so a standard client library understands
|
|
754
1103
|
the responses.
|
|
755
1104
|
|
|
756
|
-
**
|
|
757
|
-
|
|
1105
|
+
> **The grant is a factor, not a payment.** Reaching `approved` proves *who* approved and
|
|
1106
|
+
> settles **nothing**. The transaction is still waiting. `approveWithDeviceCode` is the
|
|
1107
|
+
> money step, and without it the transaction expires and is refunded. This is the single
|
|
1108
|
+
> most common integration failure on this flow — see
|
|
1109
|
+
> [Sends and transfers, stage by stage](#sends-and-transfers-stage-by-stage).
|
|
1110
|
+
|
|
1111
|
+
**Four SDK methods, since 3.7.0** (`server.beginDeviceApproval`, `pollDeviceApproval`,
|
|
1112
|
+
`confirmDeviceEnrollment`, **`approveWithDeviceCode`**), plus the optional
|
|
1113
|
+
`completeDeviceApproval` loop. Earlier versions documented this as raw REST only, which is
|
|
1114
|
+
how a grant could be polled to `approved` and then dropped. The REST endpoints are
|
|
1115
|
+
unchanged and still usable directly.
|
|
1116
|
+
|
|
1117
|
+
Every one of these calls authenticates with the **player token**, never the game secret —
|
|
1118
|
+
on a console it is your *server* that holds the token it minted for the player.
|
|
1119
|
+
|
|
1120
|
+
**The endpoints underneath**, for a stack that is not using this package. All four take
|
|
1121
|
+
`Authorization: Bearer <player token>`; none takes the game secret:
|
|
1122
|
+
|
|
1123
|
+
| SDK method | Endpoint |
|
|
1124
|
+
|---|---|
|
|
1125
|
+
| `beginDeviceApproval` | `POST /api/sdk/approvals/device/begin` |
|
|
1126
|
+
| `pollDeviceApproval` | `POST /api/sdk/approvals/device/poll` |
|
|
1127
|
+
| `confirmDeviceEnrollment` | `POST /api/sdk/approvals/device/confirm-enrollment` |
|
|
1128
|
+
| **`approveWithDeviceCode`**, `flow: "send"` | **`POST /api/sdk/send/{transaction_id}/approve`** |
|
|
1129
|
+
| **`approveWithDeviceCode`**, `flow: "transfer"` | **`POST /api/sdk/transfers/{transaction_id}/approve`** |
|
|
1130
|
+
| **`approveWithDeviceCode`**, `flow: "send_receipt"` | **`POST /api/sdk/send/{transaction_id}/confirm-receipt`** |
|
|
1131
|
+
| **`approveWithDeviceCode`**, `flow: "transfer_receipt"` | **`POST /api/sdk/transfers/{transaction_id}/confirm-receipt`** |
|
|
1132
|
+
|
|
1133
|
+
Each settle call takes the body `{"device_code": "..."}` and the player's bearer token —
|
|
1134
|
+
the same token that began the grant.
|
|
758
1135
|
|
|
759
1136
|
**Available to every title, with nothing to configure.** The constraint is a property of
|
|
760
1137
|
the *device*, not your game: a title with a website *and* a console build uses the normal
|
|
761
1138
|
ceremony in the browser and this one on the console.
|
|
762
1139
|
|
|
1140
|
+
**Native Steam and desktop game clients (Mac & Windows) belong here too.** Even though the
|
|
1141
|
+
operating system supports passkeys, an embedded game client can't invoke the platform
|
|
1142
|
+
authenticator from inside the engine — so a native desktop title uses this QR flow exactly as
|
|
1143
|
+
a console does. It is the **client** that forces QR here, not the OS.
|
|
1144
|
+
|
|
763
1145
|
```ts
|
|
764
|
-
|
|
1146
|
+
import { InvoServer } from "@invonetwork/web-sdk/server";
|
|
1147
|
+
|
|
1148
|
+
const server = new InvoServer({
|
|
1149
|
+
gameSecret: process.env.INVO_GAME_SECRET!,
|
|
1150
|
+
baseUrl: "https://sandbox.invo.network/sandbox",
|
|
1151
|
+
});
|
|
1152
|
+
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
|
|
1153
|
+
|
|
1154
|
+
// The player token your server minted for this player (mintPlayerToken).
|
|
1155
|
+
const playerToken = session.invoPlayerToken;
|
|
1156
|
+
|
|
1157
|
+
// 1. BEGIN — start an approval for ONE transaction.
|
|
765
1158
|
// flow: "transfer" | "send" | "send_receipt" | "transfer_receipt"
|
|
766
|
-
|
|
767
|
-
|
|
768
|
-
|
|
769
|
-
|
|
770
|
-
|
|
771
|
-
|
|
772
|
-
|
|
773
|
-
|
|
774
|
-
//
|
|
775
|
-
//
|
|
776
|
-
|
|
777
|
-
//
|
|
778
|
-
|
|
779
|
-
|
|
780
|
-
|
|
781
|
-
|
|
782
|
-
|
|
783
|
-
|
|
784
|
-
|
|
785
|
-
|
|
786
|
-
|
|
787
|
-
|
|
788
|
-
//
|
|
1159
|
+
// channel (optional, default "qr"): "qr" (console / TV / native desktop),
|
|
1160
|
+
// "app_browser" (the Unity / Unreal plugin opens the system browser).
|
|
1161
|
+
// "popup" is browser-only — that is client.approveHosted().
|
|
1162
|
+
const grant = await server.beginDeviceApproval({
|
|
1163
|
+
playerToken,
|
|
1164
|
+
transactionId,
|
|
1165
|
+
flow: "transfer",
|
|
1166
|
+
});
|
|
1167
|
+
// grant: { deviceCode, userCode, verificationUri, verificationUriComplete,
|
|
1168
|
+
// expiresIn, interval, channel, raw }
|
|
1169
|
+
|
|
1170
|
+
// 2. SHOW — render grant.verificationUriComplete as a QR and print grant.userCode
|
|
1171
|
+
// under it. The QR already carries the code, so most players never type.
|
|
1172
|
+
// Keep grant.deviceCode on your server: it is a bearer credential.
|
|
1173
|
+
|
|
1174
|
+
// 3. POLL — never faster than grant.interval seconds.
|
|
1175
|
+
let interval = grant.interval;
|
|
1176
|
+
for (;;) {
|
|
1177
|
+
await sleep(interval * 1000);
|
|
1178
|
+
const poll = await server.pollDeviceApproval({ playerToken, deviceCode: grant.deviceCode });
|
|
1179
|
+
|
|
1180
|
+
if (poll.status === "authorization_pending") {
|
|
1181
|
+
// A first-time phone may be waiting on YOUR screen — see `enrollment` below.
|
|
1182
|
+
if (poll.enrollment) showMatchPrompt(poll.enrollment);
|
|
1183
|
+
if (poll.interval) interval = poll.interval;
|
|
1184
|
+
continue;
|
|
1185
|
+
}
|
|
1186
|
+
if (poll.status === "slow_down") { interval += 5; continue; } // RFC 8628 §3.5
|
|
1187
|
+
if (poll.status === "access_denied") return playerDeclined();
|
|
1188
|
+
if (poll.status === "expired_token") return startOver(); // begin again
|
|
1189
|
+
|
|
1190
|
+
// 4. APPROVED → **CALL THE MONEY STEP.** Nothing has moved until this returns.
|
|
1191
|
+
const settle = await server.approveWithDeviceCode({
|
|
1192
|
+
playerToken,
|
|
1193
|
+
transactionId,
|
|
1194
|
+
flow: "transfer", // the SAME flow you began with
|
|
1195
|
+
deviceCode: grant.deviceCode,
|
|
1196
|
+
});
|
|
1197
|
+
|
|
1198
|
+
if (settle.status === "not_pending") {
|
|
1199
|
+
// Your earlier attempt already landed (settle.alreadySettled) or the transaction
|
|
1200
|
+
// is dead (expired / refunded). Read settle.currentStatus. Not a refusal.
|
|
1201
|
+
} else {
|
|
1202
|
+
// "approved" + next: "pending_claim" (+ settle.claimCode on a transfer), or
|
|
1203
|
+
// "completed" + settle.amountReceived on the receipt flows, or a 202 hold
|
|
1204
|
+
// (settle.holdReason).
|
|
1205
|
+
}
|
|
1206
|
+
break;
|
|
1207
|
+
}
|
|
1208
|
+
```
|
|
1209
|
+
|
|
1210
|
+
**Or let the SDK run stages 3 and 4** — `completeDeviceApproval` polls on `interval`,
|
|
1211
|
+
adds 5 s on `slow_down`, surfaces the enrollment prompt, and on `approved` calls
|
|
1212
|
+
`approveWithDeviceCode` for you:
|
|
1213
|
+
|
|
1214
|
+
```ts
|
|
1215
|
+
const done = await server.completeDeviceApproval({
|
|
1216
|
+
playerToken,
|
|
1217
|
+
transactionId,
|
|
1218
|
+
flow: "transfer",
|
|
1219
|
+
deviceCode: grant.deviceCode,
|
|
1220
|
+
interval: grant.interval,
|
|
1221
|
+
onEnrollment: (e, respond) => {
|
|
1222
|
+
if (!e) return hideMatchPrompt();
|
|
1223
|
+
showMatchPrompt(e); // "Set up INVO on <e.deviceLabel>? Code <e.matchCode>"
|
|
1224
|
+
// ALWAYS attach a .catch: this is called without await, and an unhandled rejection
|
|
1225
|
+
// exits a Node process. A prompt the grant has outlived resolves quietly, but any
|
|
1226
|
+
// other refusal rejects — log it and move on; the next poll reports the real state.
|
|
1227
|
+
onPlayerAnswer((yes) =>
|
|
1228
|
+
respond(yes ? "approve" : "deny").catch((err) => log.warn("enrolment answer lost", err)),
|
|
1229
|
+
);
|
|
1230
|
+
},
|
|
1231
|
+
});
|
|
1232
|
+
// done.status: "approved" (done.settlement carries the result) | "denied" | "expired" | "aborted"
|
|
789
1233
|
```
|
|
790
1234
|
|
|
1235
|
+
> **Convenience only.** It holds a request open for as long as the player takes, so it
|
|
1236
|
+
> suits a job or a per-player worker, not a request handler with a short timeout. And
|
|
1237
|
+
> because it moves money from inside a loop, **record the attempt in your own store before
|
|
1238
|
+
> the loop starts** — if your process dies between the approve call and its response, the
|
|
1239
|
+
> only way to know whether the money moved is a record you wrote first, plus
|
|
1240
|
+
> `getTransferStatus` / `getSendStatus`. Servers that can't hold a loop open should use
|
|
1241
|
+
> the three calls directly and keep `deviceCode` in their own store.
|
|
1242
|
+
|
|
791
1243
|
- **One approval authorises one transaction.** Unlike the plain RFC 8628 grant, which
|
|
792
|
-
authorises a *client*, an INVO device code is bound to the transaction
|
|
793
|
-
|
|
794
|
-
-
|
|
795
|
-
|
|
796
|
-
|
|
1244
|
+
authorises a *client*, an INVO device code is bound to the transaction **and the flow**
|
|
1245
|
+
you named. It cannot approve anything else.
|
|
1246
|
+
- **When the code is spent: at the money step, not at approval.** The `device_code` stops
|
|
1247
|
+
being usable when `approveWithDeviceCode` settles the transaction — because the
|
|
1248
|
+
transaction is then no longer pending, and that is what the settle call checks under a
|
|
1249
|
+
row lock. Polling to `approved` consumes nothing; a *second* `approveWithDeviceCode`
|
|
1250
|
+
with the same code answers `TRANSACTION_NOT_PENDING` (returned as
|
|
1251
|
+
`status: "not_pending"`, not thrown) — which, on a sender flow, is how you confirm that a
|
|
1252
|
+
settle whose response you lost did in fact land.
|
|
1253
|
+
- **`userCode` is meant to be seen; `deviceCode` is not.** Poll from your backend, never
|
|
1254
|
+
from the game client, and never log or render the device code.
|
|
1255
|
+
- **One live code per transaction and flow.** Calling `begin` again while an earlier grant
|
|
1256
|
+
is merely *pending* **supersedes** it — you get a fresh code and a page still open on the
|
|
1257
|
+
old one is told to scan again (that is the right answer when a player retries after a
|
|
1258
|
+
crash or an abandoned phone ceremony). If the earlier grant was already **approved**, the
|
|
1259
|
+
begin is refused with `409 DEVICE_APPROVAL_ALREADY_PENDING` + `expires_at`
|
|
1260
|
+
(`err.isDeviceApprovalAlreadyPending`, `err.deviceApprovalExpiresAt`): the player has
|
|
1261
|
+
approved and you are missing the money step, not a new code. Once that approved grant's
|
|
1262
|
+
own window passes, `begin` works again for the same transaction. The sender's grant and
|
|
1263
|
+
the recipient's are scoped separately, so `transfer` and `transfer_receipt` never block
|
|
1264
|
+
each other.
|
|
1265
|
+
- **Starting an approval extends the transaction's window.** For `transfer` and `send`,
|
|
1266
|
+
`begin` pushes the transaction's own approval window past the code's expiry, so an
|
|
1267
|
+
approval at minute nine can't land on a transfer that has already expired and been
|
|
1268
|
+
refunded.
|
|
797
1269
|
- **Subscribe to `device_approval.approved`** to learn the moment an approval lands
|
|
798
|
-
instead of waiting for the next poll
|
|
799
|
-
latency improvement, not a replacement
|
|
800
|
-
|
|
801
|
-
|
|
802
|
-
page
|
|
1270
|
+
instead of waiting for the next poll — then **call `approveWithDeviceCode`**. The
|
|
1271
|
+
webhook is a latency improvement, not the money step and not a replacement for it; the
|
|
1272
|
+
`transfer.*` lifecycle events that follow are what you reconcile against.
|
|
1273
|
+
- **First-time approvers enrol on the spot — your only job is one Yes/No prompt.** The
|
|
1274
|
+
approval page uses a passkey registered with INVO, on INVO's own domain; a passkey the
|
|
1275
|
+
player set up on *your* domain is a different credential and cannot be used there — that
|
|
1276
|
+
is how passkeys work. So the first scan enrols one, and the proof it's really them is
|
|
1277
|
+
**your game screen**: the phone says "Confirm on your game screen", your game shows "Set
|
|
1278
|
+
up INVO on this phone: iPhone?", the player presses Yes on the console, and their phone's
|
|
1279
|
+
fingerprint / face / screen lock creates the passkey and approves. No code to type, no
|
|
1280
|
+
SMS, ever. Every later scan is scan, biometric, done. Same `begin`/`poll`, same
|
|
1281
|
+
`device_approval.approved` webhook, same `method` value `device_grant_webauthn`, same
|
|
1282
|
+
approve call with the `device_code` afterwards.
|
|
1283
|
+
- **Poll: the `enrollment` object.** While a phone is waiting on your screen, the
|
|
1284
|
+
`authorization_pending` body gains it (absent when no phone asked — an already-enrolled
|
|
1285
|
+
phone never triggers it):
|
|
1286
|
+
|
|
1287
|
+
```json
|
|
1288
|
+
{ "error": "authorization_pending",
|
|
1289
|
+
"enrollment": { "state": "awaiting_screen", "device_label": "iPhone",
|
|
1290
|
+
"match_code": "48-27", "recovery": false,
|
|
1291
|
+
"requested_at": "2026-09-03T18:04:12+00:00" } }
|
|
1292
|
+
```
|
|
1293
|
+
|
|
1294
|
+
Show the prompt while `state` is `awaiting_screen`; remove it the moment it changes
|
|
1295
|
+
(`confirmed` / `denied`) or the object disappears. `device_label` is from a fixed list
|
|
1296
|
+
(iPhone, iPad, Android phone, Android device, Mac, Windows PC, Chromebook, Linux device,
|
|
1297
|
+
phone), derived from the scanning phone's browser — a hint, not an identity. Lead the
|
|
1298
|
+
copy with "scanned just now". **`recovery: true`** means the phone declared it is
|
|
1299
|
+
*replacing* a lost INVO passkey — word the prompt "Replace your INVO passkey with this
|
|
1300
|
+
iPhone? Code 48-27" and answer through the same `confirm-enrollment` (see *Recovering a
|
|
1301
|
+
lost passkey* below).
|
|
1302
|
+
- **Answer it: `confirmDeviceEnrollment`** — same player token as begin/poll
|
|
1303
|
+
(`POST /api/sdk/approvals/device/confirm-enrollment` underneath).
|
|
1304
|
+
|
|
1305
|
+
```ts
|
|
1306
|
+
const r = await server.confirmDeviceEnrollment({
|
|
1307
|
+
playerToken,
|
|
1308
|
+
deviceCode: grant.deviceCode,
|
|
1309
|
+
decision: "approve", // or "deny"
|
|
1310
|
+
});
|
|
1311
|
+
// r.status: "confirmed" | "denied"
|
|
1312
|
+
// throws 409 DEVICE_APPROVAL_ENROLLMENT_ALREADY_DECIDED { decided, via }
|
|
1313
|
+
// -> the backup email answered first; take the prompt down quietly
|
|
1314
|
+
// throws 409 DEVICE_APPROVAL_NO_ENROLLMENT_PENDING -> no phone has asked
|
|
1315
|
+
// throws 400 invalid_grant / expired_token
|
|
1316
|
+
```
|
|
1317
|
+
|
|
1318
|
+
**Deny ends the grant**: poll returns `access_denied`, and the phone says it was declined
|
|
1319
|
+
on the game screen.
|
|
1320
|
+
- **Backup email.** At the scan, an email goes to the address on file — "confirm on your game
|
|
1321
|
+
screen; can't see the prompt? tap here; wasn't you? tap here; ignore this if you already
|
|
1322
|
+
confirmed". Opened after the screen answered, it says "you already confirmed this". A
|
|
1323
|
+
backup for a missed prompt, not the proof channel; nothing for you to do.
|
|
1324
|
+
- **Mobile (`channel: "app_browser"`): enrolment is auto-confirmed, no prompt.** The Unity /
|
|
1325
|
+
Unreal plugins open the same page in the system browser (`ASWebAuthenticationSession` /
|
|
1326
|
+
Custom Tabs) and return on `invo-sdk-<game_id>://done`, which carries nothing. Because the
|
|
1327
|
+
phone running the page *is* the device that opened it, the game's prompt is unreachable
|
|
1328
|
+
and a match code proves nothing — so INVO confirms the enrolment itself: the poll's
|
|
1329
|
+
`enrollment` object appears already `confirmed` and goes straight to `approved`; the
|
|
1330
|
+
backup email still goes out as the "if this wasn't you" alert. Start polling on
|
|
1331
|
+
`interval` the moment `begin` returns — the return is only a hint to poll sooner.
|
|
1332
|
+
- **Recovering a lost passkey — from the page, nothing new on your side.** A player whose
|
|
1333
|
+
only INVO passkey was on a phone they no longer have taps "Recover my passkey by email"
|
|
1334
|
+
on the page. Recovery needs **both** halves of the identity: your game screen confirms
|
|
1335
|
+
the phone (the `recovery: true` prompt above — auto-confirmed on mobile), and *only then*
|
|
1336
|
+
a single-use recovery link is emailed to the address on file (never an address the page
|
|
1337
|
+
supplies; one recovery per identity per 24 h). Opened on the same phone, that tab
|
|
1338
|
+
confirms and the page carries on: INVO deactivates the old INVO passkeys, notifies the
|
|
1339
|
+
owner on every channel, enqueues an **`identity.passkey_reset`** webhook to your game,
|
|
1340
|
+
and the phone enrols a fresh passkey and settles the approval — your poll reports
|
|
1341
|
+
`approved` and `device_approval.approved` fires as usual.
|
|
1342
|
+
|
|
1343
|
+
> ⚠️ **Money out is paused for 24 hours after a recovery.** The approval settles, but the
|
|
1344
|
+
> approve call for a `transfer` / `send` is refused with `403 PASSKEY_RECOVERY_COOLDOWN`
|
|
1345
|
+
> (+ `retry_after`). The page tells the player "recovered; start this transfer again after
|
|
1346
|
+
> the hold" — expect a fresh initiate later, not a retry. Receiving and collecting are
|
|
1347
|
+
> unaffected.
|
|
1348
|
+
- **An identity with a method elsewhere must vouch for the new one.** If the identity
|
|
1349
|
+
already has an active approver — a passkey on a partner domain, the INVO app's device key —
|
|
1350
|
+
the page refuses to enrol beside it with `409 ENROLLMENT_REQUIRES_PROOF` and tells the
|
|
1351
|
+
player to add this phone from where that method lives (`linkDevice`), then scan again. An
|
|
1352
|
+
identity with no method enrols freely.
|
|
1353
|
+
- **The code box on the page is the RFC 8628 `user_code`,** there for a TV with no camera.
|
|
1354
|
+
When the QR pre-fills it, the box isn't shown. It is not an SMS field.
|
|
803
1355
|
- **Currency purchases on a console go through that console's store**, as the platform
|
|
804
1356
|
holder requires. This flow is for approving transfers and sends.
|
|
805
1357
|
|
|
@@ -863,6 +1415,7 @@ export const POST = createWebhookHandler({
|
|
|
863
1415
|
| `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`) |
|
|
864
1416
|
| `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`) |
|
|
865
1417
|
| `platform_commerce.refunded` | a Platform Commerce refund | handle the reversal (payload: `order_id, funding_source, player_email, refunded_amount, amount_unit, fee_retained`) |
|
|
1418
|
+
| `transfer.received` / `transfer.claim_expired` / `transfer.refunded` | sends & transfers | reconcile claim state — credited to the recipient (by any claim path, the hosted claim page included) / not collected within 24h / returned to the sender |
|
|
866
1419
|
|
|
867
1420
|
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.
|
|
868
1421
|
|
|
@@ -954,7 +1507,7 @@ Helpers:
|
|
|
954
1507
|
| `.isPhoneShareAlreadyApproved` | phone-share was already approved (e.g. from a `/reject`) |
|
|
955
1508
|
| `.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 |
|
|
956
1509
|
| `.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 |
|
|
957
|
-
| `.isWebauthnNotEnabledForTenant` | **(403)** tenant has no
|
|
1510
|
+
| `.isWebauthnNotEnabledForTenant` | **(403)** tenant has no partner passkey domain — the normal state now that new domains are frozen → **configuration state, not a failure**. Approve on INVO's hosted page (`approveHosted`); see [which passkey path serves your tenant](#prerequisite-which-passkey-path-serves-your-tenant) |
|
|
958
1511
|
|
|
959
1512
|
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`.
|
|
960
1513
|
|
|
@@ -998,6 +1551,11 @@ try {
|
|
|
998
1551
|
| `getTransferStatus(txnId)` / `getSendStatus(txnId)` | `TransactionStatusResult` — poll outbound state (`verificationState`) |
|
|
999
1552
|
| `getGuardianApprovalStatus(txnId)` | `GuardianApprovalStatusResult` — poll a guardian hold to resolution (`state`) |
|
|
1000
1553
|
| `getDestinations({ sourceGameId, direction? })` | `DestinationsResult` — server-side (game-secret) destinations; same rows as the browser variant |
|
|
1554
|
+
| `beginDeviceApproval({ playerToken, transactionId, flow, channel? })` | `DeviceApprovalGrant` — `{ deviceCode, userCode, verificationUri, verificationUriComplete, expiresIn, interval, channel, raw }`. **Player token**, never the game secret. Show `verificationUriComplete` as a QR |
|
|
1555
|
+
| `pollDeviceApproval({ playerToken, deviceCode })` | `DeviceApprovalPollResult` — `status: "approved" \| "authorization_pending" \| "slow_down" \| "expired_token" \| "access_denied"` (+ `enrollment` while a first-time phone waits on your screen). `invalid_grant` throws |
|
|
1556
|
+
| `confirmDeviceEnrollment({ playerToken, deviceCode, decision })` | `{ status, raw }` — answers the on-screen match-code prompt; `decision: "approve" \| "deny"` |
|
|
1557
|
+
| **`approveWithDeviceCode({ playerToken, transactionId, flow, deviceCode })`** | **The money step.** `DeviceApprovalSettleResult` — routes by `flow` to the transfer/send approve or confirm-receipt endpoint. `TRANSACTION_NOT_PENDING` comes back as `status: "not_pending"` + `alreadySettled` + `currentStatus`, **not** thrown |
|
|
1558
|
+
| `completeDeviceApproval({ playerToken, transactionId, flow, deviceCode, interval?, onEnrollment?, signal? })` | `{ status: "approved" \| "denied" \| "expired" \| "aborted", settlement?, lastPoll? }` — convenience loop: polls honouring `interval`/`slow_down`, then calls `approveWithDeviceCode` |
|
|
1001
1559
|
| `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 |
|
|
1002
1560
|
| `iterateItemPurchaseHistory({ playerEmail, pageSize? })` | async iterator over all history rows |
|
|
1003
1561
|
| `verifyWebhook(rawBody, signatureHeader, secret \| secrets, opts?)` | typed `InvoWebhookEvent` (throws on bad signature) |
|
|
@@ -1019,6 +1577,7 @@ Every method also accepts an optional final `{ signal }` (`AbortSignal`) for can
|
|
|
1019
1577
|
| `getPendingCollect()` | `{ pending, raw }` — the player's own pending-to-collect list (player-token) |
|
|
1020
1578
|
| `getDestinations({ direction? })` | `{ availableGames, sourceGameName, transferMode, … }` — where the player can send/transfer, metadata inline |
|
|
1021
1579
|
| `getBalance()` | `{ gameId, gameName, balances, totalValue, currencyCount, hasFunds, raw }` — the player's balances for this game |
|
|
1580
|
+
| `approveHosted({ transactionId, flow, platformOrigin?, onEnrollment?, renderPrompt?, popupBlocked?, popup?, signal? })` | `{ status: "approved" \| "denied" \| "expired" \| "closed" \| "blocked" \| "redirected", popupBlocked, message?, approval? }` — runs the whole RFC 8628 device-approval grant from the browser on INVO's hosted page (begin `channel:"popup"` → popup → poll → match-code prompt → confirm-enrollment → approve with the `device_code`, which the SDK holds and never exposes); `approval` is the `ApproveResult` / `ConfirmReceiptResult` of the flow's approve endpoint |
|
|
1022
1581
|
| `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 |
|
|
1023
1582
|
|
|
1024
1583
|
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.
|