@owlmeans/server-payment 0.1.18-rc.11 → 0.1.18-rc.13

package/src/plugins/fx.ts

@@ -0,0 +1,93 @@
+import type Stripe from 'stripe'
+import { PaygateError } from '@owlmeans/payment'
+import type { Context as ApiContext } from '@owlmeans/server-api'
+import { STRIPE_FX_QUOTES_API_VERSION } from '../consts.js'
+import { stripePricingConfig } from '../utils.js'
+
+interface FxQuoteResponse {
+  rates?: Record<string, {
+    exchange_rate?: number
+    rate_details?: { base_rate?: number; fx_fee_rate?: number; reference_rate?: number }
+  }>
+}
+
+export interface StripeFxRate {
+  fromCurrency: string
+  toCurrency: string
+  /** Stripe's fee-inclusive conversion rate. */
+  exchangeRate: number
+  /** Market/reference rate used to translate catalogue value into settlement value. */
+  referenceRate: number
+  fxFeeRate?: number
+}
+
+/** One unlocked Stripe FX quote. `toCurrency` units per one `fromCurrency` unit. */
+export const stripeFxRate = async (
+  stripe: Stripe, fromCurrency: string, toCurrency: string, apiVersion: string,
+): Promise<StripeFxRate | null> => {
+  const from = fromCurrency.toLowerCase()
+  const to = toCurrency.toLowerCase()
+  if (from === to) return { fromCurrency: from, toCurrency: to, exchangeRate: 1, referenceRate: 1 }
+  const response = await stripe.rawRequest(
+    'POST', '/v1/fx_quotes',
+    { to_currency: to, 'from_currencies[]': from, lock_duration: 'none' },
+    { apiVersion },
+  ) as Stripe.Response<FxQuoteResponse>
+  const rate = response.rates?.[from]
+  if (rate?.exchange_rate == null) return null
+  return {
+    fromCurrency: from,
+    toCurrency: to,
+    exchangeRate: rate.exchange_rate,
+    referenceRate: rate.rate_details?.reference_rate ?? rate.rate_details?.base_rate ?? rate.exchange_rate,
+    ...(rate.rate_details?.fx_fee_rate != null ? { fxFeeRate: rate.rate_details.fx_fee_rate } : {}),
+  }
+}
+
+/** Convert whole source minor units at the reference rate, rounding up so value is never lost. */
+export const convertMinor = (amountMinor: number, rate: number): number => {
+  const converted = Math.ceil(amountMinor * rate)
+  if (!Number.isSafeInteger(amountMinor) || amountMinor < 0 || !Number.isFinite(rate) || rate <= 0
+    || !Number.isSafeInteger(converted)) {
+    throw new PaygateError('fx-amount')
+  }
+  return converted
+}
+
+export interface SettlementAmount {
+  amountMinor: number
+  currency: string
+  sourceAmountMinor: number
+  sourceCurrency: string
+  referenceRate: number
+}
+
+export type StripeFxRateCache = Map<string, Promise<StripeFxRate | null>>
+
+/** Translate a catalogue amount into the configured Stripe settlement currency. */
+export const settlementAmount = async (
+  ctx: ApiContext, stripe: Stripe, sourceAmountMinor: number, sourceCurrency: string,
+  cache?: StripeFxRateCache,
+): Promise<SettlementAmount> => {
+  const source = sourceCurrency.toLowerCase()
+  const pricing = await stripePricingConfig(ctx)
+  const currency = pricing?.settlementCurrency?.toLowerCase() ?? source
+  if (currency === source) {
+    return {
+      amountMinor: sourceAmountMinor, currency, sourceAmountMinor, sourceCurrency: source, referenceRate: 1,
+    }
+  }
+  const apiVersion = pricing?.fxApiVersion ?? STRIPE_FX_QUOTES_API_VERSION
+  const key = `${source}:${currency}:${apiVersion}`
+  let pending = cache?.get(key)
+  if (pending == null) {
+    pending = stripeFxRate(stripe, source, currency, apiVersion)
+    cache?.set(key, pending)
+  }
+  const quote = await pending
+  if (quote == null) throw new PaygateError(`fx-rate:${source}:${currency}`)
+  return {
+    amountMinor: convertMinor(sourceAmountMinor, quote.referenceRate), currency,
+    sourceAmountMinor, sourceCurrency: source, referenceRate: quote.referenceRate,
+  }
+}

