@invonetwork/web-sdk 3.12.1 → 3.14.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 +27 -0
- package/README.md +169 -20
- package/dist/{chunk-5BMM5ZTW.js → chunk-BLY4NUMG.js} +116 -4
- package/dist/index.cjs +105 -1
- package/dist/index.d.cts +2 -17
- package/dist/index.d.ts +2 -17
- package/dist/index.js +3 -2
- package/dist/server.cjs +280 -4
- package/dist/server.d.cts +128 -11
- package/dist/server.d.ts +128 -11
- package/dist/server.js +169 -5
- package/dist/{types-CT0Ksonp.d.cts → types-CD83iV3D.d.cts} +358 -12
- package/dist/{types-CT0Ksonp.d.ts → types-CD83iV3D.d.ts} +358 -12
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,32 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 3.14.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- 8f2298b: `credited` and `reasonCode` on `confirmPayment()` and `steamFinalizePurchase()` results (mapped from the additive `credited` / `reason_code` response fields; `status` is unchanged and still means the payment succeeded, so report a completed purchase only when `credited` is `true`). Merchant of Record receipt fields `receiptNumber` / `receiptUrl` on `purchaseCurrency()`, `getOrderDetails()`, `CheckoutClient.getPurchaseStatus()`, `platformCommerce.getStatus()` and `firstCharge`, and `receipt_number` / `receipt_url` (plus `tax_treatment` on `purchase.completed`) on the purchase, Platform Commerce and subscription webhook payload types. README: the tier's effect on responses (`tax_treatment: "partner_responsible"` on Open, receipts and the chargeback reserve on Merchant of Record). Platform Commerce card refunds in parts: optional `refundRemaining` / `confirmAdditionalRefund` on `platformCommerce.refund()`, optional `partialRefund` / `adopted` / `refundedTotalUsd` / `chargeTotalUsd` / `remainingUsd` on its result, and `err.isRefundRemainingRequiresConfirmation` / `err.isRefundRecentlyIssued` / `err.isRefundNotCompleted` (`err.isAlreadyRefunded` is now false for the two refund-in-parts refusals). All additive and optional. README: subscription card charges are 4% + $0.30 on Open and 5% + $0.50 on Merchant of Record (were 7% + $0.30 and 8.5% + $0.30); international card and currency conversion costs on subscriptions pass through at cost; chargebacks by tier; Merchant of Record is applied for from the console.
|
|
8
|
+
|
|
9
|
+
## 3.13.0
|
|
10
|
+
|
|
11
|
+
### Minor Changes
|
|
12
|
+
|
|
13
|
+
- INVO's card fee on coin purchases, paid trials, and the two tiers.
|
|
14
|
+
|
|
15
|
+
**Coin purchases carry INVO's card fee: 3.5% + $0.30** of the price (on the Open tier), never less than the card cost. `purchaseCurrency` charges in the same request, so there are now two shapes and you pick one by what you send:
|
|
16
|
+
|
|
17
|
+
- **Quote, show, acknowledge.** New `server.quoteCurrencyPurchase({ playerEmail, usdAmount, country?, subdivision? })` calls `POST /api/currency-purchases/quote`. It moves no money and creates nothing, and returns `totalUsd`, `amountCents`, `subtotalUsd`, `processingFeeUsd`, `coins`, `currencyName`, a camelCase `breakdown` and `ifUnacknowledged`. Show the player `totalUsd`, then pass it as the new optional `acknowledgedTotalUsd` on `purchaseCurrency`: the card is charged that total, to the cent, and the coins are priced off `usdAmount`. $10.00 quotes $10.65.
|
|
18
|
+
- **Send only `usdAmount`.** The card is charged exactly `usdAmount`, never more, and the fee comes out of the coins: $10.00 credits 93.70 coins at the default 10 per USD.
|
|
19
|
+
|
|
20
|
+
A `success` result now also carries `processingFeeUsd`, `feeTakenFrom` (`"charge"` or `"coins"`), `coinsCredited` and `chargeTotalUsd`. New error helpers: `err.isQuoteStale` (409 `QUOTE_STALE`, with `err.expectedTotalUsd` and `err.acknowledgedTotalUsd`) and `err.isAmountBelowFee` (400 `AMOUNT_BELOW_FEE`). Nothing is charged on either. `acknowledgedTotalUsd` is shape-checked locally (a positive two-decimal amount) with a ceiling above the largest price, because the fee rides above INVO's card maximum.
|
|
21
|
+
|
|
22
|
+
**Refunds of coin purchases:** only unspent coins are refundable; spent coins are never refunded. Documented; no SDK call refunds a coin purchase.
|
|
23
|
+
|
|
24
|
+
**Paid trials on card subscriptions.** `subscriptions.create` accepts `trialAmountUsd` (with `trialDays` or `trialEnd`, card only, at least 0.50 and less than `amountUsd`): period 1 is charged the trial price inside the call and `amountUsd` from period 2. The consent object accepts `disclosedTrialAmountUsd`, `disclosedTrialDays` and `disclosedTrialEnd`, and returns `disclosed_trial_amount_usd`, `disclosed_trial_days` and `disclosed_trial_end`. The subscription gains `trialAmountUsd` and, on create and finalize bodies, `trialAmountCoinsEstimate`. Webhook types: `is_trial` on `subscription.renewed`; `is_trial` and `trial_amount_usd` on the trial period's `payment_failed`, `past_due`, `authentication_required` and `expired` (new `SubscriptionTrialEventFields`); `expire_cause` (`"trial_payment_failed"`) on `subscription.expired`. New error helpers: `isPaymentMethodRequired`, `isTrialAmountInvalid`, `isTrialAmountRequiresTrial`, `isTrialAmountNotSupportedForFunding`, `isConsentDisclosedTrialInvalid`. The SDK refuses, before the network and with INVO's own codes, a `trialAmountUsd` without a trial, with `walletOnly: true`, or on `steamInit`; the $0.50 floor and the "less than `amountUsd`" rule are left to INVO.
|
|
25
|
+
|
|
26
|
+
**README:** a new Tiers section (Open by default: you are the seller and handle tax; Merchant of Record by application: INVO is the seller and handles tax; fees per tier), the coin fee flow, the refund rule and paid trials. Every statement that INVO is the merchant of record on the card rail for everyone is removed.
|
|
27
|
+
|
|
28
|
+
All additive: no export was removed, renamed or retyped, and every new field on an existing type is optional.
|
|
29
|
+
|
|
3
30
|
## 3.12.1
|
|
4
31
|
|
|
5
32
|
### Patch Changes
|
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
First-party TypeScript SDK for integrating **INVO** into partner **web** platforms (storefronts, web games, dashboards). It wraps INVO's web money flows behind a typed, versioned API — the web analog of the Unity/Unreal plugins.
|
|
4
4
|
|
|
5
|
-
> **Status:** `v3.
|
|
5
|
+
> **Status:** `v3.14.0`, stable, published on npm. The backend it wraps is **live** on sandbox + production. The API is covered by a [stability commitment](#stability): no breaking changes without a major bump. Recent highlights: **3.14.0** adds `credited` / `reasonCode` on `confirmPayment()` and `steamFinalizePurchase()`, Merchant of Record receipt fields, Platform Commerce card refunds in parts, and updates the **[tiers](#tiers)**: subscription card charges are now **4% + $0.30** on Open and **5% + $0.50** on Merchant of Record, international card and currency conversion costs on subscriptions pass through at cost, chargeback handling by tier, and Merchant of Record is applied for from the console; **3.13.0** documents the two **[tiers](#tiers)** (Open by default, Merchant of Record by application), adds **[INVO's card fee on coin purchases](#invos-card-fee-quote-show-acknowledge)** (3.5% + $0.30): `quoteCurrencyPurchase()`, `acknowledgedTotalUsd` on `purchaseCurrency()`, the new `processingFeeUsd` / `feeTakenFrom` / `coinsCredited` / `chargeTotalUsd` fields and `err.isAmountBelowFee` / `err.isQuoteStale`, states the coin refund rule (only unspent coins), and adds **[paid trials](#paid-trials)** on card subscriptions (`trialAmountUsd`, the disclosed trial consent fields, `is_trial` / `expire_cause` on the events, `err.isPaymentMethodRequired` and the `isTrialAmount*` helpers); **3.12.0** removes the SDK's own card maximum (INVO's is a runtime setting, $100,000.00 by default); **3.11.0** adds the **[purchase status read](#did-the-purchase-go-through-the-status-read)**, where `invo.checkout.getPurchaseStatus()` / `waitForPurchase()` (and the standalone `CheckoutClient`) answer what happened to a hosted-checkout purchase in six words, four of them terminal, so a buyer is never shown a page that closes on nothing; stopping is decided by INVO's `terminal` and never re-derived from `status`, `nothingWasCharged()` says when a **Try again** is safe, `createCheckout()` now also returns `sessionToken`, and the subscription fee is corrected to **7% + $0.30** (it is its own rate; item purchases stay at 10/90); **3.10.0** documents **card-only subscriptions** (the card pays the full price every period, the coin wallet never pays; `walletOnly` deprecated; new `failure_code` `wallet_negative`; a renewal's `purchase.completed` is not a purchase) and the **[subscription refund limits](#refunds)**: `subscriptions.refund` can now return a 202 `pending_approval` refund request (`isRefundPendingApproval`), with `warnings`, the processor fee you bear, `subscriptionCanceled` (a full refund cancels), new classifiers (`isRefundsNotEnabled`, `isRefundWindowClosed`, `isRefundRequestPending`, `isRefundRequestRejected`, `isConcurrentRequest`, `isRefundMismatch`) and typed `subscription.refund_requested` / `refund_approved` / `refund_rejected` events, all additive; **3.9.0** adds the **[INVO-hosted card page for subscriptions](#cards-for-subscriptions)**, `invo.cards.createSetupSession`: mint a 10-minute link server-side, send the member to it, read the card back from `cards.list`, with no browser code and no card processor named anywhere (`beginSetup`/`confirmSetup` remain as the processor-bound alternative), plus the `isPlayerNotFound`, `isInvalidPlayerEmail` and `isInvalidInput` classifiers and a fix that makes `includePlayer` reads actually surface `playerEmail`/`playerName`; **3.8.0** adds **[Subscriptions](#subscriptions-recurring-billing)** as a first-class server surface on both rails — `invo.subscriptions.create/get/listForPlayer/cancel/changeAmount/setPaymentMethod/refund/steamInit/steamFinalize`, the off-session card capture (`invo.cards.beginSetup/confirmSetup/list`), the sandbox clock tools (`invo.sandbox.subscriptions.*`, which post to `/subscriptions/<id>/...` **relative to the sandbox base, not under `/api`**, with the new `sandboxClockKey`), typed `data` for all seven `subscription.*` webhook events, and eleven new error classifiers; **3.7.0** makes the **device approval grant a first-class SDK surface** — `beginDeviceApproval`, `pollDeviceApproval`, `confirmDeviceEnrollment` and, the step that actually moves the money, **`approveWithDeviceCode`** (plus the optional `completeDeviceApproval` loop); a grant that is polled to `approved` and left there settles **nothing**, which is the failure this release exists to make impossible, and `TRANSACTION_NOT_PENDING` now comes back as a typed `status: "not_pending"` result with `alreadySettled` rather than a thrown error you would have to string-match; **3.4.0** documents that a Steam title now bills through **its own Steam application** — the studio registers their appid + publisher Web API key and keeps a payment method on file, because Valve pays the studio and INVO settles afterwards (new `isSteamNotConfigured`, `isPartnerBillingNotSetUp`, `isPartnerSettlementUnavailable`, `isSteamAppChanged` error helpers); **3.2.3** corrects the base path and auth header in the Steam snippets (`/api/currency-purchases`, `X-Game-Secret-Key`) — 3.2.2 published both wrong, and copying them returned a 404; **3.2.x** documents **Steam currency purchases on a pack model** — INVO owns the catalogue, you pass a `pack_id` and never a price, and the currency inside a pack varies by country because Steam prices are VAT-inclusive; **3.1.0** makes the authentication guidance explicit — **[passkeys are the gold standard](#passkeys-are-the-gold-standard-dont-build-on-sms)** and the SMS-PIN completion (`verifySmsTransfer`/`verifySmsSend`) is **deprecated and being phased out** (documentation only — no behavior change, no runtime warnings); **3.0.0** moves the Platform Commerce card leg to **INVO's hosted checkout** — the server `purchase()` now returns a `checkoutUrl` and the browser just sends the buyer there (redirect or `mountCheckout` iframe); the 2.5.x card-element surface (`confirmCardPayment`/`mountCardPayment`, `billingAddress`, `commercePublishableKey`) is **removed** — see the [CHANGELOG](CHANGELOG.md) migration note; **2.5.0** added **Platform Commerce** (ecommerce) — a platform tenant selling items funded by balance **or** card, with `invo.platformCommerce.purchase/getStatus/refund` (server) and the `platform_commerce.*` webhooks; **2.4.0** adds Steam transfer-policy handling (`isSteamValueNonTransferable`/`isNonSteamValueIntoSteamBlocked` + `DestinationGame.acceptsSteamOriginValue`); **2.3.0** surfaces the claim-time phone-share `409` on `confirmReceipt*`/`claim*` (+ `err.phoneShareLast4`). Full history in the [CHANGELOG](CHANGELOG.md).
|
|
6
6
|
> Canonical partner reference: **https://docs.invo.network/docs/currency-purchase** and **https://docs.invo.network/docs/game-developer-integration**.
|
|
7
7
|
|
|
8
8
|
## What it does
|
|
@@ -20,7 +20,7 @@ Six money flows plus passkey (WebAuthn) authentication, split across a trusted s
|
|
|
20
20
|
|
|
21
21
|
> **Item purchase vs Platform Commerce — don't mix them up.** They share a body shape (`itemId`, `unitPrice`, `totalPrice`, `clientRequestId`) but are different products:
|
|
22
22
|
> - **[Item purchase](#item-purchase-spend-game-currency)** — a **game** tenant. A player spends **game currency they already hold** on an **in-game** item (a sword, a skin). Always a balance debit — **never a card, never new money, no refunds**. `server.purchaseItem(...)` → `/api/item-purchases`.
|
|
23
|
-
> - **[Platform Commerce](#platform-commerce-ecommerce)** — a **platform** tenant (a non-game app: vertical video, creator merch, marketplace). A **storefront** sale funded by **INVO balance or a real card** (new money), with **
|
|
23
|
+
> - **[Platform Commerce](#platform-commerce-ecommerce)** — a **platform** tenant (a non-game app: vertical video, creator merch, marketplace). A **storefront** sale funded by **INVO balance or a real card** (new money), with **refunds**. Who is the seller of record depends on your [tier](#tiers). `server.platformCommerce.purchase(...)` → `/api/platform-commerce`. A game tenant calling it gets `403 NOT_A_PLATFORM_TENANT`.
|
|
24
24
|
|
|
25
25
|
The **game secret stays on your server**; the browser only ever holds a short-lived, game-scoped **player token** (and, for the card leg, a per-purchase `checkoutUrl`).
|
|
26
26
|
|
|
@@ -95,13 +95,17 @@ The right approval method is a property of the **client the player is sitting in
|
|
|
95
95
|
- [Architecture & the two entry points](#architecture--the-two-entry-points)
|
|
96
96
|
- [Before you go live](#before-you-go-live)
|
|
97
97
|
- [Configuration](#configuration)
|
|
98
|
+
- [Tiers](#tiers)
|
|
98
99
|
- [Currency purchase (real money in)](#currency-purchase-real-money-in)
|
|
99
100
|
- [The card maximum is INVO's, not the SDK's](#the-card-maximum-is-invos-not-the-sdks)
|
|
101
|
+
- [INVO's card fee: quote, show, acknowledge](#invos-card-fee-quote-show-acknowledge)
|
|
102
|
+
- [Refunds of coin purchases](#refunds-of-coin-purchases)
|
|
100
103
|
- [Did the purchase go through? (the status read)](#did-the-purchase-go-through-the-status-read)
|
|
101
104
|
- [Item purchase (spend game currency)](#item-purchase-spend-game-currency)
|
|
102
105
|
- [Platform Commerce (ecommerce)](#platform-commerce-ecommerce)
|
|
103
106
|
- [Subscriptions (recurring billing)](#subscriptions-recurring-billing)
|
|
104
107
|
- [Cards for subscriptions](#cards-for-subscriptions)
|
|
108
|
+
- [Paid trials](#paid-trials)
|
|
105
109
|
- [Subscription packages](#subscription-packages)
|
|
106
110
|
- [Player balance](#player-balance)
|
|
107
111
|
- [Sends & transfers (move currency between players)](#sends--transfers-move-currency-between-players)
|
|
@@ -282,13 +286,35 @@ const client = new InvoClient({
|
|
|
282
286
|
|
|
283
287
|
---
|
|
284
288
|
|
|
289
|
+
## Tiers
|
|
290
|
+
|
|
291
|
+
Every INVO developer account is on one of two tiers. The SDK calls are the same on both; what differs is who the seller is, who handles tax, and the fees.
|
|
292
|
+
|
|
293
|
+
| | **Open** (default) | **Merchant of Record** (by application) |
|
|
294
|
+
|---|---|---|
|
|
295
|
+
| Who it is for | every account, including all current ones | accounts INVO has approved |
|
|
296
|
+
| Who the seller is | **you** | **INVO** |
|
|
297
|
+
| Tax on sales | **you** are responsible for it; INVO collects none | **INVO** calculates, collects and remits it |
|
|
298
|
+
| Card purchase of coins | 3.5% + $0.30 | 5% + $0.30 |
|
|
299
|
+
| Subscriptions | 4% + $0.30 per card charge | 5% + $0.50 per card charge |
|
|
300
|
+
| Chargebacks | the disputed amount comes out of your share; on subscription charges the dispute fee is passed through too | INVO manages the dispute and pays the dispute fee; the disputed amount comes out of your share and is restored if INVO wins |
|
|
301
|
+
| Item purchases (coins spent on an item) | 10% | 10% |
|
|
302
|
+
|
|
303
|
+
On both tiers every card charge runs on INVO's card rail and INVO pays you out, as today. On subscription card charges made on a card issued outside the United States, or needing a currency conversion, the extra processing cost is passed through to you at INVO's actual cost, reported separately from INVO's fee. On Merchant of Record, if your chargeback rate (disputed card charges divided by successful card charges in a calendar month) goes above 0.75%, dispute fees on your subscription charges pass through to you as on Open and INVO reviews your approval. Merchant of Record is applied for per developer account, not per game, from the Seller tier page in your INVO console, and INVO reviews each application. Full details: https://docs.invo.network/docs/tiers/
|
|
304
|
+
|
|
305
|
+
**What the tier changes in what the SDK returns** (all additive):
|
|
306
|
+
|
|
307
|
+
- **`tax_treatment`** on an Open account's card sales reads `"partner_responsible"` (you are the seller; INVO charged no tax). It appears as `breakdown.taxTreatment` on `quoteCurrencyPurchase()` and `tax_treatment` on the `purchase.completed` webhook. Tax amounts stay `"0.00"`. Treat an unknown value as informational.
|
|
308
|
+
- **Receipts (Merchant of Record only).** INVO issues a receipt for every card sale and a refund receipt for every card refund, and emails it to the buyer when the buyer's email is known; the number is always issued (a pending refund's number follows once it settles) and always reaches you. The number and link reach you as `receiptNumber` / `receiptUrl` on `purchaseCurrency()`, `getOrderDetails()` (from `GET /order-details`, which returns `receipt_number` / `receipt_url`), `CheckoutClient.getPurchaseStatus()` (once `credited`), `platformCommerce.getStatus()` and a paid `firstCharge`, and as `receipt_number` / `receipt_url` on the `purchase.completed`, `platform_commerce.purchased` and `subscription.renewed` webhooks. The refund webhooks (`purchase.refunded`, `platform_commerce.refunded`, `subscription.refunded`) carry the refund receipt's. On Open, and on storefront rails, the fields are absent. Anyone with a `receiptUrl` can read the receipt.
|
|
309
|
+
- **Chargeback reserve (Merchant of Record only).** Part of your share of each card-funded sale (Platform Commerce card sales, card subscription charges) is held, by default 10% for 90 days (terms may differ per account), then released automatically. It affects your withdrawable balance, not anything this SDK returns: see https://docs.invo.network/docs/tiers/ for the balance fields.
|
|
310
|
+
|
|
285
311
|
## Currency purchase (real money in)
|
|
286
312
|
|
|
287
313
|
Buy game currency with real money. Authenticated by the **payment rail**, not a passkey — there's no WebAuthn step. Two paths:
|
|
288
314
|
|
|
289
315
|
### The card maximum is INVO's, not the SDK's
|
|
290
316
|
|
|
291
|
-
**Minimum: $0.50.** That is the card rail's own floor: below it a charge cannot settle at all
|
|
317
|
+
**Minimum: $0.50.** That is the card rail's own floor: below it a charge cannot settle at all. (The SDK checks it locally on the Platform Commerce card leg.) A direct `purchaseCurrency` sent **without** an acknowledged total must also be large enough to carry INVO's card fee, or INVO refuses it before charging anything (`400 AMOUNT_BELOW_FEE`, see [below](#invos-card-fee-quote-show-acknowledge)).
|
|
292
318
|
|
|
293
319
|
**Maximum: an INVO setting, $100,000.00 by default.** It is changed by an INVO admin without a deploy, and it differs between sandbox and production, so **this package does not pin it and never refuses an amount for being too large.** Your amount is sent; INVO decides.
|
|
294
320
|
|
|
@@ -403,7 +429,7 @@ Rules worth taking literally:
|
|
|
403
429
|
- **A failed poll is not a failed purchase.** `waitForPurchase` polls through a dropped connection, a timeout, a 429 and a 5xx; it raises a `401`, `403` or `410` at once (`err.isWrongSessionPurpose`, `err.isCheckoutSessionMismatch`, `err.isCheckoutSessionExpired`).
|
|
404
430
|
- **Render `message` verbatim and never show `reasonCode` on its own.** The six post-charge refusal codes all read the same to a buyer (they paid and the coins are not there), and the code exists for support to quote. Offer a **Try again** only where `nothingWasCharged(r)` is true (`PAYMENT_DECLINED`, `PAYMENT_CANCELLED`, `expired`); every other refusal happened *after* the card was charged.
|
|
405
431
|
- **`expired` is not declared the second the link lapses.** A payment made in the last minutes of a checkout can leave no order row until a recovery sweep finds it, so an unpaid checkout reads `pending` for about 30 minutes past expiry. Poll through it.
|
|
406
|
-
- **`amountChargedUsd` minus `listedUsd`** is
|
|
432
|
+
- **`amountChargedUsd` minus `listedUsd`** is INVO's card fee the buyer pays on the card rail (3.5% + $0.30 on the Open tier). A buyer billed 207.30 for a 200 pack will ask; both numbers are here.
|
|
407
433
|
- **Storefront (in-client) purchases do not reach this read.** Those orders are keyed on your own purchase reference rather than on a checkout session, so a lookup by session id finds nothing and answers `pending`. Do not conclude the purchase never happened.
|
|
408
434
|
- `newBalance` is `null` once the session is past its expiry: the token rides in the checkout URL, so a stale link must not serve a live wallet. `coinsCredited` and `transactionId`, which are about *this* purchase, still come back.
|
|
409
435
|
|
|
@@ -496,7 +522,8 @@ const init = await server.steamInitPurchase({
|
|
|
496
522
|
|
|
497
523
|
// 4. Finalize: INVO re-checks the authorization with Steam, captures, credits.
|
|
498
524
|
const done = await server.steamFinalizePurchase({ orderId: init.orderId });
|
|
499
|
-
// -> { status: "success", newBalance, alreadyProcessed }
|
|
525
|
+
// -> { status: "success", newBalance, alreadyProcessed, credited }
|
|
526
|
+
// credited === true means the currency is in; see "credited: did the coins arrive?" above.
|
|
500
527
|
```
|
|
501
528
|
|
|
502
529
|
**The price is identical everywhere; the currency inside is not.** Steam prices are
|
|
@@ -565,11 +592,76 @@ const purchase = await server.purchaseCurrency({
|
|
|
565
592
|
// purchase.status:
|
|
566
593
|
// "success" → captured, purchase.newBalance updated
|
|
567
594
|
// "requires_action" → 3-D Secure: run the client action with purchase.clientSecret,
|
|
568
|
-
// then call server.confirmPayment({ paymentIntentId })
|
|
595
|
+
// then call server.confirmPayment({ paymentIntentId }) and read `credited`
|
|
569
596
|
// "pending_payment" → redirect the browser to purchase.paymentUrl (game rail)
|
|
570
597
|
```
|
|
571
598
|
`rail: "steam"` is rejected here (`WRONG_RAIL_ENDPOINT`) — Steam uses its own in-client flow. Reconcile with `server.getOrderDetails({ orderId })`. Most browser integrations should use hosted checkout instead.
|
|
572
599
|
|
|
600
|
+
#### `credited`: did the coins arrive?
|
|
601
|
+
|
|
602
|
+
`confirmPayment()` and `steamFinalizePurchase()` keep `status: "success"` whenever the **payment** succeeded. That alone does not prove the coins were added, so both results carry `credited` and `reasonCode` (backends from 2026-09-24):
|
|
603
|
+
|
|
604
|
+
```ts
|
|
605
|
+
const c = await server.confirmPayment({ paymentIntentId });
|
|
606
|
+
if (c.credited === true) {
|
|
607
|
+
// the coins are in: show "purchase complete"
|
|
608
|
+
} else if (c.credited === false && c.reasonCode?.startsWith("CREDIT_REFUSED_")) {
|
|
609
|
+
// e.g. "CREDIT_REFUSED_MINT_CEILING": the money was taken and no coins were added.
|
|
610
|
+
// INVO is alerted. Do NOT ask the buyer to pay again; show support with the order id.
|
|
611
|
+
} else if (c.credited === false && c.reasonCode) {
|
|
612
|
+
// "REFUNDED" or "CHARGEBACK_LOST": the payment went back to the buyer.
|
|
613
|
+
} else if (c.credited === false) {
|
|
614
|
+
// reasonCode === null: the credit is still being finished. Poll getOrderDetails until "completed".
|
|
615
|
+
} else {
|
|
616
|
+
// credited === undefined: an older backend. Fall back to the order status.
|
|
617
|
+
}
|
|
618
|
+
```
|
|
619
|
+
|
|
620
|
+
Show "purchase complete" only when `credited` is `true`. `alreadyProcessed` is also `true` whenever the call added nothing (a refused credit included), so do not read success from it.
|
|
621
|
+
|
|
622
|
+
### INVO's card fee: quote, show, acknowledge
|
|
623
|
+
|
|
624
|
+
A card purchase of coins carries INVO's card fee: **3.5% + $0.30** of the price on the Open [tier](#tiers), never less than the card cost. The hosted checkout adds it to the total on its own page, so there is nothing to do there. `purchaseCurrency` charges in the same request it is called, so it cannot show the buyer anything first. You choose what happens by what you send:
|
|
625
|
+
|
|
626
|
+
- **Quote, show, acknowledge (recommended).** Ask `quoteCurrencyPurchase()` for the total, show the player that total, then send the same figure back as `acknowledgedTotalUsd`. The card is charged that total and the player gets coins for the full price.
|
|
627
|
+
- **Send only `usdAmount`.** The card is charged **exactly `usdAmount`, never more**, and the fee comes out of the coins instead.
|
|
628
|
+
|
|
629
|
+
```ts
|
|
630
|
+
// 1) SERVER: quote. Moves no money and creates nothing: safe on every price render.
|
|
631
|
+
const q = await server.quoteCurrencyPurchase({
|
|
632
|
+
playerEmail: "p@example.com",
|
|
633
|
+
usdAmount: "10.00",
|
|
634
|
+
// country: "US", subdivision: "NY", // optional: the buyer's billing place, for any tax
|
|
635
|
+
});
|
|
636
|
+
// q.subtotalUsd "10.00" + q.processingFeeUsd "0.65" = q.totalUsd "10.65" (q.coins "100.00")
|
|
637
|
+
// q.breakdown: every line, with taxNote / processingFeeNote sentences you can show as is
|
|
638
|
+
// q.ifUnacknowledged: { chargeTotalUsd: "10.00", processingFeeUsd: "0.63", coins: "93.70", feeTakenFrom: "coins" }
|
|
639
|
+
|
|
640
|
+
// 2) Show the player q.totalUsd ("$10.65"). 3) Charge exactly what they saw:
|
|
641
|
+
const purchase = await server.purchaseCurrency({
|
|
642
|
+
playerEmail: "p@example.com",
|
|
643
|
+
usdAmount: "10.00", // the price; the coins are priced off this
|
|
644
|
+
acknowledgedTotalUsd: q.totalUsd, // "10.65": the card is charged this, to the cent
|
|
645
|
+
purchaseReference: crypto.randomUUID(),
|
|
646
|
+
paymentMethodId: "pm_...",
|
|
647
|
+
});
|
|
648
|
+
// On "success": purchase.chargeTotalUsd "10.65", purchase.processingFeeUsd "0.65",
|
|
649
|
+
// purchase.feeTakenFrom "charge", purchase.coinsCredited "100.00"
|
|
650
|
+
```
|
|
651
|
+
|
|
652
|
+
The same $10.00 **unacknowledged** charges the card $10.00, takes the $0.63 fee out of the coins and credits **93.70 coins** at the default rate of 10 per USD (`feeTakenFrom: "coins"`). Sending $10.65 unacknowledged buys the same $10.00 of coins as the acknowledged path: the fee is never charged on the fee.
|
|
653
|
+
|
|
654
|
+
| Error | When | What to do |
|
|
655
|
+
|---|---|---|
|
|
656
|
+
| `409 QUOTE_STALE` (`err.isQuoteStale`) | the acknowledged total is not the total INVO would charge now | nothing was charged; quote again, show `err.expectedTotalUsd`, retry with the new total and a new `purchaseReference` |
|
|
657
|
+
| `400 AMOUNT_BELOW_FEE` (`err.isAmountBelowFee`) | unacknowledged, and the amount cannot carry the fee (well under a dollar) | nothing was charged; send a larger amount, or quote and acknowledge |
|
|
658
|
+
|
|
659
|
+
Only a `success` response carries the four fee fields; `requires_action` and `pending_payment` do not. Storefront rails bill no INVO card fee: the storefront takes its own cut.
|
|
660
|
+
|
|
661
|
+
### Refunds of coin purchases
|
|
662
|
+
|
|
663
|
+
**Only coins that have not been spent are refundable. Spent coins are never refunded**, including when new coins have arrived in the balance since. A refund of a card purchase of coins returns the price of the unspent coins and takes those coins back; if every coin from the purchase has been spent, nothing is refunded. Refunds are issued by INVO: this SDK has no call that refunds a coin purchase, so ask INVO support.
|
|
664
|
+
|
|
573
665
|
---
|
|
574
666
|
|
|
575
667
|
## Item purchase (spend game currency)
|
|
@@ -607,7 +699,7 @@ const item = await server.purchaseItem({
|
|
|
607
699
|
|
|
608
700
|
## Platform Commerce (ecommerce)
|
|
609
701
|
|
|
610
|
-
> **This is not [item purchase](#item-purchase-spend-game-currency).** Item purchase is a *game* tenant spending a player's *existing game currency* on an *in-game* item — always a balance debit, never a card, no refunds. **Platform Commerce is a _platform_ tenant (a non-game app: vertical video, creator merch, marketplace) running a storefront.** The buyer pays with **INVO balance** *or* a **real card** (new money),
|
|
702
|
+
> **This is not [item purchase](#item-purchase-spend-game-currency).** Item purchase is a *game* tenant spending a player's *existing game currency* on an *in-game* item — always a balance debit, never a card, no refunds. **Platform Commerce is a _platform_ tenant (a non-game app: vertical video, creator merch, marketplace) running a storefront.** The buyer pays with **INVO balance** *or* a **real card** (new money), and **refunds** exist. Who is the seller of record, and who handles tax, depends on your [tier](#tiers). Only platform tenants may call it — a game tenant gets `403` (`err.isNotPlatformTenant`).
|
|
611
703
|
|
|
612
704
|
The funding source is resolved **server-side under lock** — the client can *request* `balance` or `card`, but the backend verifies the real balance before any value moves. Everything money-shaped is a server call (holds the secret, creates the purchase/refund); the browser's only job on the card leg is to **send the buyer to INVO's hosted checkout page**. Reached via the `platformCommerce` namespace on each entry point.
|
|
613
705
|
|
|
@@ -682,6 +774,19 @@ const ref = await server.platformCommerce.refund({ orderId: r.orderId, reason: "
|
|
|
682
774
|
// A second refund of the same order throws 409 (err.isAlreadyRefunded) — treat as already done.
|
|
683
775
|
```
|
|
684
776
|
|
|
777
|
+
**Card sales refunded in parts.** A card refund normally returns the whole charge in one go, and the result is as above. A sale ends up refunded in parts only when part of the charge was already refunded outside INVO's API: the next `refund()` records that existing refund and moves no new money (`ref.adopted === true`, `ref.partialRefund === true`, `ref.refundedTotalUsd`, `ref.chargeTotalUsd`, `ref.remainingUsd`; the order stays `completed`). Every figure is then that refund's own share, and `partialRefund` / `refundedTotalUsd` / `chargeTotalUsd` appear on each part (`partialRefund: false` on the last); on a one-shot full refund none of the parts keys appear; `adopted: true` can still appear if the call recorded an existing full refund.
|
|
778
|
+
|
|
779
|
+
```ts
|
|
780
|
+
// Refund what is left, on purpose:
|
|
781
|
+
await server.platformCommerce.refund({ orderId, refundRemaining: true });
|
|
782
|
+
// Within 120 s of the order's last refund, also confirmAdditionalRefund: true.
|
|
783
|
+
```
|
|
784
|
+
|
|
785
|
+
- `err.isRefundRemainingRequiresConfirmation` (409 `REFUND_REMAINING_REQUIRES_CONFIRMATION`): send `refundRemaining: true`; `refunded_total_usd` / `remaining_usd` are on `err.body`. Nothing moved.
|
|
786
|
+
- `err.isRefundRecentlyIssued` (409 `REFUND_RECENTLY_ISSUED`): a refund of this order was applied in the last 120 seconds. Re-read the order; send `confirmAdditionalRefund: true` to refund anyway.
|
|
787
|
+
- `err.isRefundNotCompleted` (502 `REFUND_NOT_COMPLETED`): the card refund failed, was canceled or still needs an action. Nothing was recorded; retry (a refund that was in fact created is recorded on the retry, never issued twice).
|
|
788
|
+
- `platform_commerce.refunded` for a sale refunded in parts also carries `partial_refund`, `refunded_total_usd` and `charge_total_usd` (`refunded_amount` is that refund's own amount); a one-shot full refund sends none of them.
|
|
789
|
+
|
|
685
790
|
- **Idempotency on `clientRequestId`:** a duplicate BALANCE purchase throws `409` (`err.isDuplicateRequest`); a duplicate CARD purchase **replays the same checkout session** (`r.idempotentReplay === true`, same URL — never a second charge), so a lost card-leg response is safely recovered by retrying with the *same* `clientRequestId`.
|
|
686
791
|
- INVO fee: **3.5% flat** (balance) · **3.5% + $0.30** (card). Too-small amounts throw `err.isAmountBelowMinimum` / `err.isBelowCardMinimum` (card < $0.50); a card total over INVO's maximum single card charge comes back as `err.isAboveCardMaximum` (400) with the live figure in `err.message`.
|
|
687
792
|
- Client-side validation (missing fields, bad funding source, quantity outside `1..1000`, total ≠ unit×qty, card total under $0.50, non-E.164 `playerPhone`) throws **before** any network call. The card **maximum** is deliberately not among them: see [The card maximum is INVO's, not the SDK's](#the-card-maximum-is-invos-not-the-sdks).
|
|
@@ -700,9 +805,9 @@ A subscription is a standing agreement, created by **your server**, under which
|
|
|
700
805
|
|
|
701
806
|
Each period INVO works out what the period is worth in coins (card: price × the currency's coins-per-USD rate, 10 per USD by default; Steam: what the price buys through Steam for the member's country) and splits it between INVO's platform fee and your revenue. Every figure is reported on the `subscription.renewed` event.
|
|
702
807
|
|
|
703
|
-
- **Card rail: card only (since 2026-09-17).** The card is charged the full price every period, whatever the member's coin wallet holds. The coins that charge buys are minted and spent in the same step, so **the wallet never pays for a card subscription and never moves**. There is no shortfall, no rounding and no minimum top-up. INVO's fee is
|
|
808
|
+
- **Card rail: card only (since 2026-09-17).** The card is charged the full price every period, whatever the member's coin wallet holds. The coins that charge buys are minted and spent in the same step, so **the wallet never pays for a card subscription and never moves**. There is no shortfall, no rounding and no minimum top-up. INVO's fee is 4% plus $0.30 on Open (5% plus $0.50 on Merchant of Record), on the full price ($9.99 pays INVO $0.70 and you $9.29 on Open). Subscriptions are their own rate: item purchases stay at 10/90.
|
|
704
809
|
- **Steam rail: unchanged.** INVO spends the member's wallet first and tops up from Steam for the shortfall only.
|
|
705
|
-
- **Save a card before `subscriptions.create`.** A member with coins but no saved card is still subscribed (the create succeeds), but the first charge fails with `failureCode: "no_payment_method"` and the subscription enters dunning. Coins never pay it.
|
|
810
|
+
- **Save a card before `subscriptions.create`.** A member with coins but no saved card is still subscribed (the create succeeds), but the first charge fails with `failureCode: "no_payment_method"` and the subscription enters dunning. Coins never pay it. A [paid trial](#paid-trials) is stricter: without a usable saved card it is refused (`400 PAYMENT_METHOD_REQUIRED`) and nothing is created.
|
|
706
811
|
- **`walletOnly` is deprecated.** It is still accepted and returned, but a `walletOnly: true` card subscription never charges a card and so can never be paid: every charge fails with `failure_code: "wallet_only"` and it lapses to `expired`. Do not send it on new integrations.
|
|
707
812
|
|
|
708
813
|
**Three rules to carry through everything below.**
|
|
@@ -800,7 +905,7 @@ switch (setup.status) {
|
|
|
800
905
|
const { cards } = await server.cards.list("member@example.com"); // unexpired, newest first; `id` is the only handle
|
|
801
906
|
```
|
|
802
907
|
|
|
803
|
-
**2. Create the subscription.** `create` **charges the first period before responding** (unless it is a trial), so expect it to take as long as a card charge.
|
|
908
|
+
**2. Create the subscription.** `create` **charges the first period before responding** (unless it is a free trial; a [paid trial](#paid-trials) charges its trial price), so expect it to take as long as a card charge.
|
|
804
909
|
|
|
805
910
|
```ts
|
|
806
911
|
const r = await server.subscriptions.create({
|
|
@@ -813,10 +918,11 @@ const r = await server.subscriptions.create({
|
|
|
813
918
|
interval: "month", // "month" (default) | "year"
|
|
814
919
|
// intervalCount: 3, // quarterly; 1..36
|
|
815
920
|
// trialDays: 7, // or trialEnd: "2026-10-01T00:00:00Z"
|
|
921
|
+
// trialAmountUsd: "1.00", // a PAID trial: see "Paid trials" below
|
|
816
922
|
// playerCardId: cards[0].id, // omitted: INVO attaches the newest unexpired saved card
|
|
817
923
|
// walletOnly: true, // DEPRECATED: never charges a card, so it can never be paid ("wallet_only")
|
|
818
924
|
metadata: { guild_id: "42" }, // echoed on every read and event (`_invo` is reserved)
|
|
819
|
-
consent: { // send it:
|
|
925
|
+
consent: { // send it: a dispute over a recurring charge is argued from this
|
|
820
926
|
consentAt: new Date().toISOString(),
|
|
821
927
|
consentIp: memberIp, // the MEMBER's IP as your server saw it
|
|
822
928
|
consentUserAgent: memberUserAgent,
|
|
@@ -838,7 +944,7 @@ switch (r.firstCharge.status) {
|
|
|
838
944
|
case "requires_action": // NOTHING has been charged; status is awaiting_authentication
|
|
839
945
|
relayToMember(r.firstCharge.confirmationUrl!, r.firstCharge.expiresAt!); // a single-use bearer link: never log it
|
|
840
946
|
break; // access follows on subscription.renewed; if the link lapses INVO retries on its own
|
|
841
|
-
case "skipped_trial": // status is trialing; the first charge runs at trialEnd
|
|
947
|
+
case "skipped_trial": // a FREE trial: status is trialing; the first charge runs at trialEnd
|
|
842
948
|
grantTrialUntil(r.subscription.trialEnd!);
|
|
843
949
|
break;
|
|
844
950
|
case "failed": // status is past_due, in dunning; INVO retries at nextRetryAt
|
|
@@ -854,6 +960,41 @@ switch (r.firstCharge.status) {
|
|
|
854
960
|
|
|
855
961
|
**4. Replay before retry.** `create` is idempotent on `clientRequestId`: a repeat returns HTTP 200 with the identical shape and `r.idempotentReplay === true`, nothing is charged again, and `firstCharge` is re-derived from what already happened (so a replay after the charge settled reports `paid`). The SDK auto-retries transient failures with the same key. **On any timeout or 5xx, replay the same key before you do anything else.** A fresh key inside a retry loop lands on `409 ACTIVE_SUBSCRIPTION_EXISTS` (`err.isActiveSubscriptionExists`, the live id on `err.existingSubscriptionId`) at best and a second subscription at worst; the same key with different terms is `err.isIdempotentReplayMismatch` (`err.mismatchedFields`).
|
|
856
962
|
|
|
963
|
+
### Paid trials
|
|
964
|
+
|
|
965
|
+
Charge a small amount for the trial window, then the regular price, as **one subscription with one card**: for example **$1.00 for 7 days, then $29.00 a month**. Card subscriptions only.
|
|
966
|
+
|
|
967
|
+
```ts
|
|
968
|
+
const r = await server.subscriptions.create({
|
|
969
|
+
clientRequestId: "member-7-pro",
|
|
970
|
+
playerEmail: "member@example.com",
|
|
971
|
+
playerName: "Member",
|
|
972
|
+
itemId: "pro-membership",
|
|
973
|
+
amountUsd: "29.00", // the regular price, charged from period 2
|
|
974
|
+
interval: "month",
|
|
975
|
+
trialDays: 7, // or trialEnd; a paid trial needs one of them
|
|
976
|
+
trialAmountUsd: "1.00", // at least 0.50 and less than amountUsd
|
|
977
|
+
consent: {
|
|
978
|
+
consentAt: new Date().toISOString(),
|
|
979
|
+
disclosedAmountUsd: "29.00",
|
|
980
|
+
disclosedInterval: "month",
|
|
981
|
+
disclosedTrialAmountUsd: "1.00", // what you showed the member
|
|
982
|
+
disclosedTrialDays: 7, // or disclosedTrialEnd
|
|
983
|
+
},
|
|
984
|
+
});
|
|
985
|
+
// On success: r.firstCharge.status "paid", r.firstCharge.amountUsd "1.00", r.firstCharge.paidPeriodSeq 1,
|
|
986
|
+
// r.subscription.status "trialing", r.subscription.amountUsd "29.00", r.subscription.trialAmountUsd "1.00",
|
|
987
|
+
// r.subscription.paidThrough === r.subscription.trialEnd, r.subscription.trialAmountCoinsEstimate "10.00"
|
|
988
|
+
```
|
|
989
|
+
|
|
990
|
+
- **Period 1 is the trial window** and is charged `trialAmountUsd` inside the `create` call, through the same first charge as any subscription. `firstCharge` reports it as any first charge is reported (`paid`, `requires_action`, `failed`, `pending`) with the trial price; `skipped_trial` is never returned for a paid trial. `subscription.renewed` fires for period 1 with `is_trial: true` and `amount_usd: "1.00"`.
|
|
991
|
+
- **At the trial end INVO charges `amountUsd` as period 2** (`subscription.renewed` with `period_seq: 2`, `is_trial: false`) and billing continues as normal. This is not a price change: nothing is staged and the doubling rule does not apply.
|
|
992
|
+
- **Save the card first.** Without a usable saved card the create is refused with `400 PAYMENT_METHOD_REQUIRED` (`err.isPaymentMethodRequired`) and nothing is created.
|
|
993
|
+
- **A refused trial charge ends it.** The subscription goes straight to `expired`, `firstCharge.status` is `failed` with `nextRetryAt: null`, and you receive `subscription.payment_failed` then `subscription.expired` with `expire_cause: "trial_payment_failed"`. Subscribe again with a **new** `clientRequestId` once the member has a working card. A temporary processing error is not a refusal: that goes to ordinary dunning and is retried.
|
|
994
|
+
- **Events about the trial period** (`payment_failed`, `past_due`, `authentication_required`, `expired`) carry `is_trial: true` and `trial_amount_usd`; their `amount_usd` is still the regular price and `amount_due_usd` is the trial price. The keys are absent on every other event of those types.
|
|
995
|
+
- **Refusals:** `err.isTrialAmountRequiresTrial` (no `trialDays`/`trialEnd`), `err.isTrialAmountNotSupportedForFunding` (`walletOnly: true`, or the Steam rail), `err.isTrialAmountInvalid` (below $0.50 or not below `amountUsd`), `err.isConsentDisclosedTrialInvalid` (a malformed `disclosedTrial*` field). The first two, and a malformed amount, are also caught by the SDK before the network. A changed `trialAmountUsd` on a replay is `err.isIdempotentReplayMismatch` with `trial_amount_usd` in `err.mismatchedFields`.
|
|
996
|
+
- The trial period is refundable like any other period.
|
|
997
|
+
|
|
857
998
|
### The Steam road
|
|
858
999
|
|
|
859
1000
|
A Steam subscription is funded from the member's Steam wallet through a recurring agreement they authorise **once, in Steam**. INVO still owns the clock. Valve pays you through your Steamworks account; INVO mints the currency and settles with you afterwards. The title must be enabled for Steam in INVO (`err.isSteamRailNotEntitled` / `err.isSteamNotConfigured` otherwise), and the coins a period is worth depend on the member's country because Steam prices include VAT: **show `amountCoins` from the init response, never price × 10.**
|
|
@@ -1066,7 +1207,10 @@ Match on `err.code` (and on `body.status` where the body carries one), never on
|
|
|
1066
1207
|
|---|---|
|
|
1067
1208
|
| `.isGameNotLive` | (403) create refused; the game is `testing`. Make it live in the console |
|
|
1068
1209
|
| `.isActiveSubscriptionExists` + `.existingSubscriptionId` | (409) the player already has a live subscription to this item. You regenerated `clientRequestId` in a retry loop |
|
|
1069
|
-
| `.isIdempotentReplayMismatch` + `.mismatchedFields` | (409) same key, same player + item, different material terms. Use `changeAmount`/`setPaymentMethod`, or a new key |
|
|
1210
|
+
| `.isIdempotentReplayMismatch` + `.mismatchedFields` | (409) same key, same player + item, different material terms (`trial_amount_usd` included). Use `changeAmount`/`setPaymentMethod`, or a new key |
|
|
1211
|
+
| `.isPaymentMethodRequired` | (400) a paid trial with no usable saved card; nothing was created. Save a card first. (Also `setPaymentMethod` without a card id) |
|
|
1212
|
+
| `.isTrialAmountRequiresTrial` / `.isTrialAmountNotSupportedForFunding` / `.isTrialAmountInvalid` | (400) `trialAmountUsd` without a trial; with `walletOnly: true` or on Steam; below $0.50 or not below `amountUsd` |
|
|
1213
|
+
| `.isConsentDisclosedTrialInvalid` | (400) a malformed `disclosedTrialAmountUsd` / `disclosedTrialDays` / `disclosedTrialEnd`; `err.code` says which |
|
|
1070
1214
|
| `.isFlowPaused` | (503) maintenance pause. Retry later with the **same** key |
|
|
1071
1215
|
| `.isSubscriptionTerminal` | (409) the subscription is `canceled`/`expired`. Start a new one |
|
|
1072
1216
|
| `.isSteamReauthorizationRequired` | (409) a price **increase** on Steam. Start a new Steam subscription at the new price |
|
|
@@ -1091,7 +1235,7 @@ Match on `err.code` (and on `body.status` where the body carries one), never on
|
|
|
1091
1235
|
| `.isPlayerNotFound` / `.isInvalidPlayerEmail` / `.isInvalidInput` | (404 / 400 / 400) `cards.createSetupSession`: the member does not exist yet (the card page never creates players); `playerEmail` is not an email; `successUrl`/`cancelUrl` uses a script scheme (`isInvalidInput` is also the SDK's own pre-network guard code, at `.status === 0`) |
|
|
1092
1236
|
| `SETUP_REFERENCE_REUSED` / `PLAYER_NOT_FOUND` / `CARD_DECLINED` / `RAW_CARD_NOT_SUPPORTED` / `CARD_PERSIST_FAILED` | the processor-bound card capture (`beginSetup`/`confirmSetup`); on `CARD_PERSIST_FAILED` (500) retry `confirmSetup` with the same `setupIntentId` |
|
|
1093
1237
|
|
|
1094
|
-
Client-side guards (missing key, a `sub_`-prefixed key, a bad amount, a non-E.164 `playerPhone`, a trial or card field on Steam, a web session without `playerIp`, a missing `sandboxClockKey`) throw `InvoError` with `.status === 0` **before** any network call.
|
|
1238
|
+
Client-side guards (missing key, a `sub_`-prefixed key, a bad amount, a non-E.164 `playerPhone`, a trial or card field on Steam, `trialAmountUsd` without a trial or with `walletOnly: true`, a web session without `playerIp`, a missing `sandboxClockKey`) throw `InvoError` with `.status === 0` **before** any network call.
|
|
1095
1239
|
|
|
1096
1240
|
### Traps
|
|
1097
1241
|
|
|
@@ -1986,6 +2130,8 @@ export const POST = createWebhookHandler({
|
|
|
1986
2130
|
| `subscription.refund_requested` / `subscription.refund_approved` / `subscription.refund_rejected` | a refund over the game's daily self-serve limit became a request / INVO approved it (sent together with `subscription.refunded`, and `subscription.canceled` on a full refund, in any order) / INVO rejected it | track the request (`request_id, status, subscription_id, item_id, period_seq, client_request_id, amount_usd, reason, requested_at, daily_cap_usd, executed_today_usd, player_email, identity_id, metadata`; approved adds `decided_at, transaction_id`; rejected adds `decided_at, decision_reason`) |
|
|
1987
2131
|
| `transfer.received` / `transfer.claim_expired` / `transfer.refunded` | sends & transfers | reconcile claim state — credited to the recipient (by any claim path, the hosted claim page included) / not collected within 24h / returned to the sender |
|
|
1988
2132
|
|
|
2133
|
+
On a Merchant of Record account, `purchase.completed`, `platform_commerce.purchased` and `subscription.renewed` for a card sale also carry `receipt_number` and `receipt_url` (the receipt INVO issued to the buyer), and `purchase.refunded`, `platform_commerce.refunded` and `subscription.refunded` carry the refund receipt's. Absent on Open. `purchase.completed` also carries `tax_treatment` (`"partner_responsible"` on Open).
|
|
2134
|
+
|
|
1989
2135
|
Don't block waiting on `purchase.failed` for the `game`/`steam` rails — they only emit `completed`/`refunded`. Reconcile off `*.completed` + the status endpoints. For Platform Commerce **card** orders, fulfill on `platform_commerce.purchased`, not the browser confirmation.
|
|
1990
2136
|
|
|
1991
2137
|
---
|
|
@@ -2067,6 +2213,8 @@ Helpers:
|
|
|
2067
2213
|
| `.isNotPlatformTenant` | Platform Commerce called by a non-platform tenant (403) — use `purchaseItem`/`createCheckout` instead |
|
|
2068
2214
|
| `.isAmountBelowMinimum` / `.isBelowCardMinimum` / `.isAboveCardMaximum` | amount too small for the fee to round up / card charge under $0.50 / card charge over INVO's maximum single card charge, which is a runtime setting (400) |
|
|
2069
2215
|
| `.isAlreadyRefunded` | Platform Commerce refund of an already-refunded order (409) — treat as already done |
|
|
2216
|
+
| `.isQuoteStale` + `.expectedTotalUsd` | `purchaseCurrency` with an `acknowledgedTotalUsd` that is no longer the total (409); nothing charged: quote again |
|
|
2217
|
+
| `.isAmountBelowFee` | unacknowledged `purchaseCurrency` too small to carry INVO's card fee (400); nothing charged |
|
|
2070
2218
|
| `.retryAfter` | seconds to back off on a 429 throttle |
|
|
2071
2219
|
| `.isEnrollmentAuthorizationRequired` | first-enrollment needs the OTP grant → `enrollmentBegin`/`enrollmentVerify` |
|
|
2072
2220
|
| `.isEnrollmentProofRequired` | another method exists → prove it via `linkDevice` |
|
|
@@ -2104,16 +2252,17 @@ try {
|
|
|
2104
2252
|
| `initiateSend(input)` | `{ transactionId, verificationMethod, guardianApproval?, raw }` |
|
|
2105
2253
|
| `initiateTransfer(input)` | `{ transactionId, verificationMethod, guardianApproval?, raw }` |
|
|
2106
2254
|
| `createCheckout(input)` | `{ sessionId, checkoutUrl, sessionToken?, expiresAt, expiresInSeconds, raw }`, where `sessionToken` is INVO's own `session_token` field (falling back to the `checkoutUrl` query string on a backend that predates it) and is the credential for the [status read](#did-the-purchase-go-through-the-status-read) |
|
|
2107
|
-
| `
|
|
2108
|
-
| `
|
|
2109
|
-
| `
|
|
2255
|
+
| `quoteCurrencyPurchase({ playerEmail, usdAmount, country?, subdivision? })` | `CurrencyPurchaseQuote`: `{ totalUsd, amountCents, subtotalUsd, processingFeeUsd, coins, currencyName, breakdown, ifUnacknowledged, raw }`; moves no money; send `totalUsd` back as `acknowledgedTotalUsd` (see [INVO's card fee](#invos-card-fee-quote-show-acknowledge)) |
|
|
2256
|
+
| `purchaseCurrency(input)` | `{ status, clientSecret?, paymentIntentId?, paymentUrl?, transactionId?, orderId?, newBalance?, processingFeeUsd?, feeTakenFrom?, coinsCredited?, chargeTotalUsd?, receiptNumber?, receiptUrl?, raw }`; optional `acknowledgedTotalUsd` input; `receiptNumber` / `receiptUrl` on Merchant of Record only |
|
|
2257
|
+
| `confirmPayment({ paymentIntentId, orderId? })` | `{ status, transactionId?, newBalance?, credited?, reasonCode?, raw }`; report success only on `credited: true` |
|
|
2258
|
+
| `getOrderDetails({ orderId? \| transactionId? })` | `{ order, financialSummary, statusTimeline, receiptNumber?, receiptUrl?, raw }`; the receipt fields on a Merchant of Record currency purchase only |
|
|
2110
2259
|
| `purchaseItem(input)` | `{ status, transactionId, orderId, newBalance, previousBalance, currencyName, financialBreakdown?, raw }` — **game** tenant spending game currency on an in-game item |
|
|
2111
2260
|
| `getItemPurchaseHistory({ playerEmail, limit?, offset? })` | `{ history, pagination, raw }` |
|
|
2112
2261
|
| `getItemOrderDetails({ orderId? \| transactionId? \| clientRequestId? })` | `{ order, financialSummary, statusTimeline, raw }` |
|
|
2113
2262
|
| `platformCommerce.purchase(input)` | `{ status, fundingSource, orderId?, transactionId?, newBalance?, financialBreakdown?, sessionId?, checkoutUrl?, expiresAt?, amountUsd?, idempotentReplay?, raw }` — **ecommerce** (platform tenant); `balance` settles now, `card` returns a hosted-checkout `checkoutUrl` |
|
|
2114
|
-
| `platformCommerce.getStatus(orderId)` | `{ orderId, status, gameCurrencyAmount?, usdAmount?, paymentMethod?, createdAt?, raw }` |
|
|
2115
|
-
| `platformCommerce.refund({ orderId? \| clientRequestId?, reason? })` | `{ status, orderId?, fundingSource?, refundedAmount?, amountUnit?, feeRetained?, raw }
|
|
2116
|
-
| `subscriptions.create(input)` | `SubscriptionResult` — `{ status, idempotentReplay, subscription, card, firstCharge, warning?, raw }`; **card rail**, charges the first period before answering; branch on `firstCharge.status` (`paid` \| `requires_action` \| `skipped_trial` \| `failed` \| `pending`); idempotent on `clientRequestId` (a repeat is `idempotentReplay: true`, never thrown) |
|
|
2263
|
+
| `platformCommerce.getStatus(orderId)` | `{ orderId, status, gameCurrencyAmount?, usdAmount?, paymentMethod?, createdAt?, receiptNumber?, receiptUrl?, raw }` |
|
|
2264
|
+
| `platformCommerce.refund({ orderId? \| clientRequestId?, reason?, refundRemaining?, confirmAdditionalRefund? })` | `{ status, orderId?, fundingSource?, refundedAmount?, amountUnit?, feeRetained?, partialRefund?, adopted?, refundedTotalUsd?, chargeTotalUsd?, remainingUsd?, raw }`; pass **exactly one** id; INVO keeps its fee; `partialRefund`, `refundedTotalUsd`, `chargeTotalUsd`, `remainingUsd` only on a card sale refunded in parts; `adopted` whenever the call recorded an existing refund (a full one included) |
|
|
2265
|
+
| `subscriptions.create(input)` | `SubscriptionResult` — `{ status, idempotentReplay, subscription, card, firstCharge, warning?, raw }`; **card rail**, charges the first period before answering; branch on `firstCharge.status` (`paid` \| `requires_action` \| `skipped_trial` \| `failed` \| `pending`); `trialAmountUsd` makes a [paid trial](#paid-trials); idempotent on `clientRequestId` (a repeat is `idempotentReplay: true`, never thrown) |
|
|
2117
2266
|
| `subscriptions.get(id, { includePlayer? })` | `{ subscription, player?, raw }`: `subscription.paidThrough` is the entitlement boundary; `currentPeriodEnd` is only the billing window; `includePlayer: true` adds `subscription.playerEmail` / `subscription.playerName` (INVO puts them on the object; `player` is derived from them) |
|
|
2118
2267
|
| `subscriptions.listForPlayer(playerEmail, { status?, limit?, offset?, includePlayer? })` | `{ playerEmail, subscriptions, pagination: { totalCount, limit, offset, hasMore }, raw }` — newest first; `status: "live"` expands to the four live statuses |
|
|
2119
2268
|
| `subscriptions.cancel(id, { atPeriodEnd?, reason? })` | `CancelResult` — `{ alreadyCanceled, cancelAtPeriodEnd, terminatedImmediately, effectiveAt, accessUntil, paidThrough, subscription, raw }`; an already-terminal row is a 200 with `alreadyCanceled: true` |
|
|
@@ -381,14 +381,68 @@ var InvoError = class _InvoError extends Error {
|
|
|
381
381
|
get isAboveCardMaximum() {
|
|
382
382
|
return this.code === "ABOVE_CARD_MAXIMUM";
|
|
383
383
|
}
|
|
384
|
+
// ---- Coin purchase: INVO's card fee (2026-09-23) ----
|
|
385
|
+
/**
|
|
386
|
+
* True when an UNACKNOWLEDGED `purchaseCurrency` was refused because the amount is too
|
|
387
|
+
* small to carry INVO's card fee (`AMOUNT_BELOW_FEE`, 400). Nothing was charged. Send a
|
|
388
|
+
* larger amount, or quote it with `quoteCurrencyPurchase` and send `acknowledgedTotalUsd`
|
|
389
|
+
* so the fee is added on top.
|
|
390
|
+
*/
|
|
391
|
+
get isAmountBelowFee() {
|
|
392
|
+
return this.code === "AMOUNT_BELOW_FEE";
|
|
393
|
+
}
|
|
394
|
+
/**
|
|
395
|
+
* True when `purchaseCurrency` was sent an `acknowledgedTotalUsd` that is not the total
|
|
396
|
+
* INVO would charge now (`QUOTE_STALE`, 409). Nothing was charged. Quote again, show the
|
|
397
|
+
* player the new total, and retry with it. {@link expectedTotalUsd} carries INVO's figure.
|
|
398
|
+
*/
|
|
399
|
+
get isQuoteStale() {
|
|
400
|
+
return this.code === "QUOTE_STALE";
|
|
401
|
+
}
|
|
402
|
+
/** On `QUOTE_STALE`: the total INVO would charge (`expected_total_usd`), decimal string. */
|
|
403
|
+
get expectedTotalUsd() {
|
|
404
|
+
const v = this.bodyObject()["expected_total_usd"];
|
|
405
|
+
return typeof v === "string" && v ? v : void 0;
|
|
406
|
+
}
|
|
407
|
+
/** On `QUOTE_STALE`: the total you sent, as INVO read it (`acknowledged_total_usd`). */
|
|
408
|
+
get acknowledgedTotalUsd() {
|
|
409
|
+
const v = this.bodyObject()["acknowledged_total_usd"];
|
|
410
|
+
return typeof v === "string" && v ? v : void 0;
|
|
411
|
+
}
|
|
384
412
|
/**
|
|
385
413
|
* True if a Platform Commerce refund targeted an order that was already refunded
|
|
386
414
|
* (409). Idempotent outcome — the original refund did happen, so treat this as
|
|
387
415
|
* success, not a failure to retry-loop.
|
|
388
416
|
*/
|
|
389
417
|
get isAlreadyRefunded() {
|
|
418
|
+
if (this.isRefundRemainingRequiresConfirmation || this.isRefundRecentlyIssued) return false;
|
|
390
419
|
return this.code === "ALREADY_REFUNDED" || this.status === 409 && /already\s+refunded/i.test(this.message);
|
|
391
420
|
}
|
|
421
|
+
/**
|
|
422
|
+
* Platform Commerce card sale already refunded in part (409
|
|
423
|
+
* `REFUND_REMAINING_REQUIRES_CONFIRMATION`): nothing moved. Retry with
|
|
424
|
+
* `refundRemaining: true` to refund the rest; `refunded_total_usd` and `remaining_usd` are
|
|
425
|
+
* on `err.body`.
|
|
426
|
+
*/
|
|
427
|
+
get isRefundRemainingRequiresConfirmation() {
|
|
428
|
+
return this.code === "REFUND_REMAINING_REQUIRES_CONFIRMATION";
|
|
429
|
+
}
|
|
430
|
+
/**
|
|
431
|
+
* A Platform Commerce refund of this order was applied in the last 120 seconds (409
|
|
432
|
+
* `REFUND_RECENTLY_ISSUED`): nothing moved. Re-read the order; send
|
|
433
|
+
* `confirmAdditionalRefund: true` to refund anyway.
|
|
434
|
+
*/
|
|
435
|
+
get isRefundRecentlyIssued() {
|
|
436
|
+
return this.code === "REFUND_RECENTLY_ISSUED";
|
|
437
|
+
}
|
|
438
|
+
/**
|
|
439
|
+
* The Platform Commerce card refund failed, was canceled or still needs an action (502
|
|
440
|
+
* `REFUND_NOT_COMPLETED`): nothing was recorded. Retry; a refund that was in fact created
|
|
441
|
+
* is found and recorded on the retry, never issued twice.
|
|
442
|
+
*/
|
|
443
|
+
get isRefundNotCompleted() {
|
|
444
|
+
return this.code === "REFUND_NOT_COMPLETED";
|
|
445
|
+
}
|
|
392
446
|
/**
|
|
393
447
|
* True when an approve / confirm-receipt was refused because the transaction is no
|
|
394
448
|
* longer awaiting that step (`TRANSACTION_NOT_PENDING`, 400). `approveWithDeviceCode`
|
|
@@ -497,7 +551,8 @@ var InvoError = class _InvoError extends Error {
|
|
|
497
551
|
* True when the same `clientRequestId` was replayed for the same player and item but
|
|
498
552
|
* with DIFFERENT material terms (`IDEMPOTENT_REPLAY_MISMATCH`, 409). See
|
|
499
553
|
* `mismatchedFields` (any of `amount_usd`, `interval`, `interval_count`, `wallet_only`,
|
|
500
|
-
* `funding_rail`
|
|
554
|
+
* `funding_rail`, `trial_amount_usd`; for the last an omitted value counts, so a replay
|
|
555
|
+
* without it against a paid trial is a mismatch). To change terms use `changeAmount` / `setPaymentMethod`; to create a
|
|
501
556
|
* new subscription use a new key.
|
|
502
557
|
*/
|
|
503
558
|
get isIdempotentReplayMismatch() {
|
|
@@ -508,6 +563,46 @@ var InvoError = class _InvoError extends Error {
|
|
|
508
563
|
const v = this.bodyObject()["mismatched_fields"];
|
|
509
564
|
return Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
|
|
510
565
|
}
|
|
566
|
+
// ---- Subscriptions: paid trials (2026-09-23) ----
|
|
567
|
+
/**
|
|
568
|
+
* True on `PAYMENT_METHOD_REQUIRED` (400). From `subscriptions.create`: a paid trial
|
|
569
|
+
* (`trialAmountUsd`) with no usable saved card; nothing was created. Save the member's card
|
|
570
|
+
* (`cards.createSetupSession`), then subscribe again. From `setPaymentMethod`: no
|
|
571
|
+
* `playerCardId` was sent.
|
|
572
|
+
*/
|
|
573
|
+
get isPaymentMethodRequired() {
|
|
574
|
+
return this.code === "PAYMENT_METHOD_REQUIRED";
|
|
575
|
+
}
|
|
576
|
+
/**
|
|
577
|
+
* True when `trialAmountUsd` is not a usable trial price (`TRIAL_AMOUNT_INVALID`, 400): it
|
|
578
|
+
* must be a decimal of at least `0.50` (the card minimum) and less than `amountUsd`. The
|
|
579
|
+
* message names the rule.
|
|
580
|
+
*/
|
|
581
|
+
get isTrialAmountInvalid() {
|
|
582
|
+
return this.code === "TRIAL_AMOUNT_INVALID";
|
|
583
|
+
}
|
|
584
|
+
/** True when `trialAmountUsd` was sent without `trialDays` or `trialEnd` (`TRIAL_AMOUNT_REQUIRES_TRIAL`, 400). */
|
|
585
|
+
get isTrialAmountRequiresTrial() {
|
|
586
|
+
return this.code === "TRIAL_AMOUNT_REQUIRES_TRIAL";
|
|
587
|
+
}
|
|
588
|
+
/**
|
|
589
|
+
* True when a paid trial was asked for where it cannot be charged
|
|
590
|
+
* (`TRIAL_AMOUNT_NOT_SUPPORTED_FOR_FUNDING`, 400): with `walletOnly: true`, or on the Steam
|
|
591
|
+
* rail. Paid trials are for card subscriptions only.
|
|
592
|
+
*/
|
|
593
|
+
get isTrialAmountNotSupportedForFunding() {
|
|
594
|
+
return this.code === "TRIAL_AMOUNT_NOT_SUPPORTED_FOR_FUNDING";
|
|
595
|
+
}
|
|
596
|
+
/**
|
|
597
|
+
* True when one of the disclosed paid-trial consent fields is malformed (400):
|
|
598
|
+
* `CONSENT_DISCLOSED_TRIAL_AMOUNT_INVALID`, `CONSENT_DISCLOSED_TRIAL_DAYS_INVALID` (not an
|
|
599
|
+
* integer 1 to 365) or `CONSENT_DISCLOSED_TRIAL_END_INVALID` (not ISO 8601). `err.code`
|
|
600
|
+
* says which. A disclosed value that is well formed but disagrees with the trial is not
|
|
601
|
+
* refused; INVO records the disagreement.
|
|
602
|
+
*/
|
|
603
|
+
get isConsentDisclosedTrialInvalid() {
|
|
604
|
+
return this.code === "CONSENT_DISCLOSED_TRIAL_AMOUNT_INVALID" || this.code === "CONSENT_DISCLOSED_TRIAL_DAYS_INVALID" || this.code === "CONSENT_DISCLOSED_TRIAL_END_INVALID";
|
|
605
|
+
}
|
|
511
606
|
/**
|
|
512
607
|
* True when `changeAmount` tried to RAISE the price of a Steam subscription
|
|
513
608
|
* (`STEAM_REAUTHORIZATION_REQUIRED`, 409). The member consented to a ceiling; start a
|
|
@@ -983,6 +1078,23 @@ function toDestinationsResult(raw, direction) {
|
|
|
983
1078
|
};
|
|
984
1079
|
}
|
|
985
1080
|
|
|
986
|
-
|
|
987
|
-
|
|
988
|
-
|
|
1081
|
+
// src/shared/receipt-fields.ts
|
|
1082
|
+
function creditFields(raw) {
|
|
1083
|
+
const c = raw["credited"];
|
|
1084
|
+
if (c === true) return { credited: true };
|
|
1085
|
+
if (c === false) {
|
|
1086
|
+
const r = raw["reason_code"];
|
|
1087
|
+
return { credited: false, reasonCode: r == null ? null : String(r) };
|
|
1088
|
+
}
|
|
1089
|
+
return {};
|
|
1090
|
+
}
|
|
1091
|
+
function receiptFields(raw) {
|
|
1092
|
+
const n = raw["receipt_number"];
|
|
1093
|
+
if (typeof n !== "string" || n === "") return {};
|
|
1094
|
+
const u = raw["receipt_url"];
|
|
1095
|
+
return typeof u === "string" && u !== "" ? { receiptNumber: n, receiptUrl: u } : { receiptNumber: n };
|
|
1096
|
+
}
|
|
1097
|
+
|
|
1098
|
+
export { Http, InvoError, assertSecureBaseUrl, creditFields, receiptFields, toDestinationsResult };
|
|
1099
|
+
//# sourceMappingURL=chunk-BLY4NUMG.js.map
|
|
1100
|
+
//# sourceMappingURL=chunk-BLY4NUMG.js.map
|