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

package/tests/checkout.spec.ts

@@ -1,11 +1,14 @@
 import { describe, expect, test } from 'bun:test'
-import { CheckoutPricingMode, PlanDuration, PlanStatus, ProductError, ProductType } from '@owlmeans/payment'
+import { CheckoutPricingMode, PlanDuration, PlanStatus, ProductError, ProductType, TaxBehavior } from '@owlmeans/payment'
 import { createEventHandler } from '../src/plugins/events.js'
 import { amountCheckoutLineItem, createCheckoutLink, quantityCheckoutLineItem } from '../src/plugins/stripe.js'
 import type { PaymentPlan, PaymentProduct } from '../src/types.js'
-import { CREDITS_PRODUCT, FREE, makeFakeContext, PLANS_PRODUCT, TEAM } from './fake-stripe.js'
+import { CREDITS_PRODUCT, FREE, makeFakeContext, PLANS_PRODUCT, PRO, TEAM } from './fake-stripe.js'
 import type { FakeContext } from './fake-stripe.js'
 
+const proPrice = { id: 'price_pro', product: PLANS_PRODUCT, lookup_key: PRO, active: true, recurring: { interval: 'month' } }
+const successUrl = 'https://app.example.com/ok'
+
 const product: PaymentProduct = {
   type: ProductType.Consumable, sku: 'credits', title: 'Credits', services: ['app'],
 }
@@ -71,7 +74,103 @@ describe('Stripe checkout', () => {
   })
 })
 
