@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.
@@ -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 AuthHeader 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 AppleProductsResult as a$, type ApplePurchaseResult as a0, type PlatformPurchaseInput as a1, type PlatformPurchaseResult as a2, type PlatformApprovalResult as a3, type PlatformOrderStatusResult as a4, type PlatformPurchaseHistoryQuery as a5, type PlatformPurchaseHistoryResult as a6, type PlatformRefundInput as a7, type PlatformRefundResult as a8, type CreateSubscriptionInput as a9, type ServerConfig as aA, type MintPlayerTokenInput as aB, type PlayerToken as aC, type RegisterPlayerInput as aD, type RegisterPlayerResult as aE, type UpdatePlayerPhoneInput as aF, type UpdatePlayerPhoneResult as aG, type RequestPhoneChangeInput as aH, type RequestPhoneChangeResult as aI, type PhoneChangeRequest as aJ, type InitiateSendInput as aK, type InitiateResult as aL, type InitiateTransferInput as aM, type CreateCheckoutInput as aN, type CreateCheckoutResult as aO, type PurchaseInput as aP, type PurchaseResult as aQ, type CurrencyPurchaseQuoteInput as aR, type CurrencyPurchaseQuote as aS, type ConfirmPaymentResult as aT, type OrderDetailsResult as aU, type SteamPacksQuery as aV, type SteamPacksResult as aW, type SteamInitPurchaseInput as aX, type SteamInitPurchaseResult as aY, type SteamFinalizeInput as aZ, type SteamFinalizeResult as a_, type SubscriptionResult as aa, type GetSubscriptionOptions as ab, type GetSubscriptionResult as ac, type ListSubscriptionsOptions as ad, type SubscriptionListResult as ae, type CancelSubscriptionOptions as af, type CancelResult as ag, type ChangeAmountResult as ah, type SetPaymentMethodInput as ai, type SetPaymentMethodResult as aj, type RefundSubscriptionInput as ak, type RefundResult as al, type SteamSubscriptionInitInput as am, type SteamInitResult as an, type SteamFinalizeSubscriptionResult as ao, type CardSetupSessionInput as ap, type CardSetupSessionResult as aq, type CardSetupInput as ar, type CardSetupResult as as, type CardSetupConfirmInput as at, type CardSetupConfirmResult as au, type PlayerCardsResult as av, type SandboxClockResult as aw, type SandboxFailureOutcome as ax, type SandboxForceFailureOptions as ay, type SandboxForceAuthChallengeOptions as az, type PurchaseCredited as b, type RefundInitiation as b$, type VerifyApplePurchaseInput as b0, type PurchaseItemInput as b1, type PurchaseItemResult as b2, type ItemHistoryQuery as b3, type ItemHistoryResult as b4, type ItemOrderQuery as b5, type PlayerActivityQuery as b6, type PlayerActivityResult as b7, type PlayerActivityEntry as b8, type PlayerBalanceQuery as b9, type CompleteDeviceApprovalResult as bA, type AppleEnvironment as bB, type AppleProduct as bC, type ApplePurchaseStatus as bD, type AppleUnavailableReason as bE, type CardSetupStatus as bF, type CheckoutWarning as bG, type CurrencyBalance as bH, type CurrencyPurchaseQuoteBreakdown as bI, type DeviceApprovalChannel as bJ, type DeviceApprovalEnrollment as bK, type DeviceApprovalFlow as bL, type DeviceApprovalPollStatus as bM, type DeviceEnrollmentDecision as bN, type DeviceEnrollmentRespond as bO, type ExpiryReason as bP, type FeeTakenFrom as bQ, type FirstCharge as bR, type FirstChargeStatus as bS, type FundingSource as bT, type InboundPendingItem as bU, type LinkedIdentityEmail as bV, type MinPurchaseWarning as bW, type PhoneChangeConfirmation as bX, type PhoneChangeRequestStatus as bY, type PlatformPurchaseStatus as bZ, type PlayerActivityType as b_, type PlayerBalanceResult as ba, type InboundPendingQuery as bb, type InboundPendingResult as bc, type LinkedIdentitiesQuery as bd, type LinkedIdentitiesResult as be, type SmsVerifyResult as bf, type ClaimTransferInput as bg, type ClaimResult as bh, type ClaimCurrencyInput as bi, type TransactionStatusResult as bj, type GuardianApprovalStatusResult as bk, type ServerDestinationsQuery as bl, type PhoneShareContact as bm, type PhoneShareInitiateResult as bn, type PhoneShareApproveInput as bo, type PhoneShareApproveResult as bp, type PhoneShareStatusResult as bq, type BeginDeviceApprovalInput as br, type DeviceApprovalGrant as bs, type PollDeviceApprovalInput as bt, type DeviceApprovalPollResult as bu, type ConfirmDeviceEnrollmentInput as bv, type ConfirmDeviceEnrollmentResult as bw, type ApproveWithDeviceCodeInput as bx, type DeviceApprovalSettleResult as by, type CompleteDeviceApprovalInput as bz, type PurchaseExpired as c, type RefundPendingApproval as c0, type RefundProcessingFeeBasis as c1, type RefundReceipt as c2, type RefundRevenueShareAttribution as c3, type RefundWarning as c4, type SandboxClockState as c5, type SavedCard as c6, type SteamPack as c7, type SteamUnavailableReason as c8, type SteamUserSession as c9, type Subscription as ca, type SubscriptionBaseInput as cb, type SubscriptionConsent as cc, type SubscriptionConsentInput as cd, type SubscriptionFundingRail as ce, type SubscriptionInterval as cf, type SubscriptionRevenueShare as cg, type SubscriptionRevenueShareInput as ch, type SubscriptionStatus as ci, type UnacknowledgedPurchaseOutcome as cj, isRefundPendingApproval as ck, 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 };
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 AuthHeader 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 AppleProductsResult as a$, type ApplePurchaseResult as a0, type PlatformPurchaseInput as a1, type PlatformPurchaseResult as a2, type PlatformApprovalResult as a3, type PlatformOrderStatusResult as a4, type PlatformPurchaseHistoryQuery as a5, type PlatformPurchaseHistoryResult as a6, type PlatformRefundInput as a7, type PlatformRefundResult as a8, type CreateSubscriptionInput as a9, type ServerConfig as aA, type MintPlayerTokenInput as aB, type PlayerToken as aC, type RegisterPlayerInput as aD, type RegisterPlayerResult as aE, type UpdatePlayerPhoneInput as aF, type UpdatePlayerPhoneResult as aG, type RequestPhoneChangeInput as aH, type RequestPhoneChangeResult as aI, type PhoneChangeRequest as aJ, type InitiateSendInput as aK, type InitiateResult as aL, type InitiateTransferInput as aM, type CreateCheckoutInput as aN, type CreateCheckoutResult as aO, type PurchaseInput as aP, type PurchaseResult as aQ, type CurrencyPurchaseQuoteInput as aR, type CurrencyPurchaseQuote as aS, type ConfirmPaymentResult as aT, type OrderDetailsResult as aU, type SteamPacksQuery as aV, type SteamPacksResult as aW, type SteamInitPurchaseInput as aX, type SteamInitPurchaseResult as aY, type SteamFinalizeInput as aZ, type SteamFinalizeResult as a_, type SubscriptionResult as aa, type GetSubscriptionOptions as ab, type GetSubscriptionResult as ac, type ListSubscriptionsOptions as ad, type SubscriptionListResult as ae, type CancelSubscriptionOptions as af, type CancelResult as ag, type ChangeAmountResult as ah, type SetPaymentMethodInput as ai, type SetPaymentMethodResult as aj, type RefundSubscriptionInput as ak, type RefundResult as al, type SteamSubscriptionInitInput as am, type SteamInitResult as an, type SteamFinalizeSubscriptionResult as ao, type CardSetupSessionInput as ap, type CardSetupSessionResult as aq, type CardSetupInput as ar, type CardSetupResult as as, type CardSetupConfirmInput as at, type CardSetupConfirmResult as au, type PlayerCardsResult as av, type SandboxClockResult as aw, type SandboxFailureOutcome as ax, type SandboxForceFailureOptions as ay, type SandboxForceAuthChallengeOptions as az, type PurchaseCredited as b, type RefundInitiation as b$, type VerifyApplePurchaseInput as b0, type PurchaseItemInput as b1, type PurchaseItemResult as b2, type ItemHistoryQuery as b3, type ItemHistoryResult as b4, type ItemOrderQuery as b5, type PlayerActivityQuery as b6, type PlayerActivityResult as b7, type PlayerActivityEntry as b8, type PlayerBalanceQuery as b9, type CompleteDeviceApprovalResult as bA, type AppleEnvironment as bB, type AppleProduct as bC, type ApplePurchaseStatus as bD, type AppleUnavailableReason as bE, type CardSetupStatus as bF, type CheckoutWarning as bG, type CurrencyBalance as bH, type CurrencyPurchaseQuoteBreakdown as bI, type DeviceApprovalChannel as bJ, type DeviceApprovalEnrollment as bK, type DeviceApprovalFlow as bL, type DeviceApprovalPollStatus as bM, type DeviceEnrollmentDecision as bN, type DeviceEnrollmentRespond as bO, type ExpiryReason as bP, type FeeTakenFrom as bQ, type FirstCharge as bR, type FirstChargeStatus as bS, type FundingSource as bT, type InboundPendingItem as bU, type LinkedIdentityEmail as bV, type MinPurchaseWarning as bW, type PhoneChangeConfirmation as bX, type PhoneChangeRequestStatus as bY, type PlatformPurchaseStatus as bZ, type PlayerActivityType as b_, type PlayerBalanceResult as ba, type InboundPendingQuery as bb, type InboundPendingResult as bc, type LinkedIdentitiesQuery as bd, type LinkedIdentitiesResult as be, type SmsVerifyResult as bf, type ClaimTransferInput as bg, type ClaimResult as bh, type ClaimCurrencyInput as bi, type TransactionStatusResult as bj, type GuardianApprovalStatusResult as bk, type ServerDestinationsQuery as bl, type PhoneShareContact as bm, type PhoneShareInitiateResult as bn, type PhoneShareApproveInput as bo, type PhoneShareApproveResult as bp, type PhoneShareStatusResult as bq, type BeginDeviceApprovalInput as br, type DeviceApprovalGrant as bs, type PollDeviceApprovalInput as bt, type DeviceApprovalPollResult as bu, type ConfirmDeviceEnrollmentInput as bv, type ConfirmDeviceEnrollmentResult as bw, type ApproveWithDeviceCodeInput as bx, type DeviceApprovalSettleResult as by, type CompleteDeviceApprovalInput as bz, type PurchaseExpired as c, type RefundPendingApproval as c0, type RefundProcessingFeeBasis as c1, type RefundReceipt as c2, type RefundRevenueShareAttribution as c3, type RefundWarning as c4, type SandboxClockState as c5, type SavedCard as c6, type SteamPack as c7, type SteamUnavailableReason as c8, type SteamUserSession as c9, type Subscription as ca, type SubscriptionBaseInput as cb, type SubscriptionConsent as cc, type SubscriptionConsentInput as cd, type SubscriptionFundingRail as ce, type SubscriptionInterval as cf, type SubscriptionRevenueShare as cg, type SubscriptionRevenueShareInput as ch, type SubscriptionStatus as ci, type UnacknowledgedPurchaseOutcome as cj, isRefundPendingApproval as ck, 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 };
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 };
@@ -3,6 +3,6 @@
3
3
  * `package.json` so it cannot drift silently (it did: the UA read 3.0.0 through 3.7.0).
4
4
  * Bump it with the changeset flow.
5
5
  */
6
- declare const SDK_VERSION = "3.37.1";
6
+ declare const SDK_VERSION = "3.38.0";
7
7
 
8
8
  export { SDK_VERSION as S };
@@ -3,6 +3,6 @@
3
3
  * `package.json` so it cannot drift silently (it did: the UA read 3.0.0 through 3.7.0).
4
4
  * Bump it with the changeset flow.
5
5
  */
6
- declare const SDK_VERSION = "3.37.1";
6
+ declare const SDK_VERSION = "3.38.0";
7
7
 
8
8
  export { SDK_VERSION as S };
@@ -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.37.1",
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
  ],
@@ -1,6 +0,0 @@
1
- // src/version.ts
2
- var SDK_VERSION = "3.37.1";
3
-
4
- export { SDK_VERSION };
5
- //# sourceMappingURL=chunk-OYJUX2TH.js.map
6
- //# sourceMappingURL=chunk-OYJUX2TH.js.map