@invonetwork/web-sdk 3.34.1 → 3.35.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 +14 -0
- package/README.md +95 -2
- package/dist/{chunk-3BR7URPM.js → chunk-BGCSSWVL.js} +104 -2
- package/dist/{chunk-PEYWNML4.js → chunk-SCFK6IVH.js} +3 -3
- package/dist/{chunk-MJXQ3Q7C.js → chunk-XN6MCLQV.js} +229 -68
- package/dist/game-server.cjs +291 -71
- package/dist/game-server.d.cts +3 -3
- package/dist/game-server.d.ts +3 -3
- package/dist/game-server.js +4 -4
- package/dist/game.cjs +102 -0
- package/dist/game.d.cts +2 -2
- package/dist/game.d.ts +2 -2
- package/dist/game.js +2 -2
- package/dist/{hosted-approval-CZ5EYFlM.d.ts → hosted-approval-DIYUGgHi.d.ts} +1 -1
- package/dist/{hosted-approval-B6yY7ExK.d.cts → hosted-approval-VQ3uyeDh.d.cts} +1 -1
- package/dist/index.cjs +102 -0
- package/dist/index.d.cts +4 -4
- package/dist/index.d.ts +4 -4
- package/dist/index.js +2 -2
- package/dist/{server-JARGQrat.d.ts → server-CMJHOmYL.d.ts} +117 -6
- package/dist/{server-A1s7zqzG.d.cts → server-DF-BZU0B.d.cts} +117 -6
- package/dist/server.cjs +330 -64
- package/dist/server.d.cts +2 -2
- package/dist/server.d.ts +2 -2
- package/dist/server.js +2 -2
- package/dist/{types-B4J9Ifd2.d.ts → types-Dv0UavA9.d.cts} +146 -1
- package/dist/{types-B4J9Ifd2.d.cts → types-Dv0UavA9.d.ts} +146 -1
- package/docs/apple-in-app-purchases.md +382 -0
- package/package.json +2 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,19 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 3.35.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- Apple In-App Purchases (StoreKit 2) on `InvoServer`. All additive.
|
|
8
|
+
|
|
9
|
+
- `appleProducts()` (`GET /api/currency-purchases/apple/products`): the App Store products registered for the game and whether INVO will sell each one right now (`available`, `unavailableReason`). Call it before every purchase and offer only available products: Apple charges the player before INVO sees the purchase.
|
|
10
|
+
- `verifyApplePurchase({ playerEmail, signedTransaction, appAccountToken?, playerName?, metadata? })` (`POST /api/currency-purchases/apple/verify-purchase`): call it from your server with StoreKit's `Transaction.jwsRepresentation`. INVO verifies it and credits the coins once. Returns `status` (`"credited"` or `"already_credited"`), `orderId`, `transactionId`, `productId`, `coins`, `balance`, `environment`, `testMode` and `finish`. Safe to retry: a replay never credits twice.
|
|
11
|
+
- `shouldFinishAppleTransaction(resultOrError)`: whether to call StoreKit's `Transaction.finish()`. It reads INVO's `finish` flag, which every verify-purchase answer carries, and falls back to the same rule when a body has none: `true` for `credited`, `already_credited` and the errors `APPLE_TRANSACTION_REVOKED`, `APPLE_TRANSACTION_ALREADY_USED` and `APPLE_TRANSACTION_TOO_OLD` (exported as `APPLE_FINISH_ERROR_CODES`); `false` for everything else, including network errors. `InvoError.finish` exposes the flag on a refusal (`undefined` when the body has none). Also `isAppleCreditPending(err)` for `APPLE_CREDIT_PENDING` (503, verified and held: retry).
|
|
12
|
+
- `InvoError` predicates: `isAppleSignatureInvalid`, `isAppleBundleMismatch`, `isAppleEnvironmentNotAllowed`, `isAppleProductTypeUnsupported`, `isAppleProductUnknown`, `isInvalidMetadata`, `isAppleReviewAccountRequired`, `isAppleTransactionRevoked`, `isAppleTransactionAlreadyUsed`, `isAppleTransactionTooOld`, `isAppleValueExceedsPrice`, `isAppleAccountTokenMismatch`, `isAppleNotConfigured`, `isAppleNotVerified`, `isAppleReviewPurchaseLimit`, `isAppleCreditPending`, and `isAppleEndpointRequired` (a card purchase with a key on the Apple rail).
|
|
13
|
+
- Types: `AppleProduct`, `AppleProductsResult`, `AppleUnavailableReason`, `AppleEnvironment`, `VerifyApplePurchaseInput`, `ApplePurchaseStatus`, `ApplePurchaseResult`.
|
|
14
|
+
- Webhooks: `rail: "apple"` on `purchase.completed` and `purchase.refunded`, with the new `apple` block (`AppleWebhookDetails`: `transaction_id`, `original_transaction_id`, `product_id`, `environment`, `storefront`, `price`, `currency`, `charged_usd_estimated`, `test_mode`) and `metadata` on an Apple `purchase.refunded`.
|
|
15
|
+
- Docs: a full guide, [Apple In-App Purchases](https://github.com/Invo-Technologies/invo-web-sdk/blob/main/docs/apple-in-app-purchases.md) (`docs/apple-in-app-purchases.md`, shipped in the package), linked from the top of the README, plus a README summary section.
|
|
16
|
+
|
|
3
17
|
## 3.34.1
|
|
4
18
|
|
|
5
19
|
### Patch Changes
|
package/README.md
CHANGED
|
@@ -4,6 +4,7 @@ First-party TypeScript SDK for integrating **INVO** into partner **web** platfor
|
|
|
4
4
|
|
|
5
5
|
> **Status:** `v3.34.1`, 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.34.1** points every console link at the one INVO console (live at console.invo.network, test mode at console.invo.network/test); **3.34.0** reads the environment from the [key prefix](#key-prefixes) (`ivsdk_live_` is production, `ivsdk_test_` is the sandbox), throws `KeyEnvironmentMismatchError` when a key is pointed at the other INVO host, and adds `err.isKeyForOtherEnvironment`; **3.33.0** adds **[buyer-approved balance purchases](#buyer-approved-balance-purchases)** on Platform Commerce (`requirePlayerApproval`, `getApproval`, `cancelApproval`, the opt-in `platform_commerce.declined` webhook) and `metadata` on the `platform_commerce.*` webhooks; **3.32.0** adds `err.isPaymentsPaused`; **3.31.0** adds `invoFeeUsd` / `partnerShareUsd` on `platformCommerce.getStatus()` and `getPurchaseHistory()`, `spent_coins_charged_usd` on the coin `purchase.disputed` close (coins already spent are charged to you on a lost dispute), `err.isRateLimited` (every rate-limit 429 now carries `RATE_LIMITED`) and a `Retry-After` header fallback for `err.retryAfter`, and documents dispute holds on both tiers and the $10 payout minimum; **3.23.0** types two optional fields on the `purchase.disputed` close: `dispute_fee_usd` and `dispute_fee_charged_to_partner` (from November 8, 2026 the card dispute fee on Open-tier card sales is passed through to you at cost); **3.22.0** follows INVO's 2026-10 pricing: the Open card fee is **3.5% + $0.30** (was 4.5%), Merchant of Record stays **5.5% + $0.50**; the **chargeback guarantee** is a Merchant of Record term (Open-tier card payments made before November 8, 2026 keep it); payouts to your bank carry a **1% fee, capped at $500 per payout**. New reads: `getPlayerActivity()` / `iteratePlayerActivity()` (one merged list of a player's purchases, sends and transfers) and `platformCommerce.getPurchaseHistory()` / `iteratePurchaseHistory()`; `expiryReason` on `getTransferStatus()` / `getSendStatus()`; typed `transfer.*` and `payout.status_changed` webhook fields; new additive `err.publicCode` (the neutral twin of a code), set to `"BELOW_CARD_MINIMUM"` on the local card-floor refusal, whose `err.code` is unchanged (see [Tiers](#tiers) for the pricing); and the **[player-confirmed phone change](#player-confirmed-phone-change)**: `requestPhoneChange()` / `getPhoneChange()` on the server, `listPhoneChangeApprovals()` / `approvePhoneChange()` on the player's enrolled device, the typed `player.phone_changed` webhook, `err.changeRequestEndpoint` and new phone change error helpers; **3.18.0** follows INVO's 2026-09 card pricing: on card purchases **you pay INVO's card fee** (**4.5% + $0.30** on Open, **5.5% + $0.50** on Merchant of Record, plus **1.5%** on a card issued outside the US) and the player pays the listed price and gets the listed coins; fraud screening and a **chargeback guarantee** are included; minimum card purchase **$2.99** from 2026-10-27. New `partnerFeeUsd`, `internationalCardFeeUsd`, `minPurchaseWarning`, `feeTakenFrom: "partner"`, `err.minUsd` / `err.enforcedFrom` on `err.isBelowCardMinimum`, `minPurchaseWarning` on `createCheckout()`, `country` / `subdivision` on `purchaseCurrency()` with `err.isTaxPlaceUnavailable`, `cardFeeChargedToPartnerUsd` / `partnerDebitedUsd` on Platform Commerce card refunds, and the `partner_fee_usd` / `international_card_fee_usd` / `guarantee_covered` / `card_fee_charged_to_partner_usd` / `partner_debited_usd` webhook fields, all additive; an unacknowledged $10.00 coin purchase now credits 100.00 coins, not 93.70 (see **[Tiers](#tiers)**); **3.17.0** types the Steam fields on `purchase.refunded` / `purchase.disputed` (`rail`, `steam_transid`, nullable card-only ids): Steam chargebacks now arrive as `purchase.disputed`; **3.16.0** adds `warnings` on `createCheckout()` (item metadata on a coin session), `err.isDuplicateClientRequestId`, `err.isTrialAmountBelowFeeFloor` and `err.isIdentityCheckUnavailable`; **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 rates and chargeback handling by tier (the rates are superseded by 3.18.0), 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)** (rates superseded by 3.18.0): `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 (it is its own rate; item purchases stay at 10/90; see [Tiers](#tiers) for the current rate); **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
|
+
> **Selling on iOS?** Read the full guide: [Apple In-App Purchases (StoreKit 2)](https://github.com/Invo-Technologies/invo-web-sdk/blob/main/docs/apple-in-app-purchases.md).
|
|
7
8
|
|
|
8
9
|
## What it does
|
|
9
10
|
|
|
@@ -103,6 +104,7 @@ The right approval method is a property of the **client the player is sitting in
|
|
|
103
104
|
- [INVO's card fee: quote, show, acknowledge](#invos-card-fee-quote-show-acknowledge)
|
|
104
105
|
- [Refunds of coin purchases](#refunds-of-coin-purchases)
|
|
105
106
|
- [Did the purchase go through? (the status read)](#did-the-purchase-go-through-the-status-read)
|
|
107
|
+
- [Apple In-App Purchases (StoreKit 2)](#apple-in-app-purchases-storekit-2): full guide in [docs/apple-in-app-purchases.md](https://github.com/Invo-Technologies/invo-web-sdk/blob/main/docs/apple-in-app-purchases.md)
|
|
106
108
|
- [Item purchase (spend game currency)](#item-purchase-spend-game-currency)
|
|
107
109
|
- [Platform Commerce (ecommerce)](#platform-commerce-ecommerce)
|
|
108
110
|
- [Subscriptions (recurring billing)](#subscriptions-recurring-billing)
|
|
@@ -804,6 +806,95 @@ be issued:
|
|
|
804
806
|
names in yours
|
|
805
807
|
(`data.channel` is the channel of the KEY you presented — `"steam"` when you call with your Steam channel key; `null` on a legacy game key).
|
|
806
808
|
|
|
809
|
+
### Apple In-App Purchases (StoreKit 2)
|
|
810
|
+
|
|
811
|
+
> **Full guide: [Apple In-App Purchases](https://github.com/Invo-Technologies/invo-web-sdk/blob/main/docs/apple-in-app-purchases.md)** (prerequisites in App Store Connect and the
|
|
812
|
+
> INVO console, the flow, every error with its retry and finish rule, held purchases, refunds
|
|
813
|
+
> and webhooks, App Review on production, verification, and a complete server example). This
|
|
814
|
+
> section is the summary.
|
|
815
|
+
|
|
816
|
+
An iOS game sells coins with Apple In-App Purchase: the player pays Apple through StoreKit 2,
|
|
817
|
+
and your server sends Apple's signed transaction to INVO, which verifies it and credits the
|
|
818
|
+
coins once. Both methods are on `InvoServer` and take the game's **iOS key**, with Apple
|
|
819
|
+
In-App Purchases set up for the game in the INVO console (bundle id and products). A card
|
|
820
|
+
purchase with that key throws `WRONG_RAIL_ENDPOINT` (`err.isAppleEndpointRequired`).
|
|
821
|
+
|
|
822
|
+
**Apple charges the player before INVO sees the purchase.** So the order of calls matters:
|
|
823
|
+
|
|
824
|
+
1. **Before every purchase, call `appleProducts()`** and offer only products with
|
|
825
|
+
`available: true`. Ask StoreKit for exactly the `productId`s listed. This is the only point
|
|
826
|
+
where INVO can say no (`unavailableReason`: `APPLE_NOT_VERIFIED`,
|
|
827
|
+
`PARTNER_BILLING_NOT_SET_UP`, `PARTNER_RAIL_SUSPENDED`, `PARTNER_CREDIT_UNAVAILABLE`).
|
|
828
|
+
2. **Verify from your server, never the device.** Your app sends
|
|
829
|
+
`Transaction.jwsRepresentation` to your server, and your server calls
|
|
830
|
+
`verifyApplePurchase()`.
|
|
831
|
+
3. **Call `Transaction.finish()` only when INVO says to.** Every answer, success or error,
|
|
832
|
+
carries a boolean `finish` (`result.finish`, `err.finish`), and
|
|
833
|
+
`shouldFinishAppleTransaction()` reads it for you. It is `true` for `credited`,
|
|
834
|
+
`already_credited`, and the errors `APPLE_TRANSACTION_REVOKED`,
|
|
835
|
+
`APPLE_TRANSACTION_ALREADY_USED` and `APPLE_TRANSACTION_TOO_OLD`, after which nothing can
|
|
836
|
+
ever be delivered. On anything else, leave the transaction unfinished: StoreKit
|
|
837
|
+
redelivers it and your server retries. A retry never credits twice.
|
|
838
|
+
|
|
839
|
+
```ts
|
|
840
|
+
import { InvoServer, shouldFinishAppleTransaction } from "@invonetwork/web-sdk/server";
|
|
841
|
+
|
|
842
|
+
const server = new InvoServer({
|
|
843
|
+
gameSecret: process.env.INVO_IOS_KEY!, // the game's iOS key, server-side only
|
|
844
|
+
baseUrl: "https://sandbox.invo.network/sandbox", // prod: "https://invo.network"
|
|
845
|
+
});
|
|
846
|
+
|
|
847
|
+
// 1. Before every purchase: what may be offered right now.
|
|
848
|
+
const { canSell, products } = await server.appleProducts();
|
|
849
|
+
const offer = canSell ? products.filter((p) => p.available) : [];
|
|
850
|
+
// -> [{ productId, coins, label, priceUsd, available, unavailableReason }, ...]
|
|
851
|
+
|
|
852
|
+
// 2. After StoreKit returns a verified transaction, on your server:
|
|
853
|
+
let outcome: unknown;
|
|
854
|
+
try {
|
|
855
|
+
outcome = await server.verifyApplePurchase({
|
|
856
|
+
playerEmail: "player@example.com",
|
|
857
|
+
signedTransaction: jwsFromTheApp, // Transaction.jwsRepresentation, unchanged
|
|
858
|
+
appAccountToken: playerUuid, // optional: the appAccountToken you set
|
|
859
|
+
metadata: { playerId: myPlayerId }, // optional: echoed on the webhooks
|
|
860
|
+
});
|
|
861
|
+
// -> { status: "credited" | "already_credited", orderId, transactionId, productId,
|
|
862
|
+
// coins, balance, environment, testMode, finish }
|
|
863
|
+
} catch (err) {
|
|
864
|
+
outcome = err; // err.isAppleCreditPending: held, retry later
|
|
865
|
+
}
|
|
866
|
+
|
|
867
|
+
// 3. Tell the app whether to finish the transaction.
|
|
868
|
+
return { finish: shouldFinishAppleTransaction(outcome) };
|
|
869
|
+
```
|
|
870
|
+
|
|
871
|
+
| Outcome | HTTP | Finish? | Do |
|
|
872
|
+
|---|---|---|---|
|
|
873
|
+
| `status: "credited"` | 200 | yes | grant the coins |
|
|
874
|
+
| `status: "already_credited"` | 200 | yes | a replay; the coins were granted before (`balance` is `null` unless you name the same player) |
|
|
875
|
+
| `err.isAppleTransactionRevoked` | 409 | yes | Apple refunded or revoked it; grant nothing |
|
|
876
|
+
| `err.isAppleTransactionAlreadyUsed` | 409 | yes | credited in another INVO game; grant nothing here |
|
|
877
|
+
| `err.isAppleTransactionTooOld` | 409 | yes | bought before the game sold through INVO; grant nothing |
|
|
878
|
+
| `err.isAppleCreditPending` | 503 | no | verified and held; retry later, never ask the player to pay again |
|
|
879
|
+
| `err.isAppleProductUnknown`, `err.isAppleValueExceedsPrice` | 400, 409 | no | fix the product in the INVO console, then retry |
|
|
880
|
+
| `err.isAppleNotConfigured`, `err.isAppleNotVerified`, `err.isRailChannelMismatch` | 409 | no | finish the setup, then retry |
|
|
881
|
+
| `err.isAppleReviewPurchaseLimit` | 429 | no | today's App Review cap (per UTC day); retry the next day |
|
|
882
|
+
| `err.isAppleSignatureInvalid`, `err.isAppleBundleMismatch`, `err.isAppleEnvironmentNotAllowed`, `err.isAppleProductTypeUnsupported`, `err.isInvalidMetadata`, `err.isInvalidInput` | 400 | no | not a purchase INVO can credit as sent |
|
|
883
|
+
| `err.isAppleReviewAccountRequired` | 403 | no | a Sandbox purchase on production by an account not on the game's App Review list |
|
|
884
|
+
| `err.isAppleAccountTokenMismatch` | 409 | no | made for a different player |
|
|
885
|
+
| anything else, a network error or a timeout | | no | retry |
|
|
886
|
+
|
|
887
|
+
- **The INVO sandbox takes Sandbox transactions only.** Production takes Production ones,
|
|
888
|
+
and Sandbox ones only for the App Review accounts listed in the console (`testMode: true`,
|
|
889
|
+
capped per day). Xcode StoreKit-testing transactions are never accepted: Apple does not
|
|
890
|
+
sign them.
|
|
891
|
+
- **Webhooks:** `purchase.completed` and `purchase.refunded` carry `rail: "apple"`, your
|
|
892
|
+
`metadata` and an `apple` block (`transaction_id`,
|
|
893
|
+
`original_transaction_id`, `product_id`, `environment`, `storefront`, `price`, `currency`,
|
|
894
|
+
`charged_usd_estimated`, `test_mode`); `purchase.completed` also carries `channel: "ios"`.
|
|
895
|
+
A refund takes back only the coins the player still
|
|
896
|
+
holds from the purchase, never below zero.
|
|
897
|
+
|
|
807
898
|
### Direct rail (advanced — you tokenize the card yourself)
|
|
808
899
|
|
|
809
900
|
```ts
|
|
@@ -2758,10 +2849,10 @@ export const POST = createWebhookHandler({
|
|
|
2758
2849
|
|
|
2759
2850
|
| Event | Fires for | Use it to |
|
|
2760
2851
|
|---|---|---|
|
|
2761
|
-
| `purchase.completed` | every currency-purchase rail, **and every paid card subscription renewal** | grant currency (payload: `transaction_id, order_id, player_email, identity_id, usd_amount, currency_amount, currency_name, new_balance, rail`, `metadata`). `metadata` echoes what you passed to `createCheckout`/`purchaseCurrency` (all rails); `order_id` is also on every webhook as a secondary reconciliation key (`getOrderDetails`). Card purchases also carry `partner_fee_usd` and `international_card_fee_usd`, the card fees charged to you (the player paid the listed price). **Skip it when `metadata.source` is `"subscription_renewal"`**: those coins are spent by the renewal itself; grant on `subscription.renewed`. |
|
|
2852
|
+
| `purchase.completed` | every currency-purchase rail, **and every paid card subscription renewal** | grant currency (payload: `transaction_id, order_id, player_email, identity_id, usd_amount, currency_amount, currency_name, new_balance, rail`, `metadata`). `metadata` echoes what you passed to `createCheckout`/`purchaseCurrency` (all rails); `order_id` is also on every webhook as a secondary reconciliation key (`getOrderDetails`). Card purchases also carry `partner_fee_usd` and `international_card_fee_usd`, the card fees charged to you (the player paid the listed price). Apple purchases carry `rail: "apple"` and an `apple` block (see [Apple In-App Purchases](#apple-in-app-purchases-storekit-2)). **Skip it when `metadata.source` is `"subscription_renewal"`**: those coins are spent by the renewal itself; grant on `subscription.renewed`. |
|
|
2762
2853
|
| `purchase.failed` | `platform` rail only | handle failures |
|
|
2763
2854
|
| `purchase.disputed` | `platform` rail, and `steam` chargebacks | handle disputes. A lost chargeback takes back up to the purchase's coins from the available balance, never below zero. On a lost Platform Commerce card sale or subscription charge dispute (`order_type`), `guarantee_covered: true` means INVO's chargeback guarantee covers it (a fraud chargeback): your share is not reversed or held and no dispute fee is passed to you. Otherwise a lost dispute costs you what a refund would: your share is reversed and INVO's card fee stays charged to you, on a Platform Commerce sale and on every subscription charge (`card_fee_charged_to_partner_usd`, and `partner_debited_usd` = share reversed plus that fee, since 2026-09-28). A subscription dispute also carries `processing_fee_usd`, which reads `"0.00"`. Coin purchase disputes carry none of these keys: a lost one takes back the coins the player still holds and, since 2026-10-20, charges you for coins already spent at the price paid (`spent_coins_charged_usd` on the close, `"0.00"` when none). A Steam chargeback carries the same keys as a lost card dispute with `payment_intent_id`, `charge_id` and `dispute_id` `null`, plus `rail: "steam"` and `steam_transid`. A card dispute close also carries `dispute_fee_usd` (string decimal, `"0.00"` when INVO bears the fee, `null` when undecided) and `dispute_fee_charged_to_partner` (boolean or `null`); from November 8, 2026 the dispute fee on an Open-tier card sale is passed through to you at cost. **If you revoke on `purchase.refunded`, handle this too:** a Steam chargeback no longer arrives as `purchase.refunded` |
|
|
2764
|
-
| `purchase.refunded` | `game` / `steam` rails | handle refunds. Only coins the player still has from that purchase are taken back, never below zero. A Steam partial refund carries `fully_refunded: false` |
|
|
2855
|
+
| `purchase.refunded` | `game` / `steam` / `apple` rails | handle refunds. Only coins the player still has from that purchase are taken back, never below zero. A Steam partial refund carries `fully_refunded: false`. An Apple refund or revocation carries `rail: "apple"`, `metadata` and the `apple` block |
|
|
2765
2856
|
| `item.purchased` | every item purchase | **grant the in-game item** (payload includes `transaction_id, order_id, player_email, identity_id, item_id, item_name, item_quantity, unit_price, total_price, currency_name, new_balance, fee_breakdown`) |
|
|
2766
2857
|
| `platform_commerce.purchased` | every Platform Commerce purchase (balance immediately; **card after payment settles**) | **fulfill the ecommerce order** — never on the browser confirm (payload: `transaction_id, order_id, funding_source, player_email, identity_id, item_id, item_name, item_quantity, total_price`; + `unit_price, currency_name, new_balance` on balance; `total_price_usd` on card; `fee_breakdown`) |
|
|
2767
2858
|
| `platform_commerce.refunded` | a Platform Commerce refund | handle the reversal (payload: `order_id, funding_source, player_email, refunded_amount, amount_unit, fee_retained`) |
|
|
@@ -2913,6 +3004,8 @@ try {
|
|
|
2913
3004
|
| `purchaseCurrency(input)` | `{ status, clientSecret?, paymentIntentId?, paymentUrl?, transactionId?, orderId?, newBalance?, processingFeeUsd?, feeTakenFrom?, partnerFeeUsd?, internationalCardFeeUsd?, minPurchaseWarning?, coinsCredited?, chargeTotalUsd?, receiptNumber?, receiptUrl?, raw }`; optional `acknowledgedTotalUsd`, `country` and `subdivision` inputs; `receiptNumber` / `receiptUrl` on Merchant of Record only |
|
|
2914
3005
|
| `confirmPayment({ paymentIntentId, orderId? })` | `{ status, transactionId?, newBalance?, credited?, reasonCode?, raw }`; report success only on `credited: true` |
|
|
2915
3006
|
| `getOrderDetails({ orderId? \| transactionId? })` | `{ order, financialSummary, statusTimeline, receiptNumber?, receiptUrl?, raw }`; the receipt fields on a Merchant of Record currency purchase only |
|
|
3007
|
+
| `appleProducts()` | `{ bundleId, canSell, unavailableReason, products: [{ productId, coins, label, priceUsd, active, available, unavailableReason }], raw }`; call before every Apple purchase and offer only `available` products. See [Apple In-App Purchases](#apple-in-app-purchases-storekit-2) |
|
|
3008
|
+
| `verifyApplePurchase({ playerEmail, signedTransaction, appAccountToken?, playerName?, metadata? })` | `{ status: "credited" | "already_credited", orderId, transactionId, productId, coins, balance, environment, testMode, finish, raw }`; finish the StoreKit transaction only when\| "already_credited", orderId, transactionId, productId, coins, balance, environment, testMode, raw }`; finish the StoreKit transaction only when `shouldFinishAppleTransaction(resultOrError)` is `true` |
|
|
2916
3009
|
| `purchaseItem(input)` | `{ status, transactionId, orderId, newBalance, previousBalance, currencyName, financialBreakdown?, raw }` — **game** tenant spending game currency on an in-game item |
|
|
2917
3010
|
| `getItemPurchaseHistory({ playerEmail, limit?, offset? })` | `{ history, pagination, raw }` |
|
|
2918
3011
|
| `getPlayerActivity({ playerEmail, limit?, cursor?, types? })` | `PlayerActivityResult`: `{ playerEmail, gameId, types, activity, limit, hasMore, nextCursor, raw }`, one merged, newest-first page of purchases, sends and transfers. See [Player activity](#player-activity-one-list-of-everything) |
|
|
@@ -1161,6 +1161,108 @@ var InvoError = class _InvoError extends Error {
|
|
|
1161
1161
|
get isRateLimited() {
|
|
1162
1162
|
return this.code === "RATE_LIMITED" || this.code === "rate_limited" || this.status === 429;
|
|
1163
1163
|
}
|
|
1164
|
+
// ---- Apple In-App Purchase (verifyApplePurchase / appleProducts, 3.35.0) ----
|
|
1165
|
+
//
|
|
1166
|
+
// Apple has already charged the player when verifyApplePurchase runs. Decide whether to
|
|
1167
|
+
// call StoreKit's Transaction.finish() with shouldFinishAppleTransaction() (or `finish`),
|
|
1168
|
+
// not with these: among the errors only APPLE_TRANSACTION_REVOKED,
|
|
1169
|
+
// APPLE_TRANSACTION_ALREADY_USED and APPLE_TRANSACTION_TOO_OLD are finished.
|
|
1170
|
+
/**
|
|
1171
|
+
* The body's boolean `finish` (additive, 3.35.0), sent on every `verifyApplePurchase`
|
|
1172
|
+
* answer: `true` when the game should call StoreKit's `Transaction.finish()` for this
|
|
1173
|
+
* refusal (nothing can ever be delivered), `false` when it should leave the transaction
|
|
1174
|
+
* unfinished and retry. `undefined` when the body carries none (any other endpoint, an
|
|
1175
|
+
* older backend, or a network error); `shouldFinishAppleTransaction(err)` then falls back
|
|
1176
|
+
* to the error code.
|
|
1177
|
+
*/
|
|
1178
|
+
get finish() {
|
|
1179
|
+
const f = this.bodyObject()["finish"];
|
|
1180
|
+
return typeof f === "boolean" ? f : void 0;
|
|
1181
|
+
}
|
|
1182
|
+
/** Not a genuine Apple transaction (`APPLE_SIGNATURE_INVALID`, 400). Leave it unfinished. */
|
|
1183
|
+
get isAppleSignatureInvalid() {
|
|
1184
|
+
return this.code === "APPLE_SIGNATURE_INVALID";
|
|
1185
|
+
}
|
|
1186
|
+
/** Another app's transaction: the bundle id (or Apple ID) is not this game's
|
|
1187
|
+
* (`APPLE_BUNDLE_MISMATCH`, 400). */
|
|
1188
|
+
get isAppleBundleMismatch() {
|
|
1189
|
+
return this.code === "APPLE_BUNDLE_MISMATCH";
|
|
1190
|
+
}
|
|
1191
|
+
/** The transaction's environment is not accepted here (`APPLE_ENVIRONMENT_NOT_ALLOWED`, 400).
|
|
1192
|
+
* The INVO sandbox takes only Sandbox transactions; Xcode StoreKit-testing transactions are
|
|
1193
|
+
* never accepted, because Apple does not sign them. */
|
|
1194
|
+
get isAppleEnvironmentNotAllowed() {
|
|
1195
|
+
return this.code === "APPLE_ENVIRONMENT_NOT_ALLOWED";
|
|
1196
|
+
}
|
|
1197
|
+
/** Only consumable products buy currency (`APPLE_PRODUCT_TYPE_UNSUPPORTED`, 400). */
|
|
1198
|
+
get isAppleProductTypeUnsupported() {
|
|
1199
|
+
return this.code === "APPLE_PRODUCT_TYPE_UNSUPPORTED";
|
|
1200
|
+
}
|
|
1201
|
+
/** The product id is not registered for this game (`APPLE_PRODUCT_UNKNOWN`, 400). Register
|
|
1202
|
+
* it in the INVO console and retry; keep the transaction unfinished meanwhile. */
|
|
1203
|
+
get isAppleProductUnknown() {
|
|
1204
|
+
return this.code === "APPLE_PRODUCT_UNKNOWN";
|
|
1205
|
+
}
|
|
1206
|
+
/** `metadata` was refused (`INVALID_METADATA`, 400). Fix the request and retry. */
|
|
1207
|
+
get isInvalidMetadata() {
|
|
1208
|
+
return this.code === "INVALID_METADATA";
|
|
1209
|
+
}
|
|
1210
|
+
/** A Sandbox purchase on INVO production by an account not on the game's App Review list
|
|
1211
|
+
* (`APPLE_REVIEW_ACCOUNT_REQUIRED`, 403). */
|
|
1212
|
+
get isAppleReviewAccountRequired() {
|
|
1213
|
+
return this.code === "APPLE_REVIEW_ACCOUNT_REQUIRED";
|
|
1214
|
+
}
|
|
1215
|
+
/** Apple refunded or revoked the transaction (`APPLE_TRANSACTION_REVOKED`, 409). Nothing can
|
|
1216
|
+
* ever be delivered for it: **finish it** (`finish: true`). */
|
|
1217
|
+
get isAppleTransactionRevoked() {
|
|
1218
|
+
return this.code === "APPLE_TRANSACTION_REVOKED";
|
|
1219
|
+
}
|
|
1220
|
+
/** The transaction was already credited in another INVO game
|
|
1221
|
+
* (`APPLE_TRANSACTION_ALREADY_USED`, 409). Terminal: **finish it** (`finish: true`). */
|
|
1222
|
+
get isAppleTransactionAlreadyUsed() {
|
|
1223
|
+
return this.code === "APPLE_TRANSACTION_ALREADY_USED";
|
|
1224
|
+
}
|
|
1225
|
+
/** Bought before the game sold through INVO (`APPLE_TRANSACTION_TOO_OLD`, 409). Terminal:
|
|
1226
|
+
* **finish it** (`finish: true`). */
|
|
1227
|
+
get isAppleTransactionTooOld() {
|
|
1228
|
+
return this.code === "APPLE_TRANSACTION_TOO_OLD";
|
|
1229
|
+
}
|
|
1230
|
+
/** The product's coins are out of proportion to its signed price, or over the per-purchase
|
|
1231
|
+
* maximum (`APPLE_VALUE_EXCEEDS_PRICE`, 409). Fix the product mapping and retry. */
|
|
1232
|
+
get isAppleValueExceedsPrice() {
|
|
1233
|
+
return this.code === "APPLE_VALUE_EXCEEDS_PRICE";
|
|
1234
|
+
}
|
|
1235
|
+
/** The transaction's `appAccountToken` is not the one you sent: it was made for a
|
|
1236
|
+
* different player (`APPLE_ACCOUNT_TOKEN_MISMATCH`, 409). */
|
|
1237
|
+
get isAppleAccountTokenMismatch() {
|
|
1238
|
+
return this.code === "APPLE_ACCOUNT_TOKEN_MISMATCH";
|
|
1239
|
+
}
|
|
1240
|
+
/** The game's Apple configuration is missing or turned off (`APPLE_NOT_CONFIGURED`, 409).
|
|
1241
|
+
* Retry once it is set up. */
|
|
1242
|
+
get isAppleNotConfigured() {
|
|
1243
|
+
return this.code === "APPLE_NOT_CONFIGURED";
|
|
1244
|
+
}
|
|
1245
|
+
/** Production has not yet confirmed you own the App Store app (`APPLE_NOT_VERIFIED`, 409).
|
|
1246
|
+
* Point App Store Server Notifications at INVO; retry once verified. */
|
|
1247
|
+
get isAppleNotVerified() {
|
|
1248
|
+
return this.code === "APPLE_NOT_VERIFIED";
|
|
1249
|
+
}
|
|
1250
|
+
/** Today's App Review purchase cap on production is reached (`APPLE_REVIEW_PURCHASE_LIMIT`,
|
|
1251
|
+
* 429). */
|
|
1252
|
+
get isAppleReviewPurchaseLimit() {
|
|
1253
|
+
return this.code === "APPLE_REVIEW_PURCHASE_LIMIT";
|
|
1254
|
+
}
|
|
1255
|
+
/** Verified and held, not refused (`APPLE_CREDIT_PENDING`, 503): the coins will credit on a
|
|
1256
|
+
* later retry. Keep the transaction unfinished and retry; StoreKit also redelivers it. */
|
|
1257
|
+
get isAppleCreditPending() {
|
|
1258
|
+
return this.code === "APPLE_CREDIT_PENDING";
|
|
1259
|
+
}
|
|
1260
|
+
/** A card purchase (`purchaseCurrency`) was made with a key on the Apple rail
|
|
1261
|
+
* (`WRONG_RAIL_ENDPOINT`, 400, `status: "use_apple_endpoint"`). Use
|
|
1262
|
+
* `verifyApplePurchase` for that key. */
|
|
1263
|
+
get isAppleEndpointRequired() {
|
|
1264
|
+
return this.code === "WRONG_RAIL_ENDPOINT" && this.bodyObject()["status"] === "use_apple_endpoint";
|
|
1265
|
+
}
|
|
1164
1266
|
/** `body` as a plain object, or `{}` if it's a string/number/null (non-JSON responses).
|
|
1165
1267
|
* The `in` operator throws on primitives, so callers must go through this. */
|
|
1166
1268
|
bodyObject() {
|
|
@@ -1774,5 +1876,5 @@ function toApprovePhoneChangeResult(raw, changeRequestId) {
|
|
|
1774
1876
|
}
|
|
1775
1877
|
|
|
1776
1878
|
export { Http, InvoError, assertSecureBaseUrl, buildGameEventBody, creditFields, isPurchaseCredited, isPurchaseExpired, isPurchaseRefunded, isPurchaseRefused, newEventId, nothingWasCharged, phoneChangeSignalMessage, receiptFields, toApprovePhoneChangeResult, toDestinationsResult, toLoyaltyCardsResult, toLoyaltyVaultResult, toPhoneChangeApprovalsResult, toPhoneChangeRequest, toPurchaseStatusResult, toRedeemRewardResult, toReportGameEventResult, toRequestPhoneChangeResult, toRewardsPageLink };
|
|
1777
|
-
//# sourceMappingURL=chunk-
|
|
1778
|
-
//# sourceMappingURL=chunk-
|
|
1879
|
+
//# sourceMappingURL=chunk-BGCSSWVL.js.map
|
|
1880
|
+
//# sourceMappingURL=chunk-BGCSSWVL.js.map
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { InvoError, assertSecureBaseUrl, Http, toPurchaseStatusResult, toPhoneChangeApprovalsResult, phoneChangeSignalMessage, toApprovePhoneChangeResult, toDestinationsResult, toLoyaltyCardsResult, toLoyaltyVaultResult, toRedeemRewardResult, toRewardsPageLink, buildGameEventBody, toReportGameEventResult } from './chunk-
|
|
1
|
+
import { InvoError, assertSecureBaseUrl, Http, toPurchaseStatusResult, toPhoneChangeApprovalsResult, phoneChangeSignalMessage, toApprovePhoneChangeResult, toDestinationsResult, toLoyaltyCardsResult, toLoyaltyVaultResult, toRedeemRewardResult, toRewardsPageLink, buildGameEventBody, toReportGameEventResult } from './chunk-BGCSSWVL.js';
|
|
2
2
|
|
|
3
3
|
// src/shared/webauthn.ts
|
|
4
4
|
function malformedOptions(field) {
|
|
@@ -1586,5 +1586,5 @@ var InvoClient = class {
|
|
|
1586
1586
|
};
|
|
1587
1587
|
|
|
1588
1588
|
export { CheckoutClient, InvoClient, PlatformCommerceClient };
|
|
1589
|
-
//# sourceMappingURL=chunk-
|
|
1590
|
-
//# sourceMappingURL=chunk-
|
|
1589
|
+
//# sourceMappingURL=chunk-SCFK6IVH.js.map
|
|
1590
|
+
//# sourceMappingURL=chunk-SCFK6IVH.js.map
|