+describe('Stripe checkout — pricing policy', () => {
+  test('an undeclared policy reproduces exactly the session hard-coded before this policy existed', async () => {
+    const fake = await makeFakeContext({ stripe: { prices: [proPrice] } })
+    await createCheckoutLink(fake.ctx, fake.stripe, {
+      productSku: PLANS_PRODUCT, planSku: PRO, entityId: 'entity-1', service: 'app', successUrl,
+    })
+    const session = fake.state.checkoutSessions[0]
+    expect(session).toEqual(expect.objectContaining({
+      automatic_tax: { enabled: true }, billing_address_collection: 'required',
+      tax_id_collection: { enabled: true }, customer_update: { address: 'auto', name: 'auto' },
+    }))
+    expect(session.adaptive_pricing).toBeUndefined()
+  })
+
+  test('tax.automatic and tax.collectTaxId are independent switches', async () => {
+    const fake = await makeFakeContext({
+      pricing: { tax: { automatic: false, collectTaxId: true, estimate: false }, currency: { estimate: false } },
+      stripe: { prices: [proPrice] },
+    })
+    await createCheckoutLink(fake.ctx, fake.stripe, {
+      productSku: PLANS_PRODUCT, planSku: PRO, entityId: 'entity-1', service: 'app', successUrl,
+    })
+    const session = fake.state.checkoutSessions[0]
+    expect(session.automatic_tax).toBeUndefined()
+    expect(session.billing_address_collection).toBeUndefined()
+    expect(session.tax_id_collection).toEqual({ enabled: true })
+    // only the concern that needs it contributes a `customer_update` field
+    expect(session.customer_update).toEqual({ name: 'auto' })
+  })
+
+  test('adaptive_pricing appears on the session only when currency.adaptive is declared', async () => {
+    const fake = await makeFakeContext({
+      pricing: { tax: { automatic: true, collectTaxId: true, estimate: false }, currency: { adaptive: true, estimate: false } },
+      stripe: { prices: [proPrice] },
+    })
+    await createCheckoutLink(fake.ctx, fake.stripe, {
+      productSku: PLANS_PRODUCT, planSku: PRO, entityId: 'entity-1', service: 'app', successUrl,
+    })
+    expect(fake.state.checkoutSessions[0].adaptive_pricing).toEqual({ enabled: true })
+  })
+
+  test('subscription checkout can explicitly offer recurring-capable payment methods', async () => {
+    const fake = await makeFakeContext({
+      pricing: {
+        tax: { automatic: true, collectTaxId: true, estimate: false }, currency: { estimate: false },
+        stripe: { subscriptionPaymentMethodTypes: ['CARD', 'link', 'klarna'] },
+      },
+      stripe: { prices: [proPrice] },
+    })
+    await createCheckoutLink(fake.ctx, fake.stripe, {
+      productSku: PLANS_PRODUCT, planSku: PRO, entityId: 'entity-1', service: 'app', successUrl,
+    })
+    expect(fake.state.checkoutSessions[0].payment_method_types).toEqual(['card', 'link', 'klarna'])
+  })
+
+  test('a declared behavior is set on the inline amount line item', async () => {
+    const fake = await makeFakeContext({
+      pricing: { tax: { automatic: true, collectTaxId: true, estimate: false, behavior: TaxBehavior.Inclusive }, currency: { estimate: false } },
+    })
+    await createCheckoutLink(fake.ctx, fake.stripe, {
+      productSku: CREDITS_PRODUCT, entityId: 'entity-1', service: 'app', amountMinor: 1_000, successUrl,
+    })
+    expect(fake.state.checkoutSessions[0].line_items[0].price_data.tax_behavior).toBe('inclusive')
+  })
+
+  test('an amount checkout converts the USD catalogue charge to the settlement currency', async () => {
+    const fake = await makeFakeContext({
+      pricing: {
+        tax: { automatic: true, collectTaxId: true, estimate: false },
+        currency: { adaptive: true, estimate: false }, stripe: { settlementCurrency: 'EUR' },
+      },
+      stripe: { fxRates: { usd: { exchangeRate: 0.853568, referenceRate: 0.8726 } } },
+    })
+    await createCheckoutLink(fake.ctx, fake.stripe, {
+      productSku: CREDITS_PRODUCT, entityId: 'entity-1', service: 'app', amountMinor: 1_000, successUrl,
+    })
+    const session = fake.state.checkoutSessions[0]
+    expect(session.line_items[0].price_data).toEqual(expect.objectContaining({ currency: 'eur', unit_amount: 891 }))
+    expect(session.metadata).toEqual(expect.objectContaining({
+      amountMinor: '1000', sourceChargeAmountMinor: '1021', amountCurrency: 'usd',
+      chargeAmountMinor: '891', currency: 'eur',
+    }))
+    expect(fake.state.rawRequests[0]).toEqual(expect.objectContaining({
+      params: { to_currency: 'eur', 'from_currencies[]': 'usd', lock_duration: 'none' },
+    }))
+  })
+})
+
 describe('Stripe checkout fulfillment', () => {
+  test('fulfills a paid amount once even when the session carries Adaptive Pricing presentment details', async () => {
+    const fake = await makeFakeContext()
+    await process(fake, 'checkout.session.completed', paid({
+      presentment_details: { presentment_amount: 4_613, presentment_currency: 'eur' },
+    }))
+    expect(fake.observed.topUp).toEqual([expect.objectContaining({ amountMinor: 1_000, chargeAmountMinor: 1_021 })])
+  })
+
   test('fulfills a paid amount once, without crediting the adjustment, and records the payment intent', async () => {
     const fake = await makeFakeContext()
     await process(fake, 'checkout.session.completed', paid())
@@ -86,6 +185,23 @@ describe('Stripe checkout fulfillment', () => {
     expect(fake.stores['payment-subscription'].rows).toHaveLength(0)
   })
 
+  test('fulfills the USD credit value from an EUR settlement charge', async () => {
+    const fake = await makeFakeContext()
+    await process(fake, 'checkout.session.completed', paid({
+      currency: 'eur', amount_subtotal: 891,
+      metadata: {
+        pricingMode: 'amount', amountMinor: '1000', sourceChargeAmountMinor: '1021', amountCurrency: 'usd',
+        chargeAmountMinor: '891', currency: 'eur', entityId: 'entity-1', service: 'app',
+        productSku: CREDITS_PRODUCT, planSku: 'app-credit-unit',
+      },
+    }))
+    expect(fake.observed.topUp[0]).toEqual(expect.objectContaining({
+      amountMinor: 1_000, sourceChargeAmountMinor: 1_021, amountCurrency: 'usd',
+      chargeAmountMinor: 891, currency: 'eur',
+    }))
+    expect(fulfillment(fake)[0]).toEqual(expect.objectContaining({ amountCurrency: 'usd', currency: 'eur' }))
+  })
+
   test('grants nothing for an unpaid completion; the asynchronous success does', async () => {
     const fake = await makeFakeContext()
     await process(fake, 'checkout.session.completed', paid({ payment_status: 'unpaid' }))

package/tests/estimate.spec.ts

@@ -0,0 +1,240 @@
+import { describe, expect, test } from 'bun:test'
+import { PaygateError, TaxBehavior, TaxEstimateStatus, TaxType } from '@owlmeans/payment'
+import { makeEstimateCache, estimateStripePrice } from '../src/plugins/estimate.js'
+import { gateway, paygateCustomers } from '../src/utils.js'
+import { CREDITS_PRODUCT, makeFakeContext, PLANS_PRODUCT, PRO } from './fake-stripe.js'
+import type { FakeContext } from './fake-stripe.js'
+
+const withCustomer = async (
+  fake: FakeContext, entityId: string, country: string, taxIds: Array<{ type: string, value: string, country: string }> = [],
+  taxExempt: string = 'none',
+) => {
+  await paygateCustomers(fake.ctx).create({ paygate: 'stripe', externalId: `cus_${entityId}`, entityId })
+  fake.state.customers[`cus_${entityId}`] = {
+    id: `cus_${entityId}`, object: 'customer', address: { country }, tax_exempt: taxExempt,
+    tax_ids: { object: 'list', data: taxIds },
+  }
+}
+
+const estimatingPolicy = { tax: { automatic: true, collectTaxId: true, estimate: true }, currency: { adaptive: true, estimate: true } }
+
+describe('@owlmeans/server-payment — Stripe Tax price estimate', () => {
+  test('taxes the reference amount of a recurring plan at a given country, half-cent rounded up', async () => {
+    const fake = await makeFakeContext({
+      pricing: estimatingPolicy, stripe: { taxRates: { PL: [{ type: 'vat', percentage: '23' }] } },
+    })
+    const cache = makeEstimateCache()
+    const result = await estimateStripePrice(fake.ctx, fake.stripe, {
+      entityId: 'entity-1', productSku: PLANS_PRODUCT, planSku: PRO, country: 'PL',
+    }, cache)
+    expect(result).toEqual(expect.objectContaining({
+      country: 'PL', source: 'request', currency: 'usd', behavior: TaxBehavior.Exclusive,
+    }))
+    expect(result.tax).toEqual({
+      status: TaxEstimateStatus.Taxed, subtotalMinor: 2_000, taxMinor: 460, totalMinor: 2_460,
+      scalable: true, rates: [{ type: TaxType.Vat, percentage: '23', ratePpm: 230_000, country: 'PL' }],
+    })
+  })
+
+  test('taxes an amount-priced consumable at its default preset, gross-up included', async () => {
+    const fake = await makeFakeContext({
+      pricing: estimatingPolicy, stripe: { taxRates: { PL: [{ type: 'vat', percentage: '23' }] } },
+    })
+    const cache = makeEstimateCache()
+    const result = await estimateStripePrice(fake.ctx, fake.stripe, {
+      entityId: 'entity-1', productSku: CREDITS_PRODUCT, country: 'PL',
+    }, cache)
+    // the credit unit's default preset is 1_000, grossed up to 1_021 by its own amount policy
+    expect(result.tax.subtotalMinor).toBe(1_021)
+    expect(result.tax.taxMinor).toBe(235)
+    expect(result.tax.totalMinor).toBe(1_256)
+  })
+
+  test('no request country and no paygate customer: `location-required`, zero Stripe calls', async () => {
+    const fake = await makeFakeContext({ pricing: estimatingPolicy })
+    const cache = makeEstimateCache()
+    const result = await estimateStripePrice(fake.ctx, fake.stripe, {
+      entityId: 'unknown-entity', productSku: PLANS_PRODUCT, planSku: PRO,
+    }, cache)
+    expect(result.tax.status).toBe(TaxEstimateStatus.LocationRequired)
+    expect(fake.state.calls).not.toContain('tax.calculations.create')
+  })
+
+  test("falls back to the entity's paygate customer address, tagged `source: 'customer'`", async () => {
+    const fake = await makeFakeContext({
+      pricing: estimatingPolicy, stripe: { taxRates: { DE: [{ type: 'vat', percentage: '19' }] } },
+    })
+    await withCustomer(fake, 'entity-1', 'DE')
+    const result = await estimateStripePrice(fake.ctx, fake.stripe, {
+      entityId: 'entity-1', productSku: PLANS_PRODUCT, planSku: PRO,
+    }, makeEstimateCache())
+    expect(result.country).toBe('DE')
+    expect(result.source).toBe('customer')
+    expect(result.tax.status).toBe(TaxEstimateStatus.Taxed)
+  })
+
+  test('a saved tax id for a DIFFERENT country than the resolved one is never sent', async () => {
+    const fake = await makeFakeContext({
+      pricing: estimatingPolicy, stripe: { taxRates: { PL: [{ type: 'vat', percentage: '23' }] } },
+    })
+    await withCustomer(fake, 'entity-1', 'PL', [{ type: 'eu_vat', value: 'DE123456789', country: 'DE' }])
+    const result = await estimateStripePrice(fake.ctx, fake.stripe, {
+      entityId: 'entity-1', productSku: PLANS_PRODUCT, planSku: PRO,
+    }, makeEstimateCache())
+    // taxed, not reverse-charged — the DE tax id never reached the calculation
+    expect(result.tax.status).toBe(TaxEstimateStatus.Taxed)
+    expect(fake.state.taxCalculations[0].customer_details.tax_ids).toBeUndefined()
+  })
+
+  test('a matching-country tax id triggers reverse charge, with zero tax', async () => {
+    const fake = await makeFakeContext({
+      pricing: estimatingPolicy, stripe: { taxRates: { DE: [{ type: 'vat', percentage: '19' }] } },
+    })
+    await withCustomer(fake, 'entity-1', 'DE', [{ type: 'eu_vat', value: 'DE123456789', country: 'DE' }])
+    const result = await estimateStripePrice(fake.ctx, fake.stripe, {
+      entityId: 'entity-1', productSku: PLANS_PRODUCT, planSku: PRO,
+    }, makeEstimateCache())
+    expect(result.tax.status).toBe(TaxEstimateStatus.ReverseCharge)
+    expect(result.tax.taxMinor).toBe(0)
+    expect(result.tax.totalMinor).toBe(2_000)
+  })
+
+  test('an unconfigured country (no registration) reads `none`', async () => {
+    const fake = await makeFakeContext({ pricing: estimatingPolicy })
+    const result = await estimateStripePrice(fake.ctx, fake.stripe, {
+      entityId: 'entity-1', productSku: PLANS_PRODUCT, planSku: PRO, country: 'FR',
+    }, makeEstimateCache())
+    expect(result.tax.status).toBe(TaxEstimateStatus.None)
+    expect(result.tax.taxMinor).toBe(0)
+  })
+
+  test('a jurisdiction Stripe Tax does not cover reads `at-checkout`', async () => {
+    const fake = await makeFakeContext({ pricing: estimatingPolicy, stripe: { taxUnsupportedCountries: ['CU'] } })
+    const result = await estimateStripePrice(fake.ctx, fake.stripe, {
+      entityId: 'entity-1', productSku: PLANS_PRODUCT, planSku: PRO, country: 'CU',
+    }, makeEstimateCache())
+    expect(result.tax.status).toBe(TaxEstimateStatus.AtCheckout)
+  })
+
+  test('a Stripe invalid-request error (e.g. US missing a postal code) reads `at-checkout`, and the outcome is cached', async () => {
+    const fake = await makeFakeContext({ pricing: estimatingPolicy, stripe: { taxInvalidCountries: ['US'] } })
+    const cache = makeEstimateCache()
+    const first = await estimateStripePrice(fake.ctx, fake.stripe, {
+      entityId: 'entity-1', productSku: PLANS_PRODUCT, planSku: PRO, country: 'US',
+    }, cache)
+    expect(first.tax.status).toBe(TaxEstimateStatus.AtCheckout)
+    const callsAfterFirst = fake.state.calls.filter(name => name === 'tax.calculations.create').length
+    await estimateStripePrice(fake.ctx, fake.stripe, {
+      entityId: 'entity-1', productSku: PLANS_PRODUCT, planSku: PRO, country: 'US',
+    }, cache)
+    expect(fake.state.calls.filter(name => name === 'tax.calculations.create')).toHaveLength(callsAfterFirst)
+  })
+
+  test('an identical request within the cache TTL makes exactly one Stripe Tax call; a different entity with its own tax id makes another', async () => {
+    const fake = await makeFakeContext({ pricing: estimatingPolicy, stripe: { taxRates: { PL: [{ type: 'vat', percentage: '23' }] } } })
+    const cache = makeEstimateCache()
+    const params = { entityId: 'entity-1', productSku: PLANS_PRODUCT, planSku: PRO, country: 'PL' }
+    await estimateStripePrice(fake.ctx, fake.stripe, params, cache)
+    await estimateStripePrice(fake.ctx, fake.stripe, params, cache)
+    expect(fake.state.taxCalculations).toHaveLength(1)
+
+    await withCustomer(fake, 'entity-2', 'PL', [{ type: 'eu_vat', value: 'PL123456789', country: 'PL' }])
+    await estimateStripePrice(fake.ctx, fake.stripe, { ...params, entityId: 'entity-2' }, cache)
+    expect(fake.state.taxCalculations).toHaveLength(2)
+  })
+
+  test('never caches a rate-limit or connection error', async () => {
+    let fail = true
+    const fake = await makeFakeContext({ pricing: estimatingPolicy, stripe: { taxRates: { PL: [{ type: 'vat', percentage: '23' }] } } })
+    const cache = makeEstimateCache()
+    const original = (fake.stripe as never as { tax: { calculations: { create: (...args: unknown[]) => unknown } } })
+      .tax.calculations.create
+    ;(fake.stripe as never as { tax: { calculations: { create: (...args: unknown[]) => unknown } } })
+      .tax.calculations.create = async (...args: unknown[]) => {
+        if (fail) { fail = false; throw new Error('connection reset') }
+        return await original(...args)
+      }
+    const params = { entityId: 'entity-1', productSku: PLANS_PRODUCT, planSku: PRO, country: 'PL' }
+    await expect(estimateStripePrice(fake.ctx, fake.stripe, params, cache)).rejects.toThrow('connection reset')
+    const result = await estimateStripePrice(fake.ctx, fake.stripe, params, cache)
+    expect(result.tax.status).toBe(TaxEstimateStatus.Taxed)
+  })
+
+  test('carries a local-currency conversion from the FX Quotes API, requested to_currency=usd from_currencies=[local]', async () => {
+    const fake = await makeFakeContext({
+      pricing: estimatingPolicy,
+      stripe: { taxRates: { PL: [{ type: 'vat', percentage: '23' }] }, fxRates: { pln: { exchangeRate: 0.25, fxFeeRate: 0.02 } } },
+    })
+    const result = await estimateStripePrice(fake.ctx, fake.stripe, {
+      entityId: 'entity-1', productSku: PLANS_PRODUCT, planSku: PRO, country: 'PL',
+    }, makeEstimateCache())
+    expect(result.local).toEqual({ currency: 'pln', exchangeRate: 0.25, fxFeeRate: 0.02 })
+    expect(fake.state.rawRequests[0]).toEqual(expect.objectContaining({
+      method: 'POST', path: '/v1/fx_quotes', params: { to_currency: 'usd', 'from_currencies[]': 'pln', lock_duration: 'none' },
+    }))
+  })
+
+  test('estimates the same USD to EUR to local chain used by settlement and Adaptive Pricing', async () => {
+    const fake = await makeFakeContext({
+      pricing: { ...estimatingPolicy, stripe: { settlementCurrency: 'eur' } },
+      stripe: {
+        taxRates: { PL: [{ type: 'vat', percentage: '23' }] },
+        fxRates: {
+          usd: { exchangeRate: 0.853568, referenceRate: 0.8726 },
+          pln: { exchangeRate: 0.22, referenceRate: 0.224, fxFeeRate: 0.02 },
+        },
+      },
+    })
+    const result = await estimateStripePrice(fake.ctx, fake.stripe, {
+      entityId: 'entity-1', productSku: PLANS_PRODUCT, planSku: PRO, country: 'PL',
+    }, makeEstimateCache())
+    expect(result.local?.currency).toBe('pln')
+    expect(result.local?.exchangeRate).toBeCloseTo(0.22 / 0.8726)
+    expect(fake.state.rawRequests.map(request => request.params)).toEqual([
+      { to_currency: 'eur', 'from_currencies[]': 'usd', lock_duration: 'none' },
+      { to_currency: 'eur', 'from_currencies[]': 'pln', lock_duration: 'none' },
+    ])
+  })
+
+  test('omits `local` when the FX Quotes call fails, without failing the estimate', async () => {
+    const fake = await makeFakeContext({
+      pricing: estimatingPolicy, stripe: { taxRates: { PL: [{ type: 'vat', percentage: '23' }] }, fxUnavailable: true },
+    })
+    const result = await estimateStripePrice(fake.ctx, fake.stripe, {
+      entityId: 'entity-1', productSku: PLANS_PRODUCT, planSku: PRO, country: 'PL',
+    }, makeEstimateCache())
+    expect(result.tax.status).toBe(TaxEstimateStatus.Taxed)
+    expect(result.local).toBeUndefined()
+  })
+
+  test('omits `local` for a US billing country (same currency as the integration currency), with no FX call', async () => {
+    const fake = await makeFakeContext({ pricing: estimatingPolicy })
+    const result = await estimateStripePrice(fake.ctx, fake.stripe, {
+      entityId: 'entity-1', productSku: PLANS_PRODUCT, planSku: PRO, country: 'US',
+    }, makeEstimateCache())
+    expect(result.local).toBeUndefined()
+    expect(fake.state.rawRequests).toHaveLength(0)
+  })
+
+  test('`currency.estimate: false` never computes a local total, even with `currency.adaptive: true`', async () => {
+    const fake = await makeFakeContext({
+      pricing: {
+        tax: { automatic: true, collectTaxId: true, estimate: true },
+        currency: { adaptive: true, estimate: false },
+      },
+      stripe: { taxRates: { PL: [{ type: 'vat', percentage: '23' }] }, fxRates: { pln: { exchangeRate: 0.25 } } },
+    })
+    const result = await estimateStripePrice(fake.ctx, fake.stripe, {
+      entityId: 'entity-1', productSku: PLANS_PRODUCT, planSku: PRO, country: 'PL',
+    }, makeEstimateCache())
+    expect(result.local).toBeUndefined()
+    expect(fake.state.rawRequests).toHaveLength(0)
+  })
+
+  test('an unmanaged gateway throws PaygateError before ever reaching Stripe', async () => {
+    const fake = await makeFakeContext({ pricing: estimatingPolicy })
+    await expect(gateway(fake.ctx).estimatePrice(fake.ctx, {
+      entityId: 'entity-1', productSku: PLANS_PRODUCT, planSku: PRO,
+    })).rejects.toBeInstanceOf(PaygateError)
+  })
+})

package/tests/events.spec.ts

@@ -127,6 +127,19 @@ describe('@owlmeans/server-payment — subscription events', () => {
     expect(changes(fake)).toEqual(['created'])
   })
 
+  test("resolves the plan from the price's `metadata.sku` when a replaced price carries no lookup key", async () => {
+    const fake = await makeFakeContext()
+    const replaced = {
+      ...subscriptionOf(),
+      items: {
+        object: 'list', has_more: false, url: '',
+        data: [{ id: 'si_1', price: { id: 'price_new', lookup_key: null, metadata: { sku: PRO } } }],
+      },
+    } as never
+    await send(fake, 'customer.subscription.updated', replaced)
+    expect(rows(fake)[0]).toEqual(expect.objectContaining({ planSku: PRO, priceId: 'price_new' }))
+  })
+
   test('plan changes and cancel scheduling are classified with stable keys', async () => {
     const fake = await makeFakeContext()
     await subscribe(fake)

package/tests/fake-stripe.ts

@@ -11,7 +11,7 @@ import type { Criteria, ListOptions, ResourceRecord } from '@owlmeans/resource'
 import type { MongoResource } from '@owlmeans/mongo-resource'
 import type { Context as ApiContext } from '@owlmeans/server-api'
 import {
-  declarePaymentPlan, declarePaymentProduct, portalBranding, stripeSecrets,
+  declarePaymentPlan, declarePaymentPricing, declarePaymentProduct, portalBranding, stripeSecrets,
 } from '../src/config.js'
 import {
   RES_PAYGATE_CUSTOMER, RES_PAYMENT_FINGERPRINT, RES_PAYMENT_FULFILLMENT, RES_PAYMENT_SUBSCRIPTION,
@@ -24,7 +24,7 @@ import {
 import { appendPaymentGatewayService } from '../src/service.js'
 import { observer } from '../src/utils.js'
 import type {
-  Config, DisputeEvent, PaymentFailedEvent, PaymentPlanDef, PortalBrandingDef, RefundEvent,
+  Config, DisputeEvent, PaymentFailedEvent, PaymentPlanDef, PortalBrandingDef, PricingDef, RefundEvent,
   SubscriptionEvent, TopUpCompletion,
 } from '../src/types.js'
 
@@ -139,6 +139,21 @@ export interface FakeStripeState {
   customers: Record<string, Rec>
   lineItemQuantity: number
   seq: number
+  /** Every `tax.calculations.create` params, in call order. */
+  taxCalculations: Rec[]
+  /** Flat-percentage rates a country charges (uppercase alpha-2). Absent/empty: `not_collecting`. */
+  taxRates: Record<string, Array<{ type: string, percentage: string }>>
+  /** Countries whose calculation throws `customer_tax_location_invalid` (simulates a missing ZIP). */
+  taxInvalidCountries: string[]
+  /** Countries Stripe Tax does not cover: a `not_supported`, zero-tax breakdown row. */
+  taxUnsupportedCountries: string[]
+  taxSettings: Rec
+  /** Every `rawRequest` call, in order: `{ method, path, params }`. */
+  rawRequests: Rec[]
+  /** FX Quotes rates by lowercase source currency. */
+  fxRates: Record<string, { exchangeRate: number, baseRate?: number, referenceRate?: number, fxFeeRate?: number }>
+  /** Every `rawRequest` to `/v1/fx_quotes` throws. */
+  fxUnavailable: boolean
 }
 
 /** The API version the installed SDK defaults to, read from a real client. */
@@ -149,6 +164,11 @@ export const missing = (what: string): Error => Object.assign(new Error(`No such
   type: 'StripeInvalidRequestError', code: 'resource_missing', statusCode: 404,
 })
 
+/** A Stripe `invalid_request_error`, duck-typed the same way `missing` fakes `resource_missing`. */
+export const invalidRequest = (code: string): Error => Object.assign(new Error(code), {
+  type: 'StripeInvalidRequestError', code, statusCode: 400,
+})
+
 const page = (items: Rec[], params: Rec = {}) => {
   let start = 0
   if (params.starting_after != null) {
@@ -164,7 +184,11 @@ export const makeFakeStripe = (initial: Partial<FakeStripeState> = {}): { stripe
   const state: FakeStripeState = {
     apiVersion: SDK_API_VERSION, calls: [], webhookEndpoints: [], portalConfigurations: [], portalSessions: [],
     checkoutSessions: [], subscriptions: {}, invoices: {}, charges: {}, refunds: [], prices: [], products: {},
-    customers: {}, lineItemQuantity: 7, seq: 0, ...initial,
+    customers: {}, lineItemQuantity: 7, seq: 0,
+    taxCalculations: [], taxRates: {}, taxInvalidCountries: [], taxUnsupportedCountries: [],
+    taxSettings: { defaults: { tax_behavior: null, tax_code: null }, head_office: null, status: 'active', status_details: {} },
+    rawRequests: [], fxRates: {}, fxUnavailable: false,
+    ...initial,
   }
   const next = (prefix: string): string => `${prefix}_${++state.seq}`
   const call = (name: string): void => { state.calls.push(name) }
@@ -280,14 +304,23 @@ export const makeFakeStripe = (initial: Partial<FakeStripeState> = {}): { stripe
       },
       create: async (params: Rec) => {
         call('prices.create')
-        const price = { id: next('price'), active: true, ...structuredClone(params) }
+        // Stripe's own default: a price created with no `tax_behavior` is `unspecified`.
+        const price = { id: next('price'), active: true, tax_behavior: 'unspecified', ...structuredClone(params) }
         state.prices.push(price)
         return structuredClone(price)
       },
       update: async (id: string, params: Rec) => {
         call('prices.update')
-        Object.assign(find(state.prices, id, 'price'), params)
-        return structuredClone(find(state.prices, id, 'price'))
+        const price = find(state.prices, id, 'price')
+        if (
+          params.tax_behavior != null && price.tax_behavior != null && price.tax_behavior !== 'unspecified'
+          && price.tax_behavior !== params.tax_behavior
+        ) {
+          // Real Stripe: once a price's `tax_behavior` is `exclusive` or `inclusive`, it cannot change.
+          throw invalidRequest('parameter_invalid_empty')
+        }
+        Object.assign(price, params)
+        return structuredClone(price)
       },
     },
     products: {
@@ -333,6 +366,93 @@ export const makeFakeStripe = (initial: Partial<FakeStripeState> = {}): { stripe
         },
       },
     },
+    tax: {
+      calculations: {
+        /**
+         * A flat-percentage tax model, entirely driven by `state.taxRates` / `taxInvalidCountries`
+         * / `taxUnsupportedCountries` — real enough to exercise the status mapping and the
+         * scalability rule, never a stand-in for Stripe's actual jurisdiction logic.
+         */
+        create: async (params: Rec) => {
+          call('tax.calculations.create')
+          state.taxCalculations.push(structuredClone(params))
+          const country = params.customer_details?.address?.country as string | undefined
+          if (country != null && state.taxInvalidCountries.includes(country)) {
+            throw invalidRequest('customer_tax_location_invalid')
+          }
+          const lineItem = params.line_items[0]
+          const amount: number = lineItem.amount
+          const inclusive = lineItem.tax_behavior === 'inclusive'
+          const reverseCharge = (params.customer_details?.tax_ids ?? []).length > 0
+          const rates = reverseCharge ? [] : (country != null ? state.taxRates[country] ?? [] : [])
+          const unsupported = !reverseCharge && rates.length === 0
+            && country != null && state.taxUnsupportedCountries.includes(country)
+
+          const breakdown = reverseCharge
+            ? [{
+              amount: 0, inclusive, taxable_amount: amount, taxability_reason: 'reverse_charge',
+              tax_rate_details: { country, state: null, percentage_decimal: '0', tax_type: 'vat' },
+            }]
+            : unsupported
+              ? [{
+                amount: 0, inclusive, taxable_amount: amount, taxability_reason: 'not_supported',
+                tax_rate_details: null,
+              }]
+              : rates.length === 0
+                ? [{
+                  amount: 0, inclusive, taxable_amount: amount, taxability_reason: 'not_collecting',
+                  tax_rate_details: { country, state: null, percentage_decimal: '0', tax_type: 'vat' },
+                }]
+                : rates.map(rate => ({
+                  amount: Math.round(amount * Number(rate.percentage) / 100), inclusive, taxable_amount: amount,
+                  taxability_reason: 'standard_rated',
+                  tax_rate_details: { country, state: null, percentage_decimal: rate.percentage, tax_type: rate.type },
+                }))
+          const taxTotal = breakdown.reduce((sum, row) => sum + row.amount, 0)
+
+          return {
+            id: next('taxcalc'), object: 'tax.calculation', currency: params.currency,
+            amount_total: inclusive ? amount : amount + taxTotal,
+            tax_amount_exclusive: inclusive ? 0 : taxTotal,
+            tax_amount_inclusive: inclusive ? taxTotal : 0,
+            tax_breakdown: breakdown,
+          }
+        },
+      },
+      settings: {
+        retrieve: async () => {
+          call('tax.settings.retrieve')
+          return structuredClone(state.taxSettings)
+        },
+      },
+    },
+    rawRequest: async (method: string, path: string, params: Rec = {}) => {
+      call('rawRequest')
+      state.rawRequests.push({ method, path, params: structuredClone(params) })
+      if (path !== '/v1/fx_quotes') {
+        throw new Error(`fake-stripe: unhandled rawRequest path "${path}"`)
+      }
+      if (state.fxUnavailable) {
+        throw new Error('fx_quotes unavailable')
+      }
+      const local = params['from_currencies[]'] as string
+      const rate = state.fxRates[local]
+      if (rate == null) {
+        return { rates: {} }
+      }
+      return {
+        rates: {
+          [local]: {
+            exchange_rate: rate.exchangeRate,
+            rate_details: {
+              base_rate: rate.baseRate ?? rate.exchangeRate,
+              reference_rate: rate.referenceRate ?? rate.baseRate ?? rate.exchangeRate,
+              fx_fee_rate: rate.fxFeeRate ?? 0.02,
+            },
+          },
+        },
+      }
+    },
     webhooks: {
       /** Accepts the signature `sig:<secret>` over any body. */
       constructEventAsync: async (raw: string | Buffer, signature: string, secret: string) => {
@@ -582,6 +702,7 @@ export interface FakeContextOptions {
   /** The configured webhook override secret. */
   webhookSecret?: string
   portal?: PortalBrandingDef
+  pricing?: PricingDef
   stripe?: Partial<FakeStripeState>
 }
 
@@ -623,6 +744,9 @@ export const makeFakeContext = async (opts: FakeContextOptions = {}): Promise<Fa
   if (opts.portal != null) {
     portalBranding(cfg, opts.portal)
   }
+  if (opts.pricing != null) {
+    declarePaymentPricing(cfg, opts.pricing)
+  }
 
   const ctx = makeServerContext(cfg as unknown as ServerConfig) as unknown as ApiContext
   const stores: Record<string, MemoryStore> = {}

package/tests/portal.spec.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from 'bun:test'
-import { PortalFlow, PortalUnavailable, ProductType, PlanDuration, SubscriptionStatus } from '@owlmeans/payment'
-import { declarePaymentPlan, declarePaymentProduct } from '../src/config.js'
+import { PortalFlow, PortalUnavailable, ProductType, PlanDuration, SubscriptionStatus, TaxBehavior } from '@owlmeans/payment'
+import { declarePaymentPlan, declarePaymentPricing, declarePaymentProduct } from '../src/config.js'
 import { createPortalLink, ensurePortalConfiguration } from '../src/plugins/portal.js'
 import { fingerprints, paygateCustomers, subscriptions } from '../src/utils.js'
 import { makeFakeContext, PLANS_PRODUCT, PRO, SERVICE, TEAM } from './fake-stripe.js'
@@ -73,6 +73,23 @@ describe('@owlmeans/server-payment — portal configuration', () => {
       ])
   })
 
+  test('a declared tax behavior is hashed: changing it re-hashes and updates the configuration', async () => {
+    const fake = await withPortal({
+      pricing: { tax: { automatic: true, collectTaxId: true, estimate: false, behavior: TaxBehavior.Exclusive }, currency: { estimate: false } },
+    })
+    const id = await ensurePortalConfiguration(fake.ctx, fake.stripe)
+    fake.state.calls.length = 0
+    expect(await ensurePortalConfiguration(fake.ctx, fake.stripe)).toBe(id)
+    expect(fake.state.calls).toEqual([])
+
+    declarePaymentPricing(fake.ctx.cfg as never, {
+      tax: { automatic: true, collectTaxId: true, estimate: false, behavior: TaxBehavior.Inclusive },
+      currency: { estimate: false },
+    })
+    expect(await ensurePortalConfiguration(fake.ctx, fake.stripe)).toBe(id)
+    expect(fake.state.calls).toContain('billingPortal.configurations.update')
+  })
+
   test('two deployments on one Stripe account keep separate configurations, even when both rows name one', async () => {
     const shared = { owlmeans: 'payment', service: SERVICE }
     const stage = await withPortal({