@invonetwork/web-sdk 3.37.0 → 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.
Files changed (33) hide show
  1. package/CHANGELOG.md +24 -0
  2. package/README.md +49 -8
  3. package/dist/{chunk-AUHRMREF.js → chunk-3HK32FE4.js} +3 -3
  4. package/dist/{chunk-KWAUFFDY.js → chunk-7B7MFAQ3.js} +33 -5
  5. package/dist/chunk-MOHWLDOQ.js +6 -0
  6. package/dist/{chunk-ZHEQAZLW.js → chunk-NS33T5FB.js} +64 -15
  7. package/dist/game-server.cjs +99 -22
  8. package/dist/game-server.d.cts +4 -4
  9. package/dist/game-server.d.ts +4 -4
  10. package/dist/game-server.js +5 -5
  11. package/dist/game.cjs +32 -4
  12. package/dist/game.d.cts +3 -3
  13. package/dist/game.d.ts +3 -3
  14. package/dist/game.js +3 -3
  15. package/dist/{hosted-approval-DS9gcCF5.d.cts → hosted-approval-B-kbdFDL.d.cts} +1 -1
  16. package/dist/{hosted-approval-Dv462L4e.d.ts → hosted-approval-CtAZ1Rzt.d.ts} +1 -1
  17. package/dist/index.cjs +31 -3
  18. package/dist/index.d.cts +4 -4
  19. package/dist/index.d.ts +4 -4
  20. package/dist/index.js +2 -2
  21. package/dist/{server-B9PtYZaM.d.cts → server-BWGl9v5j.d.cts} +93 -13
  22. package/dist/{server-B7Pw1HMp.d.ts → server-CaaP-Nc3.d.ts} +93 -13
  23. package/dist/server.cjs +99 -22
  24. package/dist/server.d.cts +3 -3
  25. package/dist/server.d.ts +3 -3
  26. package/dist/server.js +3 -3
  27. package/dist/{types-BdKpJX93.d.cts → types-DGgWWX1v.d.cts} +89 -9
  28. package/dist/{types-BdKpJX93.d.ts → types-DGgWWX1v.d.ts} +89 -9
  29. package/dist/{version-CuhMO-6s.d.cts → version-D_cJUvMp.d.cts} +1 -1
  30. package/dist/{version-CuhMO-6s.d.ts → version-D_cJUvMp.d.ts} +1 -1
  31. package/docs/merchant-of-record-tax.md +176 -0
  32. package/package.json +2 -1
  33. package/dist/chunk-MENRG67H.js +0 -6
@@ -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.0",
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.0";
3
-
4
- export { SDK_VERSION };
5
- //# sourceMappingURL=chunk-MENRG67H.js.map
6
- //# sourceMappingURL=chunk-MENRG67H.js.map