@invonetwork/web-sdk 3.28.0 → 3.29.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 +11 -0
- package/README.md +24 -1
- package/dist/{chunk-4YKTKXC5.js → chunk-FJR44FKW.js} +22 -5
- package/dist/chunk-KZJABBVT.js +6 -0
- package/dist/game-server.cjs +166 -14
- package/dist/game-server.d.cts +77 -4
- package/dist/game-server.d.ts +77 -4
- package/dist/game-server.js +147 -17
- package/dist/game.cjs +1 -1
- package/dist/game.d.cts +1 -1
- package/dist/game.d.ts +1 -1
- package/dist/game.js +1 -1
- package/dist/server-Dnx5jxS4.d.ts +2165 -0
- package/dist/server-UZ38eD2p.d.cts +2165 -0
- package/dist/server.cjs +16 -2
- package/dist/server.d.cts +3 -2159
- package/dist/server.d.ts +3 -2159
- package/dist/server.js +2 -2
- package/dist/{version-iWmcxjYu.d.cts → version-xyYQO5hp.d.cts} +1 -1
- package/dist/{version-iWmcxjYu.d.ts → version-xyYQO5hp.d.ts} +1 -1
- package/package.json +1 -1
- package/dist/chunk-3DRWLDDF.js +0 -6
|
@@ -0,0 +1,2165 @@
|
|
|
1
|
+
import { I as InvoError, H as Http, a2 as AuthHeader, g as CallOptions, a3 as PlatformPurchaseInput, a4 as PlatformPurchaseResult, a5 as PlatformOrderStatusResult, a6 as PlatformPurchaseHistoryQuery, a7 as PlatformPurchaseHistoryResult, a8 as PlatformRefundInput, a9 as PlatformRefundResult, aa as CreateSubscriptionInput, ab as SubscriptionResult, ac as GetSubscriptionOptions, ad as GetSubscriptionResult, ae as ListSubscriptionsOptions, af as SubscriptionListResult, ag as CancelSubscriptionOptions, ah as CancelResult, ai as ChangeAmountResult, aj as SetPaymentMethodInput, ak as SetPaymentMethodResult, al as RefundSubscriptionInput, am as RefundResult, an as SteamSubscriptionInitInput, ao as SteamInitResult, ap as SteamFinalizeSubscriptionResult, aq as CardSetupSessionInput, ar as CardSetupSessionResult, as as CardSetupInput, at as CardSetupResult, au as CardSetupConfirmInput, av as CardSetupConfirmResult, aw as PlayerCardsResult, ax as SandboxClockResult, ay as SandboxFailureOutcome, az as SandboxForceFailureOptions, aA as SandboxForceAuthChallengeOptions, aB as ServerConfig, aC as MintPlayerTokenInput, aD as PlayerToken, aE as RegisterPlayerInput, aF as RegisterPlayerResult, aG as UpdatePlayerPhoneInput, aH as UpdatePlayerPhoneResult, aI as RequestPhoneChangeInput, aJ as RequestPhoneChangeResult, aK as PhoneChangeRequest, aL as InitiateSendInput, aM as InitiateResult, aN as InitiateTransferInput, aO as CreateCheckoutInput, aP as CreateCheckoutResult, aQ as PurchaseInput, aR as PurchaseResult, aS as CurrencyPurchaseQuoteInput, aT as CurrencyPurchaseQuote, aU as ConfirmPaymentResult, aV as OrderDetailsResult, aW as SteamPacksQuery, aX as SteamPacksResult, aY as SteamInitPurchaseInput, aZ as SteamInitPurchaseResult, a_ as SteamFinalizeInput, a$ as SteamFinalizeResult, b0 as PurchaseItemInput, b1 as PurchaseItemResult, b2 as ItemHistoryQuery, b3 as ItemHistoryResult, b4 as ItemOrderQuery, b5 as PlayerActivityQuery, b6 as PlayerActivityResult, b7 as PlayerActivityEntry, b8 as PlayerBalanceQuery, b9 as PlayerBalanceResult, o as LoyaltyCardsResult, ba as ReportServerGameEventInput, s as ReportGameEventResult, bb as InboundPendingQuery, bc as InboundPendingResult, bd as LinkedIdentitiesQuery, be as LinkedIdentitiesResult, bf as SmsVerifyResult, bg as ClaimTransferInput, bh as ClaimResult, bi as ClaimCurrencyInput, bj as TransactionStatusResult, bk as GuardianApprovalStatusResult, bl as ServerDestinationsQuery, n as DestinationsResult, bm as PhoneShareContact, bn as PhoneShareInitiateResult, bo as PhoneShareApproveInput, bp as PhoneShareApproveResult, bq as PhoneShareStatusResult, br as BeginDeviceApprovalInput, bs as DeviceApprovalGrant, bt as PollDeviceApprovalInput, bu as DeviceApprovalPollResult, bv as ConfirmDeviceEnrollmentInput, bw as ConfirmDeviceEnrollmentResult, bx as ApproveWithDeviceCodeInput, by as DeviceApprovalSettleResult, bz as CompleteDeviceApprovalInput, bA as CompleteDeviceApprovalResult } from './types-_lIm74kd.js';
|
|
2
|
+
import './version-xyYQO5hp.js';
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* Pick the INVO environment from the game secret alone (3.28.0).
|
|
6
|
+
*
|
|
7
|
+
* Going live is swapping the key: a sandbox key (including the public demo key baked into
|
|
8
|
+
* INVO's game templates) talks to the sandbox, a live key to production, and nothing else in
|
|
9
|
+
* your code changes.
|
|
10
|
+
*
|
|
11
|
+
* - The public demo key starts with `ivsdk_demo_`: always the sandbox, no network call.
|
|
12
|
+
* - Any other key: INVO is asked once (`GET /api/sdk/key-environment`), production first,
|
|
13
|
+
* then the sandbox. The answer is cached per key for the life of the process.
|
|
14
|
+
*/
|
|
15
|
+
declare const PRODUCTION_BASE_URL = "https://invo.network";
|
|
16
|
+
declare const SANDBOX_BASE_URL = "https://sandbox.invo.network/sandbox";
|
|
17
|
+
declare const DEMO_KEY_PREFIX = "ivsdk_demo_";
|
|
18
|
+
type InvoEnvironment = "production" | "sandbox";
|
|
19
|
+
/** Neither environment recognised the key, or INVO could not be reached. */
|
|
20
|
+
declare class EnvironmentUnknownError extends Error {
|
|
21
|
+
constructor(message: string);
|
|
22
|
+
}
|
|
23
|
+
declare function isDemoKey(gameSecret: string | undefined | null): boolean;
|
|
24
|
+
/**
|
|
25
|
+
* `"production"` or `"sandbox"` for this key. Rejects with {@link EnvironmentUnknownError}
|
|
26
|
+
* when neither environment knows the key (a failed lookup is not cached, so it is retried).
|
|
27
|
+
*/
|
|
28
|
+
declare function resolveEnvironment(gameSecret: string, opts?: {
|
|
29
|
+
fetch?: typeof fetch;
|
|
30
|
+
}): Promise<InvoEnvironment>;
|
|
31
|
+
/** The API base URL for this key (see {@link resolveEnvironment}). */
|
|
32
|
+
declare function baseUrlForKey(gameSecret: string, opts?: {
|
|
33
|
+
fetch?: typeof fetch;
|
|
34
|
+
}): Promise<string>;
|
|
35
|
+
|
|
36
|
+
interface VerifyWebhookOptions {
|
|
37
|
+
/** Max age of the signed timestamp, in seconds. Default 300 (5 min). */
|
|
38
|
+
toleranceSec?: number;
|
|
39
|
+
/** Override the current time (unix seconds) — for tests. Defaults to Date.now(). */
|
|
40
|
+
nowSec?: number;
|
|
41
|
+
}
|
|
42
|
+
interface WebhookBase {
|
|
43
|
+
event_id: string;
|
|
44
|
+
idempotency_key: string;
|
|
45
|
+
schema_version: string;
|
|
46
|
+
created_at: string;
|
|
47
|
+
/** Your game_id. */
|
|
48
|
+
tenant_id: string;
|
|
49
|
+
}
|
|
50
|
+
interface PurchaseCompletedData {
|
|
51
|
+
transaction_id: string;
|
|
52
|
+
order_id: string;
|
|
53
|
+
player_email: string;
|
|
54
|
+
identity_id: string;
|
|
55
|
+
usd_amount: string;
|
|
56
|
+
currency_amount: string;
|
|
57
|
+
currency_name: string;
|
|
58
|
+
new_balance: string;
|
|
59
|
+
/** Which settlement rail carried the money. Provider-neutral. */
|
|
60
|
+
rail: string;
|
|
61
|
+
/**
|
|
62
|
+
* Which STOREFRONT the purchase came from — "steam" / "ios" / "android" /
|
|
63
|
+
* "web" / "console" — beside the rail it was paid on. Read off the order,
|
|
64
|
+
* not the request. `null` when the caller used a legacy game key: that is a
|
|
65
|
+
* real answer ("unattributed"), read it as one.
|
|
66
|
+
*/
|
|
67
|
+
channel?: string | null;
|
|
68
|
+
/**
|
|
69
|
+
* The metadata you passed to createCheckout/purchaseCurrency/steamInitPurchase, echoed back
|
|
70
|
+
* (all rails).
|
|
71
|
+
*
|
|
72
|
+
* **Subscription renewals also emit `purchase.completed`** (every paid card renewal, for the
|
|
73
|
+
* coins its charge minted). Those carry `metadata.source === "subscription_renewal"` and
|
|
74
|
+
* `metadata.subscription_id` (plus `period_seq`, `attempt_no`, `item_id`, `funding_rail`,
|
|
75
|
+
* and `funding_model: "card_only"` on the card rail). **Do not grant currency or access from
|
|
76
|
+
* them**: the renewal spends those coins in the same step. Act on `subscription.renewed`;
|
|
77
|
+
* its `mint_order_id` equals this event's `order_id`.
|
|
78
|
+
*/
|
|
79
|
+
metadata?: Record<string, unknown>;
|
|
80
|
+
/**
|
|
81
|
+
* Why the tax is what it is. `"partner_responsible"` on an Open-tier account (you are the
|
|
82
|
+
* seller; INVO charged no tax); on Merchant of Record, how INVO handled it (for example
|
|
83
|
+
* `"collected"`). Treat an unknown value as informational.
|
|
84
|
+
*/
|
|
85
|
+
tax_treatment?: string | null;
|
|
86
|
+
/**
|
|
87
|
+
* Merchant of Record accounts only (card sales): the receipt INVO issued to the buyer.
|
|
88
|
+
* Absent on Open accounts and storefront rails.
|
|
89
|
+
*/
|
|
90
|
+
receipt_number?: string;
|
|
91
|
+
/** Merchant of Record only: link to the printable receipt page. Anyone with it can read it. */
|
|
92
|
+
receipt_url?: string;
|
|
93
|
+
/**
|
|
94
|
+
* Additive (2026-09 pricing). INVO's card fee charged to you for this purchase, USD decimal
|
|
95
|
+
* string: 3.5% + $0.30 on Open, 5.5% + $0.50 on Merchant of Record. The buyer paid the listed
|
|
96
|
+
* price (plus any tax) and received the listed coins; the fee nets against your earnings.
|
|
97
|
+
* Card purchases only; absent on purchases through a third-party storefront or payment rail,
|
|
98
|
+
* on an order charged before the 2026-09 pricing, and from backends that do not send it.
|
|
99
|
+
* `null` when the fee could not be booked when the purchase completed (the purchase itself
|
|
100
|
+
* succeeded; INVO books the fee shortly after).
|
|
101
|
+
*/
|
|
102
|
+
partner_fee_usd?: string | null;
|
|
103
|
+
/**
|
|
104
|
+
* Additive (2026-09 pricing). The international card fee charged to you, USD decimal string:
|
|
105
|
+
* 1.5% of the listed price (before tax) on a card issued outside the US, `"0.00"` otherwise
|
|
106
|
+
* (a card whose country is unknown counts as domestic). Separate from `partner_fee_usd`.
|
|
107
|
+
* Card purchases only; absent and `null` on the same terms as `partner_fee_usd`.
|
|
108
|
+
*/
|
|
109
|
+
international_card_fee_usd?: string | null;
|
|
110
|
+
[key: string]: unknown;
|
|
111
|
+
}
|
|
112
|
+
interface PurchaseEventData {
|
|
113
|
+
transaction_id: string;
|
|
114
|
+
order_id?: string;
|
|
115
|
+
player_email?: string;
|
|
116
|
+
identity_id?: string;
|
|
117
|
+
/** Present on purchase.disputed, e.g. "lost". */
|
|
118
|
+
dispute_status?: string;
|
|
119
|
+
/**
|
|
120
|
+
* Additive (2026-09 pricing), on a LOST purchase.disputed for a Platform Commerce card sale
|
|
121
|
+
* or a subscription charge (`order_type` `"platform_commerce"` or `"subscription_renewal"`).
|
|
122
|
+
* `true` when INVO's chargeback guarantee covers this dispute: a fraud chargeback on a card
|
|
123
|
+
* sale, which INVO absorbs, so your share is not reversed or held and no dispute fee is passed
|
|
124
|
+
* to you. The guarantee is a Merchant of Record term; Open-tier card payments made before
|
|
125
|
+
* November 8, 2026 keep it, later ones do not (`false`, passed through at cost). `false`
|
|
126
|
+
* for any other dispute, handled as before. Never sent on a coin purchase
|
|
127
|
+
* dispute (a lost coin chargeback takes back the player's coins, not your share, so there is
|
|
128
|
+
* nothing to cover), nor on an opened or won event. Do not read absence as either value.
|
|
129
|
+
*/
|
|
130
|
+
guarantee_covered?: boolean;
|
|
131
|
+
/**
|
|
132
|
+
* Additive, on a lost purchase.disputed for an order that sold no coins: `"platform_commerce"`
|
|
133
|
+
* or `"subscription_renewal"`. Absent on a coin purchase dispute.
|
|
134
|
+
*/
|
|
135
|
+
order_type?: string;
|
|
136
|
+
/**
|
|
137
|
+
* Additive, on a lost Platform Commerce or subscription purchase.disputed: your share of the
|
|
138
|
+
* sale reversed, USD decimal string (`"0.00"` when the chargeback guarantee covered it).
|
|
139
|
+
*/
|
|
140
|
+
developer_revenue_reversed_usd?: string | null;
|
|
141
|
+
/**
|
|
142
|
+
* Additive (2026-09-27), on a lost subscription purchase.disputed. Since 2026-09-28
|
|
143
|
+
* (D-PRICE-012) always `"0.00"`: a lost dispute charges INVO's card fee instead
|
|
144
|
+
* (`card_fee_charged_to_partner_usd`), not a separate processor fee. `null` where it does not
|
|
145
|
+
* apply (for example a Platform Commerce dispute). Absent on coin purchase disputes.
|
|
146
|
+
*/
|
|
147
|
+
processing_fee_usd?: string | null;
|
|
148
|
+
/**
|
|
149
|
+
* Additive (2026-09-28, D-PRICE-012), on a lost Platform Commerce or subscription
|
|
150
|
+
* purchase.disputed: INVO's card fee on the lost amount, charged to you, USD decimal string.
|
|
151
|
+
* A lost dispute not covered by the chargeback guarantee costs you exactly what a refund of
|
|
152
|
+
* the same charge does, on every charge. `"0.00"` when the guarantee covered it; `null` where
|
|
153
|
+
* it does not apply (including a settlement replay). Absent on coin purchase disputes.
|
|
154
|
+
*/
|
|
155
|
+
card_fee_charged_to_partner_usd?: string | null;
|
|
156
|
+
/**
|
|
157
|
+
* Additive (2026-09-28, D-PRICE-012), same events: your whole debit for the lost dispute,
|
|
158
|
+
* `developer_revenue_reversed_usd` plus `card_fee_charged_to_partner_usd`. `"0.00"` when the
|
|
159
|
+
* guarantee covered it; `null` where it does not apply.
|
|
160
|
+
*/
|
|
161
|
+
partner_debited_usd?: string | null;
|
|
162
|
+
/**
|
|
163
|
+
* Additive (2026-10-09), on a card purchase.disputed sent when the dispute closes (won or
|
|
164
|
+
* lost): the card network's dispute fee charged to you for this dispute, USD decimal string
|
|
165
|
+
* such as `"15.00"`. `"0.00"` when INVO bears it or it was returned to INVO. From November 8,
|
|
166
|
+
* 2026, on Open-tier card sales (coin purchases, Platform Commerce card sales and subscription
|
|
167
|
+
* charges), the dispute fee is passed through to you at cost. `null` when it cannot be decided.
|
|
168
|
+
* A lost dispute is purchase.disputed with `dispute_status` `"lost"`; there is no separate
|
|
169
|
+
* lost-dispute event. Absent on older events and storefront chargebacks; do not read absence
|
|
170
|
+
* as zero.
|
|
171
|
+
*/
|
|
172
|
+
dispute_fee_usd?: string | null;
|
|
173
|
+
/**
|
|
174
|
+
* Additive (2026-10-09), same events: `true` when `dispute_fee_usd` is above zero (the fee is
|
|
175
|
+
* charged to you), `false` when it is not, `null` when it cannot be decided. Absent where
|
|
176
|
+
* `dispute_fee_usd` is absent.
|
|
177
|
+
*/
|
|
178
|
+
dispute_fee_charged_to_partner?: boolean | null;
|
|
179
|
+
/** On a lost subscription purchase.disputed: the subscription and period it concerns. */
|
|
180
|
+
subscription_id?: string | null;
|
|
181
|
+
period_seq?: number | null;
|
|
182
|
+
/**
|
|
183
|
+
* Card-only ids on purchase.disputed. `null` on a storefront chargeback (for example a
|
|
184
|
+
* Steam chargeback, which has no payment intent, charge or dispute id).
|
|
185
|
+
*/
|
|
186
|
+
payment_intent_id?: string | null;
|
|
187
|
+
charge_id?: string | null;
|
|
188
|
+
dispute_id?: string | null;
|
|
189
|
+
/**
|
|
190
|
+
* The rail the purchase was paid on, where the event carries it: `"steam"` on a Steam
|
|
191
|
+
* `purchase.refunded` or `purchase.disputed`.
|
|
192
|
+
*/
|
|
193
|
+
rail?: string;
|
|
194
|
+
/** The Steam transaction id, on a Steam `purchase.refunded` or `purchase.disputed`. */
|
|
195
|
+
steam_transid?: string;
|
|
196
|
+
/** On purchase.refunded: `false` for a partial refund (a Steam partial refund included). */
|
|
197
|
+
fully_refunded?: boolean;
|
|
198
|
+
/** Coins taken back by this event, or `null` when the player has no balance row. */
|
|
199
|
+
currency_debited?: string | null;
|
|
200
|
+
/** The player's balance after this event. Never below zero. */
|
|
201
|
+
new_balance?: string | null;
|
|
202
|
+
/**
|
|
203
|
+
* Merchant of Record accounts only (on `purchase.refunded`, card refunds): the REFUND receipt INVO issued to the
|
|
204
|
+
* buyer. Absent on Open accounts, and while a refund is still pending.
|
|
205
|
+
*/
|
|
206
|
+
receipt_number?: string;
|
|
207
|
+
/** Merchant of Record only: link to the printable refund receipt page. */
|
|
208
|
+
receipt_url?: string;
|
|
209
|
+
[key: string]: unknown;
|
|
210
|
+
}
|
|
211
|
+
interface ItemPurchasedData {
|
|
212
|
+
transaction_id: string;
|
|
213
|
+
order_id: string;
|
|
214
|
+
player_email: string;
|
|
215
|
+
identity_id: string;
|
|
216
|
+
item_id: string;
|
|
217
|
+
item_name: string;
|
|
218
|
+
item_quantity: number;
|
|
219
|
+
unit_price: string;
|
|
220
|
+
total_price: string;
|
|
221
|
+
currency_name: string;
|
|
222
|
+
new_balance: string;
|
|
223
|
+
fee_breakdown?: Record<string, unknown>;
|
|
224
|
+
[key: string]: unknown;
|
|
225
|
+
}
|
|
226
|
+
/** `platform_commerce.purchased` — a Platform Commerce (ecommerce) purchase completed
|
|
227
|
+
* (balance immediately; card after the payment settles). Fulfill card orders on THIS,
|
|
228
|
+
* never on the browser confirmation. */
|
|
229
|
+
interface PlatformCommercePurchasedData {
|
|
230
|
+
transaction_id: string;
|
|
231
|
+
order_id: string | number;
|
|
232
|
+
/** "balance" | "card". */
|
|
233
|
+
funding_source: string;
|
|
234
|
+
player_email: string;
|
|
235
|
+
identity_id: string;
|
|
236
|
+
item_id: string;
|
|
237
|
+
item_name: string;
|
|
238
|
+
item_quantity: number;
|
|
239
|
+
/** Balance leg only — the network-currency amount. The CARD leg carries `total_price_usd`
|
|
240
|
+
* instead (this field is absent there). */
|
|
241
|
+
total_price?: string;
|
|
242
|
+
/** Balance leg only. */
|
|
243
|
+
unit_price?: string;
|
|
244
|
+
currency_name?: string;
|
|
245
|
+
new_balance?: string;
|
|
246
|
+
/** Card leg only (the USD charged). */
|
|
247
|
+
total_price_usd?: string;
|
|
248
|
+
/**
|
|
249
|
+
* `{ total_paid, platform_fee, developer_revenue, ... }`. `platform_fee` is INVO's whole fee
|
|
250
|
+
* and INCLUDES the international card fee; `platform_fee + developer_revenue = total_paid`.
|
|
251
|
+
* Since the 2026-09 pricing it also carries `international_card_fee_usd` (the part of
|
|
252
|
+
* `platform_fee` that is the international card fee, `"0.00"` on a US card and on the
|
|
253
|
+
* balance leg), so the card rate part is `platform_fee - international_card_fee_usd`.
|
|
254
|
+
*/
|
|
255
|
+
fee_breakdown?: Record<string, unknown>;
|
|
256
|
+
/**
|
|
257
|
+
* Additive (2026-09 pricing). The international card fee on this sale, USD decimal string:
|
|
258
|
+
* 1.5% of the listed price (before tax) on a card issued outside the US, `"0.00"` otherwise
|
|
259
|
+
* and on the balance leg. Already INCLUDED in `fee_breakdown.platform_fee`; do not add it
|
|
260
|
+
* again.
|
|
261
|
+
*/
|
|
262
|
+
international_card_fee_usd?: string;
|
|
263
|
+
/**
|
|
264
|
+
* Merchant of Record accounts only (card sales): the receipt INVO issued to the buyer.
|
|
265
|
+
* Absent on Open accounts and storefront rails.
|
|
266
|
+
*/
|
|
267
|
+
receipt_number?: string;
|
|
268
|
+
/** Merchant of Record only: link to the printable receipt page. Anyone with it can read it. */
|
|
269
|
+
receipt_url?: string;
|
|
270
|
+
[key: string]: unknown;
|
|
271
|
+
}
|
|
272
|
+
/** `platform_commerce.refunded`: a Platform Commerce purchase was refunded. INVO's fee is
|
|
273
|
+
* not returned (`fee_retained: true`). On a card refund the fee stays charged to you
|
|
274
|
+
* (`card_fee_charged_to_partner_usd`, `partner_debited_usd`). */
|
|
275
|
+
interface PlatformCommerceRefundedData {
|
|
276
|
+
order_id: string | number;
|
|
277
|
+
/** "balance" | "card". */
|
|
278
|
+
funding_source: string;
|
|
279
|
+
/** Null when the player row no longer exists at refund time. */
|
|
280
|
+
player_email: string | null;
|
|
281
|
+
/** Nullable for the same reason. */
|
|
282
|
+
identity_id?: string | null;
|
|
283
|
+
refunded_amount: string;
|
|
284
|
+
/** `"usd"` (card) or the literal `"currency"` (balance). */
|
|
285
|
+
amount_unit: string;
|
|
286
|
+
fee_retained: boolean;
|
|
287
|
+
/**
|
|
288
|
+
* Merchant of Record accounts only (card refunds): the REFUND receipt INVO issued to the
|
|
289
|
+
* buyer. Absent on Open accounts, and while a refund is still pending.
|
|
290
|
+
*/
|
|
291
|
+
receipt_number?: string;
|
|
292
|
+
/** Merchant of Record only: link to the printable refund receipt page. */
|
|
293
|
+
receipt_url?: string;
|
|
294
|
+
/**
|
|
295
|
+
* Additive (2026-09 pricing), card refunds only: the part of INVO's card fee on this refund
|
|
296
|
+
* that stays charged to you, USD decimal string. The card fee is not returned on a refund.
|
|
297
|
+
*/
|
|
298
|
+
card_fee_charged_to_partner_usd?: string;
|
|
299
|
+
/**
|
|
300
|
+
* Additive (2026-09 pricing), card refunds only: everything this refund takes from your
|
|
301
|
+
* earnings, USD decimal string: your share of the sale reversed plus
|
|
302
|
+
* `card_fee_charged_to_partner_usd`.
|
|
303
|
+
*/
|
|
304
|
+
partner_debited_usd?: string;
|
|
305
|
+
[key: string]: unknown;
|
|
306
|
+
}
|
|
307
|
+
interface TransferEventData {
|
|
308
|
+
transaction_id: string;
|
|
309
|
+
/** "transfer" | "send". */
|
|
310
|
+
flow?: string;
|
|
311
|
+
amount?: string;
|
|
312
|
+
net_amount?: string;
|
|
313
|
+
/**
|
|
314
|
+
* On `transfer.claim_pending` / `transfer.claim_expired`: `"outbound"` on the copy sent to
|
|
315
|
+
* the sending title (drives the sender's UI), `"inbound"` on the copy sent to the
|
|
316
|
+
* destination title (drives the receiving player's UI). A move inside one title sends that
|
|
317
|
+
* title BOTH copies, each with its own `event_id`: dedupe on `event_id`, not
|
|
318
|
+
* `transaction_id`, and act on `direction`.
|
|
319
|
+
*/
|
|
320
|
+
direction?: "inbound" | "outbound" | (string & {});
|
|
321
|
+
/** On inbound claim_pending: the recipient's phone (match to your player). */
|
|
322
|
+
to_phone?: string;
|
|
323
|
+
/** Recipient's opaque identity, present only when the phone maps to a single player. */
|
|
324
|
+
to_identity_id?: string | null;
|
|
325
|
+
/** On `transfer.claim_pending`: the order id of the send or transfer. */
|
|
326
|
+
order_id?: string | null;
|
|
327
|
+
/** On `transfer.claim_pending`: what the recipient receives after fees. */
|
|
328
|
+
net_transfer_amount?: string;
|
|
329
|
+
/** On `transfer.claim_pending`: when the recipient's chance to collect lapses (ISO 8601). */
|
|
330
|
+
claim_code_expires_at?: string | null;
|
|
331
|
+
from_game_id?: string | number;
|
|
332
|
+
to_game_id?: string | number;
|
|
333
|
+
from_player_id?: string | number;
|
|
334
|
+
/** On `transfer.claim_expired` and an expiry `transfer.refunded`: when it expired (ISO 8601). */
|
|
335
|
+
expired_at?: string;
|
|
336
|
+
/**
|
|
337
|
+
* On `transfer.refunded` after an expiry: `"claim_expired"` or `"pin_expired"` (the latter
|
|
338
|
+
* also covers a lapsed in-app approval). Read `expiry_reason` for the precise cause.
|
|
339
|
+
*/
|
|
340
|
+
reason?: string;
|
|
341
|
+
/**
|
|
342
|
+
* Additive. On `transfer.claim_expired` and an expiry `transfer.refunded`: why it lapsed,
|
|
343
|
+
* `"approval_expired"`, `"pin_expired"` or `"claim_expired"`. Absent on older deliveries.
|
|
344
|
+
*/
|
|
345
|
+
expiry_reason?: "approval_expired" | "pin_expired" | "claim_expired" | (string & {});
|
|
346
|
+
/** On `transfer.refunded`: the amount returned to the sender. */
|
|
347
|
+
refunded_amount?: string;
|
|
348
|
+
[key: string]: unknown;
|
|
349
|
+
}
|
|
350
|
+
/**
|
|
351
|
+
* `payout.status_changed`: a payout of your balance to your bank moved to a new status. The
|
|
352
|
+
* money fields are decimal strings (USD) or `null`. The payout fee fields are `null` on a
|
|
353
|
+
* payout recorded before the fee existed.
|
|
354
|
+
*/
|
|
355
|
+
/** Payout statuses. `cancelled` and `returned` are 3.25.0. */
|
|
356
|
+
type PayoutStatus = "requested" | "approved" | "processing" | "completed" | "rejected" | "failed" | "cancelled" | "returned" | (string & {});
|
|
357
|
+
/** Why a completed payout came back. A creator payout always reads `"returned"`. */
|
|
358
|
+
type ReturnReasonCode = "account_closed" | "no_account" | "invalid_account" | "refused" | "other" | "returned" | (string & {});
|
|
359
|
+
interface PayoutStatusChangedData {
|
|
360
|
+
payout_id: string | number;
|
|
361
|
+
status: PayoutStatus;
|
|
362
|
+
previous_status: PayoutStatus | null;
|
|
363
|
+
requested_amount_usd: string | null;
|
|
364
|
+
/** The payout fee rate applied, percent (for example `"1"`). */
|
|
365
|
+
offboarding_fee_pct?: string | null;
|
|
366
|
+
/** The payout fee deducted from this payout. */
|
|
367
|
+
offboarding_fee_usd?: string | null;
|
|
368
|
+
/** What reaches your bank: the requested amount less the payout fee. */
|
|
369
|
+
net_payout_usd?: string | null;
|
|
370
|
+
/** The cap on the payout fee per payout (for example `"500.00"`); `null` means no cap. */
|
|
371
|
+
offboarding_fee_cap_usd?: string | null;
|
|
372
|
+
/**
|
|
373
|
+
* Additive (3.25.0). On a creator payout, the creator INVO paid (`cp_...`); `null` on a
|
|
374
|
+
* payout to your own bank. Never carries the creator's bank or personal details.
|
|
375
|
+
*/
|
|
376
|
+
payee_id?: string | null;
|
|
377
|
+
/** Additive (3.25.0). `"standard"` or `"manual"`; `null` before approval. */
|
|
378
|
+
payout_method?: "standard" | "manual" | (string & {}) | null;
|
|
379
|
+
/** Additive (3.25.0). On `status: "returned"`: when the receiving bank sent it back. */
|
|
380
|
+
returned_at?: string | null;
|
|
381
|
+
/** On `status: "returned"`. Always `"returned"` on a creator payout. */
|
|
382
|
+
return_reason_code?: ReturnReasonCode | null;
|
|
383
|
+
/** Additive (3.26.0). A note INVO wrote for you, or `null`. */
|
|
384
|
+
partner_message?: string | null;
|
|
385
|
+
/** Additive (3.26.0). The payout waits for the account owner's confirmation in the console. */
|
|
386
|
+
owner_confirmation_required?: boolean;
|
|
387
|
+
[key: string]: unknown;
|
|
388
|
+
}
|
|
389
|
+
/** Creator statuses (3.25.0). */
|
|
390
|
+
type PayeeStatus = "invited" | "details_submitted" | "verified" | "rejected" | "suspended" | "expired" | "closed" | (string & {});
|
|
391
|
+
/**
|
|
392
|
+
* `payee.status_changed` (3.25.0): a creator you registered for creator payouts was
|
|
393
|
+
* registered or changed status. Never carries the creator's name or email. Subscribe to it
|
|
394
|
+
* by name.
|
|
395
|
+
*/
|
|
396
|
+
interface PayeeStatusChangedData {
|
|
397
|
+
payee_id: string;
|
|
398
|
+
partner_reference: string;
|
|
399
|
+
status: PayeeStatus;
|
|
400
|
+
previous_status: PayeeStatus | null;
|
|
401
|
+
payee_type: "individual" | "business" | (string & {});
|
|
402
|
+
country: string;
|
|
403
|
+
created_via: "api" | "console" | (string & {});
|
|
404
|
+
status_changed_at: string;
|
|
405
|
+
[key: string]: unknown;
|
|
406
|
+
}
|
|
407
|
+
/**
|
|
408
|
+
* `player.phone_changed`: a player's phone changed (confirmed by the player, or changed by
|
|
409
|
+
* INVO support). Sent to every game the player is in. `new_phone` is present only for the
|
|
410
|
+
* game that requested the change (`new_phone_included: true`); every other game, and every
|
|
411
|
+
* game on a support change, gets `new_phone_masked` only. Store the new `identity_id` and
|
|
412
|
+
* re-mint the player's token. Never push the number you have stored back to INVO; if you
|
|
413
|
+
* need the full new number and did not receive it, ask the player.
|
|
414
|
+
*/
|
|
415
|
+
interface PlayerPhoneChangedData {
|
|
416
|
+
player_email: string;
|
|
417
|
+
previous_phone_masked: string | null;
|
|
418
|
+
new_phone_masked: string | null;
|
|
419
|
+
/** `true` only for the game that requested the change; then `new_phone` is present. */
|
|
420
|
+
new_phone_included: boolean;
|
|
421
|
+
/** The full new number, E.164. Present only when `new_phone_included` is `true`. */
|
|
422
|
+
new_phone?: string;
|
|
423
|
+
changed_at: string;
|
|
424
|
+
/** `"player"` (confirmed by the player) or `"support"` (changed by INVO support). */
|
|
425
|
+
source: "player" | "support" | (string & {});
|
|
426
|
+
/** The player's new identity id. */
|
|
427
|
+
identity_id: string;
|
|
428
|
+
previous_identity_id: string;
|
|
429
|
+
[key: string]: unknown;
|
|
430
|
+
}
|
|
431
|
+
/**
|
|
432
|
+
* `identity.passkey_reset`: a player replaced a lost INVO passkey through recovery, on
|
|
433
|
+
* INVO's approval or claim page or in your app through `recoveryBegin` /
|
|
434
|
+
* `recoveryComplete` (the in-app path sends it since backend 2026-10-12). Sent to the
|
|
435
|
+
* game the recovery ran in. Sending money out is paused for that player until
|
|
436
|
+
* `cooldown_until`; receiving and collecting still work. Tell the player, or flag the
|
|
437
|
+
* account, if they did not start it.
|
|
438
|
+
*/
|
|
439
|
+
interface IdentityPasskeyResetData {
|
|
440
|
+
/** The player's opaque identity id (the same id `player.phone_changed` carries). */
|
|
441
|
+
identity_id: string;
|
|
442
|
+
/** `"hosted_device"`, `"hosted_claim"` or `"sdk"`. */
|
|
443
|
+
reset_via: "hosted_device" | "hosted_claim" | "sdk" | (string & {});
|
|
444
|
+
/** ISO timestamp: until when sending money out is paused for this player. */
|
|
445
|
+
cooldown_until: string | null;
|
|
446
|
+
/** How many passkeys were switched off. */
|
|
447
|
+
deactivated_count: number;
|
|
448
|
+
[key: string]: unknown;
|
|
449
|
+
}
|
|
450
|
+
/**
|
|
451
|
+
* The block every subscription event carries EXCEPT `subscription.renewed` and
|
|
452
|
+
* `subscription.refunded`, which have their own shapes. `identity_id` is an opaque,
|
|
453
|
+
* stable member id across INVO events; it is not the email.
|
|
454
|
+
*/
|
|
455
|
+
interface SubscriptionEventCommon {
|
|
456
|
+
subscription_id: string;
|
|
457
|
+
item_id: string;
|
|
458
|
+
item_name: string | null;
|
|
459
|
+
player_email: string;
|
|
460
|
+
identity_id: string;
|
|
461
|
+
status: string;
|
|
462
|
+
/** The current price, decimal string. */
|
|
463
|
+
amount_usd: string;
|
|
464
|
+
interval: string;
|
|
465
|
+
interval_count: number;
|
|
466
|
+
period_seq: number;
|
|
467
|
+
current_period_start: string | null;
|
|
468
|
+
current_period_end: string | null;
|
|
469
|
+
next_charge_at: string | null;
|
|
470
|
+
cancel_at_period_end: boolean;
|
|
471
|
+
/** "card" | "steam". */
|
|
472
|
+
funding_rail: string;
|
|
473
|
+
steam_agreement_status: string | null;
|
|
474
|
+
metadata: Record<string, unknown> | null;
|
|
475
|
+
[key: string]: unknown;
|
|
476
|
+
}
|
|
477
|
+
/**
|
|
478
|
+
* The two keys an event about period 1 of a PAID trial carries (`subscription.payment_failed`,
|
|
479
|
+
* `past_due`, `authentication_required` and `expired`). The shared `amount_usd` is the regular
|
|
480
|
+
* price; `amount_due_usd` and `trial_amount_usd` are the trial price. Absent on every other
|
|
481
|
+
* event of these types, so test for presence.
|
|
482
|
+
*/
|
|
483
|
+
interface SubscriptionTrialEventFields {
|
|
484
|
+
/** `true` when present. */
|
|
485
|
+
is_trial?: boolean;
|
|
486
|
+
/** The paid-trial price, decimal string. */
|
|
487
|
+
trial_amount_usd?: string;
|
|
488
|
+
}
|
|
489
|
+
/**
|
|
490
|
+
* How a renewal was funded.
|
|
491
|
+
*
|
|
492
|
+
* Card rail (card only since 2026-09-17): the card pays the full price, so
|
|
493
|
+
* `balance_applied_coins` is always `"0.00"`, `card_charged_usd` is the price, `minted_coins`
|
|
494
|
+
* equals the event's `amount_coins`, and `new_balance` is the member's unchanged balance.
|
|
495
|
+
* Steam rail: the wallet is spent first and Steam tops up the shortfall only.
|
|
496
|
+
*/
|
|
497
|
+
interface SubscriptionRenewalFunding {
|
|
498
|
+
/** The pre-existing wallet portion, in coins. Always `"0.00"` on the card rail. */
|
|
499
|
+
balance_applied_coins: string;
|
|
500
|
+
/** On the card rail, the full period price. */
|
|
501
|
+
card_charged_usd: string;
|
|
502
|
+
/** "card" | "steam". */
|
|
503
|
+
rail: string;
|
|
504
|
+
steam_charged_usd: string;
|
|
505
|
+
minted_coins: string;
|
|
506
|
+
new_balance: string;
|
|
507
|
+
[key: string]: unknown;
|
|
508
|
+
}
|
|
509
|
+
/**
|
|
510
|
+
* The fee split for one renewal. On the card rail INVO's fee (`invo_fee_usd`) is 3.5% + $0.30
|
|
511
|
+
* on Open (5.5% + $0.50 on Merchant of Record) of the listed price (before tax). The 1.5%
|
|
512
|
+
* international card fee on a card issued outside the US is NOT inside `invo_fee_usd`: it is
|
|
513
|
+
* reported separately as `international_card_fee_usd` (also `pass_through_fees_usd`) and charged
|
|
514
|
+
* to you on top. Read the figures; do not recompute them. On Steam, `basis` is
|
|
515
|
+
* `"steam_net"` and `total_usd` is what the coins are worth after Valve's share and VAT, NOT the price (the price is the
|
|
516
|
+
* event's top-level `amount_usd`).
|
|
517
|
+
*/
|
|
518
|
+
interface SubscriptionRenewalSplit {
|
|
519
|
+
total_usd: string;
|
|
520
|
+
/** "price" (card) | "steam_net" (Steam). */
|
|
521
|
+
basis: string;
|
|
522
|
+
invo_fee_usd: string;
|
|
523
|
+
partner_revenue_usd: string;
|
|
524
|
+
invo_fee_coins: string;
|
|
525
|
+
partner_revenue_coins: string;
|
|
526
|
+
invo_fee_percent: string;
|
|
527
|
+
/**
|
|
528
|
+
* The international card fee charged to you on this renewal, USD decimal string, billed on
|
|
529
|
+
* top of `invo_fee_usd`: `partner_revenue_usd` stays the gross figure and does not include
|
|
530
|
+
* it. Since the 2026-09 pricing it is the flat international card fee, and
|
|
531
|
+
* `international_card_fee_usd` carries the same figure under its own name. They are ONE
|
|
532
|
+
* charge reported twice: never add the two together. `"0.00"` on a US card.
|
|
533
|
+
*/
|
|
534
|
+
pass_through_fees_usd?: string;
|
|
535
|
+
/** `"recorded"`, `"none"`, `"pending"` or `"not_applicable"` (no card charge). Treat unknown values as informational. */
|
|
536
|
+
pass_through_status?: string;
|
|
537
|
+
/**
|
|
538
|
+
* Additive (2026-09 pricing). The international card fee on this renewal: 1.5% of the listed
|
|
539
|
+
* price (before tax) on a card issued outside the US, `"0.00"` otherwise, while pending, and
|
|
540
|
+
* on a charge opened before the 2026-09 pricing. The same figure as
|
|
541
|
+
* `pass_through_fees_usd`; do not add them.
|
|
542
|
+
*/
|
|
543
|
+
international_card_fee_usd?: string;
|
|
544
|
+
[key: string]: unknown;
|
|
545
|
+
}
|
|
546
|
+
/** Revenue-share attribution on a renewal. INVO pays nothing (`settled_by_invo: false`). */
|
|
547
|
+
interface SubscriptionRevenueShareAttribution {
|
|
548
|
+
recipient_player_id: number;
|
|
549
|
+
percent: string;
|
|
550
|
+
base_usd: string;
|
|
551
|
+
attributed_amount_usd: string;
|
|
552
|
+
settled_by_invo: boolean;
|
|
553
|
+
[key: string]: unknown;
|
|
554
|
+
}
|
|
555
|
+
/**
|
|
556
|
+
* `subscription.renewed`: THE SOURCE OF TRUTH FOR ENTITLEMENT. Fires once per successfully
|
|
557
|
+
* charged period, including period 1. Extend access to `period_end` (the new `paid_through`).
|
|
558
|
+
* `period_start`/`period_end` are the period JUST PAID; `current_period_*` and
|
|
559
|
+
* `next_charge_at` are the NEW window. `mint_order_id` is never `null` on a card renewal; on
|
|
560
|
+
* Steam it is `null` when the wallet covered the period.
|
|
561
|
+
*
|
|
562
|
+
* Every paid card renewal also emits `purchase.completed` (with
|
|
563
|
+
* `data.metadata.source === "subscription_renewal"`) for the coins its charge minted. Do not
|
|
564
|
+
* grant anything from that event; its `order_id` is this event's `mint_order_id`.
|
|
565
|
+
*/
|
|
566
|
+
interface SubscriptionRenewedData {
|
|
567
|
+
subscription_id: string;
|
|
568
|
+
item_id: string;
|
|
569
|
+
period_seq: number;
|
|
570
|
+
/**
|
|
571
|
+
* `true` only on the event for period 1 of a PAID trial, whose `amount_usd` is then the trial
|
|
572
|
+
* price; `false` on every other renewal. INVO sends it on every event from 2026-09-23 on;
|
|
573
|
+
* optional here only because an event from an older backend does not carry it.
|
|
574
|
+
*/
|
|
575
|
+
is_trial?: boolean;
|
|
576
|
+
transaction_id: string;
|
|
577
|
+
order_id: string;
|
|
578
|
+
mint_order_id: string | null;
|
|
579
|
+
player_email: string;
|
|
580
|
+
identity_id: string;
|
|
581
|
+
/** The price the period was billed at (a staged change appears from the period it applies to). */
|
|
582
|
+
amount_usd: string;
|
|
583
|
+
/** What the period was worth in coins. */
|
|
584
|
+
amount_coins: string;
|
|
585
|
+
period_start: string;
|
|
586
|
+
period_end: string;
|
|
587
|
+
current_period_start: string;
|
|
588
|
+
current_period_end: string;
|
|
589
|
+
next_charge_at: string | null;
|
|
590
|
+
funding: SubscriptionRenewalFunding;
|
|
591
|
+
split: SubscriptionRenewalSplit;
|
|
592
|
+
revenue_share_attribution: SubscriptionRevenueShareAttribution | null;
|
|
593
|
+
metadata: Record<string, unknown> | null;
|
|
594
|
+
/**
|
|
595
|
+
* Merchant of Record accounts only (card sales): the receipt INVO issued to the buyer.
|
|
596
|
+
* Absent on Open accounts and storefront rails.
|
|
597
|
+
*/
|
|
598
|
+
receipt_number?: string;
|
|
599
|
+
/** Merchant of Record only: link to the printable receipt page. Anyone with it can read it. */
|
|
600
|
+
receipt_url?: string;
|
|
601
|
+
[key: string]: unknown;
|
|
602
|
+
}
|
|
603
|
+
/**
|
|
604
|
+
* `subscription.payment_failed`: fires on EVERY failed attempt while the member still has
|
|
605
|
+
* access. Does not revoke anything. On the final failure `retry_at` and `grace_period_end`
|
|
606
|
+
* are `null`, `retries_remaining` is `0`, and `subscription.expired` follows.
|
|
607
|
+
*/
|
|
608
|
+
interface SubscriptionPaymentFailedData extends SubscriptionEventCommon, SubscriptionTrialEventFields {
|
|
609
|
+
attempt_no: number;
|
|
610
|
+
period_start: string;
|
|
611
|
+
period_end: string;
|
|
612
|
+
amount_due_usd: string;
|
|
613
|
+
/** "card_declined" | "insufficient_funds" | "error". */
|
|
614
|
+
outcome: string;
|
|
615
|
+
reason: string;
|
|
616
|
+
/**
|
|
617
|
+
* Why the attempt failed. Card rail: `card_declined`, `no_payment_method` (no saved card;
|
|
618
|
+
* the coin wallet never pays a card subscription), `wallet_only` (a deprecated wallet-only
|
|
619
|
+
* subscription, which can never be paid), `wallet_negative` (the member's coin balance is
|
|
620
|
+
* below zero; nothing was charged), `card_expired`, `card_detached`, `card_mismatch`,
|
|
621
|
+
* `no_customer_snapshot`, `processing_error`, `settlement_error`. Steam: `steam_*` codes.
|
|
622
|
+
* Treat unknown values as a generic failure.
|
|
623
|
+
*/
|
|
624
|
+
failure_code: string;
|
|
625
|
+
failure_message: string | null;
|
|
626
|
+
first_failure: boolean;
|
|
627
|
+
retry_at: string | null;
|
|
628
|
+
retries_remaining: number;
|
|
629
|
+
grace_period_end: string | null;
|
|
630
|
+
access_retained: boolean;
|
|
631
|
+
}
|
|
632
|
+
/** `subscription.past_due`: fires ONCE when the subscription enters `past_due`, not on every retry. */
|
|
633
|
+
interface SubscriptionPastDueData extends SubscriptionEventCommon, SubscriptionTrialEventFields {
|
|
634
|
+
amount_due_usd: string;
|
|
635
|
+
grace_period_end: string | null;
|
|
636
|
+
retry_at: string | null;
|
|
637
|
+
retries_remaining: number;
|
|
638
|
+
access_retained: boolean;
|
|
639
|
+
}
|
|
640
|
+
/**
|
|
641
|
+
* `subscription.authentication_required`: NOT a failure. Card rail only. Nothing was
|
|
642
|
+
* charged and no retry was consumed. Relay `confirmation_url` (a single-use bearer link)
|
|
643
|
+
* to the member before `expires_at`. `card_amount_usd` is what the card is asked for: since
|
|
644
|
+
* 2026-09-17 the full period price, the same figure as `amount_due_usd` (a challenge opened
|
|
645
|
+
* before that date can still show the older wallet-shortfall figure).
|
|
646
|
+
*/
|
|
647
|
+
interface SubscriptionAuthenticationRequiredData extends SubscriptionEventCommon, SubscriptionTrialEventFields {
|
|
648
|
+
attempt_no: number;
|
|
649
|
+
period_start: string;
|
|
650
|
+
period_end: string;
|
|
651
|
+
amount_due_usd: string;
|
|
652
|
+
card_amount_usd: string;
|
|
653
|
+
confirmation_url: string;
|
|
654
|
+
expires_at: string;
|
|
655
|
+
reason: string;
|
|
656
|
+
access_retained: boolean;
|
|
657
|
+
retry_consumed: boolean;
|
|
658
|
+
}
|
|
659
|
+
/**
|
|
660
|
+
* `subscription.canceled`: fires once, at the moment cancellation is requested, in both
|
|
661
|
+
* modes. Revoke at `access_until`. `canceled_by` is `"partner"` for your API call and
|
|
662
|
+
* `"steam"` when the member cancelled the agreement from their Steam account. A full refund
|
|
663
|
+
* also cancels the subscription immediately: that event carries `canceled_by: "partner"` and
|
|
664
|
+
* `cancel_cause: "full_refund"`; it and `subscription.refunded` are sent together and may arrive in any order.
|
|
665
|
+
*/
|
|
666
|
+
interface SubscriptionCanceledData extends SubscriptionEventCommon {
|
|
667
|
+
effective_at: string;
|
|
668
|
+
canceled_at: string | null;
|
|
669
|
+
ended_at: string | null;
|
|
670
|
+
access_until: string | null;
|
|
671
|
+
paid_through: string | null;
|
|
672
|
+
reason: string | null;
|
|
673
|
+
/** "partner" | "steam". */
|
|
674
|
+
canceled_by: string;
|
|
675
|
+
/** Present only when the cancellation was a side effect: `"full_refund"`. Absent on an ordinary cancel. */
|
|
676
|
+
cancel_cause?: string;
|
|
677
|
+
}
|
|
678
|
+
/**
|
|
679
|
+
* `subscription.expired`: THE EVENT THAT REVOKES ENTITLEMENT. Revoke at `final_period_end`
|
|
680
|
+
* (the last instant the member paid for; `null` if nothing was ever collected), not at
|
|
681
|
+
* `ended_at`. A never-authorised Steam row carries `failure_code: "steam_authorization_abandoned"`.
|
|
682
|
+
* `failure_code: "steam_containment"` is no longer sent (spending is not restricted by which
|
|
683
|
+
* rail bought the currency). A refused PAID-trial charge ends the subscription at once with
|
|
684
|
+
* `expire_cause: "trial_payment_failed"`, `is_trial: true`, `period_seq: 1` and
|
|
685
|
+
* `final_period_end: null` (it follows a `subscription.payment_failed` with
|
|
686
|
+
* `retries_remaining: 0`).
|
|
687
|
+
*/
|
|
688
|
+
interface SubscriptionExpiredData extends SubscriptionEventCommon, SubscriptionTrialEventFields {
|
|
689
|
+
failed_period_start: string | null;
|
|
690
|
+
failed_period_end: string | null;
|
|
691
|
+
final_attempt_no: number | null;
|
|
692
|
+
attempts_used: number | null;
|
|
693
|
+
failure_code: string | null;
|
|
694
|
+
failure_message: string | null;
|
|
695
|
+
ended_at: string;
|
|
696
|
+
final_period_end: string | null;
|
|
697
|
+
access_retained: boolean;
|
|
698
|
+
/**
|
|
699
|
+
* Present only when the expiry was not the ordinary end of dunning: `"trial_payment_failed"`
|
|
700
|
+
* when a paid trial's own charge was refused. Absent on an ordinary expiry.
|
|
701
|
+
*/
|
|
702
|
+
expire_cause?: string;
|
|
703
|
+
}
|
|
704
|
+
/** The `refund` block on `subscription.refunded`. */
|
|
705
|
+
interface SubscriptionRefundDetail {
|
|
706
|
+
/** "wallet" | "card" | "mixed". */
|
|
707
|
+
funding_shape: string;
|
|
708
|
+
/** Signed; can be negative. */
|
|
709
|
+
balance_delta_coins: string;
|
|
710
|
+
card_refunded_usd: string;
|
|
711
|
+
processor_refund_adopted: boolean;
|
|
712
|
+
new_balance: string;
|
|
713
|
+
invo_fee_retained: boolean;
|
|
714
|
+
partner_revenue_reversed_usd: string;
|
|
715
|
+
/** "full" | "prorata". */
|
|
716
|
+
partner_revenue_reversal_mode: string;
|
|
717
|
+
/**
|
|
718
|
+
* Additive (2026-09-17). Since 2026-09-28 (D-PRICE-012) always `"0.00"`: a card refund charges
|
|
719
|
+
* INVO's card fee (`card_fee_charged_to_partner_usd`), not a separate processor fee. Older
|
|
720
|
+
* events carried the processor fee here.
|
|
721
|
+
*/
|
|
722
|
+
processing_fee_usd?: string;
|
|
723
|
+
/** Additive (2026-09-17). "actual" | "estimated" | "none"; `"none"` since 2026-09-28. */
|
|
724
|
+
processing_fee_basis?: string;
|
|
725
|
+
/** Additive (2026-09-17). Always "partner". */
|
|
726
|
+
processing_fee_borne_by?: string;
|
|
727
|
+
/**
|
|
728
|
+
* Additive (2026-09-17). Everything this refund took from your revenue; since 2026-09-28 the
|
|
729
|
+
* same value as `partner_debited_usd`.
|
|
730
|
+
*/
|
|
731
|
+
partner_total_reversed_usd?: string;
|
|
732
|
+
/**
|
|
733
|
+
* Additive (2026-09-28, D-PRICE-012). INVO's card fee on the refunded part, charged to you
|
|
734
|
+
* (the card fee is not returned on a refund). `"0.00"` on a coin refund. Absent on older events.
|
|
735
|
+
*/
|
|
736
|
+
card_fee_charged_to_partner_usd?: string;
|
|
737
|
+
/**
|
|
738
|
+
* Additive (2026-09-28, D-PRICE-012). Your whole debit: `partner_revenue_reversed_usd` plus
|
|
739
|
+
* `card_fee_charged_to_partner_usd`, the refunded price before tax on a card refund. Absent on
|
|
740
|
+
* older events; read `partner_total_reversed_usd` there.
|
|
741
|
+
*/
|
|
742
|
+
partner_debited_usd?: string;
|
|
743
|
+
[key: string]: unknown;
|
|
744
|
+
}
|
|
745
|
+
/**
|
|
746
|
+
* `subscription.refunded`: its own shape. Your revenue for the refunded portion is
|
|
747
|
+
* reversed (`refund.partner_revenue_reversed_usd`); INVO's fee is retained; on a card refund
|
|
748
|
+
* you bear the whole refunded amount, INVO's card fee included (`refund.card_fee_charged_to_partner_usd`,
|
|
749
|
+
* since 2026-09-28). "What did I earn" subtracts `refund.partner_debited_usd` (older events:
|
|
750
|
+
* `refund.partner_total_reversed_usd`, then `partner_revenue_reversed_usd`).
|
|
751
|
+
* A FULL refund cancels the subscription (`subscription_canceled: true`), and a
|
|
752
|
+
* `subscription.canceled` with `cancel_cause: "full_refund"` is sent with it (sent together and may arrive in any order).
|
|
753
|
+
* A partial one does not.
|
|
754
|
+
*/
|
|
755
|
+
interface SubscriptionRefundedData {
|
|
756
|
+
subscription_id: string;
|
|
757
|
+
item_id: string;
|
|
758
|
+
period_seq: number;
|
|
759
|
+
transaction_id: string;
|
|
760
|
+
client_request_id: string;
|
|
761
|
+
player_email: string;
|
|
762
|
+
identity_id: string;
|
|
763
|
+
/** The amount refunded by this call. */
|
|
764
|
+
amount_usd: string;
|
|
765
|
+
total_refunded_amount_usd: string;
|
|
766
|
+
period_amount_usd: string;
|
|
767
|
+
is_full_refund: boolean;
|
|
768
|
+
reason: string | null;
|
|
769
|
+
period_status: string;
|
|
770
|
+
refund: SubscriptionRefundDetail;
|
|
771
|
+
revenue_share_attribution: Record<string, unknown> | null;
|
|
772
|
+
metadata: Record<string, unknown> | null;
|
|
773
|
+
/** Additive (2026-09-17). "self_serve" | "approved_request". */
|
|
774
|
+
initiation?: string;
|
|
775
|
+
/** Additive (2026-09-17). The refund request INVO approved, or `null`. */
|
|
776
|
+
refund_request_id?: string | null;
|
|
777
|
+
/** Additive (2026-09-17). `true` when this refund cancelled the subscription. */
|
|
778
|
+
subscription_canceled?: boolean;
|
|
779
|
+
/**
|
|
780
|
+
* Merchant of Record accounts only (card refunds): the REFUND receipt INVO issued to the
|
|
781
|
+
* buyer. Absent on Open accounts, and while a refund is still pending.
|
|
782
|
+
*/
|
|
783
|
+
receipt_number?: string;
|
|
784
|
+
/** Merchant of Record only: link to the printable refund receipt page. */
|
|
785
|
+
receipt_url?: string;
|
|
786
|
+
[key: string]: unknown;
|
|
787
|
+
}
|
|
788
|
+
/**
|
|
789
|
+
* `subscription.refund_requested`: a refund over your game's daily self-serve limit became a
|
|
790
|
+
* refund request (your `/refund` call answered 202 `pending_approval`). Nothing has moved.
|
|
791
|
+
* Not the common subscription block: it describes the request.
|
|
792
|
+
*/
|
|
793
|
+
interface SubscriptionRefundRequestData {
|
|
794
|
+
/** `SRR...`. */
|
|
795
|
+
request_id: string;
|
|
796
|
+
/** "pending" | "approved" | "rejected". */
|
|
797
|
+
status: string;
|
|
798
|
+
subscription_id: string;
|
|
799
|
+
item_id: string;
|
|
800
|
+
period_seq: number;
|
|
801
|
+
client_request_id: string;
|
|
802
|
+
/** The amount asked for. */
|
|
803
|
+
amount_usd: string;
|
|
804
|
+
/** Your reason, or `null` when you sent none. */
|
|
805
|
+
reason: string | null;
|
|
806
|
+
requested_at: string;
|
|
807
|
+
daily_cap_usd: string;
|
|
808
|
+
executed_today_usd: string;
|
|
809
|
+
player_email: string | null;
|
|
810
|
+
identity_id: string | null;
|
|
811
|
+
metadata: Record<string, unknown> | null;
|
|
812
|
+
[key: string]: unknown;
|
|
813
|
+
}
|
|
814
|
+
/**
|
|
815
|
+
* `subscription.refund_approved`: INVO approved the request and the refund ran;
|
|
816
|
+
* `subscription.refunded` (and `subscription.canceled` on a full refund) are sent in the same
|
|
817
|
+
* step and may arrive before or after this event. A retry of your `clientRequestId` now returns the receipt.
|
|
818
|
+
*/
|
|
819
|
+
interface SubscriptionRefundApprovedData extends SubscriptionRefundRequestData {
|
|
820
|
+
decided_at: string;
|
|
821
|
+
/** The refund transaction. */
|
|
822
|
+
transaction_id: string;
|
|
823
|
+
}
|
|
824
|
+
/**
|
|
825
|
+
* `subscription.refund_rejected`: INVO rejected the request; nothing moved. Your
|
|
826
|
+
* `clientRequestId` now answers `409 REFUND_REQUEST_REJECTED`; use a new one to try again.
|
|
827
|
+
*/
|
|
828
|
+
interface SubscriptionRefundRejectedData extends SubscriptionRefundRequestData {
|
|
829
|
+
decided_at: string;
|
|
830
|
+
decision_reason: string | null;
|
|
831
|
+
}
|
|
832
|
+
type PurchaseEventType = "purchase.failed" | "purchase.refunded" | "purchase.disputed" | "purchase.fraud_warning";
|
|
833
|
+
type TransferEventType = "transfer.sent" | "transfer.received" | "transfer.claim_pending" | "transfer.claim_expired" | "transfer.refunded";
|
|
834
|
+
/**
|
|
835
|
+
* A verified webhook event. Discriminate on `event_type` to narrow `data`.
|
|
836
|
+
* Unknown/future event types fall through to the generic member (data is a record).
|
|
837
|
+
*/
|
|
838
|
+
type InvoWebhookEvent = (WebhookBase & {
|
|
839
|
+
event_type: "purchase.completed";
|
|
840
|
+
data: PurchaseCompletedData;
|
|
841
|
+
}) | (WebhookBase & {
|
|
842
|
+
event_type: "item.purchased";
|
|
843
|
+
data: ItemPurchasedData;
|
|
844
|
+
}) | (WebhookBase & {
|
|
845
|
+
event_type: "platform_commerce.purchased";
|
|
846
|
+
data: PlatformCommercePurchasedData;
|
|
847
|
+
}) | (WebhookBase & {
|
|
848
|
+
event_type: "platform_commerce.refunded";
|
|
849
|
+
data: PlatformCommerceRefundedData;
|
|
850
|
+
}) | (WebhookBase & {
|
|
851
|
+
event_type: PurchaseEventType;
|
|
852
|
+
data: PurchaseEventData;
|
|
853
|
+
}) | (WebhookBase & {
|
|
854
|
+
event_type: TransferEventType;
|
|
855
|
+
data: TransferEventData;
|
|
856
|
+
}) | (WebhookBase & {
|
|
857
|
+
event_type: "subscription.renewed";
|
|
858
|
+
data: SubscriptionRenewedData;
|
|
859
|
+
}) | (WebhookBase & {
|
|
860
|
+
event_type: "subscription.payment_failed";
|
|
861
|
+
data: SubscriptionPaymentFailedData;
|
|
862
|
+
}) | (WebhookBase & {
|
|
863
|
+
event_type: "subscription.past_due";
|
|
864
|
+
data: SubscriptionPastDueData;
|
|
865
|
+
}) | (WebhookBase & {
|
|
866
|
+
event_type: "subscription.authentication_required";
|
|
867
|
+
data: SubscriptionAuthenticationRequiredData;
|
|
868
|
+
}) | (WebhookBase & {
|
|
869
|
+
event_type: "subscription.canceled";
|
|
870
|
+
data: SubscriptionCanceledData;
|
|
871
|
+
}) | (WebhookBase & {
|
|
872
|
+
event_type: "subscription.expired";
|
|
873
|
+
data: SubscriptionExpiredData;
|
|
874
|
+
}) | (WebhookBase & {
|
|
875
|
+
event_type: "subscription.refunded";
|
|
876
|
+
data: SubscriptionRefundedData;
|
|
877
|
+
}) | (WebhookBase & {
|
|
878
|
+
event_type: "subscription.refund_requested";
|
|
879
|
+
data: SubscriptionRefundRequestData;
|
|
880
|
+
}) | (WebhookBase & {
|
|
881
|
+
event_type: "subscription.refund_approved";
|
|
882
|
+
data: SubscriptionRefundApprovedData;
|
|
883
|
+
}) | (WebhookBase & {
|
|
884
|
+
event_type: "subscription.refund_rejected";
|
|
885
|
+
data: SubscriptionRefundRejectedData;
|
|
886
|
+
}) | (WebhookBase & {
|
|
887
|
+
event_type: "payout.status_changed";
|
|
888
|
+
data: PayoutStatusChangedData;
|
|
889
|
+
}) | (WebhookBase & {
|
|
890
|
+
event_type: "payee.status_changed";
|
|
891
|
+
data: PayeeStatusChangedData;
|
|
892
|
+
}) | (WebhookBase & {
|
|
893
|
+
event_type: "player.phone_changed";
|
|
894
|
+
data: PlayerPhoneChangedData;
|
|
895
|
+
}) | (WebhookBase & {
|
|
896
|
+
event_type: "identity.passkey_reset";
|
|
897
|
+
data: IdentityPasskeyResetData;
|
|
898
|
+
}) | (WebhookBase & {
|
|
899
|
+
event_type: "webhook.test";
|
|
900
|
+
data: Record<string, unknown>;
|
|
901
|
+
}) | (WebhookBase & {
|
|
902
|
+
event_type: string;
|
|
903
|
+
data: Record<string, unknown>;
|
|
904
|
+
});
|
|
905
|
+
/**
|
|
906
|
+
* Verify an Invo webhook and return the parsed, typed event. **Synchronous; uses
|
|
907
|
+
* `node:crypto`** — for non-Node runtimes (Cloudflare Workers, Deno, Vercel/Netlify
|
|
908
|
+
* Edge, Bun edge) use {@link verifyWebhookAsync}.
|
|
909
|
+
*
|
|
910
|
+
* @param rawBody The exact raw request body (bytes or string) — never a re-serialized object.
|
|
911
|
+
* @param signatureHeader The `X-Invo-Signature` header value.
|
|
912
|
+
* @param secret Your signing secret, or an array (to accept old + new during rotation).
|
|
913
|
+
* @throws InvoError (status 0): WEBHOOK_SIGNATURE_MISSING | WEBHOOK_SECRET_MISSING |
|
|
914
|
+
* WEBHOOK_TIMESTAMP_EXPIRED | WEBHOOK_SIGNATURE_INVALID | WEBHOOK_MALFORMED.
|
|
915
|
+
*/
|
|
916
|
+
declare function verifyWebhook(rawBody: string | Uint8Array, signatureHeader: string | null | undefined, secret: string | string[], opts?: VerifyWebhookOptions): InvoWebhookEvent;
|
|
917
|
+
/**
|
|
918
|
+
* Verify an INVO webhook signature (3.29.0): the same check as {@link verifyWebhook}, named for
|
|
919
|
+
* the template integration guide. `X-Invo-Signature: t=<unix>,v1=<hex HMAC-SHA256 of "<t>." +
|
|
920
|
+
* raw body>`, 300-second tolerance, constant-time compare; pass several secrets while rotating.
|
|
921
|
+
* Returns the parsed event, or throws {@link InvoError} (status 0).
|
|
922
|
+
*/
|
|
923
|
+
declare function verifyInvoSignature(rawBody: string | Uint8Array, signatureHeader: string | null | undefined, secrets: string | string[], opts?: VerifyWebhookOptions): InvoWebhookEvent;
|
|
924
|
+
/**
|
|
925
|
+
* Cross-runtime async variant of {@link verifyWebhook}. Uses the Web Crypto API
|
|
926
|
+
* (`crypto.subtle`) instead of `node:crypto`, so it works on Cloudflare Workers,
|
|
927
|
+
* Deno, Vercel/Netlify Edge, Bun, and modern browsers (as well as Node ≥ 18).
|
|
928
|
+
* Same arguments, errors, and return value — just `await` it.
|
|
929
|
+
*/
|
|
930
|
+
declare function verifyWebhookAsync(rawBody: string | Uint8Array, signatureHeader: string | null | undefined, secret: string | string[], opts?: VerifyWebhookOptions): Promise<InvoWebhookEvent>;
|
|
931
|
+
interface WebhookHandlerOptions {
|
|
932
|
+
/** Signing secret, or an array to accept old + new during rotation. */
|
|
933
|
+
secret: string | string[];
|
|
934
|
+
/** Called with the verified, typed event after the signature passes. De-dupe on
|
|
935
|
+
* `ctx.idempotencyKey`. Throw to return a 500 (Invo will retry). */
|
|
936
|
+
onEvent: (event: InvoWebhookEvent, ctx: {
|
|
937
|
+
idempotencyKey: string | null;
|
|
938
|
+
request: Request;
|
|
939
|
+
}) => void | Promise<void>;
|
|
940
|
+
/** Optional: handle a verification failure. Return a Response to override the default 400. */
|
|
941
|
+
onError?: (error: InvoError, request: Request) => void | Response | Promise<void | Response>;
|
|
942
|
+
/** Replay tolerance (seconds). Default 300. */
|
|
943
|
+
toleranceSec?: number;
|
|
944
|
+
}
|
|
945
|
+
/**
|
|
946
|
+
* Build a webhook route handler from the Fetch API `(Request) => Promise<Response>` —
|
|
947
|
+
* works in Next.js App Router route handlers, Cloudflare Workers, Deno, Hono, and Bun.
|
|
948
|
+
* It reads the raw body, verifies with {@link verifyWebhookAsync}, and on success calls
|
|
949
|
+
* `onEvent` with the typed event and the idempotency key (de-dupe is yours). Verification
|
|
950
|
+
* failures return `400`; a throwing `onEvent` returns `500` so Invo retries.
|
|
951
|
+
*
|
|
952
|
+
* ```ts
|
|
953
|
+
* // app/invo/webhooks/route.ts (Next.js)
|
|
954
|
+
* export const POST = createWebhookHandler({
|
|
955
|
+
* secret: process.env.INVO_WEBHOOK_SECRET!,
|
|
956
|
+
* onEvent: async (event, { idempotencyKey }) => { await grantValue(event); },
|
|
957
|
+
* });
|
|
958
|
+
* ```
|
|
959
|
+
*/
|
|
960
|
+
declare function createWebhookHandler(opts: WebhookHandlerOptions): (request: Request) => Promise<Response>;
|
|
961
|
+
|
|
962
|
+
/**
|
|
963
|
+
* Partner payouts and creator payouts (3.25.0).
|
|
964
|
+
*
|
|
965
|
+
* A platform partner can ask INVO to pay out the earnings INVO owes it, and can register
|
|
966
|
+
* creators that INVO verifies and pays directly, as INVO's own payees. Creators are INVO's
|
|
967
|
+
* customers: you never see their documents, tax id or bank details, only their status and
|
|
968
|
+
* the details you registered. Server only: these calls use your game secret key.
|
|
969
|
+
*
|
|
970
|
+
* Fields keep the server's snake_case names, exactly as the API returns them.
|
|
971
|
+
*/
|
|
972
|
+
|
|
973
|
+
interface Payee {
|
|
974
|
+
/** Opaque id, `cp_` followed by 24 hex characters. Store it as a string. */
|
|
975
|
+
payee_id: string;
|
|
976
|
+
game_id: number | string;
|
|
977
|
+
partner_reference: string;
|
|
978
|
+
legal_name: string;
|
|
979
|
+
email: string;
|
|
980
|
+
country: string;
|
|
981
|
+
payee_type: "individual" | "business" | (string & {});
|
|
982
|
+
status: PayeeStatus;
|
|
983
|
+
created_via: "api" | "console" | (string & {});
|
|
984
|
+
status_changed_at: string | null;
|
|
985
|
+
created_at: string | null;
|
|
986
|
+
updated_at: string | null;
|
|
987
|
+
/** 3.26.0. `true` once the creator's details were erased; such a creator can't be invited or paid. */
|
|
988
|
+
erased?: boolean;
|
|
989
|
+
/** 3.26.1. `true` when nothing on INVO's side stops a payout to this creator right now. */
|
|
990
|
+
payable?: boolean;
|
|
991
|
+
/** 3.26.1. Why `payable` is false: see {@link PayableBlocker}. Empty when payable. */
|
|
992
|
+
payable_blockers?: PayableBlocker[];
|
|
993
|
+
[key: string]: unknown;
|
|
994
|
+
}
|
|
995
|
+
/** 3.26.1. `not_payable_now`: no action is needed from you; try again later. */
|
|
996
|
+
type PayableBlocker = "erased" | "closed" | "not_verified" | "verification_expired" | "terms_not_accepted" | "bank_not_verified" | "not_payable_now" | (string & {});
|
|
997
|
+
interface PayeeInvite {
|
|
998
|
+
sent: boolean;
|
|
999
|
+
expires_at?: string | null;
|
|
1000
|
+
error_code?: string;
|
|
1001
|
+
error?: string;
|
|
1002
|
+
}
|
|
1003
|
+
interface RegisterPayeeInput {
|
|
1004
|
+
/** Your own id for the creator: 1 to 128 of `A-Z a-z 0-9 . _ : @ -`, unique in your account. No personal data. */
|
|
1005
|
+
partnerReference: string;
|
|
1006
|
+
/** The creator's legal name, or the registered business name. */
|
|
1007
|
+
legalName: string;
|
|
1008
|
+
email: string;
|
|
1009
|
+
/** ISO 3166-1 alpha-2, for example `"GB"`. */
|
|
1010
|
+
country: string;
|
|
1011
|
+
payeeType: "individual" | "business";
|
|
1012
|
+
}
|
|
1013
|
+
interface RegisterPayeeResult {
|
|
1014
|
+
payee: Payee;
|
|
1015
|
+
/** Present on a new registration. */
|
|
1016
|
+
invite?: PayeeInvite;
|
|
1017
|
+
/** `true` when this `partnerReference` was already registered with the same details. */
|
|
1018
|
+
duplicate: boolean;
|
|
1019
|
+
raw: Record<string, unknown>;
|
|
1020
|
+
}
|
|
1021
|
+
interface ListPayeesQuery {
|
|
1022
|
+
limit?: number;
|
|
1023
|
+
offset?: number;
|
|
1024
|
+
status?: PayeeStatus;
|
|
1025
|
+
}
|
|
1026
|
+
interface ListPayeesResult {
|
|
1027
|
+
total: number;
|
|
1028
|
+
limit: number;
|
|
1029
|
+
offset: number;
|
|
1030
|
+
items: Payee[];
|
|
1031
|
+
raw: Record<string, unknown>;
|
|
1032
|
+
}
|
|
1033
|
+
interface Payout {
|
|
1034
|
+
id: number;
|
|
1035
|
+
game_id: number | string;
|
|
1036
|
+
status: PayoutStatus;
|
|
1037
|
+
requested_amount_usd: string | null;
|
|
1038
|
+
offboarding_fee_pct?: string | null;
|
|
1039
|
+
offboarding_fee_usd?: string | null;
|
|
1040
|
+
offboarding_fee_cap_usd?: string | null;
|
|
1041
|
+
net_payout_usd?: string | null;
|
|
1042
|
+
/** On a creator payout, the creator INVO pays; `null` on a payout to your own bank. */
|
|
1043
|
+
payee_id?: string | null;
|
|
1044
|
+
/** `null` on a creator payout: INVO pays the creator's verified account. */
|
|
1045
|
+
bank_account?: Record<string, unknown> | null;
|
|
1046
|
+
client_request_id?: string | null;
|
|
1047
|
+
paid_at?: string | null;
|
|
1048
|
+
returned_at?: string | null;
|
|
1049
|
+
/** On `returned`: the bank's reason for a payout to your own bank; always `"returned"` on a creator payout. */
|
|
1050
|
+
return_reason_code?: ReturnReasonCode | null;
|
|
1051
|
+
/** 3.26.0. A note INVO wrote for you, or `null`. */
|
|
1052
|
+
partner_message?: string | null;
|
|
1053
|
+
/**
|
|
1054
|
+
* 3.26.0. `true` on the first payout to a creator registered with the game secret key: INVO
|
|
1055
|
+
* approves it only after the account owner confirms it in the console.
|
|
1056
|
+
*/
|
|
1057
|
+
owner_confirmation_required?: boolean;
|
|
1058
|
+
owner_confirmed_at?: string | null;
|
|
1059
|
+
created_at?: string | null;
|
|
1060
|
+
[key: string]: unknown;
|
|
1061
|
+
}
|
|
1062
|
+
interface RequestPayoutInput {
|
|
1063
|
+
/** USD, positive, at most two decimal places. */
|
|
1064
|
+
amountUsd: string | number;
|
|
1065
|
+
contactEmail: string;
|
|
1066
|
+
/** Pay a verified creator. Send exactly one of `payeeId` or `bankAccountId`. */
|
|
1067
|
+
payeeId?: string;
|
|
1068
|
+
/** Pay your own verified bank account (id from the INVO console). */
|
|
1069
|
+
bankAccountId?: number;
|
|
1070
|
+
/** Idempotency key. Reuse it to retry the same request safely. */
|
|
1071
|
+
clientRequestId?: string;
|
|
1072
|
+
partnerNote?: string;
|
|
1073
|
+
additionalEmails?: string[];
|
|
1074
|
+
}
|
|
1075
|
+
interface RequestPayoutResult {
|
|
1076
|
+
payout: Payout;
|
|
1077
|
+
/** `true` when `clientRequestId` matched an earlier request with the same amount and creator. */
|
|
1078
|
+
duplicate: boolean;
|
|
1079
|
+
raw: Record<string, unknown>;
|
|
1080
|
+
}
|
|
1081
|
+
interface ListPayoutsQuery {
|
|
1082
|
+
limit?: number;
|
|
1083
|
+
offset?: number;
|
|
1084
|
+
status?: PayoutStatus;
|
|
1085
|
+
/** Only this creator's payouts. */
|
|
1086
|
+
payeeId?: string;
|
|
1087
|
+
}
|
|
1088
|
+
interface ListPayoutsResult {
|
|
1089
|
+
total: number;
|
|
1090
|
+
items: Payout[];
|
|
1091
|
+
raw: Record<string, unknown>;
|
|
1092
|
+
}
|
|
1093
|
+
/** `InvoServer.payouts`: partner payouts and creator payouts. */
|
|
1094
|
+
declare class PayoutsServer {
|
|
1095
|
+
private readonly http;
|
|
1096
|
+
private readonly auth;
|
|
1097
|
+
constructor(http: Http, auth: AuthHeader);
|
|
1098
|
+
/**
|
|
1099
|
+
* Register a creator (`POST /api/partner-payees`). INVO emails the creator a link to INVO's
|
|
1100
|
+
* own page to give INVO their identity, tax and bank details. `invite.sent` is `false` when
|
|
1101
|
+
* INVO did not email the link (`invite.error_code` says why); the creator is registered
|
|
1102
|
+
* either way. Refusals: `409 PARTNER_REFERENCE_CONFLICT`, `400 INVALID_INPUT`,
|
|
1103
|
+
* `400 COUNTRY_NOT_SUPPORTED`.
|
|
1104
|
+
*/
|
|
1105
|
+
registerPayee(input: RegisterPayeeInput, opts?: CallOptions): Promise<RegisterPayeeResult>;
|
|
1106
|
+
/** This game's creators, newest first (`GET /api/partner-payees`). */
|
|
1107
|
+
listPayees(q?: ListPayeesQuery, opts?: CallOptions): Promise<ListPayeesResult>;
|
|
1108
|
+
/** One creator (`GET /api/partner-payees/{payeeId}`); `404 NOT_FOUND` if not this game's. */
|
|
1109
|
+
getPayee(payeeId: string, opts?: CallOptions): Promise<Payee>;
|
|
1110
|
+
/**
|
|
1111
|
+
* Email the creator a new link (`POST /api/partner-payees/{payeeId}/resend-invite`); the old
|
|
1112
|
+
* link stops working. Allowed while the creator is `invited`, `rejected` or `expired`
|
|
1113
|
+
* (`409 INVITE_NOT_NEEDED` otherwise); `409 PAYEE_ERASED`; `429 INVITE_RATE_LIMITED` with
|
|
1114
|
+
* `retry_after_seconds`. If INVO asked the creator to update their details, the resend sends
|
|
1115
|
+
* INVO's update notice again. Never auto-retried.
|
|
1116
|
+
*/
|
|
1117
|
+
resendPayeeInvite(payeeId: string, opts?: CallOptions): Promise<PayeeInvite>;
|
|
1118
|
+
/**
|
|
1119
|
+
* Remove a creator from your program (`POST /api/partner-payees/{payeeId}/remove`, 3.26.0).
|
|
1120
|
+
* The status becomes `closed`. `409 PAYEE_HAS_PAYOUTS_IN_FLIGHT` while a payout to them is in
|
|
1121
|
+
* progress, `409 ALREADY_CLOSED`, `409 PAYEE_NOT_CLOSABLE`. Not a block: the same person can
|
|
1122
|
+
* be registered again under a new reference. Never auto-retried.
|
|
1123
|
+
*/
|
|
1124
|
+
removePayee(payeeId: string, opts?: CallOptions): Promise<Payee>;
|
|
1125
|
+
/**
|
|
1126
|
+
* Ask INVO to pay out (`POST /api/partner-payouts/request`). Send exactly one of `payeeId`
|
|
1127
|
+
* (INVO pays that verified creator's bank account) or `bankAccountId` (your own verified bank
|
|
1128
|
+
* account). The money comes from the earnings INVO owes your game, and the payout fee is
|
|
1129
|
+
* taken from the payout. Creator refusals: `404 PAYEE_NOT_FOUND`, `409 PAYEE_NOT_VERIFIED`,
|
|
1130
|
+
* `409 PAYEE_VERIFICATION_EXPIRED`, `409 PAYEE_BANK_NOT_VERIFIED`, `409 PAYEE_CLOSED`,
|
|
1131
|
+
* `409 PAYEE_TERMS_NOT_ACCEPTED` (the creator hasn't accepted INVO's current Payee Terms yet),
|
|
1132
|
+
* `409 PAYEE_NOT_PAYABLE` (can't be paid right now; no action needed; try again later),
|
|
1133
|
+
* `409 IDEMPOTENCY_KEY_REUSED`. The first payout to a creator registered with the game key
|
|
1134
|
+
* carries `owner_confirmation_required: true`. Retried safely only when `clientRequestId` is
|
|
1135
|
+
* set.
|
|
1136
|
+
*/
|
|
1137
|
+
requestPayout(input: RequestPayoutInput, opts?: CallOptions): Promise<RequestPayoutResult>;
|
|
1138
|
+
/** One payout (`GET /api/partner-payouts/{payoutId}`). */
|
|
1139
|
+
getPayout(payoutIdValue: number, opts?: CallOptions): Promise<Payout>;
|
|
1140
|
+
/** Your payouts (`GET /api/partner-payouts`), optionally one creator's (`payeeId`). */
|
|
1141
|
+
listPayouts(q?: ListPayoutsQuery, opts?: CallOptions): Promise<ListPayoutsResult>;
|
|
1142
|
+
/**
|
|
1143
|
+
* Cancel a creator payout that is still `requested`
|
|
1144
|
+
* (`POST /api/partner-payouts/{payoutId}/cancel`). Anything past `requested` is
|
|
1145
|
+
* `409 PAYOUT_NOT_CANCELLABLE`; a payout to your own bank is `404 NOT_FOUND`.
|
|
1146
|
+
*/
|
|
1147
|
+
cancelPayout(payoutIdValue: number, opts?: CallOptions): Promise<Payout>;
|
|
1148
|
+
}
|
|
1149
|
+
|
|
1150
|
+
/**
|
|
1151
|
+
* @invonetwork/web-sdk/server — NODE entry.
|
|
1152
|
+
*
|
|
1153
|
+
* InvoServer holds the game secret and runs every server-side call: minting the
|
|
1154
|
+
* short-lived player token for the browser, initiating sends/transfers, and the
|
|
1155
|
+
* currency-purchase flow (hosted checkout + rail selector). The game secret must
|
|
1156
|
+
* NEVER reach the browser.
|
|
1157
|
+
*
|
|
1158
|
+
* All endpoints here authenticate with the `X-Game-Secret-Key` header.
|
|
1159
|
+
*/
|
|
1160
|
+
|
|
1161
|
+
/**
|
|
1162
|
+
* Platform Commerce — the ECOMMERCE surface (server side). A PLATFORM tenant (a non-game
|
|
1163
|
+
* app: vertical video, creator merch, marketplace) sells items funded by INVO balance OR a
|
|
1164
|
+
* real card, with full refunds (the seller of record depends on the account tier). This is NOT item purchase
|
|
1165
|
+
* (§4.8) — that is a GAME tenant spending a player's existing game currency on an in-game
|
|
1166
|
+
* item (balance only, no card, no refund). Different endpoints, different fee, different
|
|
1167
|
+
* settlement. Reached as `invo.platformCommerce.*`.
|
|
1168
|
+
*/
|
|
1169
|
+
declare class PlatformCommerceServer {
|
|
1170
|
+
private readonly http;
|
|
1171
|
+
private readonly auth;
|
|
1172
|
+
constructor(http: Http, auth: AuthHeader);
|
|
1173
|
+
/**
|
|
1174
|
+
* Create a purchase. The funding source is resolved server-side under lock — the client
|
|
1175
|
+
* can request `"balance"` or `"card"`, but the backend verifies the real balance before
|
|
1176
|
+
* value moves.
|
|
1177
|
+
*
|
|
1178
|
+
* - `fundingSource: "balance"` → settles synchronously; result `status:"success"` with
|
|
1179
|
+
* `newBalance`/`financialBreakdown`. `totalPrice` is the tenant's network-currency amount.
|
|
1180
|
+
* - `fundingSource: "card"` → result `status:"requires_payment"` + `checkoutUrl`/`sessionId`.
|
|
1181
|
+
* Send the buyer to `checkoutUrl` — INVO's hosted page owns the card form, wallets,
|
|
1182
|
+
* billing address, and 3-D Secure (there is NO billing address in this request, and no
|
|
1183
|
+
* client payment code to write; optionally embed via
|
|
1184
|
+
* `InvoClient.platformCommerce.mountCheckout`). `totalPrice` is USD, at least $0.50;
|
|
1185
|
+
* the maximum is an INVO setting ($100,000.00 by default) and is enforced on the
|
|
1186
|
+
* request, not here, so read the live figure off `ABOVE_CARD_MAXIMUM` rather than
|
|
1187
|
+
* pinning one.
|
|
1188
|
+
* The sale is real only on the `platform_commerce.purchased` webhook — never on the
|
|
1189
|
+
* client return.
|
|
1190
|
+
*
|
|
1191
|
+
* Idempotency on `clientRequestId`: the balance leg throws a 409
|
|
1192
|
+
* (`err.isDuplicateRequest`) on a duplicate; the card leg REPLAYS the same checkout
|
|
1193
|
+
* session (`idempotentReplay: true`) — a lost response is safely recovered by retrying
|
|
1194
|
+
* with the SAME `clientRequestId`. A non-platform tenant throws
|
|
1195
|
+
* `err.isNotPlatformTenant` (403).
|
|
1196
|
+
*/
|
|
1197
|
+
purchase(input: PlatformPurchaseInput, opts?: CallOptions): Promise<PlatformPurchaseResult>;
|
|
1198
|
+
/** Poll an order's status: `completed` (balance immediately; card after the webhook),
|
|
1199
|
+
* `pending_payment` (card awaiting confirmation), or `refunded`. */
|
|
1200
|
+
getStatus(orderId: string | number, opts?: CallOptions): Promise<PlatformOrderStatusResult>;
|
|
1201
|
+
/**
|
|
1202
|
+
* One player's Platform Commerce purchases in your app, newest first, one page at a time
|
|
1203
|
+
* (`GET /api/platform-commerce/purchase-history`). Each entry carries exactly the fields
|
|
1204
|
+
* `getStatus` returns for that order (including `receiptNumber` / `receiptUrl` on a
|
|
1205
|
+
* Merchant of Record card sale once issued). Pass `nextCursor` back as `cursor` for the
|
|
1206
|
+
* next page; it is `null` on the last one. `iteratePurchaseHistory` walks every page.
|
|
1207
|
+
*
|
|
1208
|
+
* Refusals (`InvoError`; this route reports its code in `error_code`, surfaced as
|
|
1209
|
+
* `err.code`): a blank `playerEmail` or a bad `limit` / `cursor` throws `INVALID_INPUT`
|
|
1210
|
+
* before the network; `400 INVALID_INPUT`, `400 INVALID_CURSOR` (a cursor from another
|
|
1211
|
+
* player), `404 PLAYER_NOT_FOUND` (`err.isPlayerNotFound`), `403` for a non-platform
|
|
1212
|
+
* tenant (`err.isNotPlatformTenant`), `429` (back off; `err.retryAfter`). A GET, so
|
|
1213
|
+
* transient failures are retried automatically.
|
|
1214
|
+
*/
|
|
1215
|
+
getPurchaseHistory(query: PlatformPurchaseHistoryQuery, opts?: CallOptions): Promise<PlatformPurchaseHistoryResult>;
|
|
1216
|
+
/**
|
|
1217
|
+
* Async iterator over ALL of a player's Platform Commerce purchases, newest first: pages
|
|
1218
|
+
* through `getPurchaseHistory` by `nextCursor`, yielding one order at a time.
|
|
1219
|
+
*
|
|
1220
|
+
* ```ts
|
|
1221
|
+
* for await (const order of invo.platformCommerce.iteratePurchaseHistory({ playerEmail })) { … }
|
|
1222
|
+
* ```
|
|
1223
|
+
*/
|
|
1224
|
+
iteratePurchaseHistory(query: {
|
|
1225
|
+
playerEmail: string;
|
|
1226
|
+
pageSize?: number;
|
|
1227
|
+
}, opts?: CallOptions): AsyncGenerator<PlatformOrderStatusResult, void, unknown>;
|
|
1228
|
+
/**
|
|
1229
|
+
* Refund a completed purchase. Provide EXACTLY ONE of `orderId` or `clientRequestId`.
|
|
1230
|
+
* INVO retains its fee — the customer is made whole (balance re-credit or card refund)
|
|
1231
|
+
* minus that fee. Idempotent on the order: a second refund throws a 409
|
|
1232
|
+
* (`err.isAlreadyRefunded`) — treat that as "already done", not a failure.
|
|
1233
|
+
*/
|
|
1234
|
+
refund(input: PlatformRefundInput, opts?: CallOptions): Promise<PlatformRefundResult>;
|
|
1235
|
+
}
|
|
1236
|
+
/**
|
|
1237
|
+
* Subscriptions: INVO bills a member a fixed USD price on a fixed interval and grants
|
|
1238
|
+
* your game's currency each period. You keep the entitlement; INVO keeps the clock, the
|
|
1239
|
+
* charges, the retries, the events and the revenue split. Reached as
|
|
1240
|
+
* `invo.subscriptions.*`. Two rails, fixed at creation: `card` (`create`) and `steam`
|
|
1241
|
+
* (`steamInit` + `steamFinalize`).
|
|
1242
|
+
*
|
|
1243
|
+
* TWO CLOCKS. `currentPeriodEnd` is the billing window, a projection; `paidThrough` is
|
|
1244
|
+
* what the member has actually paid for. Grant access from `paidThrough`. Renewals are
|
|
1245
|
+
* reported by the `subscription.renewed` webhook (the source of truth for entitlement);
|
|
1246
|
+
* only `subscription.expired` and `subscription.canceled` revoke it.
|
|
1247
|
+
*/
|
|
1248
|
+
declare class SubscriptionsServer {
|
|
1249
|
+
private readonly http;
|
|
1250
|
+
private readonly auth;
|
|
1251
|
+
constructor(http: Http, auth: AuthHeader);
|
|
1252
|
+
/**
|
|
1253
|
+
* Create a CARD-rail subscription. **Charges the first period before responding**
|
|
1254
|
+
* (unless it is a trial), so expect the call to take as long as a card charge.
|
|
1255
|
+
*
|
|
1256
|
+
* Branch on `result.firstCharge.status`: `paid` (grant until `paidThrough`),
|
|
1257
|
+
* `requires_action` (NOTHING charged; send the member to `confirmationUrl`),
|
|
1258
|
+
* `skipped_trial` (grant trial access until `subscription.trialEnd`), `failed` (in
|
|
1259
|
+
* dunning; INVO retries at `nextRetryAt`), `pending` (wait for the event).
|
|
1260
|
+
*
|
|
1261
|
+
* Idempotent on `clientRequestId`: a repeat returns HTTP 200 with the identical shape
|
|
1262
|
+
* and `idempotentReplay: true`, and NOTHING is charged again. **On any timeout or 5xx,
|
|
1263
|
+
* replay the same key before you do anything else**; a fresh key inside a retry loop
|
|
1264
|
+
* lands on `409 ACTIVE_SUBSCRIPTION_EXISTS` (`err.isActiveSubscriptionExists`,
|
|
1265
|
+
* `err.existingSubscriptionId`) at best and a second subscription at worst. Same key
|
|
1266
|
+
* with different terms is `err.isIdempotentReplayMismatch` (`err.mismatchedFields`).
|
|
1267
|
+
*
|
|
1268
|
+
* Card only (since 2026-09-17): the card is charged the full price every period and the
|
|
1269
|
+
* member's coin wallet never pays and never moves. Card selection: `playerCardId` names one
|
|
1270
|
+
* (from `cards.list`); omitted, INVO attaches the member's newest unexpired saved card. With
|
|
1271
|
+
* no saved card the subscription is still created (201) but `firstCharge` is `failed` with
|
|
1272
|
+
* `failureCode: "no_payment_method"`, whatever the member's balance: save a card first.
|
|
1273
|
+
* `walletOnly: true` is deprecated: it never charges a card, so such a subscription can never
|
|
1274
|
+
* be paid (`failureCode: "wallet_only"`).
|
|
1275
|
+
*
|
|
1276
|
+
* PAID TRIAL: send `trialAmountUsd` with `trialDays` or `trialEnd` (for example $1.00 for 7
|
|
1277
|
+
* days, then `amountUsd` monthly). Period 1 is charged the trial price inside this call, so a
|
|
1278
|
+
* usable saved card is required (`400 PAYMENT_METHOD_REQUIRED`, `err.isPaymentMethodRequired`),
|
|
1279
|
+
* `firstCharge` reports the trial charge (never `skipped_trial`), and a refused trial charge
|
|
1280
|
+
* ends the subscription at once (`expired`, no retry). Other refusals:
|
|
1281
|
+
* `err.isTrialAmountRequiresTrial`, `err.isTrialAmountNotSupportedForFunding`,
|
|
1282
|
+
* `err.isTrialAmountInvalid` (below $0.50, or not less than `amountUsd`),
|
|
1283
|
+
* `err.isConsentDisclosedTrialInvalid`.
|
|
1284
|
+
* Requires the game to be `live` (`err.isGameNotLive`).
|
|
1285
|
+
*/
|
|
1286
|
+
create(input: CreateSubscriptionInput, opts?: CallOptions): Promise<SubscriptionResult>;
|
|
1287
|
+
/** Read one subscription. `404 SUBSCRIPTION_NOT_FOUND` for an id that is not your game's. */
|
|
1288
|
+
get(subscriptionId: string, options?: GetSubscriptionOptions, opts?: CallOptions): Promise<GetSubscriptionResult>;
|
|
1289
|
+
/**
|
|
1290
|
+
* List a member's subscriptions, newest first, paged (`limit` 1..100, `offset`
|
|
1291
|
+
* 0..100000). `status` filters; `"live"` expands to the four live statuses and may be
|
|
1292
|
+
* mixed in (`["live", "canceled"]`). A player who does not exist yet is an empty list
|
|
1293
|
+
* with `totalCount: 0`, not a 404.
|
|
1294
|
+
*/
|
|
1295
|
+
listForPlayer(playerEmail: string, options?: ListSubscriptionsOptions, opts?: CallOptions): Promise<SubscriptionListResult>;
|
|
1296
|
+
/**
|
|
1297
|
+
* Cancel. `atPeriodEnd` defaults to `true`: the subscription stays live with
|
|
1298
|
+
* `cancelAtPeriodEnd: true` and is retired at `paidThrough` without another charge.
|
|
1299
|
+
* If nothing has been paid (or the paid window has elapsed) an at-period-end cancel is
|
|
1300
|
+
* **downgraded to immediate**: read `terminatedImmediately`. `atPeriodEnd: false` ends
|
|
1301
|
+
* it now. Revoke access at `accessUntil`.
|
|
1302
|
+
*
|
|
1303
|
+
* Cancelling an already-terminal subscription is a 200 with `alreadyCanceled: true`
|
|
1304
|
+
* (never thrown), so a batch reconciler needs no special case; that is also what makes
|
|
1305
|
+
* a lost-response retry safe. One `subscription.canceled` event fires at request time.
|
|
1306
|
+
* Never blocked by a maintenance pause.
|
|
1307
|
+
*/
|
|
1308
|
+
cancel(subscriptionId: string, options?: CancelSubscriptionOptions, opts?: CallOptions): Promise<CancelResult>;
|
|
1309
|
+
/**
|
|
1310
|
+
* Stage a price change. Applied on the NEXT successful renewal (the current window is
|
|
1311
|
+
* billed at the old price first; no proration). Sending the current price clears a
|
|
1312
|
+
* staged change (`changeQueued: false`). The billed price appears on that period's
|
|
1313
|
+
* `subscription.renewed`; there is no `amount_changed` event.
|
|
1314
|
+
*
|
|
1315
|
+
* Steam: an increase is refused (`err.isSteamReauthorizationRequired`; start a new
|
|
1316
|
+
* Steam subscription at the new price), a decrease stages. An increase to more than
|
|
1317
|
+
* double the last agreed price, or above 25000.00, is staged but never applied: raise
|
|
1318
|
+
* prices in steps. `err.isSubscriptionTerminal` on a canceled/expired row.
|
|
1319
|
+
*/
|
|
1320
|
+
changeAmount(subscriptionId: string, amountUsd: string | number, opts?: CallOptions): Promise<ChangeAmountResult>;
|
|
1321
|
+
/**
|
|
1322
|
+
* Card subscriptions only. Attach a card (`{ playerCardId }`, an `id` from
|
|
1323
|
+
* `cards.list` belonging to this player, unexpired) or make the subscription wallet-only
|
|
1324
|
+
* (`{ walletOnly: true }`, deprecated: a wallet-only card subscription can never be paid).
|
|
1325
|
+
* On a wallet-only subscription pass `walletOnly: false` beside the card to convert it
|
|
1326
|
+
* back. The new card is used from the next charge, including a pending retry in dunning.
|
|
1327
|
+
*
|
|
1328
|
+
* `err.isNotACardSubscription` on Steam; `err.isSubscriptionTerminal` on a terminal row.
|
|
1329
|
+
*/
|
|
1330
|
+
setPaymentMethod(subscriptionId: string, input: SetPaymentMethodInput, opts?: CallOptions): Promise<SetPaymentMethodResult>;
|
|
1331
|
+
/**
|
|
1332
|
+
* Refund a billed period (card rail). Idempotent on `clientRequestId`: a repeat returns
|
|
1333
|
+
* the stored receipt with `idempotentReplay: true` and moves nothing.
|
|
1334
|
+
*
|
|
1335
|
+
* **Branch on `status`.** `"refunded"` (HTTP 200): the refund ran. `"pending_approval"`
|
|
1336
|
+
* (HTTP 202): the refund would exceed the game's daily self-serve limit per UTC day (by
|
|
1337
|
+
* default never lower than the largest single subscription charge, so a single period
|
|
1338
|
+
* always runs unless INVO set a lower limit for the game), NOTHING moved, and INVO reviews it as a refund request (`requestId`); the
|
|
1339
|
+
* outcome arrives as `subscription.refund_approved` (sent together with
|
|
1340
|
+
* `subscription.refunded`, and `subscription.canceled` on a full refund, in any order) or
|
|
1341
|
+
* `subscription.refund_rejected`. The 202 carries every receipt field with nothing moved
|
|
1342
|
+
* (`refundedAmountUsd` is `"0.00"`; `totalRefundedAmountUsd` and `remainingRefundableUsd`
|
|
1343
|
+
* carry the period's real values). Check it with {@link isRefundPendingApproval}.
|
|
1344
|
+
*
|
|
1345
|
+
* A card-only period (every card period charged since 2026-09-17) is refunded in cash, full
|
|
1346
|
+
* or partial: `cardRefundedUsd` equals the amount and `balanceDeltaCoins` is `"0.00"`. A
|
|
1347
|
+
* period charged before that keeps the earlier rule: a full refund returns the card charge
|
|
1348
|
+
* and reclaims the coins it minted (`balanceDeltaCoins` is signed), a partial refund
|
|
1349
|
+
* credits coins. Your revenue is reversed for the refunded portion
|
|
1350
|
+
* (`partnerRevenueReversedUsd`), INVO's fee is retained, and on a card refund you bear the
|
|
1351
|
+
* whole refunded amount, INVO's card fee included (`cardFeeChargedToPartnerUsd`;
|
|
1352
|
+
* `partnerDebitedUsd` is the sum; since 2026-09-28, with no separate processor fee:
|
|
1353
|
+
* `processingFeeUsd` reads `"0.00"`). **A full refund
|
|
1354
|
+
* cancels the subscription** (`subscriptionCanceled`, and a `subscription.canceled` event
|
|
1355
|
+
* with `cancel_cause: "full_refund"`, sent together with `subscription.refunded` in any
|
|
1356
|
+
* order); a partial one does not. INVO emails the member.
|
|
1357
|
+
* Refunds run within 30 days of the period's charge. Send a `reason`: it is recommended now
|
|
1358
|
+
* and will be required later (`warnings` says so when it is missing).
|
|
1359
|
+
*
|
|
1360
|
+
* Refusals: `err.isRefundsNotEnabled` (403), `err.isRefundWindowClosed` (409),
|
|
1361
|
+
* `err.isRefundRequestPending` (409, `err.refundRequestId`), `err.isRefundRequestRejected`
|
|
1362
|
+
* (409, use a new key), `err.isConcurrentRequest` (409, retry with the same key),
|
|
1363
|
+
* `err.isRefundMismatch` (502, contact INVO), `NO_PAID_PERIOD` (409, nothing collected yet),
|
|
1364
|
+
* `PERIOD_NOT_REFUNDABLE`, `ALREADY_REFUNDED` (`err.isAlreadyRefunded`),
|
|
1365
|
+
* `AMOUNT_EXCEEDS_REMAINING` (body carries `remaining_refundable_usd`),
|
|
1366
|
+
* `err.isSteamRefundNotSupported`, `err.isFlowPaused`.
|
|
1367
|
+
*/
|
|
1368
|
+
refund(subscriptionId: string, input: RefundSubscriptionInput, opts?: CallOptions): Promise<RefundResult>;
|
|
1369
|
+
/**
|
|
1370
|
+
* Start a STEAM-rail subscription: creates it in `pending_steam_authorization`, opens
|
|
1371
|
+
* period 1 for the full price and starts the Steam authorisation. Nothing is charged
|
|
1372
|
+
* until the member authorises and you call {@link steamFinalize}. Idempotent on
|
|
1373
|
+
* `clientRequestId`; a replay answers with the row's CURRENT status (which may already
|
|
1374
|
+
* be `active`, `canceled` or `expired`).
|
|
1375
|
+
*
|
|
1376
|
+
* `userSession: "client"` (default): the Steam overlay presents the authorisation inside
|
|
1377
|
+
* the game; match the Steam client callback's `order_id` against `steamOrderId` (never
|
|
1378
|
+
* `steamTransid`). `"web"`: open `steamCheckoutUrl` as a TOP-LEVEL window (it cannot be
|
|
1379
|
+
* framed); requires `playerIp`, the MEMBER's address. Show `amountCoins`: what one
|
|
1380
|
+
* period is worth for THIS member depends on their country and is fixed at init.
|
|
1381
|
+
*
|
|
1382
|
+
* A pending authorisation for the same player and item with the SAME terms is handed
|
|
1383
|
+
* back (`pendingReuse: true`, no new agreement): finalize that one. With DIFFERENT
|
|
1384
|
+
* terms the call throws `409 STEAM_AUTHORIZATION_PENDING` (`err.isSteamAuthorizationPending`,
|
|
1385
|
+
* `err.existingSubscriptionId`): finalize or cancel the pending one first.
|
|
1386
|
+
*
|
|
1387
|
+
* Not available on Steam, refused before the network: trials, `walletOnly`, card
|
|
1388
|
+
* fields, `intervalCount` other than 1. Backend refusals worth branching on:
|
|
1389
|
+
* `err.isSteamChannelRequired` (409, wrong channel key), `err.isActiveSubscriptionExists`,
|
|
1390
|
+
* `err.isSteamRailNotEntitled` (403), `err.isSteamNotConfigured` (503),
|
|
1391
|
+
* `err.isPartnerBillingNotSetUp` / `isPartnerSettlementUnavailable` (409),
|
|
1392
|
+
* `AMOUNT_TOO_SMALL_FOR_STEAM` (400). When a Steam-side failure abandons the row after
|
|
1393
|
+
* creation the body carries the abandoned `subscription_id`; retry with a NEW key.
|
|
1394
|
+
*/
|
|
1395
|
+
steamInit(input: SteamSubscriptionInitInput, opts?: CallOptions): Promise<SteamInitResult>;
|
|
1396
|
+
/**
|
|
1397
|
+
* Finalize a Steam subscription after the member has authorised: INVO verifies with
|
|
1398
|
+
* Steam, captures period 1, records the agreement and settles period 1 exactly as a
|
|
1399
|
+
* renewal. Idempotent: a repeat returns `alreadyProcessed: true` with
|
|
1400
|
+
* `idempotentReplay: true` (treat as success; never thrown).
|
|
1401
|
+
*
|
|
1402
|
+
* **Finalize is your call.** Steam does not tell INVO the member authorised; call this
|
|
1403
|
+
* after the overlay or checkout closes, and again if it threw `err.isNotAuthorized`
|
|
1404
|
+
* (409 `status: "not_authorized"`: the normal wait state). The member has 24 hours.
|
|
1405
|
+
* A 200 with `warning` means Steam charged but period 1 could not settle in one step:
|
|
1406
|
+
* the money is taken, do not retry the charge, watch for `subscription.renewed`.
|
|
1407
|
+
* In sandbox this does not call Steam (`sandboxAutoApproved: true`).
|
|
1408
|
+
*
|
|
1409
|
+
* Other refusals: `err.isSubscriptionTerminal`, `NOT_A_STEAM_SUBSCRIPTION`,
|
|
1410
|
+
* `NO_STEAM_AUTHORIZATION`, `err.isSteamAppChanged` (409); 502/503 are transient.
|
|
1411
|
+
*/
|
|
1412
|
+
steamFinalize(subscriptionId: string, opts?: CallOptions): Promise<SteamFinalizeSubscriptionResult>;
|
|
1413
|
+
}
|
|
1414
|
+
/**
|
|
1415
|
+
* Saved cards for off-session (recurring) use: the card capture a card subscription
|
|
1416
|
+
* needs. Reached as `invo.cards.*`. The subscription endpoints never receive card data
|
|
1417
|
+
* and neither does this SDK.
|
|
1418
|
+
*
|
|
1419
|
+
* THE RECOMMENDED CAPTURE IS {@link createSetupSession}: INVO hosts the card page, you
|
|
1420
|
+
* mint a link server-side and send the member to it, and nothing in your integration
|
|
1421
|
+
* references a card processor or loads its script. {@link beginSetup} /
|
|
1422
|
+
* {@link confirmSetup} are the processor-bound alternative for a partner who already
|
|
1423
|
+
* runs a card form in their own client against INVO's current processor.
|
|
1424
|
+
*
|
|
1425
|
+
* A card saved through the hosted CHECKOUT page, or through a `savedCardId` purchase,
|
|
1426
|
+
* does NOT carry the off-session consent a subscription needs; capture it here (or with
|
|
1427
|
+
* a `purchaseCurrency` that sets `save_card: true`).
|
|
1428
|
+
*/
|
|
1429
|
+
declare class CardsServer {
|
|
1430
|
+
private readonly http;
|
|
1431
|
+
private readonly auth;
|
|
1432
|
+
constructor(http: Http, auth: AuthHeader);
|
|
1433
|
+
/**
|
|
1434
|
+
* Mint a short-lived session for the INVO-hosted card page and return its URL. THE
|
|
1435
|
+
* RECOMMENDED WAY TO SAVE A CARD FOR A SUBSCRIPTION: two server-to-server calls (this
|
|
1436
|
+
* one, then `cards.list`) and one redirect. No browser code, no processor script, no
|
|
1437
|
+
* client secret; INVO can change card processor without you changing anything.
|
|
1438
|
+
*
|
|
1439
|
+
* A member this game already knows needs only `playerEmail`. A BRAND-NEW member (a
|
|
1440
|
+
* first-time signup, for example before a paid trial) is created here when you also
|
|
1441
|
+
* send `playerName` (and optionally `playerPhone`), exactly as `subscriptions.create`
|
|
1442
|
+
* creates one: same phone-share gate, same wallet binding. Without `playerName` an
|
|
1443
|
+
* unknown member is `err.isPlayerNotFound` (404) and nothing is created. A known member
|
|
1444
|
+
* is never re-created or renamed by this call; `playerName` / `playerPhone` are used
|
|
1445
|
+
* only when the member is new. Send the member to `result.cardSetupUrl` top-level (do
|
|
1446
|
+
* not frame it). The page says in words that no money moves, saves the card, and then
|
|
1447
|
+
* redirects to `successUrl` (or shows "Card saved" when you gave none). The saved card
|
|
1448
|
+
* appears in {@link list} immediately, carries the off-session consent a subscription
|
|
1449
|
+
* needs, and is indistinguishable from one saved any other way. There is no event for
|
|
1450
|
+
* a saved card; `cards.list` is the signal.
|
|
1451
|
+
*
|
|
1452
|
+
* The session lives 10 minutes (entering a card is one sitting); mint it when the
|
|
1453
|
+
* member is about to use it. The link may be reloaded freely before the save; once the
|
|
1454
|
+
* card is saved the link is spent and reopening it returns the same card again.
|
|
1455
|
+
* `successUrl` is redirected to verbatim (nothing appended) and `metadata` is stored on
|
|
1456
|
+
* the session and not returned anywhere today, so put your own correlation id in
|
|
1457
|
+
* `successUrl`.
|
|
1458
|
+
*
|
|
1459
|
+
* Refusals: `err.isInvalidPlayerEmail` (400, a non-email string; a missing or blank
|
|
1460
|
+
* `playerEmail` is refused here first with `status: 0`), `err.isPlayerNotFound` (404),
|
|
1461
|
+
* `err.isInvalidInput` (400: a script-scheme `successUrl` / `cancelUrl`, or, when the
|
|
1462
|
+
* member is new, a `playerName` over 255 characters or a `playerPhone` over 30; the SDK
|
|
1463
|
+
* refuses script schemes, a blank or over-long `playerName` and a non-E.164
|
|
1464
|
+
* `playerPhone` first with `status: 0`), `err.isPhoneShareApprovalRequired` (409, creating the member needs the
|
|
1465
|
+
* existing phone owner's approval; same body as `subscriptions.create`),
|
|
1466
|
+
* `err.isPlayerCreateFailed` (503, the member could not be created; call again),
|
|
1467
|
+
* 401 / 403 on the key or the game (body `{ message }`, no code), 503 when card setup
|
|
1468
|
+
* is not available right now. Never auto-retried: each call mints a fresh link, so on a
|
|
1469
|
+
* timeout call it again.
|
|
1470
|
+
*/
|
|
1471
|
+
createSetupSession(input: CardSetupSessionInput, opts?: CallOptions): Promise<CardSetupSessionResult>;
|
|
1472
|
+
/**
|
|
1473
|
+
* THE PROCESSOR-BOUND ALTERNATIVE to {@link createSetupSession}. Use it only if you
|
|
1474
|
+
* already run a card form in your own client against INVO's current card processor:
|
|
1475
|
+
* the `clientSecret` it hands back can only be consumed by that processor's client
|
|
1476
|
+
* library, so the browser code you write for it will need rework when INVO changes
|
|
1477
|
+
* processor. `createSetupSession` does not have that problem.
|
|
1478
|
+
*
|
|
1479
|
+
* Begin saving a card (charges nothing). The player must already exist in this game
|
|
1480
|
+
* (`404 PLAYER_NOT_FOUND`). Idempotent on `setupReference`: resend the same value on a
|
|
1481
|
+
* retry and you get the same setup back (`409 SETUP_REFERENCE_REUSED` if you reuse it
|
|
1482
|
+
* with different parameters).
|
|
1483
|
+
*
|
|
1484
|
+
* With `paymentMethodId` (a card tokenised on the client) INVO confirms server-side
|
|
1485
|
+
* and answers `succeeded` with the `card`, or `requires_action` with a `clientSecret`
|
|
1486
|
+
* for the card form to run the cardholder authentication. Without it, INVO answers
|
|
1487
|
+
* `requires_confirmation` / `requires_payment_method` with a `clientSecret`: confirm on
|
|
1488
|
+
* the client, then call {@link confirmSetup}. Send tokens only, never raw card numbers
|
|
1489
|
+
* (`RAW_CARD_NOT_SUPPORTED`).
|
|
1490
|
+
*/
|
|
1491
|
+
beginSetup(input: CardSetupInput, opts?: CallOptions): Promise<CardSetupResult>;
|
|
1492
|
+
/**
|
|
1493
|
+
* The second half of the processor-bound alternative (see {@link beginSetup}); not
|
|
1494
|
+
* needed on the {@link createSetupSession} path, where INVO's page completes the save.
|
|
1495
|
+
*
|
|
1496
|
+
* Finish a client-confirmed setup and save the card. Idempotent on `setupIntentId`.
|
|
1497
|
+
* While the client has not finished, this throws a 400 with body
|
|
1498
|
+
* `status: "still_requires_action"`. On `500 CARD_PERSIST_FAILED` (authorised but not
|
|
1499
|
+
* recorded) retry this call with the same `setupIntentId`.
|
|
1500
|
+
*/
|
|
1501
|
+
confirmSetup(input: CardSetupConfirmInput, opts?: CallOptions): Promise<CardSetupConfirmResult>;
|
|
1502
|
+
/**
|
|
1503
|
+
* A member's unexpired saved cards, newest first. An unknown player is `{ cards: [] }`.
|
|
1504
|
+
* The `id` is the value you pass as `playerCardId`; INVO never returns processor
|
|
1505
|
+
* identifiers for a card. Served from a short cache (about 60 s); a card saved through
|
|
1506
|
+
* the hosted card page (`createSetupSession`) or through `beginSetup` / `confirmSetup`
|
|
1507
|
+
* appears immediately. This read is the signal that the hosted page saved a card.
|
|
1508
|
+
*/
|
|
1509
|
+
list(playerEmail: string, opts?: CallOptions): Promise<PlayerCardsResult>;
|
|
1510
|
+
}
|
|
1511
|
+
/**
|
|
1512
|
+
* Sandbox-only clock tools for subscriptions. Reached as `invo.sandbox.subscriptions.*`.
|
|
1513
|
+
*
|
|
1514
|
+
* **Path note.** These four endpoints live DIRECTLY under the sandbox base, not under
|
|
1515
|
+
* `/api`: the full URL is `https://sandbox.invo.network/sandbox/subscriptions/<id>/advance-clock`.
|
|
1516
|
+
* Because `baseUrl` already ends in `/sandbox`, this class posts to
|
|
1517
|
+
* `/subscriptions/<id>/...` relative to it. They do not exist in production (404).
|
|
1518
|
+
*
|
|
1519
|
+
* **Second credential.** Every call sends `X-Game-Secret-Key` AND `X-Sandbox-Clock-Key`
|
|
1520
|
+
* (`new InvoServer({ ..., sandboxClockKey })`, from the sandbox console: open the game,
|
|
1521
|
+
* Game Settings, "Sandbox clock key"). A missing key throws `INVALID_INPUT` before the
|
|
1522
|
+
* network; a wrong one is `401 SANDBOX_CLOCK_UNAUTHORIZED` (`err.isSandboxClockUnauthorized`).
|
|
1523
|
+
* None of these calls is auto-retried: each one moves the clock or runs the engine.
|
|
1524
|
+
*/
|
|
1525
|
+
declare class SandboxSubscriptionsServer {
|
|
1526
|
+
private readonly http;
|
|
1527
|
+
private readonly auth;
|
|
1528
|
+
private readonly clockKey;
|
|
1529
|
+
constructor(http: Http, auth: AuthHeader, clockKey: string | undefined);
|
|
1530
|
+
private call;
|
|
1531
|
+
/**
|
|
1532
|
+
* Make the next period due now. `intervals` 0..60, default 1. `0` makes it due without
|
|
1533
|
+
* moving the window (use it to trigger a retry). `N` on a never-paid subscription
|
|
1534
|
+
* (a trial, a fresh row) also moves the window back by up to N intervals; once anything
|
|
1535
|
+
* has been paid the window stays put (`intervalsAppliedToWindow: 0`). No window is ever
|
|
1536
|
+
* billed twice. Then `forceRenewal`, or wait for the next sweep (within a minute or two).
|
|
1537
|
+
* `409 SUBSCRIPTION_NOT_LIVE` on a terminal or pending row.
|
|
1538
|
+
*/
|
|
1539
|
+
advanceClock(subscriptionId: string, intervals?: number, opts?: CallOptions): Promise<SandboxClockResult>;
|
|
1540
|
+
/**
|
|
1541
|
+
* Run the renewal immediately. **Charges the test card** (or the Steam stand-in): the
|
|
1542
|
+
* real money path (card: the full price; Steam: wallet first, then the shortfall), mint,
|
|
1543
|
+
* spend, split, `subscription.renewed`,
|
|
1544
|
+
* and on failure the real dunning. Read `engineStats` (`renewed: 1` on success). A
|
|
1545
|
+
* cancel-at-period-end row answers `action: "retired-at-period-end"`, `retired: true`.
|
|
1546
|
+
* `409 PERIOD_TOO_FAR_AHEAD` means you forced twice without advancing the clock.
|
|
1547
|
+
*/
|
|
1548
|
+
forceRenewal(subscriptionId: string, opts?: CallOptions): Promise<SandboxClockResult>;
|
|
1549
|
+
/**
|
|
1550
|
+
* Synthesise a failed attempt and run real dunning. No charge. `outcome` defaults to
|
|
1551
|
+
* `card_declined`. Returns `retryBudgetUsed`, `retryScheduleDays` (e.g. `[2, 3, 2]`),
|
|
1552
|
+
* `retriesRemaining`. Call it four times to walk `active` through `past_due` to `expired`
|
|
1553
|
+
* and watch the events. Does not model a Steam refusal.
|
|
1554
|
+
*/
|
|
1555
|
+
forceFailure(subscriptionId: string, outcome?: SandboxFailureOutcome, options?: SandboxForceFailureOptions, opts?: CallOptions): Promise<SandboxClockResult>;
|
|
1556
|
+
/**
|
|
1557
|
+
* Synthesise a cardholder authentication challenge: moves the subscription to
|
|
1558
|
+
* `awaiting_authentication` (no charge). Returns `authChallengesUsed`,
|
|
1559
|
+
* `maxAuthChallenges` (2) and `downgradedToDecline`. It does NOT mint a confirmation
|
|
1560
|
+
* link; to exercise the link and the `subscription.authentication_required` event use a
|
|
1561
|
+
* test card that requires authentication, then `forceRenewal`.
|
|
1562
|
+
*/
|
|
1563
|
+
forceAuthChallenge(subscriptionId: string, options?: SandboxForceAuthChallengeOptions, opts?: CallOptions): Promise<SandboxClockResult>;
|
|
1564
|
+
}
|
|
1565
|
+
/** Sandbox-only tooling. Reached as `invo.sandbox.*`. Nothing here exists in production. */
|
|
1566
|
+
declare class SandboxServer {
|
|
1567
|
+
/** The four subscription clock tools. See {@link SandboxSubscriptionsServer}. */
|
|
1568
|
+
readonly subscriptions: SandboxSubscriptionsServer;
|
|
1569
|
+
constructor(http: Http, auth: AuthHeader, clockKey: string | undefined);
|
|
1570
|
+
}
|
|
1571
|
+
/**
|
|
1572
|
+
* ## Storefront keys — one client per storefront
|
|
1573
|
+
*
|
|
1574
|
+
* A game that ships on more than one storefront (Steam, iOS, Android, web,
|
|
1575
|
+
* console) has one SDK key per storefront. Construct one `InvoServer` per key
|
|
1576
|
+
* and use whichever matches where the player is buying:
|
|
1577
|
+
*
|
|
1578
|
+
* ```ts
|
|
1579
|
+
* const invo = {
|
|
1580
|
+
* ios: new InvoServer({ gameSecret: process.env.INVO_KEY_IOS! }),
|
|
1581
|
+
* android: new InvoServer({ gameSecret: process.env.INVO_KEY_ANDROID! }),
|
|
1582
|
+
* web: new InvoServer({ gameSecret: process.env.INVO_KEY_WEB! }),
|
|
1583
|
+
* };
|
|
1584
|
+
* await invo[player.storefront].purchaseCurrency({ ... });
|
|
1585
|
+
* ```
|
|
1586
|
+
*
|
|
1587
|
+
* **Do not pass `rail` when using a storefront key.** The key already
|
|
1588
|
+
* determines it, and a conflicting `rail` is refused with
|
|
1589
|
+
* `RAIL_CHANNEL_MISMATCH` rather than silently overridden — see
|
|
1590
|
+
* {@link InvoError.isRailChannelMismatch}. A single legacy key with no
|
|
1591
|
+
* storefront keeps working exactly as before, `rail` included.
|
|
1592
|
+
*
|
|
1593
|
+
* These are still **server-side** keys. A storefront key names where the
|
|
1594
|
+
* purchase came from, not where the key lives; it never belongs in a game
|
|
1595
|
+
* client, an app bundle, or browser code.
|
|
1596
|
+
*/
|
|
1597
|
+
declare class InvoServer {
|
|
1598
|
+
private readonly http;
|
|
1599
|
+
private readonly auth;
|
|
1600
|
+
/**
|
|
1601
|
+
* Platform Commerce (ecommerce) — a PLATFORM tenant selling items funded by balance or
|
|
1602
|
+
* card, with refunds. DISTINCT from `purchaseItem` (a game tenant spending existing game
|
|
1603
|
+
* currency on an in-game item). See {@link PlatformCommerceServer}.
|
|
1604
|
+
*/
|
|
1605
|
+
readonly platformCommerce: PlatformCommerceServer;
|
|
1606
|
+
/**
|
|
1607
|
+
* Subscriptions (recurring billing on the card rail or the Steam rail):
|
|
1608
|
+
* `create` / `get` / `listForPlayer` / `cancel` / `changeAmount` / `setPaymentMethod` /
|
|
1609
|
+
* `refund` / `steamInit` / `steamFinalize`. See {@link SubscriptionsServer}.
|
|
1610
|
+
*/
|
|
1611
|
+
readonly subscriptions: SubscriptionsServer;
|
|
1612
|
+
/** Saved-card capture for subscriptions: `beginSetup` / `confirmSetup` / `list`. See {@link CardsServer}. */
|
|
1613
|
+
readonly cards: CardsServer;
|
|
1614
|
+
/**
|
|
1615
|
+
* Sandbox-only tooling: `sandbox.subscriptions.advanceClock` / `forceRenewal` /
|
|
1616
|
+
* `forceFailure` / `forceAuthChallenge`. Needs `sandboxClockKey`. See {@link SandboxSubscriptionsServer}.
|
|
1617
|
+
*/
|
|
1618
|
+
readonly sandbox: SandboxServer;
|
|
1619
|
+
/**
|
|
1620
|
+
* Partner payouts and creator payouts (3.25.0): `registerPayee` / `listPayees` /
|
|
1621
|
+
* `getPayee` / `resendPayeeInvite` / `requestPayout` / `getPayout` / `listPayouts` /
|
|
1622
|
+
* `cancelPayout`. See {@link PayoutsServer}.
|
|
1623
|
+
*/
|
|
1624
|
+
readonly payouts: PayoutsServer;
|
|
1625
|
+
constructor(config: ServerConfig);
|
|
1626
|
+
/**
|
|
1627
|
+
* Mint a short-lived, game-scoped player token to hand to the browser InvoClient.
|
|
1628
|
+
*
|
|
1629
|
+
* For a player who already exists in your game, this is a session mint: INVO looks the
|
|
1630
|
+
* player up by `playerEmail` and returns a token for their identity. `playerPhone` and
|
|
1631
|
+
* `playerName` do not change an existing player.
|
|
1632
|
+
*
|
|
1633
|
+
* For a player who is NOT in your game yet: without `playerPhone` INVO answers 404
|
|
1634
|
+
* (`err.isPlayerNotFound`); with `playerPhone` INVO creates the player and the result
|
|
1635
|
+
* carries `created: true`, so a first-time receiver can collect without buying first.
|
|
1636
|
+
* Use `registerPlayer` when you want creation to be explicit.
|
|
1637
|
+
*
|
|
1638
|
+
* `phoneMismatch: true` means the existing player has a different phone than the one
|
|
1639
|
+
* you passed; the token is still for that player and their phone is unchanged
|
|
1640
|
+
* (`updatePlayerPhone` changes it). A phone already held by another email is a 409
|
|
1641
|
+
* (`err.isPhoneShareRefused`).
|
|
1642
|
+
*/
|
|
1643
|
+
mintPlayerToken(input: MintPlayerTokenInput, opts?: CallOptions): Promise<PlayerToken>;
|
|
1644
|
+
/**
|
|
1645
|
+
* Create a player in your game without moving money (`POST /api/sdk/players`), so a
|
|
1646
|
+
* first-time receiver can collect in-game. Sends no message to the player.
|
|
1647
|
+
*
|
|
1648
|
+
* Returns `status: "created"` (new) or `"exists"` (already in your game with that
|
|
1649
|
+
* phone), with a player token when INVO can issue one. Refusals: 409
|
|
1650
|
+
* `err.isPhoneMismatch` (already in your game with a different phone; use
|
|
1651
|
+
* `updatePlayerPhone`), 409 `err.isPhoneShareRefused` (the phone belongs to another
|
|
1652
|
+
* email), 400 `INVALID_INPUT` / `INVALID_PHONE`, 429 (`err.retryAfter`).
|
|
1653
|
+
*/
|
|
1654
|
+
registerPlayer(input: RegisterPlayerInput, opts?: CallOptions): Promise<RegisterPlayerResult>;
|
|
1655
|
+
/**
|
|
1656
|
+
* Set a player's phone from your server (`POST /api/sdk/players/phone`). A phone change
|
|
1657
|
+
* can give the player a new INVO identity: `identityRekeyed: true`, and the result
|
|
1658
|
+
* carries a fresh `playerToken` for it (tokens minted before the change are then out
|
|
1659
|
+
* of date).
|
|
1660
|
+
*
|
|
1661
|
+
* Refusals: 409 `err.isPhoneChangeRequiresVerification` (the player has secured this
|
|
1662
|
+
* account, so the change needs the player's own confirmation: call `requestPhoneChange`;
|
|
1663
|
+
* `err.changeRequestEndpoint` names the route), 409 `err.isPhoneShareRefused` (the
|
|
1664
|
+
* number belongs to another email), 409 `err.isPendingTransfersToOldPhone` /
|
|
1665
|
+
* `err.isPendingTransfersToNewPhone` (transfers to the current or the new number are still
|
|
1666
|
+
* waiting to be collected), 404 `err.isPlayerNotFound`, 400 `INVALID_INPUT` / `INVALID_PHONE`, 429
|
|
1667
|
+
* (`err.retryAfter`), 503 (could not be checked right now; try again shortly).
|
|
1668
|
+
*
|
|
1669
|
+
* Never auto-retried: a retry after a change that landed would answer `"unchanged"` and
|
|
1670
|
+
* hide `identityRekeyed`.
|
|
1671
|
+
*/
|
|
1672
|
+
updatePlayerPhone(input: UpdatePlayerPhoneInput, opts?: CallOptions): Promise<UpdatePlayerPhoneResult>;
|
|
1673
|
+
/**
|
|
1674
|
+
* Ask the player to confirm a new phone number
|
|
1675
|
+
* (`POST /api/sdk/players/phone/change-requests`, HTTP 202). Use it when `updatePlayerPhone`
|
|
1676
|
+
* answers 409 `err.isPhoneChangeRequiresVerification`.
|
|
1677
|
+
*
|
|
1678
|
+
* Nothing about the player changes here. INVO emails the player a code and a link to a
|
|
1679
|
+
* page on INVO's site, and the player confirms there (plus their passkey on that page, or
|
|
1680
|
+
* an approval on their enrolled device, when they have one: see `confirmation`). Your game
|
|
1681
|
+
* never collects the code and never receives the link: do not ask the player for it.
|
|
1682
|
+
* Follow up with `getPhoneChange`, or wait for the `player.phone_changed` webhook.
|
|
1683
|
+
*
|
|
1684
|
+
* Refusals carry `err.code`, for example 409 `PHONE_SAME`, `PHONE_IN_USE_BY_ANOTHER_PLAYER`,
|
|
1685
|
+
* `PENDING_TRANSFERS_TO_NEW_PHONE` (`err.isPendingTransfersToNewPhone`),
|
|
1686
|
+
* `PENDING_TRANSFERS_TO_OLD_PHONE` (`err.isPendingTransfersToOldPhone`),
|
|
1687
|
+
* `CHANGE_REQUEST_IN_PROGRESS` (`err.isChangeRequestInProgress`), `PHONE_CHANGE_LOCKED`
|
|
1688
|
+
* (`err.isPhoneChangeLocked`), `PHONE_CHANGE_RECOVERY_COOLDOWN`
|
|
1689
|
+
* (`err.isPhoneChangeRecoveryCooldown`), `STEP_UP_UNAVAILABLE`, `WALLET_SECURED`,
|
|
1690
|
+
* `PHONE_NOT_SET`;
|
|
1691
|
+
* 429 `err.isTooManyChangeRequests`; 404 `err.isPlayerNotFound`; 503
|
|
1692
|
+
* `err.isPhoneChangeUnavailable`.
|
|
1693
|
+
*
|
|
1694
|
+
* Never auto-retried: a new request replaces your earlier pending one and sends the player
|
|
1695
|
+
* another email.
|
|
1696
|
+
*/
|
|
1697
|
+
requestPhoneChange(input: RequestPhoneChangeInput, opts?: CallOptions): Promise<RequestPhoneChangeResult>;
|
|
1698
|
+
/**
|
|
1699
|
+
* Read a change request your game created
|
|
1700
|
+
* (`GET /api/sdk/players/phone/change-requests/{changeRequestId}`). `status` is `pending`,
|
|
1701
|
+
* `confirmed`, `expired`, `cancelled`, `refused` or `denied`. A request another game
|
|
1702
|
+
* created, or an unknown id, is 404 `err.isChangeRequestNotFound`. Poll sparingly, or wait
|
|
1703
|
+
* for the `player.phone_changed` webhook.
|
|
1704
|
+
*/
|
|
1705
|
+
getPhoneChange(changeRequestId: string, opts?: CallOptions): Promise<PhoneChangeRequest>;
|
|
1706
|
+
/**
|
|
1707
|
+
* Initiate a cross-game currency SEND. Inspect result.verificationMethod.
|
|
1708
|
+
*
|
|
1709
|
+
* Steam titles: can throw a 409 `err.isSteamValueNonTransferable` (moving more than the
|
|
1710
|
+
* player's non-Steam balance to a non-Steam destination — cap at `err.steamTransferableMax`)
|
|
1711
|
+
* or `err.isNonSteamValueIntoSteamBlocked` (non-Steam value into a Steam title). Prevent both
|
|
1712
|
+
* up front with `DestinationGame.acceptsSteamOriginValue`.
|
|
1713
|
+
*/
|
|
1714
|
+
initiateSend(input: InitiateSendInput, opts?: CallOptions): Promise<InitiateResult>;
|
|
1715
|
+
/** Initiate a cross-game TRANSFER. Inspect result.verificationMethod. Can throw the same
|
|
1716
|
+
* Steam-policy 409s as {@link initiateSend} (`isSteamValueNonTransferable` /
|
|
1717
|
+
* `isNonSteamValueIntoSteamBlocked`). */
|
|
1718
|
+
initiateTransfer(input: InitiateTransferInput, opts?: CallOptions): Promise<InitiateResult>;
|
|
1719
|
+
/** Create a hosted checkout session (the recommended purchase path). Open the
|
|
1720
|
+
* returned checkoutUrl in a WebView/redirect or an iframe; the INVO-hosted page
|
|
1721
|
+
* handles cards, saved cards, and 3-D Secure. Crediting is server-side via the
|
|
1722
|
+
* purchase.completed webhook. */
|
|
1723
|
+
createCheckout(input: CreateCheckoutInput, opts?: CallOptions): Promise<CreateCheckoutResult>;
|
|
1724
|
+
/**
|
|
1725
|
+
* Direct purchase via the rail selector. Use when you need a specific rail.
|
|
1726
|
+
* - rail "platform" (default): standard card. May return status "requires_action"
|
|
1727
|
+
* (run client-side 3-D Secure with clientSecret, then call confirmPayment).
|
|
1728
|
+
* - rail "game": returns status "pending_payment" + paymentUrl (redirect the browser).
|
|
1729
|
+
* - rail "steam": NOT a browser flow — the backend returns WRONG_RAIL_ENDPOINT.
|
|
1730
|
+
*
|
|
1731
|
+
* INVO's card fee (3.5% + $0.30 on Open, 5.5% + $0.50 on Merchant of Record, plus 1.5% of
|
|
1732
|
+
* the listed price (before tax) on a card issued outside the US) is charged to you, the partner. The player
|
|
1733
|
+
* pays the listed price (plus any tax) and receives the listed coins. Card purchases only;
|
|
1734
|
+
* purchases through a third-party storefront or payment rail are unaffected. Two shapes,
|
|
1735
|
+
* chosen by what you send:
|
|
1736
|
+
* - with `acknowledgedTotalUsd` (the `totalUsd` from {@link quoteCurrencyPurchase}): the
|
|
1737
|
+
* card is never charged more than that total, and the coins are priced off `usdAmount`.
|
|
1738
|
+
* An older, higher fee-inclusive total is accepted and the true, lower total charged. A
|
|
1739
|
+
* total below what INVO would charge now throws `409 QUOTE_STALE` (`err.isQuoteStale`);
|
|
1740
|
+
* nothing was charged.
|
|
1741
|
+
* - without it: the card is charged exactly `usdAmount`, never more.
|
|
1742
|
+
*
|
|
1743
|
+
* From 2026-10-27 a card purchase under INVO's minimum card purchase ($2.99) throws
|
|
1744
|
+
* `400 BELOW_CARD_MINIMUM` (`err.isBelowCardMinimum`, `err.minUsd`, `err.enforcedFrom`);
|
|
1745
|
+
* until then it is accepted with `minPurchaseWarning`. `AMOUNT_BELOW_FEE` is no longer
|
|
1746
|
+
* returned.
|
|
1747
|
+
*
|
|
1748
|
+
* A `success` result reports `processingFeeUsd` (`"0.00"`), `feeTakenFrom` (`"partner"`),
|
|
1749
|
+
* `partnerFeeUsd`, `internationalCardFeeUsd` (`"0.00"` on a US card or one whose country
|
|
1750
|
+
* is unknown; both `null` if the fee could not be booked yet, which INVO does shortly after),
|
|
1751
|
+
* `coinsCredited` and `chargeTotalUsd`, each as INVO sent it.
|
|
1752
|
+
*/
|
|
1753
|
+
purchaseCurrency(input: PurchaseInput, opts?: CallOptions): Promise<PurchaseResult>;
|
|
1754
|
+
/**
|
|
1755
|
+
* What a card purchase of coins will cost, BEFORE charging for it. Moves no money and
|
|
1756
|
+
* creates nothing, so it is safe to call on every price render (`POST
|
|
1757
|
+
* /api/currency-purchases/quote`, authenticated by your game secret like the purchase).
|
|
1758
|
+
*
|
|
1759
|
+
* The player pays the listed price plus any tax (when you pass `country`) and receives the
|
|
1760
|
+
* listed coins: `totalUsd` carries no card fee, and `processingFeeUsd` is `"0.00"`. INVO's
|
|
1761
|
+
* card fee (3.5% + $0.30 on Open, 5.5% + $0.50 on Merchant of Record) is charged to you;
|
|
1762
|
+
* `partnerFeeUsd` carries it when INVO sends it. $10.00 quotes a $10.00 total, 100.00 coins
|
|
1763
|
+
* at the default 10 per USD, and a $0.65 partner fee on Open. Show the player `totalUsd`,
|
|
1764
|
+
* then send the same figure back as `acknowledgedTotalUsd` on {@link purchaseCurrency}; the
|
|
1765
|
+
* card is never charged more than that. `ifUnacknowledged` shows the purchase without the
|
|
1766
|
+
* acknowledgement (the card charged exactly `usdAmount`), or `null` when INVO sends none.
|
|
1767
|
+
* `minPurchaseWarning` is set while an amount under INVO's minimum card purchase is still
|
|
1768
|
+
* accepted. Card purchases only; purchases through a third-party storefront or payment
|
|
1769
|
+
* rail are unaffected.
|
|
1770
|
+
*
|
|
1771
|
+
* Refusals: `400 INVALID_INPUT` (amount missing, not above zero, or above INVO's card
|
|
1772
|
+
* maximum), `400 CURRENCY_NOT_CONFIGURED`, `503 RATE_UNAVAILABLE`.
|
|
1773
|
+
*/
|
|
1774
|
+
quoteCurrencyPurchase(input: CurrencyPurchaseQuoteInput, opts?: CallOptions): Promise<CurrencyPurchaseQuote>;
|
|
1775
|
+
/**
|
|
1776
|
+
* Complete the card-rail 3-D Secure step after the client finished card action.
|
|
1777
|
+
* `status: "success"` means the payment succeeded; tell the buyer the purchase is complete
|
|
1778
|
+
* only when `credited` is `true` (see {@link ConfirmPaymentResult.credited}).
|
|
1779
|
+
*/
|
|
1780
|
+
confirmPayment(input: {
|
|
1781
|
+
paymentIntentId: string;
|
|
1782
|
+
orderId?: string;
|
|
1783
|
+
}, opts?: CallOptions): Promise<ConfirmPaymentResult>;
|
|
1784
|
+
/** Fetch purchase status (order + financial summary + timeline). */
|
|
1785
|
+
getOrderDetails(query: {
|
|
1786
|
+
orderId?: string;
|
|
1787
|
+
transactionId?: string;
|
|
1788
|
+
}, opts?: CallOptions): Promise<OrderDetailsResult>;
|
|
1789
|
+
/**
|
|
1790
|
+
* The Steam packs INVO sells, and what each contains for one player.
|
|
1791
|
+
*
|
|
1792
|
+
* The PRICE is identical for every player and is INVO's to set; the
|
|
1793
|
+
* `currencyAmount` varies by country. Render it verbatim — never compute
|
|
1794
|
+
* currency from the sticker price (VAT and the storefront's revenue share
|
|
1795
|
+
* come out of the sticker before currency is derived), and never cache one
|
|
1796
|
+
* answer for all players. Without `steamid` the quote assumes no VAT — the
|
|
1797
|
+
* most any pack yields; the purchase itself always re-derives.
|
|
1798
|
+
*
|
|
1799
|
+
* Refusals: `err.isSteamRailNotEntitled` (403). A missing Steam
|
|
1800
|
+
* registration does NOT refuse here — packs deliberately answers with the
|
|
1801
|
+
* no-VAT catalogue and lets the PURCHASE be what refuses; the only 503 is
|
|
1802
|
+
* the rail being disabled platform-wide, whose body carries no error code.
|
|
1803
|
+
*/
|
|
1804
|
+
steamPacks(query?: SteamPacksQuery, opts?: CallOptions): Promise<SteamPacksResult>;
|
|
1805
|
+
/**
|
|
1806
|
+
* Start a Steam micro-transaction. The player then authorizes — in the Steam
|
|
1807
|
+
* overlay (`usersession: "client"`, the default) or on Steam's hosted
|
|
1808
|
+
* checkout page (`usersession: "web"`, returned as `steamCheckoutUrl`; open
|
|
1809
|
+
* it as a TOP-LEVEL tab, never an iframe; requires `playerIp`). After
|
|
1810
|
+
* authorization, call {@link steamFinalizePurchase} with the returned
|
|
1811
|
+
* `orderId`.
|
|
1812
|
+
*
|
|
1813
|
+
* Idempotent on `purchaseReference`, with one wire subtlety: a resend does
|
|
1814
|
+
* not replay the original body — it answers **409 `DUPLICATE_REQUEST`**
|
|
1815
|
+
* whose body carries the existing `order_id` (read it from `err.body`).
|
|
1816
|
+
* Never double-charges. Retries — including manual retries after a 409 —
|
|
1817
|
+
* MUST reuse the reference; a fresh one is a second intended purchase. For
|
|
1818
|
+
* WEB sessions, persist `steamCheckoutUrl` from the first success: the 409
|
|
1819
|
+
* body does not repeat it.
|
|
1820
|
+
*
|
|
1821
|
+
* Refusals worth branching on: `err.isPartnerCreditUnavailable` (409, the
|
|
1822
|
+
* studio's settlement float cannot cover it — plain failure toast, do NOT
|
|
1823
|
+
* hot-poll), `err.isPartnerRailSuspended` (409, terminal from the game's
|
|
1824
|
+
* seat), `err.isPartnerBillingNotSetUp` (409), `err.isUnknownSteamPack`
|
|
1825
|
+
* (400 — re-fetch `steamPacks()`), `err.isSteamNotConfigured` (503),
|
|
1826
|
+
* `err.isSteamRailNotEntitled` (403), `err.isMissingPlayerIp` (400),
|
|
1827
|
+
* `err.isDuplicateRequest` (409).
|
|
1828
|
+
*/
|
|
1829
|
+
steamInitPurchase(input: SteamInitPurchaseInput, opts?: CallOptions): Promise<SteamInitPurchaseResult>;
|
|
1830
|
+
/**
|
|
1831
|
+
* Capture an authorized Steam transaction and credit the player.
|
|
1832
|
+
*
|
|
1833
|
+
* Idempotent: a retry or duplicate returns `alreadyProcessed: true` and
|
|
1834
|
+
* never credits twice. Poller taxonomy — NOT every 409 means "not yet":
|
|
1835
|
+
*
|
|
1836
|
+
* - `err.isSteamAuthorizationPending` — the player has not approved yet
|
|
1837
|
+
* (Steam still reports Init). Wait / poll again. THE NORMAL STATE.
|
|
1838
|
+
* - `err.isSteamAuthorizationDead` — Failed / Refunded / Chargedback.
|
|
1839
|
+
* STOP polling; no later call can succeed.
|
|
1840
|
+
* - `err.isSteamAppChanged` (409) — the title's registration changed under
|
|
1841
|
+
* the order. Terminal for this order.
|
|
1842
|
+
* - 502 / 503 — transient; retry.
|
|
1843
|
+
*
|
|
1844
|
+
* A missed finalize is not a lost credit: INVO's reconciler independently
|
|
1845
|
+
* detects the authorized transaction and credits, on a delay.
|
|
1846
|
+
*/
|
|
1847
|
+
steamFinalizePurchase(input: SteamFinalizeInput, opts?: CallOptions): Promise<SteamFinalizeResult>;
|
|
1848
|
+
/**
|
|
1849
|
+
* Buy an in-game item by SPENDING the player's existing game currency (§4.8).
|
|
1850
|
+
* No real money, no payment rail, no passkey — it's a balance debit, authenticated
|
|
1851
|
+
* server-side by the game secret. Idempotent on clientRequestId (a duplicate throws
|
|
1852
|
+
* a 409 InvoError; check err.isDuplicateRequest). Insufficient balance throws a 400
|
|
1853
|
+
* (err.isInsufficientBalance; required_amount/current_balance on err.body). Grant the
|
|
1854
|
+
* item to your inventory off the `item.purchased` webhook, not just this response.
|
|
1855
|
+
*/
|
|
1856
|
+
purchaseItem(input: PurchaseItemInput, opts?: CallOptions): Promise<PurchaseItemResult>;
|
|
1857
|
+
/** Paginated item-purchase history for a player (§4.8 companion read). */
|
|
1858
|
+
getItemPurchaseHistory(query: ItemHistoryQuery, opts?: CallOptions): Promise<ItemHistoryResult>;
|
|
1859
|
+
/** Look up one item order by EXACTLY ONE of orderId | transactionId | clientRequestId
|
|
1860
|
+
* (§4.8). Use clientRequestId for saga/recovery: "did this purchase actually complete?" */
|
|
1861
|
+
getItemOrderDetails(query: ItemOrderQuery, opts?: CallOptions): Promise<OrderDetailsResult>;
|
|
1862
|
+
/**
|
|
1863
|
+
* Async iterator over a player's entire item-purchase history — pages through
|
|
1864
|
+
* `getItemPurchaseHistory` (limit/offset) until exhausted, yielding one row at a time.
|
|
1865
|
+
*
|
|
1866
|
+
* ```ts
|
|
1867
|
+
* for await (const row of invo.iterateItemPurchaseHistory({ playerEmail })) { … }
|
|
1868
|
+
* ```
|
|
1869
|
+
*/
|
|
1870
|
+
iterateItemPurchaseHistory(query: {
|
|
1871
|
+
playerEmail: string;
|
|
1872
|
+
pageSize?: number;
|
|
1873
|
+
}, opts?: CallOptions): AsyncGenerator<Record<string, unknown>, void, unknown>;
|
|
1874
|
+
/**
|
|
1875
|
+
* One merged, newest-first list of a player's money activity in your game, one page at a
|
|
1876
|
+
* time (`GET /api/sdk/players/activity`): currency purchases, item purchases, Platform
|
|
1877
|
+
* Commerce purchases, sends and transfers, in both directions. Only rows where your game
|
|
1878
|
+
* is a party through this player are listed; the other side of a cross-game send or
|
|
1879
|
+
* transfer is named by game only (`counterpartyGame`).
|
|
1880
|
+
*
|
|
1881
|
+
* An inbound (`direction: "in"`) send or transfer is listed as soon as it names this
|
|
1882
|
+
* player, in ANY status (awaiting collection, completed, expired, refunded): read `status`
|
|
1883
|
+
* and `statusDetail` before treating it as credited. `direction` is `"in"` / `"out"` /
|
|
1884
|
+
* `"self"`, not the `"incoming"` / `"outgoing"` of the per-type history reads.
|
|
1885
|
+
*
|
|
1886
|
+
* Pass `nextCursor` back as `cursor` (with the same `types`) for the next page; it is
|
|
1887
|
+
* `null` on the last one. `iteratePlayerActivity` walks every page.
|
|
1888
|
+
*
|
|
1889
|
+
* Refusals (`InvoError`): a blank `playerEmail` or a bad `limit` / `cursor` / `types`
|
|
1890
|
+
* throws `INVALID_INPUT` before the network; `400 INVALID_INPUT` (for example an unknown
|
|
1891
|
+
* kind in `types`), `400 INVALID_CURSOR` (a cursor from another player or other `types`),
|
|
1892
|
+
* `401 INVALID_GAME_SECRET`, `404 PLAYER_NOT_FOUND` (`err.isPlayerNotFound`),
|
|
1893
|
+
* `500 PLAYER_ACTIVITY_FAILED` (retry later), `429` (back off; `err.retryAfter`). A GET, so
|
|
1894
|
+
* transient failures are retried automatically.
|
|
1895
|
+
*/
|
|
1896
|
+
getPlayerActivity(query: PlayerActivityQuery, opts?: CallOptions): Promise<PlayerActivityResult>;
|
|
1897
|
+
/**
|
|
1898
|
+
* Async iterator over a player's ENTIRE activity, newest first: pages through
|
|
1899
|
+
* `getPlayerActivity` by `nextCursor`, yielding one row at a time.
|
|
1900
|
+
*
|
|
1901
|
+
* ```ts
|
|
1902
|
+
* for await (const row of invo.iteratePlayerActivity({ playerEmail, types: ["send", "transfer"] })) { … }
|
|
1903
|
+
* ```
|
|
1904
|
+
*/
|
|
1905
|
+
iteratePlayerActivity(query: {
|
|
1906
|
+
playerEmail: string;
|
|
1907
|
+
types?: PlayerActivityQuery["types"];
|
|
1908
|
+
pageSize?: number;
|
|
1909
|
+
}, opts?: CallOptions): AsyncGenerator<PlayerActivityEntry, void, unknown>;
|
|
1910
|
+
/**
|
|
1911
|
+
* Read a player's currency balances by email (server-side, game-secret).
|
|
1912
|
+
*
|
|
1913
|
+
* NOTE: lookup is by EMAIL only. There is no by-id balance route on the backend
|
|
1914
|
+
* (`playerId` is a per-game internal id), so passing `playerId` throws — use the
|
|
1915
|
+
* browser `InvoClient.getBalance()` (token-authed, identity from the token) for a
|
|
1916
|
+
* client-side read, or `playerEmail` here server-side.
|
|
1917
|
+
*/
|
|
1918
|
+
getPlayerBalance(query: PlayerBalanceQuery, opts?: CallOptions): Promise<PlayerBalanceResult>;
|
|
1919
|
+
/**
|
|
1920
|
+
* One player's loyalty cards, read by your SERVER with the game secret: the same cards
|
|
1921
|
+
* the player sees through `InvoClient.getMyRewards()`, for the player with this email in
|
|
1922
|
+
* your game. Each step carries `state` and `progress` (`{ current, target }`, or `null`
|
|
1923
|
+
* when the number could not be read this time: render `state` alone then). Rewards carry
|
|
1924
|
+
* their masked code only; a code is never returned here.
|
|
1925
|
+
*
|
|
1926
|
+
* Refusals (all `InvoError`): a blank email throws `INVALID_INPUT` before the network;
|
|
1927
|
+
* `400 INVALID_PLAYER_EMAIL` (`err.isInvalidPlayerEmail`), `401 INVALID_GAME_SECRET` for a missing or wrong key, or
|
|
1928
|
+
* a per-channel key (this read takes the game's server secret only), `404 PLAYER_NOT_FOUND`
|
|
1929
|
+
* (`err.isPlayerNotFound`: no player with this email in this game), `429` (back off;
|
|
1930
|
+
* `err.retryAfter`). Also `409 NO_TENANT` (the game is not set up for loyalty), `503`
|
|
1931
|
+
* (temporarily unavailable) and `502` / `504` (the loyalty service could not be reached or
|
|
1932
|
+
* timed out): retry later. A GET, so transient failures are retried automatically.
|
|
1933
|
+
*/
|
|
1934
|
+
getPlayerRewards(playerEmail: string, opts?: CallOptions): Promise<LoyaltyCardsResult>;
|
|
1935
|
+
/**
|
|
1936
|
+
* Report a gameplay event for one player to INVO's loyalty engine from your SERVER
|
|
1937
|
+
* (`POST /api/sdk/loyalty/server-events`, game secret). Server-reported events are the
|
|
1938
|
+
* ones trusted for rewards. Use it for sessions, level milestones and custom events
|
|
1939
|
+
* registered in the console (see {@link GameEventType}); currency steps are tracked by
|
|
1940
|
+
* INVO itself and are never reported.
|
|
1941
|
+
*
|
|
1942
|
+
* Idempotent on `eventId`: pass your own UUID, or let the SDK generate one, and reuse the
|
|
1943
|
+
* returned `eventId` if you retry. Transient failures (429, 5xx) are retried with it.
|
|
1944
|
+
*
|
|
1945
|
+
* Refusals (all `InvoError`): `INVALID_INPUT` before the network for a non-`game.*` type,
|
|
1946
|
+
* a malformed `eventId`, an `occurredAt` without a timezone or a non-object payload;
|
|
1947
|
+
* `400 RESERVED_EVENT_TYPE` / `EVENT_TYPE_NOT_ALLOWED`; `401 INVALID_GAME_SECRET`;
|
|
1948
|
+
* `404 PLAYER_NOT_FOUND` (`err.isPlayerNotFound`); `422 validation_failed` (for example an
|
|
1949
|
+
* unregistered `event_name`).
|
|
1950
|
+
*/
|
|
1951
|
+
reportGameEvent(input: ReportServerGameEventInput, opts?: CallOptions): Promise<ReportGameEventResult>;
|
|
1952
|
+
/**
|
|
1953
|
+
* List LIVE, unclaimed inbound sends/transfers addressed to a player at YOUR game —
|
|
1954
|
+
* the source of truth for a "you have X to collect" badge. Pass the player's email
|
|
1955
|
+
* or phone. Match `toPhone` to the logged-in player (don't require `toIdentityId`,
|
|
1956
|
+
* which is null when the phone maps to more than one of your players). Pairs with the
|
|
1957
|
+
* `transfer.claim_pending` webhook (the webhook is the wake-up; this is the list).
|
|
1958
|
+
*/
|
|
1959
|
+
getInboundPending(query: InboundPendingQuery, opts?: CallOptions): Promise<InboundPendingResult>;
|
|
1960
|
+
/**
|
|
1961
|
+
* Look up a player's linked wallet identities (SERVER-only, game-secret). Game-scoped:
|
|
1962
|
+
* returns wallet members that also have a Player row on this game. Provide a `playerEmail`
|
|
1963
|
+
* or `playerPhone` (phone wins if both). No in-game match (backend 404) returns
|
|
1964
|
+
* `notFound: true` with empty `emails` — not an error.
|
|
1965
|
+
*
|
|
1966
|
+
* ⚠️ Returns first-party PII (emails/phones) — never expose this to the browser.
|
|
1967
|
+
*/
|
|
1968
|
+
getLinkedIdentities(query: LinkedIdentitiesQuery, opts?: CallOptions): Promise<LinkedIdentitiesResult>;
|
|
1969
|
+
/**
|
|
1970
|
+
* Complete a TRANSFER's SMS-PIN step — the LAST-RESORT fallback for a sender who has
|
|
1971
|
+
* no passkey.
|
|
1972
|
+
*
|
|
1973
|
+
* @deprecated The SMS-PIN path is being phased out and a future major version will
|
|
1974
|
+
* remove this method. **Passkeys are the gold standard for authorizing money movement**
|
|
1975
|
+
* — an SMS PIN is a shared secret on a channel exposed to SIM swap and interception,
|
|
1976
|
+
* and it is not a peer of a WebAuthn assertion. When `initiate*` returns
|
|
1977
|
+
* `verificationMethod: "sms"` it is telling you the sender has no passkey: prompt
|
|
1978
|
+
* `InvoClient.enrollPasskey()` and then approve with
|
|
1979
|
+
* `InvoClient.approveTransfer(transactionId)`. Reach for this method only when the user
|
|
1980
|
+
* cannot enroll (unsupported device) or declines. Still fully functional — this
|
|
1981
|
+
* annotation changes documentation only, not behavior.
|
|
1982
|
+
*
|
|
1983
|
+
* NOT idempotent — each attempt is counted server-side, so this is never auto-retried.
|
|
1984
|
+
* A bad PIN throws a 400 InvoError carrying `attempts_remaining` on `err.body`; a
|
|
1985
|
+
* blocked recipient throws 429 (`sms_verification_blocked`).
|
|
1986
|
+
*/
|
|
1987
|
+
verifySmsTransfer(transactionId: string, smsPin: string, opts?: CallOptions): Promise<SmsVerifyResult>;
|
|
1988
|
+
/**
|
|
1989
|
+
* Complete a SEND's SMS-PIN step — the LAST-RESORT fallback for a sender who has no
|
|
1990
|
+
* passkey. See {@link verifySmsTransfer}.
|
|
1991
|
+
*
|
|
1992
|
+
* @deprecated The SMS-PIN path is being phased out and a future major version will
|
|
1993
|
+
* remove this method. Prompt `InvoClient.enrollPasskey()` and approve with
|
|
1994
|
+
* `InvoClient.approveSend(transactionId)` instead; use this only when the user cannot
|
|
1995
|
+
* enroll or declines. Documentation only — behavior is unchanged.
|
|
1996
|
+
*/
|
|
1997
|
+
verifySmsSend(transactionId: string, smsPin: string, opts?: CallOptions): Promise<SmsVerifyResult>;
|
|
1998
|
+
/**
|
|
1999
|
+
* Claim an inbound TRANSFER by its claim code, crediting one of this game's currencies.
|
|
2000
|
+
* NOT idempotent. A 200 may come back as `needsAccountSelection` (the recipient phone
|
|
2001
|
+
* maps to >1 of your players) — inspect `result.candidates` and re-submit with
|
|
2002
|
+
* `targetPlayerId`. Errors surface via InvoError (404 unknown code, 403 phone mismatch,
|
|
2003
|
+
* 400 not-claimable/expired/wrong-value, 409 `err.isPhoneShareApprovalRequired`, …).
|
|
2004
|
+
*/
|
|
2005
|
+
claimTransfer(input: ClaimTransferInput, opts?: CallOptions): Promise<ClaimResult>;
|
|
2006
|
+
/**
|
|
2007
|
+
* Claim an inbound SEND by its claim code. NOT idempotent. May return
|
|
2008
|
+
* `needsAccountSelection` (multi-account phone) — re-submit with `receiverPlayerId`.
|
|
2009
|
+
* See claimTransfer for the error surface.
|
|
2010
|
+
*/
|
|
2011
|
+
claimCurrency(input: ClaimCurrencyInput, opts?: CallOptions): Promise<ClaimResult>;
|
|
2012
|
+
/** Read a TRANSFER's status (verification_state + amounts + destination). */
|
|
2013
|
+
getTransferStatus(transactionId: string, opts?: CallOptions): Promise<TransactionStatusResult>;
|
|
2014
|
+
/** Read a SEND's status (adds fees, game names, claim_info, … on `raw`). */
|
|
2015
|
+
getSendStatus(transactionId: string, opts?: CallOptions): Promise<TransactionStatusResult>;
|
|
2016
|
+
/**
|
|
2017
|
+
* Poll a transaction's guardian approval status (minor/guardian flow). The retry
|
|
2018
|
+
* layer already retries the 503 (`{status:"unavailable"}`) for this idempotent GET;
|
|
2019
|
+
* a missing approval throws a 404 InvoError (`{status:"not_found"}`).
|
|
2020
|
+
*/
|
|
2021
|
+
getGuardianApprovalStatus(transactionId: string, opts?: CallOptions): Promise<GuardianApprovalStatusResult>;
|
|
2022
|
+
/**
|
|
2023
|
+
* List the games/tenants a player can send/transfer to FROM `sourceGameId`, with
|
|
2024
|
+
* display metadata inline (name, icon, currency, min/max limits) — one call, no
|
|
2025
|
+
* per-game lookup. SERVER variant (game-secret) of the browser `InvoClient.getDestinations`;
|
|
2026
|
+
* the source game is passed explicitly rather than inferred from a player token. Rows
|
|
2027
|
+
* share the browser shape. Idempotent (a POST read — safe to retry).
|
|
2028
|
+
*/
|
|
2029
|
+
getDestinations(query: ServerDestinationsQuery, opts?: CallOptions): Promise<DestinationsResult>;
|
|
2030
|
+
/**
|
|
2031
|
+
* Phone-share OTP handshake — resolves a 409 `PHONE_SHARE_APPROVAL_REQUIRED`.
|
|
2032
|
+
*
|
|
2033
|
+
* These three endpoints are UNAUTHENTICATED (phone-owner-driven: no game secret,
|
|
2034
|
+
* no player token) — a partner backend relays the handshake. The triggering 409
|
|
2035
|
+
* carries `approval_id, expires_at, code_sent, existing_account_hints[], next_endpoint`.
|
|
2036
|
+
*
|
|
2037
|
+
* `phoneShareInitiate` is the fallback OTP send (use when the 409 didn't already
|
|
2038
|
+
* dispatch a code). NOT idempotent — never auto-retried. OTP TTL ~10 min.
|
|
2039
|
+
*/
|
|
2040
|
+
phoneShareInitiate(input: PhoneShareContact, opts?: CallOptions): Promise<PhoneShareInitiateResult>;
|
|
2041
|
+
/**
|
|
2042
|
+
* Approve a phone-share with the OTP the phone owner received. On success the grant
|
|
2043
|
+
* is stored server-side, keyed by (phone, requesting_email) and auto-consumed — the
|
|
2044
|
+
* caller simply RE-ISSUES the identical original request. UNAUTHENTICATED. NOT
|
|
2045
|
+
* idempotent (attempts are counted) — never auto-retried.
|
|
2046
|
+
*/
|
|
2047
|
+
phoneShareApprove(input: PhoneShareApproveInput, opts?: CallOptions): Promise<PhoneShareApproveResult>;
|
|
2048
|
+
/**
|
|
2049
|
+
* Poll whether a phone-share (phone, requesting_email) pair is approved yet.
|
|
2050
|
+
* UNAUTHENTICATED, idempotent GET. `approved:true` means the original request can
|
|
2051
|
+
* be re-issued.
|
|
2052
|
+
*/
|
|
2053
|
+
phoneShareStatus(input: PhoneShareContact, opts?: CallOptions): Promise<PhoneShareStatusResult>;
|
|
2054
|
+
/**
|
|
2055
|
+
* Stage 1 — start a device approval for ONE transaction (RFC 8628 §3.1/§3.2).
|
|
2056
|
+
*
|
|
2057
|
+
* Returns the grant: render `verificationUriComplete` as the QR (print `userCode`
|
|
2058
|
+
* under it for a TV with no camera), keep `deviceCode` on your server, then poll.
|
|
2059
|
+
* A repeat `begin` while an earlier grant is merely PENDING supersedes it (fresh code;
|
|
2060
|
+
* a page still open on the old one is told to scan again). A grant the player already
|
|
2061
|
+
* APPROVED blocks a new `begin` for its window with `409 DEVICE_APPROVAL_ALREADY_PENDING`
|
|
2062
|
+
* (`err.isDeviceApprovalAlreadyPending`, `err.deviceApprovalExpiresAt`) — the missing
|
|
2063
|
+
* step there is `approveWithDeviceCode`, not a new code.
|
|
2064
|
+
*
|
|
2065
|
+
* For `transfer` / `send` the backend also pushes the transaction's own approval
|
|
2066
|
+
* window past the grant's expiry, so an approval at minute nine cannot land on a
|
|
2067
|
+
* transfer that has already been refunded. Auth: the player token. `channel: "popup"`
|
|
2068
|
+
* is browser-only (`InvoClient.approveHosted`) and is refused before the network.
|
|
2069
|
+
*/
|
|
2070
|
+
beginDeviceApproval(input: BeginDeviceApprovalInput, opts?: CallOptions): Promise<DeviceApprovalGrant>;
|
|
2071
|
+
/**
|
|
2072
|
+
* Stage 3 — one poll (RFC 8628 §3.4/§3.5). Call it no faster than `interval` seconds.
|
|
2073
|
+
*
|
|
2074
|
+
* Returns `status`:
|
|
2075
|
+
* - `authorization_pending` — keep polling. While a first-time phone waits on your
|
|
2076
|
+
* screen, `enrollment` is present: show "Set up INVO on <deviceLabel>? Code
|
|
2077
|
+
* <matchCode>" and answer with `confirmDeviceEnrollment`.
|
|
2078
|
+
* - `slow_down` — add 5 s to your interval, then resume.
|
|
2079
|
+
* - `approved` — **now call `approveWithDeviceCode`**. Nothing has moved yet.
|
|
2080
|
+
* - `access_denied` — the player declined; do not retry silently.
|
|
2081
|
+
* - `expired_token` — the grant lapsed; `beginDeviceApproval` again.
|
|
2082
|
+
* Throws `InvoError` for `invalid_grant` (`err.code === "invalid_grant"`: unknown code,
|
|
2083
|
+
* or not this player's — one answer for both, deliberately) and for transport failures
|
|
2084
|
+
* after the retry budget (429 / 5xx are retried: this is an idempotent read).
|
|
2085
|
+
*/
|
|
2086
|
+
pollDeviceApproval(input: PollDeviceApprovalInput, opts?: CallOptions): Promise<DeviceApprovalPollResult>;
|
|
2087
|
+
/**
|
|
2088
|
+
* Stage 3b — answer the on-screen match-code prompt for a first-time phone.
|
|
2089
|
+
*
|
|
2090
|
+
* `approve` = "yes, the phone I just scanned with shows this code" (the phone then
|
|
2091
|
+
* creates its INVO passkey and approves); `deny` ends the whole grant — the next poll
|
|
2092
|
+
* answers `access_denied`. Answered once: `409 DEVICE_APPROVAL_ENROLLMENT_ALREADY_DECIDED`
|
|
2093
|
+
* means the backup email got there first — take the prompt down quietly.
|
|
2094
|
+
* `409 DEVICE_APPROVAL_NO_ENROLLMENT_PENDING`: no phone has asked. Not auto-retried.
|
|
2095
|
+
*/
|
|
2096
|
+
confirmDeviceEnrollment(input: ConfirmDeviceEnrollmentInput, opts?: CallOptions): Promise<ConfirmDeviceEnrollmentResult>;
|
|
2097
|
+
/**
|
|
2098
|
+
* Stage 4 — THE MONEY STEP. Once the poll says `approved`, call this with the same
|
|
2099
|
+
* player token and the grant's `deviceCode`. Routes by `flow`:
|
|
2100
|
+
*
|
|
2101
|
+
* transfer → POST /api/sdk/transfers/{id}/approve
|
|
2102
|
+
* send → POST /api/sdk/send/{id}/approve
|
|
2103
|
+
* send_receipt → POST /api/sdk/send/{id}/confirm-receipt
|
|
2104
|
+
* transfer_receipt → POST /api/sdk/transfers/{id}/confirm-receipt
|
|
2105
|
+
*
|
|
2106
|
+
* The grant proves WHO approved; this call runs every gate the in-app passkey approve
|
|
2107
|
+
* runs (guardian, risk, recovery cooldown) and moves the money. A grant that is never
|
|
2108
|
+
* followed by this call moves nothing, and is consumed by nothing.
|
|
2109
|
+
*
|
|
2110
|
+
* Result: `status: "approved"` + `next: "pending_claim"` (transfer/send; `claimCode`
|
|
2111
|
+
* on a transfer) or `status: "completed"` + `amountReceived` (receipt flows). A 202
|
|
2112
|
+
* hold returns `holdReason` (money held, not refused). A repeat call after the code was
|
|
2113
|
+
* consumed returns `status: "not_pending"` with `currentStatus` and `alreadySettled`
|
|
2114
|
+
* — the backend's `TRANSACTION_NOT_PENDING` mapped into a result rather than thrown,
|
|
2115
|
+
* because for this call it is the normal answer to "did my earlier attempt land?".
|
|
2116
|
+
*
|
|
2117
|
+
* Throws `InvoError`: `err.isDeviceApprovalNotApproved` (400 — wrong/foreign code,
|
|
2118
|
+
* wrong flow, or the poll never said approved), `err.isPasskeyRecoveryCooldown` (403,
|
|
2119
|
+
* money-out after a passkey recovery — `err.retryAfterAt`), `err.isPlayerTokenStale`
|
|
2120
|
+
* (403, the player token predates the sender's phone being added: re-mint, or use the
|
|
2121
|
+
* initiate's `playerToken`, and retry once), guardian terminal states (410). Never
|
|
2122
|
+
* auto-retried: the device_code is a single-use factor.
|
|
2123
|
+
*
|
|
2124
|
+
* **A FAILURE HERE IS AMBIGUOUS ABOUT THE MONEY.** The backend commits the transfer and
|
|
2125
|
+
* *then* builds its 200 by reading the transaction back, so a fault raised after that
|
|
2126
|
+
* commit answers `SEND_APPROVE_FAILED` / `TRANSFER_APPROVE_FAILED` /
|
|
2127
|
+
* `CONFIRM_RECEIPT_FAILED` (`err.isSettleFault`, `err.errorRef`) for money that already
|
|
2128
|
+
* moved. A `status === 0` (timeout, connection dropped) is ambiguous for the same
|
|
2129
|
+
* reason, and this call is deliberately not auto-retried. So on either: read
|
|
2130
|
+
* `getTransferStatus` / `getSendStatus`, or wait for the `transfer.claim_pending`
|
|
2131
|
+
* webhook, BEFORE you tell the player it failed — and never auto-start a replacement
|
|
2132
|
+
* transaction.
|
|
2133
|
+
*/
|
|
2134
|
+
approveWithDeviceCode(input: ApproveWithDeviceCodeInput, opts?: CallOptions): Promise<DeviceApprovalSettleResult>;
|
|
2135
|
+
/**
|
|
2136
|
+
* Convenience only — stages 3 and 4 in one call, for a server that can hold the loop
|
|
2137
|
+
* open (a per-request worker, a job). Polls `pollDeviceApproval` on `interval`, adds
|
|
2138
|
+
* 5 s on `slow_down`, forwards the poll's `enrollment` to `onEnrollment` (answer with
|
|
2139
|
+
* `respond`), and on `approved` calls `approveWithDeviceCode` — THEN resolves.
|
|
2140
|
+
* `respond` is best-effort: a prompt the grant has outlived (`expired_token`,
|
|
2141
|
+
* `invalid_grant`) or that was already answered elsewhere resolves quietly rather than
|
|
2142
|
+
* rejecting, because callers fire it from UI code without awaiting it.
|
|
2143
|
+
* You still call `beginDeviceApproval` yourself first, because your game has to draw
|
|
2144
|
+
* the QR between begin and the first poll.
|
|
2145
|
+
*
|
|
2146
|
+
* Resolves `{ status: "approved", settlement }` | `denied` | `expired` | `aborted`.
|
|
2147
|
+
* Rejects on `invalid_grant`, on a refused approve (e.g. `PASSKEY_RECOVERY_COOLDOWN`),
|
|
2148
|
+
* and after 5 consecutive transport failures on the poll.
|
|
2149
|
+
*
|
|
2150
|
+
* **Record the attempt in your own store BEFORE you call this.** It blocks for as long
|
|
2151
|
+
* as the player takes and then moves money from inside the loop, so if your process
|
|
2152
|
+
* dies between the approve call and its response, a row you wrote first — plus
|
|
2153
|
+
* `getTransferStatus` / `getSendStatus` — is the only way to learn whether the money
|
|
2154
|
+
* moved. Servers that must not block a request use the three calls directly and keep
|
|
2155
|
+
* `deviceCode` in their own store.
|
|
2156
|
+
*
|
|
2157
|
+
* `respond` (handed to `onEnrollment`) is best-effort: a prompt the grant has outlived
|
|
2158
|
+
* resolves quietly rather than rejecting. Any other confirm-enrollment refusal
|
|
2159
|
+
* propagates, so `await` it if you want to see one.
|
|
2160
|
+
*/
|
|
2161
|
+
completeDeviceApproval(input: CompleteDeviceApprovalInput, opts?: CallOptions): Promise<CompleteDeviceApprovalResult>;
|
|
2162
|
+
private toInitiateResult;
|
|
2163
|
+
}
|
|
2164
|
+
|
|
2165
|
+
export { type SubscriptionRenewedData as $, type RegisterPayeeResult as A, type RequestPayoutInput as B, CardsServer as C, DEMO_KEY_PREFIX as D, EnvironmentUnknownError as E, type RequestPayoutResult as F, type ReturnReasonCode as G, SandboxServer as H, InvoServer as I, SandboxSubscriptionsServer as J, type SubscriptionAuthenticationRequiredData as K, type ListPayeesQuery as L, type SubscriptionCanceledData as M, type SubscriptionEventCommon as N, type SubscriptionExpiredData as O, PRODUCTION_BASE_URL as P, type SubscriptionPastDueData as Q, type RegisterPayeeInput as R, SANDBOX_BASE_URL as S, type SubscriptionPaymentFailedData as T, type SubscriptionRefundApprovedData as U, type SubscriptionRefundDetail as V, type SubscriptionRefundRejectedData as W, type SubscriptionRefundRequestData as X, type SubscriptionRefundedData as Y, type SubscriptionRenewalFunding as Z, type SubscriptionRenewalSplit as _, type InvoEnvironment as a, type SubscriptionRevenueShareAttribution as a0, type SubscriptionTrialEventFields as a1, SubscriptionsServer as a2, type TransferEventData as a3, type VerifyWebhookOptions as a4, type WebhookHandlerOptions as a5, createWebhookHandler as a6, verifyWebhook as a7, verifyWebhookAsync as a8, baseUrlForKey as b, type IdentityPasskeyResetData as c, type InvoWebhookEvent as d, type ItemPurchasedData as e, type ListPayeesResult as f, type ListPayoutsQuery as g, type ListPayoutsResult as h, isDemoKey as i, type PayableBlocker as j, type Payee as k, type PayeeInvite as l, type PayeeStatus as m, type PayeeStatusChangedData as n, type Payout as o, type PayoutStatus as p, type PayoutStatusChangedData as q, resolveEnvironment as r, PayoutsServer as s, type PlatformCommercePurchasedData as t, type PlatformCommerceRefundedData as u, verifyInvoSignature as v, PlatformCommerceServer as w, type PlayerPhoneChangedData as x, type PurchaseCompletedData as y, type PurchaseEventData as z };
|