package/src/plugins/portal.ts

@@ -10,7 +10,7 @@ import {
 import { findPlan, findProduct, planRank } from '../plan.js'
 import { planLookupKey, stripePlansOf } from '../sync.js'
 import {
-  fingerprints, isMissingObject, paygateCustomers, portalBrandingConfig, subscriptions,
+  fingerprints, isMissingObject, paygateCustomers, payment, portalBrandingConfig, subscriptions,
 } from '../utils.js'
 import { webhookUrlOf } from './webhook-manager.js'
 import type { PaymentProduct, PaymentSubscriptionRecord, PortalLinkOptions } from '../types.js'
@@ -21,6 +21,10 @@ export const portalFingerprintSku = (service: string): string => `${FINGERPRINT_
 
 /** The recurring plans sold through Stripe, per product — what the portal may switch between. */
 const recurringCatalog = async (ctx: ApiContext): Promise<Array<{ product: PaymentProduct, lookupKeys: string[], hashable: unknown[] }>> => {
+  // The declared tax behavior decides which Stripe price id `sync.ts` keeps for a plan (an
+  // in-place `unspecified` update keeps it, an opposite behavior replaces it) — hashed here too,
+  // so a behavior change refreshes this configuration's `products[].prices` to the new ids.
+  const behavior = (await payment(ctx).pricingPolicy()).tax.behavior ?? null
   const result: Array<{ product: PaymentProduct, lookupKeys: string[], hashable: unknown[] }> = []
   for (const { product, plans } of await stripePlansOf(ctx)) {
     const recurring = plans.filter(plan => plan.recurring != null)
@@ -32,7 +36,7 @@ const recurringCatalog = async (ctx: ApiContext): Promise<Array<{ product: Payme
       lookupKeys: recurring.map(plan => planLookupKey(product, plan)),
       hashable: recurring.map(plan => ({
         sku: plan.sku, price: plan.price, currency: plan.currency ?? 'usd', interval: plan.recurring?.interval,
-        rank: planRank(plan),
+        rank: planRank(plan), behavior,
       })).sort((a, b) => a.sku.localeCompare(b.sku)),
     })
   }

package/src/plugins/stripe.ts

@@ -1,23 +1,42 @@
 import type Stripe from 'stripe'
 import {
   assertCheckoutAmount, chargeAmountMinor, CheckoutPricingMode, PaygateError, ProductError, ProductType,
-  WebhookSetupError,
+  TaxBehavior, WebhookSetupError,
 } from '@owlmeans/payment'
+import type { PricingPolicy } from '@owlmeans/payment'
 import type { Context as ApiContext } from '@owlmeans/server-api'
 import { STRIPE_PAYGATE_ALIAS, STRIPE_SIGNATURE } from '../consts.js'
-import { paygateCustomers, payment } from '../utils.js'
+import { paygateCustomers, payment, stripePricingConfig } from '../utils.js'
 import { isSoldThrough, planLookupKey } from '../sync.js'
 import { createEventHandler } from './events.js'
+import { settlementAmount } from './fx.js'
 import { stripeWebhookSecrets } from './webhook-manager.js'
 import type { CreateLinkParams, PaymentPlan, PaymentProduct } from '../types.js'
 
-const taxOptions = (promotions: boolean): Partial<Stripe.Checkout.SessionCreateParams> => ({
-  automatic_tax: { enabled: true },
-  billing_address_collection: 'required',
-  tax_id_collection: { enabled: true },
-  customer_update: { address: 'auto', name: 'auto' },
-  allow_promotion_codes: promotions,
-})
+/**
+ * A Checkout Session's tax and currency options, entirely driven by the declared `PricingPolicy` —
+ * an undeclared one (`DEFAULT_PRICING_POLICY`) reproduces exactly what every session hard-coded
+ * before this policy existed: automatic tax and tax-id collection on, no Adaptive Pricing.
+ *
+ * `customer_update.address` lets automatic tax use the billing address Checkout just collected
+ * rather than only a previously saved one; `customer_update.name` lets tax-id collection save the
+ * business name it collects. Each is included only for the concern that needs it.
+ */
+const checkoutOptions = (policy: PricingPolicy, promotions: boolean): Partial<Stripe.Checkout.SessionCreateParams> => {
+  const customerUpdate: Stripe.Checkout.SessionCreateParams.CustomerUpdate = {}
+  if (policy.tax.automatic) customerUpdate.address = 'auto'
+  if (policy.tax.collectTaxId) customerUpdate.name = 'auto'
+
+  return {
+    ...(policy.tax.automatic
+      ? { automatic_tax: { enabled: true }, billing_address_collection: 'required' as const }
+      : {}),
+    ...(policy.tax.collectTaxId ? { tax_id_collection: { enabled: true } } : {}),
+    ...(Object.keys(customerUpdate).length > 0 ? { customer_update: customerUpdate } : {}),
+    ...(policy.currency.adaptive === true ? { adaptive_pricing: { enabled: true } } : {}),
+    allow_promotion_codes: promotions,
+  }
+}
 
 const ensureStripeCustomer = async (
   ctx: ApiContext, stripe: Stripe, params: CreateLinkParams,
@@ -72,7 +91,7 @@ const sharedSession = (
 })
 
 export const amountCheckoutLineItem = (
-  product: PaymentProduct, plan: PaymentPlan, amountMinor: number,
+  product: PaymentProduct, plan: PaymentPlan, amountMinor: number, behavior: TaxBehavior = TaxBehavior.Exclusive,
 ): { lineItem: Stripe.Checkout.SessionCreateParams.LineItem; chargeMinor: number; currency: string } => {
   if (plan.amountPolicy == null) throw new ProductError(`amount-policy:${plan.sku}`)
   assertCheckoutAmount(plan.amountPolicy, amountMinor)
@@ -81,7 +100,7 @@ export const amountCheckoutLineItem = (
   return {
     lineItem: {
       price_data: {
-        product: product.sku, currency, unit_amount: chargeMinor, tax_behavior: 'exclusive',
+        product: product.sku, currency, unit_amount: chargeMinor, tax_behavior: behavior,
       },
       quantity: 1,
     },
@@ -110,6 +129,7 @@ export const createCheckoutLink = async (ctx: ApiContext, stripe: Stripe, params
     throw new ProductError(`plan:${params.planSku}`)
   }
   const customer = await ensureStripeCustomer(ctx, stripe, params)
+  const pricing = await payment(ctx).pricingPolicy()
 
   if (product.type === ProductType.Consumable) {
     const plan = plans.find(item => item.sku === params.planSku) ?? plans[0]
@@ -117,15 +137,27 @@ export const createCheckoutLink = async (ctx: ApiContext, stripe: Stripe, params
 
     if (plan.pricingMode === CheckoutPricingMode.Amount) {
       if (params.amountMinor == null) throw new ProductError('amount')
-      const { lineItem, chargeMinor, currency } = amountCheckoutLineItem(product, plan, params.amountMinor)
+      const { chargeMinor: sourceChargeMinor, currency: amountCurrency } = amountCheckoutLineItem(
+        product, plan, params.amountMinor, pricing.tax.behavior,
+      )
+      const settled = await settlementAmount(ctx, stripe, sourceChargeMinor, amountCurrency)
+      const lineItem: Stripe.Checkout.SessionCreateParams.LineItem = {
+        price_data: {
+          product: product.sku, currency: settled.currency, unit_amount: settled.amountMinor,
+          tax_behavior: pricing.tax.behavior,
+        },
+        quantity: 1,
+      }
       const session = await stripe.checkout.sessions.create({
         mode: 'payment', line_items: [lineItem], invoice_creation: { enabled: true },
-        ...taxOptions(false),
+        ...checkoutOptions(pricing, false),
         ...sharedSession(customer, params, product, plan, {
           pricingMode: CheckoutPricingMode.Amount,
-          currency,
+          currency: settled.currency,
+          amountCurrency,
           amountMinor: String(params.amountMinor),
-          chargeAmountMinor: String(chargeMinor),
+          sourceChargeAmountMinor: String(sourceChargeMinor),
+          chargeAmountMinor: String(settled.amountMinor),
         }),
       })
       if (session.url == null) throw new PaygateError('session')
@@ -133,16 +165,16 @@ export const createCheckoutLink = async (ctx: ApiContext, stripe: Stripe, params
     }
 
     const price = await findPrice(stripe, product.sku, planLookupKey(product, plan))
-    const policy = plan.quantityPolicy ?? {
+    const quantityPolicy = plan.quantityPolicy ?? {
       minimum: plan.minQuantity ?? 1,
       maximum: plan.maxQuantity ?? Math.max(100_000, plan.minQuantity ?? 1),
       default: plan.defaultQuantity ?? plan.minQuantity ?? 1,
     }
     const session = await stripe.checkout.sessions.create({
       mode: 'payment',
-      line_items: [quantityCheckoutLineItem(price, policy)],
+      line_items: [quantityCheckoutLineItem(price, quantityPolicy)],
       invoice_creation: { enabled: true },
-      ...taxOptions(true),
+      ...checkoutOptions(pricing, true),
       ...sharedSession(customer, params, product, plan, { pricingMode: CheckoutPricingMode.Quantity }),
     })
     if (session.url == null) throw new PaygateError('session')
@@ -153,15 +185,19 @@ export const createCheckoutLink = async (ctx: ApiContext, stripe: Stripe, params
     ?? plans.find(item => item.recurring != null) ?? plans[0]
   if (plan == null) throw new ProductError('plan')
   const price = await findPrice(stripe, product.sku, planLookupKey(product, plan))
+  const subscriptionPaymentMethodTypes = (
+    await stripePricingConfig(ctx)
+  )?.subscriptionPaymentMethodTypes as Stripe.Checkout.SessionCreateParams.PaymentMethodType[] | undefined
   const session = await stripe.checkout.sessions.create({
     mode: 'subscription', line_items: [{ price: price.id, quantity: 1 }],
+    ...(subscriptionPaymentMethodTypes != null ? { payment_method_types: subscriptionPaymentMethodTypes } : {}),
     subscription_data: {
       metadata: {
         pricingMode: CheckoutPricingMode.Quantity, entityId: params.entityId,
         service: params.service, productSku: product.sku, planSku: plan.sku,
       },
     },
-    ...taxOptions(true),
+    ...checkoutOptions(pricing, true),
     ...sharedSession(customer, params, product, plan, {}),
   })
   if (session.url == null) throw new PaygateError('session')

package/src/service.ts

@@ -16,6 +16,7 @@ import { makeLimitGate } from './limit.js'
 import { appendCompletionObserver } from './observer.js'
 import { findPlan, findProduct, planRank } from './plan.js'
 import { resyncStripeSubscription, resyncStripeSubscriptions } from './plugins/events.js'
+import { makeEstimateCache, estimateStripePrice } from './plugins/estimate.js'
 import { createPortalLink, ensurePortalConfiguration } from './plugins/portal.js'
 import { createCheckoutLink } from './plugins/stripe.js'
 import { ensureWebhookEndpoint } from './plugins/webhook-manager.js'
@@ -103,6 +104,9 @@ export const makeGatewayService = (
   alias: string = GATEWAY_SERVICE, opts: Pick<PaymentGatewayOptions, 'manage'> = {},
 ): GatewayService => {
   const managed = opts.manage !== false
+  // One estimate cache per gateway SERVICE instance, never module-level: several service
+  // instances (several tests, several deployments in one process) must never share hits.
+  const estimateCache = makeEstimateCache()
   const service = createService<GatewayService>(alias, {
     managed,
     createLink: async (ctx, params) => managed
@@ -114,6 +118,8 @@ export const makeGatewayService = (
       ? await resyncStripeSubscription(ctx, await stripeClient(ctx), ref) : unmanaged(),
     resyncAll: async ctx => managed
       ? await resyncStripeSubscriptions(ctx, await stripeClient(ctx)) : unmanaged(),
+    estimatePrice: async (ctx, params) => managed
+      ? await estimateStripePrice(ctx, await stripeClient(ctx), params, estimateCache) : unmanaged(),
   }, service => async () => {
     const ctx = service.assertCtx() as unknown as ApiContext
     assertPlanDeclarations(ctx.cfg)

package/src/sync.ts

@@ -1,10 +1,20 @@
 import { createHash } from 'node:crypto'
 import type Stripe from 'stripe'
-import { CheckoutPricingMode, ProductType } from '@owlmeans/payment'
+import { CheckoutPricingMode, ProductType, TaxBehavior } from '@owlmeans/payment'
 import type { Context as ApiContext } from '@owlmeans/server-api'
 import { STRIPE_PAYGATE_ALIAS } from './consts.js'
-import { fingerprints, payment, stripeClient } from './utils.js'
+import { fingerprints, payment, stripeClient, stripePricingConfig } from './utils.js'
 import type { PaymentPlan, PaymentProduct } from './types.js'
+import { settlementAmount } from './plugins/fx.js'
+import type { StripeFxRateCache } from './plugins/fx.js'
+
+interface ResolvedPlan {
+  plan: PaymentPlan
+  unitAmount: number
+  currency: string
+  sourceUnitAmount: number
+  sourceCurrency: string
+}
 
 export const planLookupKey = (product: PaymentProduct, plan: PaymentPlan): string =>
   product.type === ProductType.Consumable ? `${product.sku}-consumable` : plan.sku
@@ -31,14 +41,22 @@ export const stripePlansOf = async (ctx: ApiContext): Promise<Array<{ product: P
   return result
 }
 
-const fingerprintOf = (product: PaymentProduct, plans: PaymentPlan[]): string => createHash('sha256')
+/**
+ * `behavior` is hashed alongside the catalogue: an undeclared policy hashes as `null`, so declaring
+ * or changing `tax.behavior` re-syncs every product exactly once, the same as any other catalogue
+ * edit.
+ */
+const fingerprintOf = (
+  product: PaymentProduct, plans: ResolvedPlan[], behavior: TaxBehavior | null,
+): string => createHash('sha256')
   .update(JSON.stringify({
     sku: product.sku, type: product.type, name: product.title,
     description: product.description ?? null, taxCode: product.taxCode ?? null,
     unitLabel: product.unitLabel ?? null, services: [...(product.services ?? [])].sort(),
-    plans: plans.map(plan => ({
-      sku: plan.sku, price: plan.price, currency: plan.currency ?? 'usd', duration: plan.duration,
-      recurring: plan.recurring ?? null, pricingMode: plan.pricingMode ?? null,
+    behavior,
+    plans: plans.map(({ plan, unitAmount, currency, sourceUnitAmount, sourceCurrency }) => ({
+      sku: plan.sku, price: plan.price, currency, unitAmount, sourceUnitAmount, sourceCurrency,
+      duration: plan.duration, recurring: plan.recurring ?? null, pricingMode: plan.pricingMode ?? null,
       amountPolicy: plan.amountPolicy ?? null, quantityPolicy: plan.quantityPolicy ?? null,
       lookup: planLookupKey(product, plan),
     })).sort((a, b) => a.sku.localeCompare(b.sku)),
@@ -69,21 +87,71 @@ const deactivateAmountPrice = async (stripe: Stripe, product: PaymentProduct, pl
   }
 }
 
-const ensureStripePrice = async (stripe: Stripe, product: PaymentProduct, plan: PaymentPlan): Promise<void> => {
+/** Whether `price` already carries the OPPOSITE of `behavior` — never `unspecified`, which is not a conflict. */
+const opposesBehavior = (price: Stripe.Price, behavior: TaxBehavior | null): boolean =>
+  behavior != null && price.tax_behavior !== 'unspecified' && price.tax_behavior !== behavior
+
+/**
+ * The behavior the Stripe account's own Tax Settings resolve to for `currency`, or `null` when no
+ * default is configured yet (nothing established to disrupt). `inferred_by_currency` follows
+ * Stripe's own rule: exclusive for USD/CAD, inclusive otherwise.
+ */
+const accountDefaultBehavior = async (stripe: Stripe, currency: string): Promise<TaxBehavior | null> => {
+  const { defaults } = await stripe.tax.settings.retrieve()
+  if (defaults.tax_behavior === 'inferred_by_currency') {
+    return ['usd', 'cad'].includes(currency.toLowerCase()) ? TaxBehavior.Exclusive : TaxBehavior.Inclusive
+  }
+  if (defaults.tax_behavior === 'exclusive') return TaxBehavior.Exclusive
+  if (defaults.tax_behavior === 'inclusive') return TaxBehavior.Inclusive
+  return null
+}
+
+/**
+ * Give `price` the declared `behavior` while it is still `unspecified` (the only state Stripe lets
+ * an existing price's `tax_behavior` be set from). Skipped, with a `console.error`, when the
+ * account's own default resolves to the opposite behavior — applying ours would then change what an
+ * existing renewal actually charges — unless `migrateUnspecifiedPrices` opts into that migration.
+ */
+const applyUnspecifiedBehavior = async (
+  stripe: Stripe, price: Stripe.Price, lookupKey: string, behavior: TaxBehavior, migrateUnspecifiedPrices: boolean,
+): Promise<void> => {
+  if (!migrateUnspecifiedPrices) {
+    const resolved = await accountDefaultBehavior(stripe, price.currency)
+    if (resolved != null && resolved !== behavior) {
+      console.error(
+        `[payment] price '${lookupKey}' left 'unspecified': the Stripe account's default tax `
+        + `behavior for ${price.currency.toUpperCase()} is '${resolved}', not the declared `
+        + `'${behavior}' — applying it would change existing renewal amounts. Set `
+        + '`stripe.migrateUnspecifiedPrices` to override.',
+      )
+      return
+    }
+  }
+  await stripe.prices.update(price.id, { tax_behavior: behavior })
+}
+
+const ensureStripePrice = async (
+  stripe: Stripe, product: PaymentProduct, resolved: ResolvedPlan,
+  behavior: TaxBehavior | null, migrateUnspecifiedPrices: boolean,
+): Promise<void> => {
+  const { plan, unitAmount, currency } = resolved
   if (plan.pricingMode === CheckoutPricingMode.Amount) {
     await deactivateAmountPrice(stripe, product, plan)
     return
   }
   const lookupKey = planLookupKey(product, plan)
-  const unitAmount = Math.round(plan.price * 100)
-  const currency = plan.currency ?? 'usd'
   const recurring = plan.recurring != null
     ? { interval: plan.recurring.interval } as Stripe.PriceCreateParams.Recurring : undefined
   const existing = await activePrices(stripe, product)
-  const match = existing.find(price => price.lookup_key === lookupKey && price.unit_amount === unitAmount
+  const candidate = existing.find(price => price.lookup_key === lookupKey && price.unit_amount === unitAmount
     && price.currency === currency
     && ((price.recurring?.interval ?? null) === (recurring?.interval ?? null)))
-  if (match != null) return
+  if (candidate != null && !opposesBehavior(candidate, behavior)) {
+    if (behavior != null && candidate.tax_behavior === 'unspecified') {
+      await applyUnspecifiedBehavior(stripe, candidate, lookupKey, behavior, migrateUnspecifiedPrices)
+    }
+    return
+  }
   for (const price of existing.filter(item => item.lookup_key === lookupKey)) {
     await stripe.prices.update(price.id, { active: false })
   }
@@ -91,6 +159,7 @@ const ensureStripePrice = async (stripe: Stripe, product: PaymentProduct, plan:
     product: product.sku, currency, unit_amount: unitAmount, lookup_key: lookupKey,
     transfer_lookup_key: true, nickname: plan.sku,
     ...(recurring != null ? { recurring } : { billing_scheme: 'per_unit' }),
+    ...(behavior != null ? { tax_behavior: behavior } : {}),
     metadata: { sku: plan.sku, ...(product.services && { services: product.services.join(',') }) },
   })
 }
