@invonetwork/web-sdk 3.12.1 → 3.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -306,12 +306,48 @@ declare class InvoError extends Error {
306
306
  * in force for the request that failed; the live figure for a tenant is also the
307
307
  * `max_amount` of the hosted checkout's `validate-game` read. */
308
308
  get isAboveCardMaximum(): boolean;
309
+ /**
310
+ * True when an UNACKNOWLEDGED `purchaseCurrency` was refused because the amount is too
311
+ * small to carry INVO's card fee (`AMOUNT_BELOW_FEE`, 400). Nothing was charged. Send a
312
+ * larger amount, or quote it with `quoteCurrencyPurchase` and send `acknowledgedTotalUsd`
313
+ * so the fee is added on top.
314
+ */
315
+ get isAmountBelowFee(): boolean;
316
+ /**
317
+ * True when `purchaseCurrency` was sent an `acknowledgedTotalUsd` that is not the total
318
+ * INVO would charge now (`QUOTE_STALE`, 409). Nothing was charged. Quote again, show the
319
+ * player the new total, and retry with it. {@link expectedTotalUsd} carries INVO's figure.
320
+ */
321
+ get isQuoteStale(): boolean;
322
+ /** On `QUOTE_STALE`: the total INVO would charge (`expected_total_usd`), decimal string. */
323
+ get expectedTotalUsd(): string | undefined;
324
+ /** On `QUOTE_STALE`: the total you sent, as INVO read it (`acknowledged_total_usd`). */
325
+ get acknowledgedTotalUsd(): string | undefined;
309
326
  /**
310
327
  * True if a Platform Commerce refund targeted an order that was already refunded
311
328
  * (409). Idempotent outcome — the original refund did happen, so treat this as
312
329
  * success, not a failure to retry-loop.
313
330
  */
314
331
  get isAlreadyRefunded(): boolean;
332
+ /**
333
+ * Platform Commerce card sale already refunded in part (409
334
+ * `REFUND_REMAINING_REQUIRES_CONFIRMATION`): nothing moved. Retry with
335
+ * `refundRemaining: true` to refund the rest; `refunded_total_usd` and `remaining_usd` are
336
+ * on `err.body`.
337
+ */
338
+ get isRefundRemainingRequiresConfirmation(): boolean;
339
+ /**
340
+ * A Platform Commerce refund of this order was applied in the last 120 seconds (409
341
+ * `REFUND_RECENTLY_ISSUED`): nothing moved. Re-read the order; send
342
+ * `confirmAdditionalRefund: true` to refund anyway.
343
+ */
344
+ get isRefundRecentlyIssued(): boolean;
345
+ /**
346
+ * The Platform Commerce card refund failed, was canceled or still needs an action (502
347
+ * `REFUND_NOT_COMPLETED`): nothing was recorded. Retry; a refund that was in fact created
348
+ * is found and recorded on the retry, never issued twice.
349
+ */
350
+ get isRefundNotCompleted(): boolean;
315
351
  /**
316
352
  * True when an approve / confirm-receipt was refused because the transaction is no
317
353
  * longer awaiting that step (`TRANSACTION_NOT_PENDING`, 400). `approveWithDeviceCode`
@@ -393,12 +429,42 @@ declare class InvoError extends Error {
393
429
  * True when the same `clientRequestId` was replayed for the same player and item but
394
430
  * with DIFFERENT material terms (`IDEMPOTENT_REPLAY_MISMATCH`, 409). See
395
431
  * `mismatchedFields` (any of `amount_usd`, `interval`, `interval_count`, `wallet_only`,
396
- * `funding_rail`). To change terms use `changeAmount` / `setPaymentMethod`; to create a
432
+ * `funding_rail`, `trial_amount_usd`; for the last an omitted value counts, so a replay
433
+ * without it against a paid trial is a mismatch). To change terms use `changeAmount` / `setPaymentMethod`; to create a
397
434
  * new subscription use a new key.
398
435
  */
399
436
  get isIdempotentReplayMismatch(): boolean;
400
437
  /** The `mismatched_fields` on an `IDEMPOTENT_REPLAY_MISMATCH` 409. */
401
438
  get mismatchedFields(): string[];
439
+ /**
440
+ * True on `PAYMENT_METHOD_REQUIRED` (400). From `subscriptions.create`: a paid trial
441
+ * (`trialAmountUsd`) with no usable saved card; nothing was created. Save the member's card
442
+ * (`cards.createSetupSession`), then subscribe again. From `setPaymentMethod`: no
443
+ * `playerCardId` was sent.
444
+ */
445
+ get isPaymentMethodRequired(): boolean;
446
+ /**
447
+ * True when `trialAmountUsd` is not a usable trial price (`TRIAL_AMOUNT_INVALID`, 400): it
448
+ * must be a decimal of at least `0.50` (the card minimum) and less than `amountUsd`. The
449
+ * message names the rule.
450
+ */
451
+ get isTrialAmountInvalid(): boolean;
452
+ /** True when `trialAmountUsd` was sent without `trialDays` or `trialEnd` (`TRIAL_AMOUNT_REQUIRES_TRIAL`, 400). */
453
+ get isTrialAmountRequiresTrial(): boolean;
454
+ /**
455
+ * True when a paid trial was asked for where it cannot be charged
456
+ * (`TRIAL_AMOUNT_NOT_SUPPORTED_FOR_FUNDING`, 400): with `walletOnly: true`, or on the Steam
457
+ * rail. Paid trials are for card subscriptions only.
458
+ */
459
+ get isTrialAmountNotSupportedForFunding(): boolean;
460
+ /**
461
+ * True when one of the disclosed paid-trial consent fields is malformed (400):
462
+ * `CONSENT_DISCLOSED_TRIAL_AMOUNT_INVALID`, `CONSENT_DISCLOSED_TRIAL_DAYS_INVALID` (not an
463
+ * integer 1 to 365) or `CONSENT_DISCLOSED_TRIAL_END_INVALID` (not ISO 8601). `err.code`
464
+ * says which. A disclosed value that is well formed but disagrees with the trial is not
465
+ * refused; INVO records the disagreement.
466
+ */
467
+ get isConsentDisclosedTrialInvalid(): boolean;
402
468
  /**
403
469
  * True when `changeAmount` tried to RAISE the price of a Steam subscription
404
470
  * (`STEAM_REAUTHORIZATION_REQUIRED`, 409). The member consented to a ceiling; start a
@@ -762,11 +828,33 @@ interface CreateCheckoutResult {
762
828
  }
763
829
  interface PurchaseInput {
764
830
  playerEmail: string;
765
- /** USD, two decimals. The advertised minimum is $0.50 (the card rail's own floor).
766
- * The maximum is an INVO runtime setting, $100,000.00 by default, editable by an
767
- * admin and different per environment, so it is enforced on the request rather than
768
- * pinned here: expect a 400 carrying the live figure. */
831
+ /**
832
+ * USD, two decimals: the listed price of the coins.
833
+ *
834
+ * **Without `acknowledgedTotalUsd` this is exactly what the card is charged, never more**,
835
+ * and INVO's card fee (3.5% + $0.30) comes out of the coins instead: $10.00 buys the
836
+ * coins for $9.37 (93.70 coins at the default 10 per USD) and $0.63 is the fee. With
837
+ * `acknowledgedTotalUsd` the coins are priced off this amount and the fee is added on
838
+ * top of it.
839
+ *
840
+ * Minimum: $0.50, the card rail's own floor. An unacknowledged amount must also be large
841
+ * enough to carry the fee, or INVO refuses it before charging anything
842
+ * (`400 AMOUNT_BELOW_FEE`, `err.isAmountBelowFee`). The maximum is an INVO runtime
843
+ * setting, $100,000.00 by default, editable by an admin and different per environment,
844
+ * so it is enforced on the request rather than pinned here: expect a 400 carrying the
845
+ * live figure.
846
+ */
769
847
  usdAmount: string | number;
848
+ /**
849
+ * The total you showed the player, taken from {@link CurrencyPurchaseQuote.totalUsd}
850
+ * (`InvoServer.quoteCurrencyPurchase`): the price plus INVO's card fee (plus any tax).
851
+ * Present, INVO checks it to the cent and charges the card exactly this, and the coins
852
+ * are priced off `usdAmount`. If the total has changed since you quoted it, nothing is
853
+ * charged and the call throws `409 QUOTE_STALE` (`err.isQuoteStale`,
854
+ * `err.expectedTotalUsd`): quote again and show the new total. Omitted, the card is
855
+ * charged exactly `usdAmount` and the fee comes out of the coins.
856
+ */
857
+ acknowledgedTotalUsd?: string | number;
770
858
  /** Idempotency key. Required. */
771
859
  purchaseReference: string;
772
860
  rail?: Rail;
@@ -789,12 +877,138 @@ interface PurchaseResult {
789
877
  transactionId?: string;
790
878
  orderId?: string;
791
879
  newBalance?: string | number | null;
880
+ /**
881
+ * INVO's card fee on this purchase, decimal string. Present on a `success` response
882
+ * (backends from 2026-09-23 on); `undefined` otherwise.
883
+ */
884
+ processingFeeUsd?: string;
885
+ /**
886
+ * Where the fee came from: `"charge"` (added on top: you sent `acknowledgedTotalUsd`) or
887
+ * `"coins"` (the card was charged exactly `usdAmount` and the fee came out of the coins).
888
+ * Present on a `success` response.
889
+ */
890
+ feeTakenFrom?: FeeTakenFrom;
891
+ /** The coins credited to the player, decimal string. Present on a `success` response. */
892
+ coinsCredited?: string;
893
+ /** What the card was charged, decimal string (fee and any tax included). Present on a `success` response. */
894
+ chargeTotalUsd?: string;
895
+ /**
896
+ * Merchant of Record accounts only: the number of the receipt INVO issued to the buyer for
897
+ * this card sale (for example `"IR-2026-00000123"`; `"IRS-..."` on the sandbox). Absent on
898
+ * Open accounts, on storefront rails, and until the receipt has been issued.
899
+ */
900
+ receiptNumber?: string;
901
+ /**
902
+ * Merchant of Record accounts only: a link to the printable receipt page (no login). Anyone
903
+ * with the link can read the receipt, so treat it like the receipt itself. Absent whenever
904
+ * `receiptNumber` is.
905
+ */
906
+ receiptUrl?: string;
907
+ raw: Record<string, unknown>;
908
+ }
909
+ /**
910
+ * Where INVO's card fee on a coin purchase came from. Widened so a value a later backend
911
+ * adds still compiles; treat an unknown value as informational.
912
+ */
913
+ type FeeTakenFrom = "charge" | "coins" | (string & {});
914
+ /** Input for `InvoServer.quoteCurrencyPurchase`. */
915
+ interface CurrencyPurchaseQuoteInput {
916
+ /** The player the purchase is for (the same field the purchase call sends). */
917
+ playerEmail: string;
918
+ /** The listed price, USD, two decimals: the `usdAmount` you will send on the purchase. */
919
+ usdAmount: string | number;
920
+ /**
921
+ * The buyer's billing country, ISO 3166-1 alpha-2 (for example `"US"`). Omit it and the
922
+ * quote is untaxed: with no place of supply no tax can be determined. An unusable value
923
+ * is treated as no country, never refused.
924
+ */
925
+ country?: string;
926
+ /** A US state or Canadian province code, with `country`. */
927
+ subdivision?: string;
928
+ }
929
+ /** The lines to show the buyer. Every money figure is a 2dp decimal string. */
930
+ interface CurrencyPurchaseQuoteBreakdown {
931
+ subtotalUsd: string;
932
+ taxUsd: string;
933
+ /**
934
+ * Why the tax is what it is. `"partner_responsible"` on an Open-tier account (you are the
935
+ * seller; INVO charged no tax). On Merchant of Record, how INVO handled it (for example
936
+ * `"collected"`). Treat an unknown value as informational.
937
+ */
938
+ taxTreatment: string | null;
939
+ /** A sentence you can show as is. */
940
+ taxNote: string;
941
+ taxRatePct: string | null;
942
+ taxJurisdiction: string | null;
943
+ processingFeeUsd: string;
944
+ /** A sentence you can show as is, or `""` when there is no fee. */
945
+ processingFeeNote: string;
946
+ totalUsd: string;
947
+ coins: string;
948
+ currencyName: string;
949
+ raw: Record<string, unknown>;
950
+ }
951
+ /** What an UNACKNOWLEDGED purchase of the same amount would do. */
952
+ interface UnacknowledgedPurchaseOutcome {
953
+ /** Exactly the `usdAmount` you quoted. */
954
+ chargeTotalUsd: string;
955
+ /** The fee, taken out of the coins. */
956
+ processingFeeUsd: string;
957
+ /** The coins the player would receive. */
958
+ coins: string;
959
+ /** `"coins"`. */
960
+ feeTakenFrom: FeeTakenFrom;
961
+ }
962
+ /**
963
+ * Result of `InvoServer.quoteCurrencyPurchase`. It moves no money and creates nothing.
964
+ * Show the player `totalUsd`, then send that same figure back as `acknowledgedTotalUsd`.
965
+ */
966
+ interface CurrencyPurchaseQuote {
967
+ /** The figure to display AND the figure to send back as `acknowledgedTotalUsd`. */
968
+ totalUsd: string;
969
+ /** `totalUsd` in cents. */
970
+ amountCents: number;
971
+ /** The listed price (your `usdAmount`). */
972
+ subtotalUsd: string;
973
+ /**
974
+ * INVO's card fee on top of the price: 3.5% + $0.30 on the Open tier (5% + $0.30 on
975
+ * Merchant of Record), never less than the card cost. Read the figure; do not recompute it.
976
+ */
977
+ processingFeeUsd: string;
978
+ /** Coins the player receives on an acknowledged purchase. */
979
+ coins: string;
980
+ currencyName: string;
981
+ breakdown: CurrencyPurchaseQuoteBreakdown;
982
+ /**
983
+ * What happens if you do NOT acknowledge: the card is charged exactly `usdAmount` and the
984
+ * fee comes out of the coins. `null` when the amount cannot carry the fee (that purchase
985
+ * would be refused with `AMOUNT_BELOW_FEE`).
986
+ */
987
+ ifUnacknowledged: UnacknowledgedPurchaseOutcome | null;
792
988
  raw: Record<string, unknown>;
793
989
  }
794
990
  interface ConfirmPaymentResult {
991
+ /** `"success"` whenever the payment succeeded (unchanged). Read `credited` for the coins. */
795
992
  status: string;
796
993
  transactionId?: string;
797
994
  newBalance?: string | number | null;
995
+ /**
996
+ * Additive (backends from 2026-09-24). `status: "success"` means the PAYMENT succeeded; it
997
+ * does not by itself mean the coins were added. `true`: the coins are in the balance (added
998
+ * by this call or an earlier one). `false`: the payment succeeded and the coins were NOT
999
+ * added: see `reasonCode`. Report a completed purchase only when this is `true`. `undefined`
1000
+ * on an older backend: fall back to the order status (`getOrderDetails`).
1001
+ */
1002
+ credited?: boolean;
1003
+ /**
1004
+ * Present when `credited` is `false`. A `CREDIT_REFUSED_*` code (for example
1005
+ * `"CREDIT_REFUSED_MINT_CEILING"`) means the buyer's money was taken and no coins were added:
1006
+ * INVO is alerted, and the buyer must NOT be asked to pay again. `"REFUNDED"` or
1007
+ * `"CHARGEBACK_LOST"` means the payment went back to the buyer. `null` means the credit is
1008
+ * still being finished: poll `getOrderDetails` until the order is `completed`. `undefined`
1009
+ * when `credited` is not `false`.
1010
+ */
1011
+ reasonCode?: string | null;
798
1012
  raw: Record<string, unknown>;
799
1013
  }
800
1014
  /** Shape of the order-details reads (currency purchase + item purchase). */
@@ -802,6 +1016,13 @@ interface OrderDetailsResult {
802
1016
  order: Record<string, unknown>;
803
1017
  financialSummary: Record<string, unknown>;
804
1018
  statusTimeline: unknown;
1019
+ /**
1020
+ * Currency purchases on a Merchant of Record account only: the receipt INVO issued to the
1021
+ * buyer, once issued. Absent on Open, on storefront rails and on item purchases.
1022
+ */
1023
+ receiptNumber?: string;
1024
+ /** Merchant of Record only: link to the printable receipt page. Anyone with it can read it. */
1025
+ receiptUrl?: string;
805
1026
  raw: Record<string, unknown>;
806
1027
  }
807
1028
  interface ItemHistoryResult {
@@ -899,7 +1120,7 @@ interface SteamFinalizeInput {
899
1120
  orderId: string;
900
1121
  }
901
1122
  interface SteamFinalizeResult {
902
- /** "success" once captured and credited. */
1123
+ /** `"success"` once Steam captured the payment (unchanged). Read `credited` for the currency. */
903
1124
  status: string;
904
1125
  orderId?: string;
905
1126
  transactionId?: string;
@@ -911,9 +1132,27 @@ interface SteamFinalizeResult {
911
1132
  * balance from the original success, or from `playerBalance()` if you need
912
1133
  * it fresh. (Documented wrong as "the current balance" until the audit
913
1134
  * checked the replay body against the backend, which returns only
914
- * status/order/transaction ids.)
1135
+ * status/order/transaction ids.) Also `true` whenever this call added nothing, including a
1136
+ * refused credit, so read `credited` rather than this.
915
1137
  */
916
1138
  alreadyProcessed: boolean;
1139
+ /**
1140
+ * Additive (backends from 2026-09-24). `status: "success"` means the PAYMENT succeeded; it
1141
+ * does not by itself mean the coins were added. `true`: the coins are in the balance (added
1142
+ * by this call or an earlier one). `false`: the payment succeeded and the coins were NOT
1143
+ * added: see `reasonCode`. Report a completed purchase only when this is `true`. `undefined`
1144
+ * on an older backend: fall back to the order status (`getOrderDetails`).
1145
+ */
1146
+ credited?: boolean;
1147
+ /**
1148
+ * Present when `credited` is `false`. A `CREDIT_REFUSED_*` code (for example
1149
+ * `"CREDIT_REFUSED_MINT_CEILING"`) means the buyer's money was taken and no coins were added:
1150
+ * INVO is alerted, and the buyer must NOT be asked to pay again. `"REFUNDED"` or
1151
+ * `"CHARGEBACK_LOST"` means the payment went back to the buyer. `null` means the credit is
1152
+ * still being finished: poll `getOrderDetails` until the order is `completed`. `undefined`
1153
+ * when `credited` is not `false`.
1154
+ */
1155
+ reasonCode?: string | null;
917
1156
  raw: Record<string, unknown>;
918
1157
  }
919
1158
  interface PurchaseItemInput {
@@ -1029,6 +1268,18 @@ interface PlatformOrderStatusResult {
1029
1268
  usdAmount?: string | number | null;
1030
1269
  paymentMethod?: string;
1031
1270
  createdAt?: string;
1271
+ /**
1272
+ * Merchant of Record accounts only: the number of the receipt INVO issued to the buyer for
1273
+ * this card sale (for example `"IR-2026-00000123"`; `"IRS-..."` on the sandbox). Absent on
1274
+ * Open accounts, on storefront rails, and until the receipt has been issued.
1275
+ */
1276
+ receiptNumber?: string;
1277
+ /**
1278
+ * Merchant of Record accounts only: a link to the printable receipt page (no login). Anyone
1279
+ * with the link can read the receipt, so treat it like the receipt itself. Absent whenever
1280
+ * `receiptNumber` is.
1281
+ */
1282
+ receiptUrl?: string;
1032
1283
  raw: Record<string, unknown>;
1033
1284
  }
1034
1285
  interface PlatformRefundInput {
@@ -1036,6 +1287,18 @@ interface PlatformRefundInput {
1036
1287
  orderId?: string | number;
1037
1288
  clientRequestId?: string;
1038
1289
  reason?: string;
1290
+ /**
1291
+ * Card sale already refunded in part: refund what is left. Sent only when `true`. Without
1292
+ * it such a refund is refused with 409 `REFUND_REMAINING_REQUIRES_CONFIRMATION`
1293
+ * (`err.isRefundRemainingRequiresConfirmation`).
1294
+ */
1295
+ refundRemaining?: boolean;
1296
+ /**
1297
+ * Refund anyway within 120 seconds of the order's last refund. Sent only when `true`.
1298
+ * Without it such a refund is refused with 409 `REFUND_RECENTLY_ISSUED`
1299
+ * (`err.isRefundRecentlyIssued`).
1300
+ */
1301
+ confirmAdditionalRefund?: boolean;
1039
1302
  }
1040
1303
  interface PlatformRefundResult {
1041
1304
  /** "refunded" on success. A second refund of the same order throws a 409
@@ -1057,6 +1320,20 @@ interface PlatformRefundResult {
1057
1320
  processorRefundId?: string;
1058
1321
  /** Always true — INVO retains its fee; the customer is made whole minus that fee. */
1059
1322
  feeRetained?: boolean;
1323
+ /**
1324
+ * Card sale refunded in parts only (absent on a one-shot full refund): `true` while part
1325
+ * of the charge is still refundable, `false` on the refund that completes it.
1326
+ * `refundedAmount` and the other figures are then this refund's own share.
1327
+ */
1328
+ partialRefund?: boolean;
1329
+ /** Present and `true` only when this call recorded a refund that already existed; no new money moved. */
1330
+ adopted?: boolean;
1331
+ /** Refunds in parts only: the USD refunded on this order so far, this refund included. */
1332
+ refundedTotalUsd?: string;
1333
+ /** Refunds in parts only: the whole card charge, USD. */
1334
+ chargeTotalUsd?: string;
1335
+ /** Present only while something is left: the USD still refundable (send `refundRemaining: true`). */
1336
+ remainingUsd?: string;
1060
1337
  raw: Record<string, unknown>;
1061
1338
  }
1062
1339
  interface MountCheckoutOptions {
@@ -1660,8 +1937,18 @@ interface SubscriptionConsentInput {
1660
1937
  disclosedInterval?: SubscriptionInterval;
1661
1938
  /** Your terms version, max 50. */
1662
1939
  termsVersion?: string;
1940
+ /** Paid trial: the trial price you showed the member; should equal `trialAmountUsd`. Decimal string. */
1941
+ disclosedTrialAmountUsd?: string;
1942
+ /** Paid trial: the trial length you showed the member, in days (1 to 365). Send this or `disclosedTrialEnd`. */
1943
+ disclosedTrialDays?: number;
1944
+ /** Paid trial: the trial end you showed the member, ISO 8601. */
1945
+ disclosedTrialEnd?: string;
1663
1946
  }
1664
- /** The `consent` block as INVO returns it: six fields, all `null` until supplied. */
1947
+ /**
1948
+ * The `consent` block as INVO returns it, every field `null` until supplied. The three
1949
+ * `disclosed_trial_*` fields are optional in the type only so code that builds this object
1950
+ * itself keeps compiling; the SDK always fills them (`null` from a backend that predates them).
1951
+ */
1665
1952
  interface SubscriptionConsent {
1666
1953
  consent_at: string | null;
1667
1954
  consent_ip: string | null;
@@ -1669,6 +1956,9 @@ interface SubscriptionConsent {
1669
1956
  disclosed_amount_usd: string | null;
1670
1957
  disclosed_interval: string | null;
1671
1958
  terms_version: string | null;
1959
+ disclosed_trial_amount_usd?: string | null;
1960
+ disclosed_trial_days?: number | null;
1961
+ disclosed_trial_end?: string | null;
1672
1962
  }
1673
1963
  /**
1674
1964
  * Attribution to a second player in your game, and ATTRIBUTION ONLY. INVO records the
@@ -1722,6 +2012,13 @@ interface Subscription {
1722
2012
  nextChargeAt: string | null;
1723
2013
  cancelAtPeriodEnd: boolean;
1724
2014
  trialEnd: string | null;
2015
+ /**
2016
+ * The paid-trial price charged for period 1 (the trial window), decimal string. `null` on a
2017
+ * free trial, on every subscription without a trial, and from a backend that predates paid
2018
+ * trials. `amountUsd` stays the regular price throughout. Optional in the type only so code
2019
+ * that builds this object itself keeps compiling; the SDK always fills it.
2020
+ */
2021
+ trialAmountUsd?: string | null;
1725
2022
  canceledAt: string | null;
1726
2023
  endedAt: string | null;
1727
2024
  /**
@@ -1744,6 +2041,11 @@ interface Subscription {
1744
2041
  paidThrough: string | null;
1745
2042
  /** Create/finalize responses only: what one period is worth in coins on this rail. */
1746
2043
  amountCoinsEstimate?: string;
2044
+ /**
2045
+ * Create/finalize responses only: what the paid-trial period is worth in coins. `null` when
2046
+ * the subscription has no paid trial; `undefined` on reads and on older backends.
2047
+ */
2048
+ trialAmountCoinsEstimate?: string | null;
1747
2049
  /**
1748
2050
  * Only when the read asked for `includePlayer: true`: the member's email. INVO puts the
1749
2051
  * two player fields ON the subscription object, not in a separate block.
@@ -1768,7 +2070,8 @@ interface SavedCard {
1768
2070
  * - `paid`: money moved, currency granted; grant access until `paidThrough`.
1769
2071
  * - `requires_action`: the card issuer wants the cardholder to authenticate. NOTHING
1770
2072
  * has been charged; send the member to `confirmationUrl` before `expiresAt`.
1771
- * - `skipped_trial`: deliberately not charged; the subscription is `trialing`.
2073
+ * - `skipped_trial`: deliberately not charged; the subscription is on a FREE trial
2074
+ * (`trialing`). Never returned for a paid trial, whose period 1 is charged like any first period.
1772
2075
  * - `failed`: the charge did not succeed; the subscription is `past_due` and in dunning.
1773
2076
  * - `pending`: not resolved yet; wait for `subscription.renewed` / `payment_failed`.
1774
2077
  * - `pending_authorization`: Steam; nothing charged until the member authorises and
@@ -1786,7 +2089,9 @@ type FirstChargeStatus = "paid" | "requires_action" | "skipped_trial" | "failed"
1786
2089
  */
1787
2090
  interface FirstCharge {
1788
2091
  status: FirstChargeStatus;
1789
- /** On `paid`: the amount actually charged for period 1 (on the card rail, always the full price). */
2092
+ /** The amount for period 1: on `paid`, what was actually charged. On the card rail that is the
2093
+ * full price, or `trialAmountUsd` on a paid trial (every other outcome of a paid trial also
2094
+ * reports the trial price). */
1790
2095
  amountUsd: string | null;
1791
2096
  /** The period that was just paid (`1` for the first period). `null` unless `status` is `paid`. */
1792
2097
  paidPeriodSeq: number | null;
@@ -1806,6 +2111,18 @@ interface FirstCharge {
1806
2111
  confirmationUrl: string | null;
1807
2112
  expiresAt: string | null;
1808
2113
  message: string | null;
2114
+ /**
2115
+ * Merchant of Record accounts only: the number of the receipt INVO issued to the buyer for
2116
+ * this paid first period (for example `"IR-2026-00000123"`; `"IRS-..."` on the sandbox). Absent on
2117
+ * Open accounts, on storefront rails, and until the receipt has been issued.
2118
+ */
2119
+ receiptNumber?: string;
2120
+ /**
2121
+ * Merchant of Record accounts only: a link to the printable receipt page (no login). Anyone
2122
+ * with the link can read the receipt, so treat it like the receipt itself. Absent whenever
2123
+ * `receiptNumber` is.
2124
+ */
2125
+ receiptUrl?: string;
1809
2126
  raw: Record<string, unknown>;
1810
2127
  }
1811
2128
  /** Fields shared by `subscriptions.create` and `subscriptions.steamInit`. */
@@ -1832,7 +2149,7 @@ interface SubscriptionBaseInput {
1832
2149
  interval?: SubscriptionInterval;
1833
2150
  /** Up to 8192 bytes serialised. Echoed on every read and event. `_invo` is reserved. */
1834
2151
  metadata?: Record<string, unknown>;
1835
- /** Supply it: INVO is merchant of record on the card rail and a dispute is argued from this. */
2152
+ /** Supply it: a dispute over a recurring charge is argued from this record. */
1836
2153
  consent?: SubscriptionConsentInput;
1837
2154
  /** Attribution only; INVO pays nothing to the recipient. Set once at create. */
1838
2155
  revenueShare?: SubscriptionRevenueShareInput;
@@ -1845,6 +2162,21 @@ interface CreateSubscriptionInput extends SubscriptionBaseInput {
1845
2162
  trialDays?: number;
1846
2163
  /** Explicit ISO 8601 trial end (future, within 365 days). Takes precedence over `trialDays`. */
1847
2164
  trialEnd?: string;
2165
+ /**
2166
+ * Makes the trial a PAID trial: period 1 (creation to the trial end) is charged this, at
2167
+ * creation, and `amountUsd` is charged from period 2 at the trial end. Decimal, at least
2168
+ * `0.50` (the card minimum) and less than `amountUsd`. Only with `trialDays` or `trialEnd`,
2169
+ * only on the card rail, never with `walletOnly: true`.
2170
+ *
2171
+ * The member must already have a usable saved card, because the trial price is charged
2172
+ * inside this call: without one INVO refuses with `400 PAYMENT_METHOD_REQUIRED`
2173
+ * (`err.isPaymentMethodRequired`) and creates nothing. If the trial charge is refused the
2174
+ * subscription ends at once (`expired`, `firstCharge.status: "failed"`, `nextRetryAt: null`);
2175
+ * subscribe again with a NEW `clientRequestId`. Record what you showed in
2176
+ * `consent.disclosedTrialAmountUsd` and `disclosedTrialDays` or `disclosedTrialEnd`.
2177
+ * Omitted: a free trial (or no trial), exactly as before.
2178
+ */
2179
+ trialAmountUsd?: string | number;
1848
2180
  /**
1849
2181
  * @deprecated Do not send `true` on new integrations. Still accepted (default `false`), but
1850
2182
  * since 2026-09-17 a card subscription is paid only by card, so `true` means the subscription
@@ -1856,6 +2188,8 @@ interface CreateSubscriptionInput extends SubscriptionBaseInput {
1856
2188
  * The `id` of a card from `cards.list`. Omitted: INVO picks the newest unexpired saved card.
1857
2189
  * With no saved card the subscription is still created, but its first charge fails with
1858
2190
  * `failureCode: "no_payment_method"` whatever the member's coin balance. Save a card first.
2191
+ * A paid trial (`trialAmountUsd`) is the exception: with no usable card it is refused with
2192
+ * `400 PAYMENT_METHOD_REQUIRED` and nothing is created.
1859
2193
  */
1860
2194
  playerCardId?: number;
1861
2195
  }
@@ -2459,6 +2793,18 @@ interface PurchaseStatusResult {
2459
2793
  listedUsd: string | null;
2460
2794
  /** What the coins are called in this game, for your own copy. */
2461
2795
  currencyName: string | null;
2796
+ /**
2797
+ * Merchant of Record accounts only: the number of the receipt INVO issued to the buyer for
2798
+ * this card sale (for example `"IR-2026-00000123"`; `"IRS-..."` on the sandbox). Absent on
2799
+ * Open accounts, on storefront rails, on every status but `credited`, and until the receipt has been issued.
2800
+ */
2801
+ receiptNumber?: string;
2802
+ /**
2803
+ * Merchant of Record accounts only: a link to the printable receipt page (no login). Anyone
2804
+ * with the link can read the receipt, so treat it like the receipt itself. Absent whenever
2805
+ * `receiptNumber` is.
2806
+ */
2807
+ receiptUrl?: string;
2462
2808
  raw: Record<string, unknown>;
2463
2809
  }
2464
2810
  /** A {@link PurchaseStatusResult} narrowed by {@link isPurchaseCredited}. */
@@ -2495,4 +2841,4 @@ interface CheckoutClientConfig {
2495
2841
  hooks?: InvoHooks;
2496
2842
  }
2497
2843
 
2498
- export { type ListSubscriptionsOptions as $, type ApproveResult as A, type BalanceResult as B, type ConfirmReceiptResult as C, type DestinationsQuery as D, type EnrollmentBeginResult as E, type CardSetupInput as F, type CardSetupResult as G, Http as H, InvoError as I, type CardSetupConfirmInput as J, type CardSetupConfirmResult as K, type LinkDeviceResult as L, type MountCheckoutOptions as M, type PlayerCardsResult as N, type PlatformPurchaseInput as O, type PurchaseStatusResult as P, type PlatformPurchaseResult as Q, type RecoveryBeginResult as R, type PlatformOrderStatusResult as S, type PlatformRefundInput as T, type PlatformRefundResult as U, type VerificationMethod as V, type WaitForPurchaseInput as W, type CreateSubscriptionInput as X, type SubscriptionResult as Y, type GetSubscriptionOptions as Z, type GetSubscriptionResult as _, type PurchaseCredited as a, type CompleteDeviceApprovalInput as a$, type SubscriptionListResult as a0, type CancelSubscriptionOptions as a1, type CancelResult as a2, type ChangeAmountResult as a3, type SetPaymentMethodInput as a4, type SetPaymentMethodResult as a5, type RefundSubscriptionInput as a6, type RefundResult as a7, type SteamSubscriptionInitInput as a8, type SteamInitResult as a9, type ItemOrderQuery as aA, type PlayerBalanceQuery as aB, type PlayerBalanceResult as aC, type InboundPendingQuery as aD, type InboundPendingResult as aE, type LinkedIdentitiesQuery as aF, type LinkedIdentitiesResult as aG, type SmsVerifyResult as aH, type ClaimTransferInput as aI, type ClaimResult as aJ, type ClaimCurrencyInput as aK, type TransactionStatusResult as aL, type GuardianApprovalStatusResult as aM, type ServerDestinationsQuery as aN, type PhoneShareContact as aO, type PhoneShareInitiateResult as aP, type PhoneShareApproveInput as aQ, type PhoneShareApproveResult as aR, type PhoneShareStatusResult as aS, type BeginDeviceApprovalInput as aT, type DeviceApprovalGrant as aU, type PollDeviceApprovalInput as aV, type DeviceApprovalPollResult as aW, type ConfirmDeviceEnrollmentInput as aX, type ConfirmDeviceEnrollmentResult as aY, type ApproveWithDeviceCodeInput as aZ, type DeviceApprovalSettleResult as a_, type SteamFinalizeSubscriptionResult as aa, type SandboxClockResult as ab, type SandboxFailureOutcome as ac, type SandboxForceFailureOptions as ad, type SandboxForceAuthChallengeOptions as ae, type ServerConfig as af, type PlayerToken as ag, type InitiateSendInput as ah, type InitiateResult as ai, type InitiateTransferInput as aj, type CreateCheckoutInput as ak, type CreateCheckoutResult as al, type PurchaseInput as am, type PurchaseResult as an, type ConfirmPaymentResult as ao, type OrderDetailsResult as ap, type SteamPacksQuery as aq, type SteamPacksResult as ar, type SteamInitPurchaseInput as as, type SteamInitPurchaseResult as at, type SteamFinalizeInput as au, type SteamFinalizeResult as av, type PurchaseItemInput as aw, type PurchaseItemResult as ax, type ItemHistoryQuery as ay, type ItemHistoryResult as az, type PurchaseExpired as b, type CompleteDeviceApprovalResult as b0, type CardSetupStatus as b1, type CurrencyBalance as b2, type DeviceApprovalChannel as b3, type DeviceApprovalEnrollment as b4, type DeviceApprovalFlow as b5, type DeviceApprovalPollStatus as b6, type DeviceEnrollmentDecision as b7, type DeviceEnrollmentRespond as b8, type FirstCharge as b9, type FirstChargeStatus as ba, type FundingSource as bb, type InboundPendingItem as bc, type LinkedIdentityEmail as bd, type PlatformPurchaseStatus as be, type RefundInitiation as bf, type RefundPendingApproval as bg, type RefundProcessingFeeBasis as bh, type RefundReceipt as bi, type RefundRevenueShareAttribution as bj, type RefundWarning as bk, type SandboxClockState as bl, type SavedCard as bm, type SteamPack as bn, type SteamUserSession as bo, type Subscription as bp, type SubscriptionBaseInput as bq, type SubscriptionConsent as br, type SubscriptionConsentInput as bs, type SubscriptionFundingRail as bt, type SubscriptionInterval as bu, type SubscriptionRevenueShare as bv, type SubscriptionRevenueShareInput as bw, type SubscriptionStatus as bx, isRefundPendingApproval as by, type PurchaseRefunded as c, type PurchaseRefused as d, type CheckoutClientConfig as e, type PurchaseStatusInput as f, type CallOptions as g, type CheckoutMountHandle as h, type ClientConfig as i, type PendingCollectResult as j, type DestinationsResult as k, type EnrollmentVerifyResult as l, type RecoveryCompleteResult as m, type BalanceRow as n, type CheckoutPurchaseStatus as o, type DestinationGame as p, type InvoErrorInfo as q, type InvoHooks as r, type InvoRequestInfo as s, type InvoResponseInfo as t, type PendingCollectItem as u, type PurchaseRefusalReason as v, type Rail as w, type AuthHeader as x, type CardSetupSessionInput as y, type CardSetupSessionResult as z };
2844
+ export { type ListSubscriptionsOptions as $, type ApproveResult as A, type BalanceResult as B, type ConfirmReceiptResult as C, type DestinationsQuery as D, type EnrollmentBeginResult as E, type CardSetupInput as F, type CardSetupResult as G, Http as H, InvoError as I, type CardSetupConfirmInput as J, type CardSetupConfirmResult as K, type LinkDeviceResult as L, type MountCheckoutOptions as M, type PlayerCardsResult as N, type PlatformPurchaseInput as O, type PurchaseStatusResult as P, type PlatformPurchaseResult as Q, type RecoveryBeginResult as R, type PlatformOrderStatusResult as S, type PlatformRefundInput as T, type PlatformRefundResult as U, type VerificationMethod as V, type WaitForPurchaseInput as W, type CreateSubscriptionInput as X, type SubscriptionResult as Y, type GetSubscriptionOptions as Z, type GetSubscriptionResult as _, type PurchaseCredited as a, type ApproveWithDeviceCodeInput as a$, type SubscriptionListResult as a0, type CancelSubscriptionOptions as a1, type CancelResult as a2, type ChangeAmountResult as a3, type SetPaymentMethodInput as a4, type SetPaymentMethodResult as a5, type RefundSubscriptionInput as a6, type RefundResult as a7, type SteamSubscriptionInitInput as a8, type SteamInitResult as a9, type ItemHistoryQuery as aA, type ItemHistoryResult as aB, type ItemOrderQuery as aC, type PlayerBalanceQuery as aD, type PlayerBalanceResult as aE, type InboundPendingQuery as aF, type InboundPendingResult as aG, type LinkedIdentitiesQuery as aH, type LinkedIdentitiesResult as aI, type SmsVerifyResult as aJ, type ClaimTransferInput as aK, type ClaimResult as aL, type ClaimCurrencyInput as aM, type TransactionStatusResult as aN, type GuardianApprovalStatusResult as aO, type ServerDestinationsQuery as aP, type PhoneShareContact as aQ, type PhoneShareInitiateResult as aR, type PhoneShareApproveInput as aS, type PhoneShareApproveResult as aT, type PhoneShareStatusResult as aU, type BeginDeviceApprovalInput as aV, type DeviceApprovalGrant as aW, type PollDeviceApprovalInput as aX, type DeviceApprovalPollResult as aY, type ConfirmDeviceEnrollmentInput as aZ, type ConfirmDeviceEnrollmentResult as a_, type SteamFinalizeSubscriptionResult as aa, type SandboxClockResult as ab, type SandboxFailureOutcome as ac, type SandboxForceFailureOptions as ad, type SandboxForceAuthChallengeOptions as ae, type ServerConfig as af, type PlayerToken as ag, type InitiateSendInput as ah, type InitiateResult as ai, type InitiateTransferInput as aj, type CreateCheckoutInput as ak, type CreateCheckoutResult as al, type PurchaseInput as am, type PurchaseResult as an, type CurrencyPurchaseQuoteInput as ao, type CurrencyPurchaseQuote as ap, type ConfirmPaymentResult as aq, type OrderDetailsResult as ar, type SteamPacksQuery as as, type SteamPacksResult as at, type SteamInitPurchaseInput as au, type SteamInitPurchaseResult as av, type SteamFinalizeInput as aw, type SteamFinalizeResult as ax, type PurchaseItemInput as ay, type PurchaseItemResult as az, type PurchaseExpired as b, type DeviceApprovalSettleResult as b0, type CompleteDeviceApprovalInput as b1, type CompleteDeviceApprovalResult as b2, type CardSetupStatus as b3, type CurrencyBalance as b4, type CurrencyPurchaseQuoteBreakdown as b5, type DeviceApprovalChannel as b6, type DeviceApprovalEnrollment as b7, type DeviceApprovalFlow as b8, type DeviceApprovalPollStatus as b9, type SubscriptionRevenueShareInput as bA, type SubscriptionStatus as bB, type UnacknowledgedPurchaseOutcome as bC, isRefundPendingApproval as bD, type DeviceEnrollmentDecision as ba, type DeviceEnrollmentRespond as bb, type FeeTakenFrom as bc, type FirstCharge as bd, type FirstChargeStatus as be, type FundingSource as bf, type InboundPendingItem as bg, type LinkedIdentityEmail as bh, type PlatformPurchaseStatus as bi, type RefundInitiation as bj, type RefundPendingApproval as bk, type RefundProcessingFeeBasis as bl, type RefundReceipt as bm, type RefundRevenueShareAttribution as bn, type RefundWarning as bo, type SandboxClockState as bp, type SavedCard as bq, type SteamPack as br, type SteamUserSession as bs, type Subscription as bt, type SubscriptionBaseInput as bu, type SubscriptionConsent as bv, type SubscriptionConsentInput as bw, type SubscriptionFundingRail as bx, type SubscriptionInterval as by, type SubscriptionRevenueShare as bz, type PurchaseRefunded as c, type PurchaseRefused as d, type CheckoutClientConfig as e, type PurchaseStatusInput as f, type CallOptions as g, type CheckoutMountHandle as h, type ClientConfig as i, type PendingCollectResult as j, type DestinationsResult as k, type EnrollmentVerifyResult as l, type RecoveryCompleteResult as m, type BalanceRow as n, type CheckoutPurchaseStatus as o, type DestinationGame as p, type InvoErrorInfo as q, type InvoHooks as r, type InvoRequestInfo as s, type InvoResponseInfo as t, type PendingCollectItem as u, type PurchaseRefusalReason as v, type Rail as w, type AuthHeader as x, type CardSetupSessionInput as y, type CardSetupSessionResult as z };