@owlmeans/server-payment 0.1.18-rc.20 → 0.1.18-rc.21

package/src/plugins/checkout-plugins.ts

@@ -0,0 +1,155 @@
+import { CheckoutLimitExceeded, narrowAmountPolicy } from '@owlmeans/payment'
+import type { AmountNarrowing, AmountPolicyView } from '@owlmeans/payment'
+import type { Context as ApiContext } from '@owlmeans/server-api'
+import { STRIPE_SESSION_TTL_MAX_SECONDS, STRIPE_SESSION_TTL_MIN_SECONDS } from '../consts.js'
+import type {
+  CheckoutAttempt, CheckoutNarrowInput, CheckoutPlugin, CheckoutSettled,
+} from '../types.js'
+
+export interface CheckoutPluginRegistry {
+  use: (plugin: CheckoutPlugin) => void
+  list: () => readonly CheckoutPlugin[]
+}
+
+/**
+ * The gateway's checkout plugins, the way `ExecutionService.use` seats its own: a plugin with an
+ * alias already registered replaces it in place (a layer wired twice must not answer twice), one
+ * without an alias is appended.
+ */
+export const makeCheckoutPluginRegistry = (): CheckoutPluginRegistry => {
+  const plugins: CheckoutPlugin[] = []
+
+  return {
+    use: plugin => {
+      const at = plugin.alias != null ? plugins.findIndex(entry => entry.alias === plugin.alias) : -1
+      if (at < 0) {
+        plugins.push(plugin)
+      } else {
+        plugins[at] = plugin
+      }
+    },
+    list: () => [...plugins],
+  }
+}
+
+/**
+ * An entity's amount policy as every plugin narrows it now — the ONE computation both
+ * `gateway.amountPolicy` and checkout enforcement use, so a control and a refusal cannot disagree.
+ * A plugin's error propagates: a narrowing that cannot be computed fails closed.
+ */
+export const narrowAmountFor = async (
+  ctx: ApiContext, plugins: readonly CheckoutPlugin[], input: CheckoutNarrowInput,
+): Promise<AmountPolicyView> => {
+  const narrowings: AmountNarrowing[] = []
+  for (const plugin of plugins) {
+    if (plugin.narrow == null) {
+      continue
+    }
+    const narrowing = await plugin.narrow(ctx, input)
+    if (narrowing != null) {
+      narrowings.push(narrowing)
+    }
+  }
+
+  return narrowAmountPolicy(input.base, narrowings, {
+    productSku: input.productSku, ...(input.planSku != null ? { planSku: input.planSku } : {}),
+  })
+}
+
+/**
+ * Refuse an amount the narrowed view does not allow: any amount while `blocked`, else one above
+ * the narrowed maximum.
+ *
+ * @throws CheckoutLimitExceeded (409)
+ */
+export const assertAmountAllowed = (view: AmountPolicyView, amountMinor: number): void => {
+  const limit = view.limit
+  if (limit == null || (!limit.blocked && amountMinor <= limit.maximumMinor)) {
+    return
+  }
+  throw new CheckoutLimitExceeded({
+    reason: limit.reason ?? 'limit', maximumMinor: limit.maximumMinor, currency: limit.currency,
+    ...(limit.resetsAt != null ? { resetsAt: limit.resetsAt } : {}),
+  })
+}
+
+/**
+ * The session lifetime: the smallest `sessionTtlSeconds` any plugin declares, clamped to Stripe's
+ * 30 minutes – 24 hours; `undefined` when none declares one (Stripe's own default).
+ */
+export const sessionTtlOf = (plugins: readonly CheckoutPlugin[]): number | undefined => {
+  const declared = plugins
+    .map(plugin => plugin.sessionTtlSeconds)
+    .filter((ttl): ttl is number => typeof ttl === 'number' && Number.isFinite(ttl))
+  if (declared.length === 0) {
+    return undefined
+  }
+
+  return Math.min(STRIPE_SESSION_TTL_MAX_SECONDS, Math.max(STRIPE_SESSION_TTL_MIN_SECONDS, Math.floor(Math.min(...declared))))
+}
+
+/** A plugin that admitted an attempt, with the reservation it holds. */
+export interface Admitted {
+  plugin: CheckoutPlugin
+  reservationId?: string
+}
+
+/**
+ * Tell plugins how a checkout ended. A plugin's error is logged, never raised: a hold carries its
+ * own TTL, and the webhook that reports the outcome must not be redelivered for it.
+ */
+export const settleCheckout = async (
+  ctx: ApiContext, plugins: readonly CheckoutPlugin[], settled: CheckoutSettled,
+): Promise<void> => {
+  for (const plugin of plugins) {
+    if (plugin.settled == null) {
+      continue
+    }
+    try {
+      await plugin.settled(ctx, settled)
+    } catch (error) {
+      console.error(`[payment] checkout plugin "${plugin.alias ?? 'anonymous'}" failed to settle`, error)
+    }
+  }
+}
+
+/** Release what admitted plugins hold for a checkout that never became usable. */
+export const releaseAdmitted = async (
+  ctx: ApiContext, admitted: readonly Admitted[], attempt: CheckoutAttempt, sessionId?: string,
+): Promise<void> => {
+  for (const { plugin, reservationId } of admitted) {
+    await settleCheckout(ctx, [plugin], {
+      entityId: attempt.entityId, productSku: attempt.productSku,
+      ...(attempt.planSku != null ? { planSku: attempt.planSku } : {}),
+      ...(sessionId != null ? { sessionId } : {}),
+      ...(reservationId != null ? { reservationId } : {}),
+      ...(attempt.amountMinor != null ? { amountMinor: attempt.amountMinor } : {}),
+      outcome: 'failed', at: new Date(),
+    })
+  }
+}
+
+/**
+ * Ask every plugin to admit the attempt, in order. A veto releases what the earlier plugins
+ * admitted and propagates.
+ */
+export const admitCheckout = async (
+  ctx: ApiContext, plugins: readonly CheckoutPlugin[], attempt: CheckoutAttempt,
+): Promise<Admitted[]> => {
+  const admitted: Admitted[] = []
+  for (const plugin of plugins) {
+    if (plugin.admit == null) {
+      admitted.push({ plugin })
+      continue
+    }
+    try {
+      const admission = await plugin.admit(ctx, attempt)
+      admitted.push({ plugin, ...(admission?.reservationId != null ? { reservationId: admission.reservationId } : {}) })
+    } catch (error) {
+      await releaseAdmitted(ctx, admitted.filter(entry => entry.plugin.admit != null), attempt)
+      throw error
+    }
+  }
+
+  return admitted
+}