@@ -99,15 +168,34 @@ const ensureStripePrice = async (stripe: Stripe, product: PaymentProduct, plan:
  * Synchronize every product sold through Stripe, and its Stripe-sold plans, to Stripe products and
  * prices. A product whose declaration fingerprint is unchanged makes no paygate call. Free plans
  * and plans sold through no Stripe gateway are never synchronized.
+ *
+ * The declared `PricingPolicy.tax.behavior` (absent by default, so a price's `tax_behavior` stays
+ * whatever it already was) is applied to a matching price only while it is `unspecified` — Stripe
+ * forbids changing a price once set to `exclusive` or `inclusive` — and to a fresh one on creation.
+ * A price carrying the OPPOSITE behavior is deactivated and replaced, same as any other mismatch.
  */
 export const syncStripeProducts = async (ctx: ApiContext, stripe: Stripe): Promise<void> => {
   const fpRes = fingerprints(ctx)
+  const behavior = (await payment(ctx).pricingPolicy()).tax.behavior ?? null
+  const migrateUnspecifiedPrices = (await stripePricingConfig(ctx))?.migrateUnspecifiedPrices ?? false
+  const fxRates: StripeFxRateCache = new Map()
   for (const { product, plans } of await stripePlansOf(ctx)) {
-    const hash = fingerprintOf(product, plans)
+    const resolvedPlans: ResolvedPlan[] = []
+    for (const plan of plans) {
+      const sourceUnitAmount = Math.round(plan.price * 100)
+      const sourceCurrency = (plan.currency ?? 'usd').toLowerCase()
+      const settled = plan.pricingMode === CheckoutPricingMode.Amount
+        ? { amountMinor: sourceUnitAmount, currency: sourceCurrency }
+        : await settlementAmount(ctx, stripe, sourceUnitAmount, sourceCurrency, fxRates)
+      resolvedPlans.push({ plan, unitAmount: settled.amountMinor, currency: settled.currency, sourceUnitAmount, sourceCurrency })
+    }
+    const hash = fingerprintOf(product, resolvedPlans, behavior)
     const stored = await fpRes.bySku(product.sku)
     if (stored != null && stored.hash === hash) continue
     const stripeProduct = await ensureStripeProduct(stripe, product)
-    for (const plan of plans) await ensureStripePrice(stripe, product, plan)
+    for (const resolved of resolvedPlans) {
+      await ensureStripePrice(stripe, product, resolved, behavior, migrateUnspecifiedPrices)
+    }
     if (stored != null) {
       await fpRes.update({ ...stored, hash, productId: stripeProduct.id, updatedAt: new Date() })
     } else {

package/src/types.ts

@@ -6,8 +6,8 @@ import type { PermissionSet } from '@owlmeans/auth'
 import type { Config as ApiConfig, Context as ApiContext } from '@owlmeans/server-api'
 import type {
   AmountCheckoutPolicy, CheckoutPricingMode, EntitlementView, LimitDeclaration, LimitView,
-  PlanCapability, PlanDuration, PortalFlow, Product, ProductPlan, ProductType, QuantityCheckoutPolicy,
-  SubscriptionStatus,
+  PlanCapability, PlanDuration, PortalFlow, PriceEstimate, PricingPolicy, Product, ProductPlan,
+  ProductType, QuantityCheckoutPolicy, SubscriptionStatus,
 } from '@owlmeans/payment'
 
 export interface Config extends ApiConfig {}
@@ -76,6 +76,32 @@ export interface PaymentPlanDef {
 export interface StripeSecretsDef { api: string; webhook?: string }
 export interface StripePluginConfig extends PluginConfig { api: string; webhook?: string }
 
+/** Stripe-only pricing settings — never a browser-visible field (see `PricingPolicy` for those). */
+export interface StripePricingDef {
+  /** Overrides `STRIPE_FX_QUOTES_API_VERSION`, when Stripe moves or renames the preview. */
+  fxApiVersion?: string
+  /**
+   * Stripe settlement currency used when a catalogue price is declared in another currency.
+   * Recurring prices are converted during product sync; amount checkout is converted per session.
+   */
+  settlementCurrency?: string
+  /** Explicit Stripe payment methods for subscription Checkout; absent keeps Stripe's dynamic selection. */
+  subscriptionPaymentMethodTypes?: string[]
+  /**
+   * Let a matching `unspecified` price take the declared `tax.behavior` even when the Stripe
+   * account's own tax-settings default resolves to the opposite one — which changes what an
+   * existing subscriber is charged at their next renewal. Absent/`false`: such a price is left
+   * `unspecified` and a `console.error` explains why.
+   */
+  migrateUnspecifiedPrices?: boolean
+}
+export interface StripePricingPluginConfig extends PluginConfig, StripePricingDef {}
+
+/** `declarePaymentPricing`'s argument: the browser-safe `PricingPolicy` plus Stripe-only settings. */
+export interface PricingDef extends PricingPolicy {
+  stripe?: StripePricingDef
+}
+
 /** What the managed customer portal configuration shows. */
 export interface PortalBrandingDef {
   headline?: string
@@ -109,6 +135,16 @@ export interface PortalLinkOptions {
   returnUrl: string
 }
 
+export interface PriceEstimateParams {
+  productSku: string
+  /** Stable database key resolved by the application before this in-process call. */
+  entityId: string
+  /** Absent: the product's own reference plan (an amount-priced consumable). */
+  planSku?: string
+  /** ISO 3166-1 alpha-2. Absent: taken from the entity's paygate customer address. */
+  country?: string
+}
+
 export interface GrantInternalPlanOptions {
   /** Required to grant a plan that is not `free`. */
   force?: boolean
@@ -127,6 +163,8 @@ export interface GatewayService extends InitializedService {
   managed: boolean
   createLink: (ctx: ApiContext, params: CreateLinkParams) => Promise<string>
   portalLink: (ctx: ApiContext, entityId: string, opts: PortalLinkOptions) => Promise<string>
+  /** @throws PaygateError('unmanaged') when `managed` is `false`. */
+  estimatePrice: (ctx: ApiContext, params: PriceEstimateParams) => Promise<PriceEstimate>
   grantInternalPlan: (
     ctx: ApiContext, entityId: string, planSku: string, opts?: GrantInternalPlanOptions,
   ) => Promise<PaymentSubscriptionRecord>
@@ -167,8 +205,15 @@ export interface QuantityTopUpCompletion extends TopUpBase {
 }
 export interface AmountTopUpCompletion extends TopUpBase {
   mode: 'amount'
+  /** Net value in the amount policy's catalogue currency. */
   amountMinor: number
+  /** Grossed-up value in the amount policy's catalogue currency, before settlement conversion. */
+  sourceChargeAmountMinor: number
+  /** The amount policy's catalogue currency. */
+  amountCurrency: string
+  /** Pre-tax subtotal actually charged by Stripe, in `currency`. */
   chargeAmountMinor: number
+  /** Stripe integration/settlement currency. */
   currency: string
 }
 export type TopUpCompletion = QuantityTopUpCompletion | AmountTopUpCompletion
@@ -369,6 +414,8 @@ export interface PaymentFulfillmentRecord extends ResourceRecord {
   mode: CheckoutPricingMode
   units?: number
   amountMinor?: number
+  sourceChargeAmountMinor?: number
+  amountCurrency?: string
   chargeAmountMinor?: number
   currency?: string
   createdAt: Date

package/src/utils.ts

@@ -7,13 +7,13 @@ import type { Context as ApiContext } from '@owlmeans/server-api'
 import {
   ENTITLEMENT_SERVICE, GATEWAY_SERVICE, PAYMENT_OBSERVER, RES_PAYGATE_CUSTOMER, RES_PAYMENT_FINGERPRINT,
   RES_PAYMENT_FULFILLMENT, RES_PAYMENT_SUBSCRIPTION, RES_PAYMENT_USAGE, RES_PAYMENT_USAGE_COUNTER,
-  RES_PAYMENT_WEBHOOK, STRIPE_PLUGIN_CONFIG, STRIPE_PORTAL_PLUGIN_CONFIG,
+  RES_PAYMENT_WEBHOOK, STRIPE_PLUGIN_CONFIG, STRIPE_PORTAL_PLUGIN_CONFIG, STRIPE_PRICING_PLUGIN_CONFIG,
 } from './consts.js'
 import type {
   CompletionObserver, EntitlementService, FingerprintResource, GatewayService, PaygateCustomerResource,
   PaymentFulfillmentResource, PaymentSubscriptionRecord, PaymentSubscriptionResource,
   PaymentUsageCounterResource, PaymentUsageResource, PaymentWebhookResource, PortalBrandingConfig,
-  StripePluginConfig,
+  StripePluginConfig, StripePricingPluginConfig,
 } from './types.js'
 
 export const payment = (ctx: ApiContext): PaymentService => ctx.service<PaymentService>(PAYMENT_SERVICE)
@@ -49,6 +49,10 @@ export const stripeConfig = async (ctx: ApiContext): Promise<StripePluginConfig>
 export const portalBrandingConfig = async (ctx: ApiContext): Promise<PortalBrandingConfig | null> =>
   await (ctx as never as PluginReader).getConfigResource(PLUGINS).load(STRIPE_PORTAL_PLUGIN_CONFIG) as PortalBrandingConfig | null
 
+/** The Stripe-only pricing settings declared with `declarePaymentPricing`, or `null`. */
+export const stripePricingConfig = async (ctx: ApiContext): Promise<StripePricingPluginConfig | null> =>
+  await (ctx as never as PluginReader).getConfigResource(PLUGINS).load(STRIPE_PRICING_PLUGIN_CONFIG) as StripePricingPluginConfig | null
+
 /**
  * A Stripe client pinned to the API version the installed SDK is typed for (its default), so every
  * object shape this package reads is the one the types describe.