@invonetwork/web-sdk 3.37.1 → 3.38.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 +13 -0
- package/README.md +14 -2
- package/dist/{chunk-QD5G355J.js → chunk-3HK32FE4.js} +3 -3
- package/dist/{chunk-I4GDKZFL.js → chunk-7B7MFAQ3.js} +22 -2
- package/dist/chunk-MOHWLDOQ.js +6 -0
- package/dist/{chunk-YFNQKYUI.js → chunk-NS33T5FB.js} +46 -5
- package/dist/game-server.cjs +70 -9
- package/dist/game-server.d.cts +4 -4
- package/dist/game-server.d.ts +4 -4
- package/dist/game-server.js +5 -5
- package/dist/game.cjs +21 -1
- package/dist/game.d.cts +3 -3
- package/dist/game.d.ts +3 -3
- package/dist/game.js +3 -3
- package/dist/{hosted-approval-CxWyQOfU.d.cts → hosted-approval-B-kbdFDL.d.cts} +1 -1
- package/dist/{hosted-approval-D-CGX-LO.d.ts → hosted-approval-CtAZ1Rzt.d.ts} +1 -1
- package/dist/index.cjs +20 -0
- package/dist/index.d.cts +4 -4
- package/dist/index.d.ts +4 -4
- package/dist/index.js +2 -2
- package/dist/{server-BuByP1JU.d.cts → server-BWGl9v5j.d.cts} +75 -3
- package/dist/{server-DzczMA-z.d.ts → server-CaaP-Nc3.d.ts} +75 -3
- package/dist/server.cjs +70 -9
- package/dist/server.d.cts +3 -3
- package/dist/server.d.ts +3 -3
- package/dist/server.js +3 -3
- package/dist/{types-IRNjMV47.d.cts → types-DGgWWX1v.d.cts} +65 -1
- package/dist/{types-IRNjMV47.d.ts → types-DGgWWX1v.d.ts} +65 -1
- package/dist/{version-BIHJFKuj.d.cts → version-D_cJUvMp.d.cts} +1 -1
- package/dist/{version-BIHJFKuj.d.ts → version-D_cJUvMp.d.ts} +1 -1
- package/docs/merchant-of-record-tax.md +176 -0
- package/package.json +2 -1
- package/dist/chunk-OYJUX2TH.js +0 -6
|
@@ -433,6 +433,20 @@ declare class InvoError extends Error {
|
|
|
433
433
|
get isTaxPlaceUnavailable(): boolean;
|
|
434
434
|
/** On `TAX_PLACE_UNAVAILABLE`: the total without tax (`untaxed_total_usd`), decimal string. */
|
|
435
435
|
get untaxedTotalUsd(): string | undefined;
|
|
436
|
+
/**
|
|
437
|
+
* Additive (3.38.0). True when a Merchant of Record card sale was refused because the buyer is in
|
|
438
|
+
* a country where INVO does not yet sell as Merchant of Record (`SALE_NOT_AVAILABLE_IN_COUNTRY`,
|
|
439
|
+
* 409; today the EU member states until January 1, 2027). NOTHING WAS CHARGED. The body carries
|
|
440
|
+
* `retryable: false`: do not retry, and do not ask for another card (the refusal follows where
|
|
441
|
+
* the buyer is). Show the message (`err.message`), for example "Purchases aren't available in
|
|
442
|
+
* your country yet. Nothing was charged." Returned by the quote, the purchase, hosted checkout
|
|
443
|
+
* and Platform Commerce card purchases. Branch on this, never on a country list.
|
|
444
|
+
* See https://docs.invo.network/docs/merchant-of-record-tax#sale-not-available
|
|
445
|
+
*/
|
|
446
|
+
get isSaleNotAvailableInCountry(): boolean;
|
|
447
|
+
/** On `SALE_NOT_AVAILABLE_IN_COUNTRY`: the buyer's country, ISO 3166-1 alpha-2 (`country`), or
|
|
448
|
+
* `undefined` when INVO did not know it. */
|
|
449
|
+
get unavailableCountry(): string | undefined;
|
|
436
450
|
/**
|
|
437
451
|
* True if a Platform Commerce refund targeted an order that was already refunded
|
|
438
452
|
* (409). Idempotent outcome — the original refund did happen, so treat this as
|
|
@@ -1524,6 +1538,29 @@ interface PurchaseResult {
|
|
|
1524
1538
|
* `receiptNumber` is.
|
|
1525
1539
|
*/
|
|
1526
1540
|
receiptUrl?: string;
|
|
1541
|
+
/**
|
|
1542
|
+
* Additive (3.38.0), Merchant of Record only, and ONLY on a sale whose price INCLUDES the tax
|
|
1543
|
+
* (outside the US): `true`. `chargeTotalUsd` is then the listed price the buyer paid, with the
|
|
1544
|
+
* tax inside it. `undefined` on every other purchase, which carries none of the tax fields
|
|
1545
|
+
* below. See https://docs.invo.network/docs/merchant-of-record-tax
|
|
1546
|
+
*/
|
|
1547
|
+
taxIncluded?: boolean;
|
|
1548
|
+
/** Additive (3.38.0), tax-inclusive sales only: the tax inside the price (what INVO remits),
|
|
1549
|
+
* for example `"1.67"` on $10.00 at 20%. Equal to {@link taxIncludedUsd}. */
|
|
1550
|
+
taxUsd?: string;
|
|
1551
|
+
/** Additive (3.38.0), tax-inclusive sales only: the tax inside the price. */
|
|
1552
|
+
taxIncludedUsd?: string;
|
|
1553
|
+
/** Additive (3.38.0), tax-inclusive sales only: `"inclusive"`. */
|
|
1554
|
+
taxPriceDisplay?: TaxPriceDisplay;
|
|
1555
|
+
/** Additive (3.38.0), tax-inclusive sales only: where the tax is owed, for example `"GB"`. */
|
|
1556
|
+
taxJurisdiction?: string | null;
|
|
1557
|
+
/** Additive (3.38.0), tax-inclusive sales only: the rate, a decimal string such as `"20"`
|
|
1558
|
+
* (compare as a number). */
|
|
1559
|
+
taxRatePct?: string | null;
|
|
1560
|
+
/** Additive (3.38.0), tax-inclusive sales only: `"VAT"`, `"GST"` or `"tax"`. */
|
|
1561
|
+
taxLabel?: string;
|
|
1562
|
+
/** Additive (3.38.0), tax-inclusive sales only: `"Includes VAT 20% ($1.67)"`, ready to show. */
|
|
1563
|
+
taxLine?: string;
|
|
1527
1564
|
raw: Record<string, unknown>;
|
|
1528
1565
|
}
|
|
1529
1566
|
/**
|
|
@@ -1593,8 +1630,35 @@ interface CurrencyPurchaseQuoteBreakdown {
|
|
|
1593
1630
|
totalUsd: string;
|
|
1594
1631
|
coins: string;
|
|
1595
1632
|
currencyName: string;
|
|
1633
|
+
/**
|
|
1634
|
+
* Additive (3.38.0), Merchant of Record only, and ONLY on a sale whose price INCLUDES the tax
|
|
1635
|
+
* (a registered place outside the US): `true`. The tax is then INSIDE {@link subtotalUsd} (the
|
|
1636
|
+
* listed price), nothing is added on top, and `totalUsd = subtotalUsd + processingFeeUsd`.
|
|
1637
|
+
* Never add `taxUsd` or `taxIncludedUsd` to the price: show `totalUsd`, then {@link taxLine}
|
|
1638
|
+
* beneath it. `undefined` on every other quote (Open, US tax added on top, a place whose
|
|
1639
|
+
* registration is pending, storefront rails). See https://docs.invo.network/docs/merchant-of-record-tax
|
|
1640
|
+
*/
|
|
1641
|
+
taxIncluded?: boolean;
|
|
1642
|
+
/** Additive (3.38.0), tax-inclusive sales only: the tax inside the price, for example `"1.67"` on
|
|
1643
|
+
* $10.00 at 20%. What INVO pays to the tax authority. `taxUsd` carries the same figure. */
|
|
1644
|
+
taxIncludedUsd?: string;
|
|
1645
|
+
/** Additive (3.38.0), tax-inclusive sales only: the tax ADDED on top, `"0.00"`. */
|
|
1646
|
+
taxAddedUsd?: string;
|
|
1647
|
+
/** Additive (3.38.0), tax-inclusive sales only: `"VAT"`, `"GST"` or `"tax"`. */
|
|
1648
|
+
taxLabel?: string;
|
|
1649
|
+
/** Additive (3.38.0), tax-inclusive sales only: the sentence to show the buyer, for example
|
|
1650
|
+
* `"Includes VAT 20% ($1.67)"`. */
|
|
1651
|
+
taxLine?: string;
|
|
1652
|
+
/** Additive (3.38.0), tax-inclusive sales only: `"inclusive"`. */
|
|
1653
|
+
taxPriceDisplay?: TaxPriceDisplay;
|
|
1596
1654
|
raw: Record<string, unknown>;
|
|
1597
1655
|
}
|
|
1656
|
+
/**
|
|
1657
|
+
* How the tax sits in the price on a Merchant of Record sale: `"inclusive"` (inside the listed
|
|
1658
|
+
* price, outside the US). Widened so a value a later backend adds still compiles; treat an
|
|
1659
|
+
* unknown value as informational.
|
|
1660
|
+
*/
|
|
1661
|
+
type TaxPriceDisplay = "inclusive" | "exclusive" | (string & {});
|
|
1598
1662
|
/**
|
|
1599
1663
|
* What an UNACKNOWLEDGED purchase of the same amount would do. On INVO's card rail the buyer
|
|
1600
1664
|
* pays no card fee either way, so this matches the acknowledged outcome apart from any tax.
|
|
@@ -4003,4 +4067,4 @@ interface RewardsPageLink {
|
|
|
4003
4067
|
raw: Record<string, unknown>;
|
|
4004
4068
|
}
|
|
4005
4069
|
|
|
4006
|
-
export { type
|
|
4070
|
+
export { type TaxPriceDisplay as $, type ApproveResult as A, type BalanceResult as B, type CheckoutClientConfig as C, type DestinationGame as D, type EnrollmentBeginResult as E, type InvoHooks as F, type InvoRequestInfo as G, Http as H, InvoError as I, type InvoResponseInfo as J, type LoyaltyCard as K, type LinkDeviceResult as L, type MountCheckoutOptions as M, type LoyaltyCardReward as N, type LoyaltyCardStep as O, type PendingCollectItem as P, type LoyaltyRewardState as Q, type RedeemRewardResult as R, type LoyaltyStepProgress as S, type LoyaltyStepState as T, type LoyaltyVaultEntry as U, type PhoneChangeApproval as V, type WaitForPurchaseInput as W, type PhoneChangeDeviceSignal as X, type PurchaseRefusalReason as Y, type Rail as Z, type VerificationMethod as _, type PurchaseStatusResult as a, type SteamFinalizeResult as a$, type AuthHeader as a0, type ApplePurchaseResult as a1, type PlatformPurchaseInput as a2, type PlatformPurchaseResult as a3, type PlatformApprovalResult as a4, type PlatformOrderStatusResult as a5, type PlatformPurchaseHistoryQuery as a6, type PlatformPurchaseHistoryResult as a7, type PlatformRefundInput as a8, type PlatformRefundResult as a9, type SandboxForceAuthChallengeOptions as aA, type ServerConfig as aB, type MintPlayerTokenInput as aC, type PlayerToken as aD, type RegisterPlayerInput as aE, type RegisterPlayerResult as aF, type UpdatePlayerPhoneInput as aG, type UpdatePlayerPhoneResult as aH, type RequestPhoneChangeInput as aI, type RequestPhoneChangeResult as aJ, type PhoneChangeRequest as aK, type InitiateSendInput as aL, type InitiateResult as aM, type InitiateTransferInput as aN, type CreateCheckoutInput as aO, type CreateCheckoutResult as aP, type PurchaseInput as aQ, type PurchaseResult as aR, type CurrencyPurchaseQuoteInput as aS, type CurrencyPurchaseQuote as aT, type ConfirmPaymentResult as aU, type OrderDetailsResult as aV, type SteamPacksQuery as aW, type SteamPacksResult as aX, type SteamInitPurchaseInput as aY, type SteamInitPurchaseResult as aZ, type SteamFinalizeInput as a_, type CreateSubscriptionInput as aa, type SubscriptionResult as ab, type GetSubscriptionOptions as ac, type GetSubscriptionResult as ad, type ListSubscriptionsOptions as ae, type SubscriptionListResult as af, type CancelSubscriptionOptions as ag, type CancelResult as ah, type ChangeAmountResult as ai, type SetPaymentMethodInput as aj, type SetPaymentMethodResult as ak, type RefundSubscriptionInput as al, type RefundResult as am, type SteamSubscriptionInitInput as an, type SteamInitResult as ao, type SteamFinalizeSubscriptionResult as ap, type CardSetupSessionInput as aq, type CardSetupSessionResult as ar, type CardSetupInput as as, type CardSetupResult as at, type CardSetupConfirmInput as au, type CardSetupConfirmResult as av, type PlayerCardsResult as aw, type SandboxClockResult as ax, type SandboxFailureOutcome as ay, type SandboxForceFailureOptions as az, type PurchaseCredited as b, type PlayerActivityType as b$, type AppleProductsResult as b0, type VerifyApplePurchaseInput as b1, type PurchaseItemInput as b2, type PurchaseItemResult as b3, type ItemHistoryQuery as b4, type ItemHistoryResult as b5, type ItemOrderQuery as b6, type PlayerActivityQuery as b7, type PlayerActivityResult as b8, type PlayerActivityEntry as b9, type CompleteDeviceApprovalInput as bA, type CompleteDeviceApprovalResult as bB, type AppleEnvironment as bC, type AppleProduct as bD, type ApplePurchaseStatus as bE, type AppleUnavailableReason as bF, type CardSetupStatus as bG, type CheckoutWarning as bH, type CurrencyBalance as bI, type CurrencyPurchaseQuoteBreakdown as bJ, type DeviceApprovalChannel as bK, type DeviceApprovalEnrollment as bL, type DeviceApprovalFlow as bM, type DeviceApprovalPollStatus as bN, type DeviceEnrollmentDecision as bO, type DeviceEnrollmentRespond as bP, type ExpiryReason as bQ, type FeeTakenFrom as bR, type FirstCharge as bS, type FirstChargeStatus as bT, type FundingSource as bU, type InboundPendingItem as bV, type LinkedIdentityEmail as bW, type MinPurchaseWarning as bX, type PhoneChangeConfirmation as bY, type PhoneChangeRequestStatus as bZ, type PlatformPurchaseStatus as b_, type PlayerBalanceQuery as ba, type PlayerBalanceResult as bb, type InboundPendingQuery as bc, type InboundPendingResult as bd, type LinkedIdentitiesQuery as be, type LinkedIdentitiesResult as bf, type SmsVerifyResult as bg, type ClaimTransferInput as bh, type ClaimResult as bi, type ClaimCurrencyInput as bj, type TransactionStatusResult as bk, type GuardianApprovalStatusResult as bl, type ServerDestinationsQuery as bm, type PhoneShareContact as bn, type PhoneShareInitiateResult as bo, type PhoneShareApproveInput as bp, type PhoneShareApproveResult as bq, type PhoneShareStatusResult as br, type BeginDeviceApprovalInput as bs, type DeviceApprovalGrant as bt, type PollDeviceApprovalInput as bu, type DeviceApprovalPollResult as bv, type ConfirmDeviceEnrollmentInput as bw, type ConfirmDeviceEnrollmentResult as bx, type ApproveWithDeviceCodeInput as by, type DeviceApprovalSettleResult as bz, type PurchaseExpired as c, type RefundInitiation as c0, type RefundPendingApproval as c1, type RefundProcessingFeeBasis as c2, type RefundReceipt as c3, type RefundRevenueShareAttribution as c4, type RefundWarning as c5, type SandboxClockState as c6, type SavedCard as c7, type SteamPack as c8, type SteamUnavailableReason as c9, type SteamUserSession as ca, type Subscription as cb, type SubscriptionBaseInput as cc, type SubscriptionConsent as cd, type SubscriptionConsentInput as ce, type SubscriptionFundingRail as cf, type SubscriptionInterval as cg, type SubscriptionRevenueShare as ch, type SubscriptionRevenueShareInput as ci, type SubscriptionStatus as cj, type UnacknowledgedPurchaseOutcome as ck, isRefundPendingApproval as cl, type PurchaseRefunded as d, type PurchaseRefused as e, type PurchaseStatusInput as f, type CallOptions as g, type CheckoutMountHandle as h, type ClientConfig as i, type ConfirmReceiptResult as j, type PhoneChangeApprovalsResult as k, type ApprovePhoneChangeInput as l, type ApprovePhoneChangeResult as m, type PendingCollectResult as n, type DestinationsQuery as o, type DestinationsResult as p, type LoyaltyCardsResult as q, type LoyaltyVaultResult as r, type RewardsPageLink as s, type EnrollmentVerifyResult as t, type RecoveryBeginResult as u, type RecoveryCompleteResult as v, type BalanceRow as w, type CheckoutPurchaseStatus as x, type ClaimDelivery as y, type InvoErrorInfo as z };
|
|
@@ -433,6 +433,20 @@ declare class InvoError extends Error {
|
|
|
433
433
|
get isTaxPlaceUnavailable(): boolean;
|
|
434
434
|
/** On `TAX_PLACE_UNAVAILABLE`: the total without tax (`untaxed_total_usd`), decimal string. */
|
|
435
435
|
get untaxedTotalUsd(): string | undefined;
|
|
436
|
+
/**
|
|
437
|
+
* Additive (3.38.0). True when a Merchant of Record card sale was refused because the buyer is in
|
|
438
|
+
* a country where INVO does not yet sell as Merchant of Record (`SALE_NOT_AVAILABLE_IN_COUNTRY`,
|
|
439
|
+
* 409; today the EU member states until January 1, 2027). NOTHING WAS CHARGED. The body carries
|
|
440
|
+
* `retryable: false`: do not retry, and do not ask for another card (the refusal follows where
|
|
441
|
+
* the buyer is). Show the message (`err.message`), for example "Purchases aren't available in
|
|
442
|
+
* your country yet. Nothing was charged." Returned by the quote, the purchase, hosted checkout
|
|
443
|
+
* and Platform Commerce card purchases. Branch on this, never on a country list.
|
|
444
|
+
* See https://docs.invo.network/docs/merchant-of-record-tax#sale-not-available
|
|
445
|
+
*/
|
|
446
|
+
get isSaleNotAvailableInCountry(): boolean;
|
|
447
|
+
/** On `SALE_NOT_AVAILABLE_IN_COUNTRY`: the buyer's country, ISO 3166-1 alpha-2 (`country`), or
|
|
448
|
+
* `undefined` when INVO did not know it. */
|
|
449
|
+
get unavailableCountry(): string | undefined;
|
|
436
450
|
/**
|
|
437
451
|
* True if a Platform Commerce refund targeted an order that was already refunded
|
|
438
452
|
* (409). Idempotent outcome — the original refund did happen, so treat this as
|
|
@@ -1524,6 +1538,29 @@ interface PurchaseResult {
|
|
|
1524
1538
|
* `receiptNumber` is.
|
|
1525
1539
|
*/
|
|
1526
1540
|
receiptUrl?: string;
|
|
1541
|
+
/**
|
|
1542
|
+
* Additive (3.38.0), Merchant of Record only, and ONLY on a sale whose price INCLUDES the tax
|
|
1543
|
+
* (outside the US): `true`. `chargeTotalUsd` is then the listed price the buyer paid, with the
|
|
1544
|
+
* tax inside it. `undefined` on every other purchase, which carries none of the tax fields
|
|
1545
|
+
* below. See https://docs.invo.network/docs/merchant-of-record-tax
|
|
1546
|
+
*/
|
|
1547
|
+
taxIncluded?: boolean;
|
|
1548
|
+
/** Additive (3.38.0), tax-inclusive sales only: the tax inside the price (what INVO remits),
|
|
1549
|
+
* for example `"1.67"` on $10.00 at 20%. Equal to {@link taxIncludedUsd}. */
|
|
1550
|
+
taxUsd?: string;
|
|
1551
|
+
/** Additive (3.38.0), tax-inclusive sales only: the tax inside the price. */
|
|
1552
|
+
taxIncludedUsd?: string;
|
|
1553
|
+
/** Additive (3.38.0), tax-inclusive sales only: `"inclusive"`. */
|
|
1554
|
+
taxPriceDisplay?: TaxPriceDisplay;
|
|
1555
|
+
/** Additive (3.38.0), tax-inclusive sales only: where the tax is owed, for example `"GB"`. */
|
|
1556
|
+
taxJurisdiction?: string | null;
|
|
1557
|
+
/** Additive (3.38.0), tax-inclusive sales only: the rate, a decimal string such as `"20"`
|
|
1558
|
+
* (compare as a number). */
|
|
1559
|
+
taxRatePct?: string | null;
|
|
1560
|
+
/** Additive (3.38.0), tax-inclusive sales only: `"VAT"`, `"GST"` or `"tax"`. */
|
|
1561
|
+
taxLabel?: string;
|
|
1562
|
+
/** Additive (3.38.0), tax-inclusive sales only: `"Includes VAT 20% ($1.67)"`, ready to show. */
|
|
1563
|
+
taxLine?: string;
|
|
1527
1564
|
raw: Record<string, unknown>;
|
|
1528
1565
|
}
|
|
1529
1566
|
/**
|
|
@@ -1593,8 +1630,35 @@ interface CurrencyPurchaseQuoteBreakdown {
|
|
|
1593
1630
|
totalUsd: string;
|
|
1594
1631
|
coins: string;
|
|
1595
1632
|
currencyName: string;
|
|
1633
|
+
/**
|
|
1634
|
+
* Additive (3.38.0), Merchant of Record only, and ONLY on a sale whose price INCLUDES the tax
|
|
1635
|
+
* (a registered place outside the US): `true`. The tax is then INSIDE {@link subtotalUsd} (the
|
|
1636
|
+
* listed price), nothing is added on top, and `totalUsd = subtotalUsd + processingFeeUsd`.
|
|
1637
|
+
* Never add `taxUsd` or `taxIncludedUsd` to the price: show `totalUsd`, then {@link taxLine}
|
|
1638
|
+
* beneath it. `undefined` on every other quote (Open, US tax added on top, a place whose
|
|
1639
|
+
* registration is pending, storefront rails). See https://docs.invo.network/docs/merchant-of-record-tax
|
|
1640
|
+
*/
|
|
1641
|
+
taxIncluded?: boolean;
|
|
1642
|
+
/** Additive (3.38.0), tax-inclusive sales only: the tax inside the price, for example `"1.67"` on
|
|
1643
|
+
* $10.00 at 20%. What INVO pays to the tax authority. `taxUsd` carries the same figure. */
|
|
1644
|
+
taxIncludedUsd?: string;
|
|
1645
|
+
/** Additive (3.38.0), tax-inclusive sales only: the tax ADDED on top, `"0.00"`. */
|
|
1646
|
+
taxAddedUsd?: string;
|
|
1647
|
+
/** Additive (3.38.0), tax-inclusive sales only: `"VAT"`, `"GST"` or `"tax"`. */
|
|
1648
|
+
taxLabel?: string;
|
|
1649
|
+
/** Additive (3.38.0), tax-inclusive sales only: the sentence to show the buyer, for example
|
|
1650
|
+
* `"Includes VAT 20% ($1.67)"`. */
|
|
1651
|
+
taxLine?: string;
|
|
1652
|
+
/** Additive (3.38.0), tax-inclusive sales only: `"inclusive"`. */
|
|
1653
|
+
taxPriceDisplay?: TaxPriceDisplay;
|
|
1596
1654
|
raw: Record<string, unknown>;
|
|
1597
1655
|
}
|
|
1656
|
+
/**
|
|
1657
|
+
* How the tax sits in the price on a Merchant of Record sale: `"inclusive"` (inside the listed
|
|
1658
|
+
* price, outside the US). Widened so a value a later backend adds still compiles; treat an
|
|
1659
|
+
* unknown value as informational.
|
|
1660
|
+
*/
|
|
1661
|
+
type TaxPriceDisplay = "inclusive" | "exclusive" | (string & {});
|
|
1598
1662
|
/**
|
|
1599
1663
|
* What an UNACKNOWLEDGED purchase of the same amount would do. On INVO's card rail the buyer
|
|
1600
1664
|
* pays no card fee either way, so this matches the acknowledged outcome apart from any tax.
|
|
@@ -4003,4 +4067,4 @@ interface RewardsPageLink {
|
|
|
4003
4067
|
raw: Record<string, unknown>;
|
|
4004
4068
|
}
|
|
4005
4069
|
|
|
4006
|
-
export { type
|
|
4070
|
+
export { type TaxPriceDisplay as $, type ApproveResult as A, type BalanceResult as B, type CheckoutClientConfig as C, type DestinationGame as D, type EnrollmentBeginResult as E, type InvoHooks as F, type InvoRequestInfo as G, Http as H, InvoError as I, type InvoResponseInfo as J, type LoyaltyCard as K, type LinkDeviceResult as L, type MountCheckoutOptions as M, type LoyaltyCardReward as N, type LoyaltyCardStep as O, type PendingCollectItem as P, type LoyaltyRewardState as Q, type RedeemRewardResult as R, type LoyaltyStepProgress as S, type LoyaltyStepState as T, type LoyaltyVaultEntry as U, type PhoneChangeApproval as V, type WaitForPurchaseInput as W, type PhoneChangeDeviceSignal as X, type PurchaseRefusalReason as Y, type Rail as Z, type VerificationMethod as _, type PurchaseStatusResult as a, type SteamFinalizeResult as a$, type AuthHeader as a0, type ApplePurchaseResult as a1, type PlatformPurchaseInput as a2, type PlatformPurchaseResult as a3, type PlatformApprovalResult as a4, type PlatformOrderStatusResult as a5, type PlatformPurchaseHistoryQuery as a6, type PlatformPurchaseHistoryResult as a7, type PlatformRefundInput as a8, type PlatformRefundResult as a9, type SandboxForceAuthChallengeOptions as aA, type ServerConfig as aB, type MintPlayerTokenInput as aC, type PlayerToken as aD, type RegisterPlayerInput as aE, type RegisterPlayerResult as aF, type UpdatePlayerPhoneInput as aG, type UpdatePlayerPhoneResult as aH, type RequestPhoneChangeInput as aI, type RequestPhoneChangeResult as aJ, type PhoneChangeRequest as aK, type InitiateSendInput as aL, type InitiateResult as aM, type InitiateTransferInput as aN, type CreateCheckoutInput as aO, type CreateCheckoutResult as aP, type PurchaseInput as aQ, type PurchaseResult as aR, type CurrencyPurchaseQuoteInput as aS, type CurrencyPurchaseQuote as aT, type ConfirmPaymentResult as aU, type OrderDetailsResult as aV, type SteamPacksQuery as aW, type SteamPacksResult as aX, type SteamInitPurchaseInput as aY, type SteamInitPurchaseResult as aZ, type SteamFinalizeInput as a_, type CreateSubscriptionInput as aa, type SubscriptionResult as ab, type GetSubscriptionOptions as ac, type GetSubscriptionResult as ad, type ListSubscriptionsOptions as ae, type SubscriptionListResult as af, type CancelSubscriptionOptions as ag, type CancelResult as ah, type ChangeAmountResult as ai, type SetPaymentMethodInput as aj, type SetPaymentMethodResult as ak, type RefundSubscriptionInput as al, type RefundResult as am, type SteamSubscriptionInitInput as an, type SteamInitResult as ao, type SteamFinalizeSubscriptionResult as ap, type CardSetupSessionInput as aq, type CardSetupSessionResult as ar, type CardSetupInput as as, type CardSetupResult as at, type CardSetupConfirmInput as au, type CardSetupConfirmResult as av, type PlayerCardsResult as aw, type SandboxClockResult as ax, type SandboxFailureOutcome as ay, type SandboxForceFailureOptions as az, type PurchaseCredited as b, type PlayerActivityType as b$, type AppleProductsResult as b0, type VerifyApplePurchaseInput as b1, type PurchaseItemInput as b2, type PurchaseItemResult as b3, type ItemHistoryQuery as b4, type ItemHistoryResult as b5, type ItemOrderQuery as b6, type PlayerActivityQuery as b7, type PlayerActivityResult as b8, type PlayerActivityEntry as b9, type CompleteDeviceApprovalInput as bA, type CompleteDeviceApprovalResult as bB, type AppleEnvironment as bC, type AppleProduct as bD, type ApplePurchaseStatus as bE, type AppleUnavailableReason as bF, type CardSetupStatus as bG, type CheckoutWarning as bH, type CurrencyBalance as bI, type CurrencyPurchaseQuoteBreakdown as bJ, type DeviceApprovalChannel as bK, type DeviceApprovalEnrollment as bL, type DeviceApprovalFlow as bM, type DeviceApprovalPollStatus as bN, type DeviceEnrollmentDecision as bO, type DeviceEnrollmentRespond as bP, type ExpiryReason as bQ, type FeeTakenFrom as bR, type FirstCharge as bS, type FirstChargeStatus as bT, type FundingSource as bU, type InboundPendingItem as bV, type LinkedIdentityEmail as bW, type MinPurchaseWarning as bX, type PhoneChangeConfirmation as bY, type PhoneChangeRequestStatus as bZ, type PlatformPurchaseStatus as b_, type PlayerBalanceQuery as ba, type PlayerBalanceResult as bb, type InboundPendingQuery as bc, type InboundPendingResult as bd, type LinkedIdentitiesQuery as be, type LinkedIdentitiesResult as bf, type SmsVerifyResult as bg, type ClaimTransferInput as bh, type ClaimResult as bi, type ClaimCurrencyInput as bj, type TransactionStatusResult as bk, type GuardianApprovalStatusResult as bl, type ServerDestinationsQuery as bm, type PhoneShareContact as bn, type PhoneShareInitiateResult as bo, type PhoneShareApproveInput as bp, type PhoneShareApproveResult as bq, type PhoneShareStatusResult as br, type BeginDeviceApprovalInput as bs, type DeviceApprovalGrant as bt, type PollDeviceApprovalInput as bu, type DeviceApprovalPollResult as bv, type ConfirmDeviceEnrollmentInput as bw, type ConfirmDeviceEnrollmentResult as bx, type ApproveWithDeviceCodeInput as by, type DeviceApprovalSettleResult as bz, type PurchaseExpired as c, type RefundInitiation as c0, type RefundPendingApproval as c1, type RefundProcessingFeeBasis as c2, type RefundReceipt as c3, type RefundRevenueShareAttribution as c4, type RefundWarning as c5, type SandboxClockState as c6, type SavedCard as c7, type SteamPack as c8, type SteamUnavailableReason as c9, type SteamUserSession as ca, type Subscription as cb, type SubscriptionBaseInput as cc, type SubscriptionConsent as cd, type SubscriptionConsentInput as ce, type SubscriptionFundingRail as cf, type SubscriptionInterval as cg, type SubscriptionRevenueShare as ch, type SubscriptionRevenueShareInput as ci, type SubscriptionStatus as cj, type UnacknowledgedPurchaseOutcome as ck, isRefundPendingApproval as cl, type PurchaseRefunded as d, type PurchaseRefused as e, type PurchaseStatusInput as f, type CallOptions as g, type CheckoutMountHandle as h, type ClientConfig as i, type ConfirmReceiptResult as j, type PhoneChangeApprovalsResult as k, type ApprovePhoneChangeInput as l, type ApprovePhoneChangeResult as m, type PendingCollectResult as n, type DestinationsQuery as o, type DestinationsResult as p, type LoyaltyCardsResult as q, type LoyaltyVaultResult as r, type RewardsPageLink as s, type EnrollmentVerifyResult as t, type RecoveryBeginResult as u, type RecoveryCompleteResult as v, type BalanceRow as w, type CheckoutPurchaseStatus as x, type ClaimDelivery as y, type InvoErrorInfo as z };
|
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
# Tax on Merchant of Record sales
|
|
2
|
+
|
|
3
|
+
On the Merchant of Record tier INVO is the seller on your card sales, so INVO handles the consumption tax on them: sales tax in the United States, and VAT or GST in other countries. This guide explains what INVO does, what the buyer sees, who bears the tax, and every field and error `@invonetwork/web-sdk` types for it (3.38.0 and later).
|
|
4
|
+
|
|
5
|
+
The full public write-up is at https://docs.invo.network/docs/merchant-of-record-tax.
|
|
6
|
+
|
|
7
|
+
## When this applies
|
|
8
|
+
|
|
9
|
+
Only when both are true:
|
|
10
|
+
|
|
11
|
+
- your developer account is on the **Merchant of Record** tier; and
|
|
12
|
+
- the buyer pays **by card on INVO's checkout**: a card purchase of coins (`purchaseCurrency()` or hosted checkout), a Platform Commerce card sale, or a subscription card charge.
|
|
13
|
+
|
|
14
|
+
Not affected: the Open tier (you are the seller and handle your own tax; INVO adds none), purchases through a third-party storefront or payment rail, items bought with coins, Platform Commerce purchases paid from a balance, and transfers and sends. Their results and payloads are unchanged.
|
|
15
|
+
|
|
16
|
+
## What INVO does as the seller
|
|
17
|
+
|
|
18
|
+
- Works out where the buyer is, from the card, and from the `country` / `subdivision` you pass when the card cannot tell it.
|
|
19
|
+
- Decides the tax for that place, at that place's rate.
|
|
20
|
+
- Shows the buyer the right price: in the United States tax is added on top; everywhere else your price includes the tax.
|
|
21
|
+
- Issues the receipt to the buyer, with INVO's registration number.
|
|
22
|
+
- Files the returns and pays the tax to each tax authority. You do not register, file or pay consumption tax for these sales.
|
|
23
|
+
- Returns the tax on a refund, and gives back to you any tax that was taken from your share.
|
|
24
|
+
|
|
25
|
+
Nothing in your integration has to change. Every field below is additive.
|
|
26
|
+
|
|
27
|
+
## Tax on top, or tax included
|
|
28
|
+
|
|
29
|
+
| | United States | Outside the United States |
|
|
30
|
+
|---|---|---|
|
|
31
|
+
| How tax is priced | added on top of your price | included in your price |
|
|
32
|
+
| Buyer pays for a $10.00 price | $10.00 plus tax, for example $10.73 | $10.00 |
|
|
33
|
+
| Buyer is shown | a tax line, then the total | the price, then "Includes VAT 20% ($1.67)" |
|
|
34
|
+
| Who bears the tax | the buyer | you: it comes out of the price |
|
|
35
|
+
| INVO's fee is worked out on | your price | the net price (price less the tax inside it) |
|
|
36
|
+
|
|
37
|
+
The word follows the country: VAT in the United Kingdom and the EU, GST in India, Australia, New Zealand, Singapore and Canada, and "tax" elsewhere. The sentence comes ready to show as `taxLine`.
|
|
38
|
+
|
|
39
|
+
## Worked example: $10.00 to a buyer in the United Kingdom (VAT 20%)
|
|
40
|
+
|
|
41
|
+
| Line | Amount | How |
|
|
42
|
+
|---|---|---|
|
|
43
|
+
| Buyer pays | $10.00 | your price; nothing is added |
|
|
44
|
+
| VAT inside the price | $1.67 | 10.00 x 20 / 120; INVO pays it to the tax authority |
|
|
45
|
+
| Net price | $8.33 | 10.00 - 1.67 |
|
|
46
|
+
| INVO's fee (5.0% + $0.15) | $0.57 | on the net: 0.4165 + 0.15, to the nearest cent |
|
|
47
|
+
| **Your share** | **$7.76** | 8.33 - 0.57 |
|
|
48
|
+
|
|
49
|
+
On a card issued outside the US the 1.5% international card fee also applies, on the same net: $0.12, so your share is $7.64.
|
|
50
|
+
|
|
51
|
+
- **Coins:** the player gets every coin you listed. The card fee and the VAT are each charged against your earnings as their own row.
|
|
52
|
+
- **Platform Commerce:** `fee_breakdown` is worked out on the net (`total_paid` 8.33, `platform_fee` 0.57, `developer_revenue` 7.76) and carries `tax_set_aside_usd` 1.67.
|
|
53
|
+
- **Subscriptions:** INVO's fee in `split` is worked out on the net, and the VAT is reported to you as its own row.
|
|
54
|
+
|
|
55
|
+
Read the figures INVO returns rather than recomputing them.
|
|
56
|
+
|
|
57
|
+
## While INVO's registration for a place is pending
|
|
58
|
+
|
|
59
|
+
In some countries INVO already owes tax while its registration is still being processed. INVO keeps selling there: the buyer pays your price and sees **no tax line**, but the tax is still **set aside from the price** exactly as above (you bear it; the fee is on the net), and INVO pays it on its first return. When the registration is issued, sales there switch to the visible "Includes VAT" display. The money is the same.
|
|
60
|
+
|
|
61
|
+
During this period the buyer-facing fields read as no tax (`taxUsd` `"0.00"`, `taxTreatment` `"not_registered"`, `taxIncluded` undefined). What was set aside from you shows on your side only: `fee_breakdown.tax_set_aside_usd` on `platform_commerce.purchased`, and the tax rows in your console.
|
|
62
|
+
|
|
63
|
+
## Showing the quote
|
|
64
|
+
|
|
65
|
+
```ts
|
|
66
|
+
const q = await invo.quoteCurrencyPurchase({ playerEmail, usdAmount: "10.00", country: "GB" });
|
|
67
|
+
|
|
68
|
+
showTotal(q.totalUsd); // "10.00": always the figure to show and acknowledge
|
|
69
|
+
if (q.breakdown.taxIncluded) {
|
|
70
|
+
showSubLine(q.breakdown.taxLine!); // "Includes VAT 20% ($1.67)"; no separate tax line
|
|
71
|
+
} else if (Number(q.breakdown.taxUsd) > 0) {
|
|
72
|
+
showTaxLine(q.breakdown.taxUsd); // US: tax added on top
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
const purchase = await invo.purchaseCurrency({
|
|
76
|
+
playerEmail, usdAmount: "10.00", acknowledgedTotalUsd: q.totalUsd,
|
|
77
|
+
country: "GB", purchaseReference: orderRef,
|
|
78
|
+
});
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
When `taxIncluded` is `true`, the tax is inside `subtotalUsd` and `totalUsd = subtotalUsd + processingFeeUsd`. **Never add `taxUsd` or `taxIncludedUsd` to the price.**
|
|
82
|
+
|
|
83
|
+
### New fields on `CurrencyPurchaseQuoteBreakdown`
|
|
84
|
+
|
|
85
|
+
Present only on a tax-inclusive sale; `undefined` otherwise.
|
|
86
|
+
|
|
87
|
+
| Field | Type | Meaning |
|
|
88
|
+
|---|---|---|
|
|
89
|
+
| `taxIncluded` | `boolean` | `true`: the tax is inside the price |
|
|
90
|
+
| `taxIncludedUsd` | `string` | the tax inside the price, for example `"1.67"`; `taxUsd` carries the same figure |
|
|
91
|
+
| `taxAddedUsd` | `string` | the tax added on top: `"0.00"` |
|
|
92
|
+
| `taxLabel` | `string` | `"VAT"`, `"GST"` or `"tax"` |
|
|
93
|
+
| `taxLine` | `string` | `"Includes VAT 20% ($1.67)"`, ready to show |
|
|
94
|
+
| `taxPriceDisplay` | `TaxPriceDisplay` | `"inclusive"` |
|
|
95
|
+
|
|
96
|
+
### New fields on `PurchaseResult` (`purchaseCurrency()`)
|
|
97
|
+
|
|
98
|
+
Present only on a tax-inclusive sale: `taxIncluded`, `taxUsd`, `taxIncludedUsd`, `taxPriceDisplay`, `taxJurisdiction`, `taxRatePct` (a decimal string such as `"20"`; compare it as a number), `taxLabel`, `taxLine`. `chargeTotalUsd` stays what the card was charged (`"10.00"`).
|
|
99
|
+
|
|
100
|
+
`TaxPriceDisplay` is `"inclusive" | "exclusive" | (string & {})`: treat an unknown value as informational.
|
|
101
|
+
|
|
102
|
+
## `SALE_NOT_AVAILABLE_IN_COUNTRY`
|
|
103
|
+
|
|
104
|
+
In a few places INVO cannot yet sell to consumers as Merchant of Record (today, the member states of the European Union until January 1, 2027). A card sale to a buyer there is refused **before the card is charged** with HTTP 409:
|
|
105
|
+
|
|
106
|
+
```json
|
|
107
|
+
{
|
|
108
|
+
"error": "Purchases aren't available in your country yet. Nothing was charged.",
|
|
109
|
+
"code": "SALE_NOT_AVAILABLE_IN_COUNTRY",
|
|
110
|
+
"error_code": "SALE_NOT_AVAILABLE_IN_COUNTRY",
|
|
111
|
+
"retryable": false,
|
|
112
|
+
"country": "DE"
|
|
113
|
+
}
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
It comes from `quoteCurrencyPurchase()`, `purchaseCurrency()`, hosted checkout and Platform Commerce card purchases.
|
|
117
|
+
|
|
118
|
+
```ts
|
|
119
|
+
try {
|
|
120
|
+
await invo.purchaseCurrency({ /* ... */ });
|
|
121
|
+
} catch (err) {
|
|
122
|
+
if (err instanceof InvoError && err.isSaleNotAvailableInCountry) {
|
|
123
|
+
// Nothing was charged. Do not retry; do not ask for another card.
|
|
124
|
+
showMessage(err.message); // "Purchases aren't available in your country yet. ..."
|
|
125
|
+
console.log(err.unavailableCountry); // "DE", or undefined when INVO did not know it
|
|
126
|
+
return;
|
|
127
|
+
}
|
|
128
|
+
throw err;
|
|
129
|
+
}
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
Branch on the code, never on a country list: INVO may add or remove places. Where you already know the buyer is in such a country, hide the purchase button.
|
|
133
|
+
|
|
134
|
+
**Subscriptions:** a charge to a member in such a country is not made. You receive `subscription.payment_failed` with `outcome: "error"` and `failure_code: "SALE_NOT_AVAILABLE_IN_COUNTRY"`, and the usual failed-renewal path follows.
|
|
135
|
+
|
|
136
|
+
In the rare case the buyer's country is learned only after the card was charged, INVO refunds that sale.
|
|
137
|
+
|
|
138
|
+
## Webhooks
|
|
139
|
+
|
|
140
|
+
All keys are additive and appear only on a tax-inclusive sale unless noted.
|
|
141
|
+
|
|
142
|
+
| Event | Keys (types in `src/webhooks.ts`) |
|
|
143
|
+
|---|---|
|
|
144
|
+
| `purchase.completed` | `charge_total_usd` (what the card was charged), `subtotal_usd` (charge less tax: the net, `"8.33"`), `tax_usd` (`"1.67"`), `tax_jurisdiction`, `tax_rate_pct`, `tax_treatment` (all existing), plus `tax_price_display: "inclusive"` and `tax_included: true` |
|
|
145
|
+
| `purchase.refunded` | `tax_refunded_usd` (the tax inside the refunded price, returned so far), `tax_jurisdiction`, plus `tax_included`, `tax_price_display` |
|
|
146
|
+
| `platform_commerce.purchased` | `total_price_usd` `"10.00"`, `tax_usd` `"1.67"`, `item_price_usd` `"8.33"`, `tax_jurisdiction`, plus `tax_price_display`, `tax_included`, `tax_rate_pct`; `fee_breakdown.tax_set_aside_usd` `"1.67"` (also while a registration is pending) with `total_paid` the net |
|
|
147
|
+
| `platform_commerce.refunded` | `tax_refunded_usd` (the tax inside this refund), `tax_jurisdiction`, plus `tax_included`, `tax_price_display` |
|
|
148
|
+
| `subscription.renewed` | `funding.tax_usd` stays the tax added on top (`"0.00"`), `funding.card_charged_usd` is the price paid; plus `funding.tax_included_usd` `"1.67"`, `funding.tax_included`, `funding.tax_price_display`, `funding.tax_rate_pct` |
|
|
149
|
+
| `subscription.payment_failed` | `failure_code: "SALE_NOT_AVAILABLE_IN_COUNTRY"` (see above) |
|
|
150
|
+
|
|
151
|
+
## Refunds and chargebacks
|
|
152
|
+
|
|
153
|
+
- The buyer gets the tax back on whatever is refunded (in full, or in proportion on a partial refund).
|
|
154
|
+
- You get back the tax that was taken from you, in the same proportion: a positive row labelled "Tax set aside returned (VAT/GST) on refund" on coins and subscriptions, and inside the refund's reversal on Platform Commerce.
|
|
155
|
+
- The same on a lost chargeback, unless the chargeback guarantee covers it.
|
|
156
|
+
- INVO's card fee is not returned, as on every card refund.
|
|
157
|
+
|
|
158
|
+
## In your console
|
|
159
|
+
|
|
160
|
+
Tax taken from your share appears as its own rows:
|
|
161
|
+
|
|
162
|
+
| Row | Sign | `transaction_type` / `transaction_type_detail` |
|
|
163
|
+
|---|---|---|
|
|
164
|
+
| Tax set aside (VAT/GST) on card coin purchase | negative | `mor_tax_withheld` / `mor_tax_withheld` |
|
|
165
|
+
| Tax set aside (VAT/GST) on subscription payment | negative | `mor_tax_withheld` / `mor_tax_withheld` |
|
|
166
|
+
| Tax set aside returned (VAT/GST) on refund | positive | `mor_tax_withheld` / `mor_tax_returned` |
|
|
167
|
+
|
|
168
|
+
Revenue summaries add `tax_set_aside_usd` (the tax set aside in the period, net of refunds, positive), reported beside your revenue rather than netted into it. Reconcile what you earned with your share and these rows, not with the buyer-facing `tax_usd`.
|
|
169
|
+
|
|
170
|
+
## Checklist
|
|
171
|
+
|
|
172
|
+
- Show `totalUsd`; when `breakdown.taxIncluded` is `true`, show `breakdown.taxLine` under it and no separate tax line.
|
|
173
|
+
- Never add `taxUsd` or `taxIncludedUsd` to a tax-inclusive price.
|
|
174
|
+
- Handle `err.isSaleNotAvailableInCountry`: show the message, do not retry, do not ask for another card.
|
|
175
|
+
- Handle `failure_code: "SALE_NOT_AVAILABLE_IN_COUNTRY"` on `subscription.payment_failed`.
|
|
176
|
+
- Keep passing `country` (and `subdivision`) on quotes and purchases when you know it.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@invonetwork/web-sdk",
|
|
3
|
-
"version": "3.
|
|
3
|
+
"version": "3.38.0",
|
|
4
4
|
"description": "INVO Web SDK — currency purchase, passkey (WebAuthn) verification, loyalty, and a drop-in game economy layer (wallet, shop, hosted checkout) for partner web platforms and browser games.",
|
|
5
5
|
"license": "SEE LICENSE IN LICENSE",
|
|
6
6
|
"private": false,
|
|
@@ -22,6 +22,7 @@
|
|
|
22
22
|
"!dist/**/*.map",
|
|
23
23
|
"README.md",
|
|
24
24
|
"docs/apple-in-app-purchases.md",
|
|
25
|
+
"docs/merchant-of-record-tax.md",
|
|
25
26
|
"LICENSE",
|
|
26
27
|
"CHANGELOG.md"
|
|
27
28
|
],
|