package/src/plugins/estimate.ts

@@ -1,14 +1,16 @@
 import type Stripe from 'stripe'
 import {
-  chargeAmountMinor, CheckoutPricingMode, currencyOfCountry, ProductError, ratePpmOf, TaxBehavior,
-  TaxEstimateStatus, TaxType, UnknownProduct,
+  chargeAmountMinor, chargeCurrencyOf, CheckoutPricingMode, currencyOfCountry, ProductError, ratePpmOf,
+  regionOf, TaxBehavior, TaxEstimateStatus, TaxType, UnknownProduct,
 } from '@owlmeans/payment'
 import type { PriceEstimate, TaxEstimate, TaxRateEstimate } from '@owlmeans/payment'
 import type { Context as ApiContext } from '@owlmeans/server-api'
 import { STRIPE_FX_QUOTES_API_VERSION, STRIPE_PAYGATE_ALIAS } from '../consts.js'
 import { findProduct } from '../plan.js'
 import { isSoldThrough } from '../sync.js'
-import { isMissingObject, paygateCustomers, payment, stripePricingConfig } from '../utils.js'
+import {
+  consumerRightsOf, fingerprints, isMissingObject, paygateCustomers, payment, stripePricingConfig,
+} from '../utils.js'
 import type { PaymentPlan, PaymentProduct, PriceEstimateParams } from '../types.js'
 import { stripeFxRate } from './fx.js'
 
