@invonetwork/web-sdk 3.6.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 +81 -0
- package/README.md +378 -61
- package/dist/{chunk-MBKE6ULW.js → chunk-23TGMTII.js} +90 -3
- package/dist/index.cjs +88 -1
- package/dist/index.d.cts +2 -2
- package/dist/index.d.ts +2 -2
- package/dist/index.js +2 -2
- 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-ZNoG09S5.d.cts → types-CspPkmK9.d.cts} +265 -11
- package/dist/{types-ZNoG09S5.d.ts → types-CspPkmK9.d.ts} +265 -11
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
First-party TypeScript SDK for integrating **INVO** into partner **web** platforms (storefronts, web games, dashboards). It wraps INVO's web money flows behind a typed, versioned API — the web analog of the Unity/Unreal plugins.
|
|
4
4
|
|
|
5
|
-
> **Status:** `v3.
|
|
5
|
+
> **Status:** `v3.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,7 +35,8 @@ 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
41
|
### Prerequisite: which passkey path serves your tenant
|
|
41
42
|
|
|
@@ -79,7 +80,7 @@ The right approval method is a property of the **client the player is sitting in
|
|
|
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 |
|
|
80
81
|
| Desktop web (browser) | **a passkey, directly** | Touch ID / Windows Hello are available to the browser |
|
|
81
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 |
|
|
82
|
-
| 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, and the
|
|
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 |
|
|
83
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 |
|
|
84
85
|
|
|
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.
|
|
@@ -96,6 +97,11 @@ The right approval method is a property of the **client the player is sitting in
|
|
|
96
97
|
- [Platform Commerce (ecommerce)](#platform-commerce-ecommerce)
|
|
97
98
|
- [Player balance](#player-balance)
|
|
98
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)
|
|
99
105
|
- [Passkeys (enroll, approve, link, recover)](#passkeys-enroll-approve-link-recover)
|
|
100
106
|
- [Web games — approving on INVO's hosted page](#web-games--approving-on-invos-hosted-page)
|
|
101
107
|
- [Consoles and TVs — approving without a browser (RFC 8628)](#consoles-and-tvs--approving-without-a-browser-rfc-8628)
|
|
@@ -609,7 +615,16 @@ comes from the token, no PII).
|
|
|
609
615
|
|
|
610
616
|
## Sends & transfers (move currency between players)
|
|
611
617
|
|
|
612
|
-
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:
|
|
613
628
|
|
|
614
629
|
| | Send | Transfer |
|
|
615
630
|
|---|---|---|
|
|
@@ -644,14 +659,17 @@ const t = await server.initiateTransfer({
|
|
|
644
659
|
|
|
645
660
|
// Check guardianApproval FIRST — the guardian path takes precedence.
|
|
646
661
|
switch (true) {
|
|
647
|
-
case !!t.guardianApproval: // minor/guardian path (HTTP 202) →
|
|
648
|
-
|
|
649
|
-
case t.verificationMethod === "
|
|
650
|
-
|
|
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.
|
|
651
667
|
}
|
|
652
668
|
|
|
653
669
|
// 2. BROWSER — the sender approves with their passkey (give them t.transactionId + the player token)
|
|
654
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".
|
|
655
673
|
// approved.claimCode + approved.claimCodeExpiresAt (transfer only) — deliver if the recipient can't self-claim
|
|
656
674
|
|
|
657
675
|
// 3. BROWSER — the recipient claims with their passkey; fall back to the claim code if not enrolled
|
|
@@ -668,10 +686,14 @@ try {
|
|
|
668
686
|
}
|
|
669
687
|
```
|
|
670
688
|
|
|
671
|
-
- **`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.
|
|
672
690
|
- **Claim codes** are returned only by `approveTransfer`; they're the out-of-band fallback when the recipient isn't enrolled.
|
|
673
691
|
- **`err.isReceiverNotEnrolled`** on `confirmReceipt*` is the explicit signal to switch to claim-code entry.
|
|
674
|
-
- **
|
|
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
|
|
675
697
|
now ends with a link to a hosted INVO page ("Or collect here: …"). They see who sent what in
|
|
676
698
|
which game, enter **one email** (the same thing in-game claim already requires), confirm it
|
|
677
699
|
with an emailed 6-digit code, and their phone's fingerprint / face / screen lock creates an
|
|
@@ -724,6 +746,186 @@ try {
|
|
|
724
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).
|
|
725
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).
|
|
726
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
|
+
|
|
727
929
|
---
|
|
728
930
|
|
|
729
931
|
## Passkeys (enroll, approve, link, recover)
|
|
@@ -894,13 +1096,42 @@ Security notes, in plain language:
|
|
|
894
1096
|
|
|
895
1097
|
A console has no browser, so it cannot run a passkey ceremony at all. **Device
|
|
896
1098
|
Approval** moves the ceremony to a device that can: your game shows a short code, the
|
|
897
|
-
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
|
|
898
1101
|
[OAuth 2.0 Device Authorization Grant, RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628)
|
|
899
1102
|
— the same flow every console and TV app uses — so a standard client library understands
|
|
900
1103
|
the responses.
|
|
901
1104
|
|
|
902
|
-
**
|
|
903
|
-
|
|
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.
|
|
904
1135
|
|
|
905
1136
|
**Available to every title, with nothing to configure.** The constraint is a property of
|
|
906
1137
|
the *device*, not your game: a title with a website *and* a console build uses the normal
|
|
@@ -912,52 +1143,133 @@ authenticator from inside the engine — so a native desktop title uses this QR
|
|
|
912
1143
|
a console does. It is the **client** that forces QR here, not the OS.
|
|
913
1144
|
|
|
914
1145
|
```ts
|
|
915
|
-
|
|
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.
|
|
916
1158
|
// flow: "transfer" | "send" | "send_receipt" | "transfer_receipt"
|
|
917
|
-
// channel (optional, default "qr"):
|
|
918
|
-
//
|
|
919
|
-
// "
|
|
920
|
-
const
|
|
921
|
-
|
|
922
|
-
|
|
923
|
-
|
|
924
|
-
})
|
|
925
|
-
//
|
|
926
|
-
//
|
|
927
|
-
|
|
928
|
-
// 2.
|
|
929
|
-
// under it. The QR already
|
|
930
|
-
|
|
931
|
-
|
|
932
|
-
|
|
933
|
-
|
|
934
|
-
|
|
935
|
-
|
|
936
|
-
|
|
937
|
-
|
|
938
|
-
|
|
939
|
-
//
|
|
940
|
-
|
|
941
|
-
|
|
942
|
-
|
|
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"
|
|
943
1233
|
```
|
|
944
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
|
+
|
|
945
1243
|
- **One approval authorises one transaction.** Unlike the plain RFC 8628 grant, which
|
|
946
|
-
authorises a *client*, an INVO device code is bound to the transaction
|
|
947
|
-
|
|
948
|
-
-
|
|
949
|
-
|
|
950
|
-
|
|
951
|
-
|
|
952
|
-
|
|
953
|
-
|
|
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.
|
|
954
1265
|
- **Starting an approval extends the transaction's window.** For `transfer` and `send`,
|
|
955
1266
|
`begin` pushes the transaction's own approval window past the code's expiry, so an
|
|
956
1267
|
approval at minute nine can't land on a transfer that has already expired and been
|
|
957
1268
|
refunded.
|
|
958
1269
|
- **Subscribe to `device_approval.approved`** to learn the moment an approval lands
|
|
959
|
-
instead of waiting for the next poll
|
|
960
|
-
latency improvement, not a replacement
|
|
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.
|
|
961
1273
|
- **First-time approvers enrol on the spot — your only job is one Yes/No prompt.** The
|
|
962
1274
|
approval page uses a passkey registered with INVO, on INVO's own domain; a passkey the
|
|
963
1275
|
player set up on *your* domain is a different credential and cannot be used there — that
|
|
@@ -987,20 +1299,20 @@ const poll = await fetch(`${INVO_BASE}/api/sdk/approvals/device/poll`, {
|
|
|
987
1299
|
*replacing* a lost INVO passkey — word the prompt "Replace your INVO passkey with this
|
|
988
1300
|
iPhone? Code 48-27" and answer through the same `confirm-enrollment` (see *Recovering a
|
|
989
1301
|
lost passkey* below).
|
|
990
|
-
- **Answer it: `
|
|
991
|
-
|
|
1302
|
+
- **Answer it: `confirmDeviceEnrollment`** — same player token as begin/poll
|
|
1303
|
+
(`POST /api/sdk/approvals/device/confirm-enrollment` underneath).
|
|
992
1304
|
|
|
993
1305
|
```ts
|
|
994
|
-
const r = await
|
|
995
|
-
|
|
996
|
-
|
|
997
|
-
|
|
998
|
-
})
|
|
999
|
-
//
|
|
1000
|
-
// 409 DEVICE_APPROVAL_ENROLLMENT_ALREADY_DECIDED { decided, via }
|
|
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 }
|
|
1001
1313
|
// -> the backup email answered first; take the prompt down quietly
|
|
1002
|
-
// 409 DEVICE_APPROVAL_NO_ENROLLMENT_PENDING -> no phone has asked
|
|
1003
|
-
// 400 invalid_grant / expired_token
|
|
1314
|
+
// throws 409 DEVICE_APPROVAL_NO_ENROLLMENT_PENDING -> no phone has asked
|
|
1315
|
+
// throws 400 invalid_grant / expired_token
|
|
1004
1316
|
```
|
|
1005
1317
|
|
|
1006
1318
|
**Deny ends the grant**: poll returns `access_denied`, and the phone says it was declined
|
|
@@ -1239,6 +1551,11 @@ try {
|
|
|
1239
1551
|
| `getTransferStatus(txnId)` / `getSendStatus(txnId)` | `TransactionStatusResult` — poll outbound state (`verificationState`) |
|
|
1240
1552
|
| `getGuardianApprovalStatus(txnId)` | `GuardianApprovalStatusResult` — poll a guardian hold to resolution (`state`) |
|
|
1241
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` |
|
|
1242
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 |
|
|
1243
1560
|
| `iterateItemPurchaseHistory({ playerEmail, pageSize? })` | async iterator over all history rows |
|
|
1244
1561
|
| `verifyWebhook(rawBody, signatureHeader, secret \| secrets, opts?)` | typed `InvoWebhookEvent` (throws on bad signature) |
|