@@ -158,6 +160,30 @@ const referenceOf = (plan: PaymentPlan): { subtotalMinor: number; currency: stri
   return { subtotalMinor: Math.round(plan.price * 100), currency: (plan.currency ?? 'usd').toLowerCase() }
 }
 
+/**
+ * The reference amount in the currency the buyer is charged in: a recurring or quantity plan's
+ * synced price in that currency (its default or an option — no paygate call), else the plan's own
+ * catalogue reference. An amount plan keeps its policy currency.
+ */
+const chargedReferenceOf = async (
+  ctx: ApiContext, product: PaymentProduct, plan: PaymentPlan, chargeCurrency: string | null,
+): Promise<{ subtotalMinor: number; currency: string }> => {
+  const reference = referenceOf(plan)
+  if (chargeCurrency == null || plan.pricingMode === CheckoutPricingMode.Amount || chargeCurrency === reference.currency && plan.currencyPrices == null) {
+    return reference
+  }
+  const synced = (await fingerprints(ctx).bySku(product.sku))?.prices?.find(price => price.planSku === plan.sku)
+  if (synced == null) {
+    return reference
+  }
+  if (synced.currency === chargeCurrency) {
+    return { subtotalMinor: synced.unitAmount, currency: chargeCurrency }
+  }
+  const option = synced.options.find(entry => entry.currency === chargeCurrency)
+
+  return option != null ? { subtotalMinor: option.unitAmount, currency: chargeCurrency } : reference
+}
+
 /** A placeholder estimate — no known tax, shown by its `status`, never by its zeroed numbers. */
 const unresolvedEstimate = (status: TaxEstimateStatus, subtotalMinor: number): TaxEstimate => ({
   status, subtotalMinor, taxMinor: 0, totalMinor: subtotalMinor, scalable: false, rates: [],
@@ -214,10 +240,13 @@ export const estimateStripePrice = async (
 
   const pricing = await payment(ctx).pricingPolicy()
   const behavior = pricing.tax.behavior ?? TaxBehavior.Exclusive
-  const { subtotalMinor, currency } = referenceOf(plan)
+  const rights = await payment(ctx).consumerRightsPolicy()
+  // A locked billing country overrides whatever the request names: a picker shows it, locked.
+  const profile = rights != null ? await consumerRightsOf(ctx)?.profile(params.entityId) ?? null : null
+  const locked = profile?.locked === true && profile.country != null
 
-  let country = params.country?.toUpperCase()
-  let source: 'request' | 'customer' | undefined = country != null ? 'request' : undefined
+  let country = locked ? profile.country as string : params.country?.toUpperCase()
+  let source: 'request' | 'customer' | 'profile' | undefined = locked ? 'profile' : country != null ? 'request' : undefined
   let matchingTaxIds: Array<{ type: string; value: string }> = []
   let taxabilityOverride: 'customer_exempt' | 'reverse_charge' | undefined
 
@@ -236,8 +265,16 @@ export const estimateStripePrice = async (
     }
   }
 
+  const region = rights != null ? regionOf(country, rights) : null
+  const settlementCurrency = (await stripePricingConfig(ctx))?.settlementCurrency?.toLowerCase()
+  const { subtotalMinor, currency } = await chargedReferenceOf(ctx, product, plan, rights != null && rights.currencies != null
+    && Object.keys(rights.currencies).length > 0
+    ? (profile?.currency ?? chargeCurrencyOf(region, rights, settlementCurrency ?? (plan.currency ?? 'usd'))).toLowerCase()
+    : null)
+  const where = { ...(region != null ? { region } : {}), ...(locked ? { locked: true } : {}) }
+
   if (country == null) {
-    return { currency, behavior, tax: unresolvedEstimate(TaxEstimateStatus.LocationRequired, subtotalMinor) }
+    return { currency, behavior, tax: unresolvedEstimate(TaxEstimateStatus.LocationRequired, subtotalMinor), ...where }
   }
 
   const cacheKey = JSON.stringify([
@@ -276,9 +313,12 @@ export const estimateStripePrice = async (
     ? taxEstimateOf(outcome.calculation, behavior, subtotalMinor)
     : unresolvedEstimate(TaxEstimateStatus.AtCheckout, subtotalMinor)
 
-  const result: PriceEstimate = { country, source, currency, behavior, tax }
+  const result: PriceEstimate = { country, source, currency, behavior, tax, ...where }
+  // Adaptive Pricing — and so a local-currency line — applies only to a session charged in the
+  // settlement currency; a forced region currency (exact USD) is shown as it is.
+  const adaptive = rights?.currencies == null || currency === (settlementCurrency ?? currency)
 
-  if (pricing.currency.estimate && pricing.currency.adaptive === true) {
+  if (pricing.currency.estimate && pricing.currency.adaptive === true && adaptive) {
     const localCurrency = currencyOfCountry(country)
     if (localCurrency != null && localCurrency !== currency) {
       const stripePricing = await stripePricingConfig(ctx)

package/src/plugins/events.ts

@@ -1,21 +1,27 @@
 import type Stripe from 'stripe'
 import { Mutex } from 'async-mutex'
 import {
-  CheckoutPricingMode, PaygateError, SubscriptionStatus, TERMINAL_STATUSES,
+  CheckoutPricingMode, ENTITLING_STATUSES, PaygateError, SubscriptionStatus, TERMINAL_STATUSES,
 } from '@owlmeans/payment'
 import type { Context as ApiContext } from '@owlmeans/server-api'
-import { STRIPE_PAYGATE_ALIAS } from '../consts.js'
+import { GATEWAY_SERVICE, STRIPE_PAYGATE_ALIAS } from '../consts.js'
 import { findPlan, planRank } from '../plan.js'
 import { commitSubscription } from '../subscription.js'
 import type { CommitResult } from '../subscription.js'
 import {
-  compact, dateOf, fulfillments, idOf, isDuplicateKey, isMissingObject, observer, paygateCustomers,
-  subscriptions,
+  compact, dateOf, fulfillments, gateway, idOf, isDuplicateKey, isMissingObject, observer, paygateCustomers,
+  purchases, subscriptions,
 } from '../utils.js'
+import {
+  capturePaymentPurchase, captureSubscriptionPurchase, completeSubscriptionPurchase, sessionEvidenceOf,
+} from '../consumer/capture.js'
+import { patchPurchase, purchaseIdOf } from '../consumer/records.js'
+import { settleCheckout } from './checkout-plugins.js'
 import { resolvePaymentTarget, retrieveCharge } from './refunds.js'
 import type { PaymentTarget } from './refunds.js'
 import type {
-  DisputePhase, PaymentFulfillmentRecord, PaymentSubscriptionRecord, SubscriptionRef, TopUpCompletion,
+  CheckoutOutcome, CheckoutPlugin, DisputePhase, PaymentFulfillmentRecord, PaymentSubscriptionRecord,
+  SubscriptionRef, TopUpCompletion,
 } from '../types.js'
 
 const customerMutex: Record<string, Mutex> = {}
@@ -82,6 +88,8 @@ export interface ApplyOptions {
   trialEnding?: boolean
   /** Store this status whatever the payload says (a deleted subscription is canceled). */
   forced?: SubscriptionStatus
+  /** The paygate client — lets the first commit read the first invoice for its purchase row. */
+  stripe?: Stripe
 }
 
 const secondsFloor = (at: Date): Date => new Date(Math.floor(at.getTime() / 1000) * 1000)
@@ -152,6 +160,7 @@ export const applySubscription = async (
     trialEnd: dateOf(subscription.trial_end),
     latestInvoiceId: opts.invoiceId ?? idOf(subscription.latest_invoice) ?? previous?.latestInvoiceId,
     customerId,
+    currency: subscription.currency?.toLowerCase() ?? previous?.currency,
     createdAt: previous?.createdAt ?? dateOf(subscription.created) ?? now,
     updatedAt: now,
     syncedAt,
@@ -160,6 +169,12 @@ export const applySubscription = async (
 
   return await commitSubscription(ctx, previous, next, {
     eventId: opts.eventId, renewal: opts.renewal, invoiceId: opts.invoiceId, trialEnding: opts.trialEnding,
+    // The first invoice is a purchase: its window exists before an observer grants the bundle.
+    beforePropagate: async (record, change) => {
+      if (change === 'created') {
+        await captureSubscriptionPurchase(ctx, opts.stripe ?? null, subscription, record)
+      }
+    },
   })
 }
 
@@ -211,7 +226,7 @@ export const resyncStripeSubscription = async (
     const subscription = await retrieveSubscription(stripe, id)
     const customerId = subscription != null ? idOf(subscription.customer) : undefined
     const result = await withCustomerLock(customerId, async () => subscription != null
-      ? await applySubscription(ctx, subscription, { source: 'resync' })
+      ? await applySubscription(ctx, subscription, { source: 'resync', stripe })
       : await cancelMissing(ctx, id))
     if (result.updated) {
       updated++
@@ -267,6 +282,11 @@ const DISPUTE_PHASES: Record<string, DisputePhase> = {
 
 type EventHandler = (event: Stripe.Event) => Promise<void>
 
+/** The registered checkout plugins — none in a context without a gateway service. */
+const checkoutPluginsOf = (ctx: ApiContext): readonly CheckoutPlugin[] =>
+  (ctx as unknown as { hasService?: (alias: string) => boolean }).hasService?.(GATEWAY_SERVICE) === true
+    ? gateway(ctx).checkoutPlugins?.() ?? [] : []
+
 /**
  * The Stripe event dispatch table. `process` runs the handler of an event type and ignores every
  * other type; a throw escapes so Stripe delivers the event again.
@@ -279,6 +299,8 @@ export const createEventHandler = (ctx: ApiContext, stripe: Stripe) => {
       const data = compact({
         email: customer.email ?? undefined, name: customer.name ?? undefined,
         taxId: customer.tax_ids?.data?.[0]?.value ?? undefined,
+        country: customer.address?.country?.toUpperCase() ?? undefined,
+        currency: customer.currency?.toLowerCase() ?? undefined,
         entityId: customer.metadata?.entityId ?? existing?.entityId ?? undefined,
         profileId: customer.metadata?.profileId ?? existing?.profileId ?? undefined,
       })
@@ -303,7 +325,22 @@ export const createEventHandler = (ctx: ApiContext, stripe: Stripe) => {
     }
   }
 
+  const settle = async (session: Stripe.Checkout.Session, outcome: CheckoutOutcome, entityId?: string): Promise<void> => {
+    const metadata = session.metadata ?? {}
+    const owner = entityId ?? metadata.entityId
+    if (owner == null) return
+    const amount = Number(metadata.amountMinor)
+    await settleCheckout(ctx, checkoutPluginsOf(ctx), compact({
+      entityId: owner, productSku: metadata.productSku, planSku: metadata.planSku, sessionId: session.id, outcome,
+      amountMinor: Number.isSafeInteger(amount) && amount > 0 ? amount : undefined, at: new Date(),
+    }))
+  }
+
   const fulfillPayment = async (session: Stripe.Checkout.Session): Promise<void> => {
+    if (session.mode === 'subscription') {
+      await completeSubscriptionCheckout(session)
+      return
+    }
     if (session.mode !== 'payment' || session.payment_status !== 'paid') return
     const metadata = session.metadata ?? {}
     if (metadata.entityId == null || metadata.service == null || metadata.productSku == null) {
@@ -353,23 +390,90 @@ export const createEventHandler = (ctx: ApiContext, stripe: Stripe) => {
         completion = { ...base, mode: 'quantity', units }
       }
 
+      // The purchase — the withdrawal window and the contract — exists BEFORE the credits do; the
+      // billing country is locked with it.
+      const captured = await capturePaymentPurchase(ctx, stripe, session, compact({
+        netAmountMinor: completion.mode === 'amount' ? completion.amountMinor : undefined,
+        amountCurrency: completion.mode === 'amount' ? completion.amountCurrency : undefined,
+        units: completion.mode === 'quantity' ? completion.units : undefined,
+      }))
+      const evidence = sessionEvidenceOf(session)
       const identifiers = compact({
         paymentIntentId: idOf(session.payment_intent), invoiceId: idOf(session.invoice),
       })
+      const evidenceFields = compact({
+        country: evidence.country, email: evidence.email, profileId: metadata.profileId,
+        amountTotalMinor: session.amount_total ?? undefined, amountTaxMinor: session.total_details?.amount_tax ?? undefined,
+        termsAccepted: evidence.termsAccepted, purchaseId: captured?.purchase.purchaseId,
+      })
       if (stored == null) {
         try {
-          stored = await ledger.create(compact({ ...base, ...record, ...identifiers, createdAt: new Date() }) as PaymentFulfillmentRecord)
+          stored = await ledger.create(compact({ ...base, ...record, ...identifiers, ...evidenceFields, createdAt: new Date() }) as PaymentFulfillmentRecord)
         } catch (error) {
           if (!isDuplicateKey(error)) throw error
           stored = await ledger.byExternalId(session.id, STRIPE_PAYGATE_ALIAS)
           if (stored == null || stored.fulfilledAt != null) return
         }
-      } else if (stored.paymentIntentId == null && identifiers.paymentIntentId != null) {
-        stored = await ledger.update({ ...stored, ...identifiers })
+      } else if ((stored.paymentIntentId == null && identifiers.paymentIntentId != null)
+        || (stored.purchaseId == null && evidenceFields.purchaseId != null)) {
+        stored = await ledger.update({ ...stored, ...identifiers, ...evidenceFields })
       }
       await observer(ctx).propagateTopUp(completion, ctx)
       await ledger.update({ ...stored, fulfilledAt: new Date() })
     })
+    await settle(session, 'paid')
+  }
+
+  /**
+   * A completed SUBSCRIPTION checkout: the subscription is applied if no webhook applied it yet
+   * (its first commit writes the purchase before the `created` observers), then the purchase is
+   * refined with the buyer's own country and totals, the billing country is locked, the evidence is
+   * stored on the subscription row and the confirmation mailed.
+   */
+  const completeSubscriptionCheckout = async (session: Stripe.Checkout.Session): Promise<void> => {
+    if (session.payment_status !== 'paid' && session.payment_status !== 'no_payment_required') return
+    const subscriptionId = idOf(session.subscription)
+    if (subscriptionId == null) return
+    await withCustomerLock(idOf(session.customer), async () => {
+      let row = await subscriptions(ctx).byExternalId(subscriptionId, STRIPE_PAYGATE_ALIAS)
+      let subscription: Stripe.Subscription | null = null
+      if (row?.propagated == null) {
+        subscription = await retrieveSubscription(stripe, subscriptionId)
+        if (subscription != null) {
+          row = (await applySubscription(ctx, subscription, { source: 'webhook', stripe })).record ?? row
+        }
+      }
+      if (row == null) {
+        console.warn(`[payment] completed checkout "${session.id}" names an unknown subscription "${subscriptionId}"`)
+        return
+      }
+      let purchase = await purchases(ctx).byPurchaseId(purchaseIdOf(subscriptionId))
+      if (purchase == null && ENTITLING_STATUSES.includes(row.status)) {
+        subscription = subscription ?? await retrieveSubscription(stripe, subscriptionId)
+        purchase = subscription != null
+          ? (await captureSubscriptionPurchase(ctx, stripe, subscription, row))?.purchase ?? null : null
+      }
+      if (purchase != null) {
+        purchase = await completeSubscriptionPurchase(ctx, stripe, session, purchase)
+      }
+      const evidence = sessionEvidenceOf(session)
+      const metadata = session.metadata ?? {}
+      const current = await subscriptions(ctx).byExternalId(subscriptionId, STRIPE_PAYGATE_ALIAS) ?? row
+      await subscriptions(ctx).update(compact({
+        ...current,
+        checkoutSessionId: session.id,
+        purchaseId: purchase?.purchaseId ?? current.purchaseId,
+        firstInvoiceId: current.firstInvoiceId ?? idOf(session.invoice),
+        currency: current.currency ?? (evidence.currency !== '' ? evidence.currency : undefined),
+        country: evidence.country ?? current.country,
+        email: evidence.email ?? current.email,
+        amountTotalMinor: evidence.totalMinor,
+        amountTaxMinor: evidence.taxMinor,
+        termsAccepted: evidence.termsAccepted ?? current.termsAccepted,
+        startRequestId: metadata.startRequestId ?? purchase?.startRequestId ?? current.startRequestId,
+      }))
+    })
+    await settle(session, 'paid')
   }
 
   const checkoutFailed = async (session: Stripe.Checkout.Session): Promise<void> => {
@@ -403,17 +507,19 @@ export const createEventHandler = (ctx: ApiContext, stripe: Stripe) => {
       entityId, kind: 'checkout' as const, externalId: session.id,
       subscriptionId: idOf(session.subscription), eventKey: `payment-failed:${session.id}:0`,
     }), ctx)
+    await settle(session, 'failed', entityId)
   }
 
   const purgeExpiredCheckout = async (session: Stripe.Checkout.Session): Promise<void> => {
     await fulfillments(ctx).purge({ paygate: STRIPE_PAYGATE_ALIAS, externalId: session.id, fulfilledAt: null })
+    await settle(session, 'expired')
   }
 
   const applyFromEvent = (opts: Partial<ApplyOptions> = {}): EventHandler => async event => {
     const subscription = event.data.object as Stripe.Subscription
     await withCustomerLock(idOf(subscription.customer), async () => {
       await applySubscription(ctx, subscription, {
-        source: 'webhook', eventId: event.id, eventCreated: event.created, ...opts,
+        source: 'webhook', eventId: event.id, eventCreated: event.created, stripe, ...opts,
       })
     })
   }
@@ -429,7 +535,7 @@ export const createEventHandler = (ctx: ApiContext, stripe: Stripe) => {
     }
 
     return await withCustomerLock(idOf(subscription.customer), async () =>
-      await applySubscription(ctx, subscription, { source: 'webhook', eventId: event.id, ...opts }))
+      await applySubscription(ctx, subscription, { source: 'webhook', eventId: event.id, stripe, ...opts }))
   }
 
   const invoicePaid: EventHandler = async event => {
@@ -488,6 +594,19 @@ export const createEventHandler = (ctx: ApiContext, stripe: Stripe) => {
       planSku: target.record.planSku, externalId: target.record.externalId,
     })
 
+  /** A refund of a purchase's payment moves its refunded total; a whole refund closes its window. */
+  const refundPurchase = async (target: PaymentTarget, refundedTotal: number, paid: number | undefined): Promise<void> => {
+    const purchaseId = purchaseIdOf(target.record.externalId)
+    const purchase = await purchases(ctx).byPurchaseId(purchaseId)
+    if (purchase == null || (target.kind === 'subscription' && purchase.invoiceId != null && purchase.invoiceId !== target.invoiceId)) {
+      return
+    }
+    await patchPurchase(ctx, purchaseId, compact({
+      refundedMinor: Math.max(purchase.refundedMinor ?? 0, refundedTotal),
+      refundedAt: purchase.refundedAt ?? (paid != null && refundedTotal >= paid ? new Date() : undefined),
+    }))
+  }
+
   const processRefund = async (refund: Stripe.Refund, charge?: Stripe.Charge | null): Promise<void> => {
     if (refund.status !== 'succeeded') return
     const target = await resolvePaymentTarget(ctx, stripe, {
@@ -507,6 +626,8 @@ export const createEventHandler = (ctx: ApiContext, stripe: Stripe) => {
         refundedAt: new Date(), chargeId: target.record.chargeId ?? refunded?.id,
       }))
     }
+    await refundPurchase(target, refundedTotal, paid)
+    const metadata = { ...(refund.metadata ?? {}) } as Record<string, string>
     await observer(ctx).propagateRefund(compact({
       ...targetFields(target),
       refundId: refund.id,
@@ -518,6 +639,9 @@ export const createEventHandler = (ctx: ApiContext, stripe: Stripe) => {
       currency: refund.currency,
       partial: paid != null ? refundedTotal < paid : false,
       eventKey: `refund:${refund.id}`,
+      metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
+      // Set by a withdrawal's own refund: its observer takes back the unused units, `onRefund` must not.
+      withdrawalId: metadata.withdrawalId != null && metadata.withdrawalId !== '' ? metadata.withdrawalId : undefined,
     }) as Parameters<ReturnType<typeof observer>['propagateRefund']>[0], ctx)
   }
 

package/src/plugins/fx.ts

@@ -64,6 +64,35 @@ export interface SettlementAmount {
 
 export type StripeFxRateCache = Map<string, Promise<StripeFxRate | null>>
 
+/**
+ * A catalogue amount in the currency the buyer is charged in: unchanged — no FX call — when the
+ * currencies are equal; otherwise converted at Stripe's FX reference rate, rounded up.
+ */
+export const chargeAmount = async (
+  ctx: ApiContext, stripe: Stripe, sourceAmountMinor: number, sourceCurrency: string, chargeCurrency: string,
+  cache?: StripeFxRateCache,
+): Promise<SettlementAmount> => {
+  const source = sourceCurrency.toLowerCase()
+  const currency = chargeCurrency.toLowerCase()
+  if (currency === source) {
+    return { amountMinor: sourceAmountMinor, currency, sourceAmountMinor, sourceCurrency: source, referenceRate: 1 }
+  }
+  const apiVersion = (await stripePricingConfig(ctx))?.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,
+  }
+}
+
 /** Translate a catalogue amount into the configured Stripe settlement currency. */
 export const settlementAmount = async (
   ctx: ApiContext, stripe: Stripe, sourceAmountMinor: number, sourceCurrency: string,

package/src/plugins/portal.ts

@@ -37,6 +37,8 @@ const recurringCatalog = async (ctx: ApiContext): Promise<Array<{ product: Payme
       hashable: recurring.map(plan => ({
         sku: plan.sku, price: plan.price, currency: plan.currency ?? 'usd', interval: plan.recurring?.interval,
         rank: planRank(plan), behavior,
+        // A changed currency option replaces the Price — the portal's price list must follow it.
+        ...(plan.currencyPrices != null ? { currencyPrices: plan.currencyPrices } : {}),
       })).sort((a, b) => a.sku.localeCompare(b.sku)),
     })
   }
@@ -114,9 +116,15 @@ export const ensurePortalConfiguration = async (
   const sku = portalFingerprintSku(service)
   const branding = await portalBrandingConfig(ctx)
   const catalog = await recurringCatalog(ctx)
+  const rights = await payment(ctx).consumerRightsPolicy()
+  // A locked billing country is never edited in the portal: tax follows the saved address.
+  const countryLock = rights?.mechanisms.countryLock === true
+  const regionCurrencies = Object.values(rights?.currencies ?? {}).filter(code => code != null).sort()
   const hash = createHash('sha256').update(JSON.stringify({
     service,
     deployment,
+    ...(countryLock ? { countryLock } : {}),
+    ...(regionCurrencies.length > 0 ? { regionCurrencies } : {}),
     branding: branding != null ? {
       headline: branding.headline ?? null, privacyPolicyUrl: branding.privacyPolicyUrl ?? null,
       termsOfServiceUrl: branding.termsOfServiceUrl ?? null, returnUrl: branding.returnUrl ?? null,
@@ -141,7 +149,9 @@ export const ensurePortalConfiguration = async (
   const metadata = { [STRIPE_OWNER_KEY]: STRIPE_OWNER_VALUE, service, [STRIPE_DEPLOYMENT_KEY]: deployment }
   const params: ConfigurationParams = {
     features: {
-      customer_update: { enabled: true, allowed_updates: ['email', 'address', 'tax_id'] },
+      customer_update: {
+        enabled: true, allowed_updates: countryLock ? ['email', 'tax_id'] : ['email', 'address', 'tax_id'],
+      },
       invoice_history: { enabled: true },
       payment_method_update: { enabled: true },
       subscription_cancel: cancelable