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

package/tests/checkout.spec.ts

@@ -1,9 +1,13 @@
 import { describe, expect, test } from 'bun:test'
-import { CheckoutPricingMode, PlanDuration, PlanStatus, ProductType } from '@owlmeans/payment'
-import { PAYMENT_OBSERVER, RES_PAYMENT_SUBSCRIPTION } from '../src/consts.js'
+import { CheckoutPricingMode, PlanDuration, PlanStatus, ProductError, ProductType, TaxBehavior } from '@owlmeans/payment'
 import { createEventHandler } from '../src/plugins/events.js'
-import { amountCheckoutLineItem, quantityCheckoutLineItem } from '../src/plugins/stripe.js'
-import type { PaymentPlan, PaymentProduct, PaymentSubscriptionRecord, TopUpCompletion } from '../src/types.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, 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'],
@@ -20,41 +24,20 @@ const plan: PaymentPlan = {
 
 const paid = (overrides: Record<string, unknown> = {}) => ({
   id: 'cs_amount', mode: 'payment', payment_status: 'paid', customer: 'cus_1',
-  currency: 'usd', amount_subtotal: 1021,
+  currency: 'usd', amount_subtotal: 1021, payment_intent: 'pi_1', invoice: 'in_1',
   metadata: {
     pricingMode: 'amount', amountMinor: '1000', chargeAmountMinor: '1021', currency: 'usd',
-    entityId: 'entity-1', service: 'app', productSku: 'credits', planSku: 'credits-unit',
+    entityId: 'entity-1', service: 'app', productSku: CREDITS_PRODUCT, planSku: 'app-credit-unit',
   },
   ...overrides,
 })
 
-const harness = () => {
-  const records: PaymentSubscriptionRecord[] = []
-  const completions: TopUpCompletion[] = []
-  const subscriptions = {
-    byExternalId: async (id: string) => records.find(record => record.externalId === id) ?? null,
-    create: async (record: PaymentSubscriptionRecord) => {
-      const created = { ...record, id: String(records.length + 1) }
-      records.push(created)
-      return created
-    },
-    save: async (record: PaymentSubscriptionRecord) => {
-      const index = records.findIndex(item => item.id === record.id)
-      records[index] = { ...record }
-      return records[index]
-    },
-  }
-  const observer = { propagateTopUp: async (completion: TopUpCompletion) => { completions.push(completion) } }
-  const context = {
-    resource: (alias: string) => alias === RES_PAYMENT_SUBSCRIPTION ? subscriptions : undefined,
-    service: (alias: string) => alias === PAYMENT_OBSERVER ? observer : undefined,
-  }
-  const stripe = { checkout: { sessions: { listLineItems: async () => ({ data: [{ quantity: 7 }] }) } } }
-  return { records, completions, context, stripe }
-}
+const process = async (fake: FakeContext, type: string, object: unknown) =>
+  await createEventHandler(fake.ctx, fake.stripe).process({ type, data: { object } } as never)
+const fulfillment = (fake: FakeContext) => fake.stores['payment-fulfillment'].rows
 
-describe('Stripe amount checkout', () => {
-  test('uses one inline, tax-exclusive item and no reusable Price', () => {
+describe('Stripe checkout', () => {
+  test('amount checkout uses one inline, tax-exclusive item and no reusable Price', () => {
     const result = amountCheckoutLineItem(product, plan, 1_000)
     expect(result.chargeMinor).toBe(1_021)
     expect(result.lineItem).toEqual({
@@ -64,7 +47,7 @@ describe('Stripe amount checkout', () => {
     expect(result.lineItem.adjustable_quantity).toBeUndefined()
   })
 
-  test('keeps reusable Price and adjustable quantity for quantity checkout', () => {
+  test('quantity checkout keeps a reusable Price and an adjustable quantity', () => {
     expect(quantityCheckoutLineItem({ id: 'price_1' } as never, {
       minimum: 5, maximum: 500, default: 10,
     })).toEqual({
@@ -73,63 +56,181 @@ describe('Stripe amount checkout', () => {
     })
   })
 
-  test('fulfills a paid amount without crediting the adjustment', async () => {
-    const h = harness()
-    await createEventHandler(h.context as never, h.stripe as never).process({
-      type: 'checkout.session.completed', data: { object: paid() },
-    } as never)
-    expect(h.completions).toEqual([expect.objectContaining({ mode: 'amount', amountMinor: 1_000, chargeAmountMinor: 1_021 })])
-    expect(h.records[0]?.fulfilledAt).toBeInstanceOf(Date)
+  test('a subscription checkout takes the asked plan, locale and disclosure; a free plan is never checked out', async () => {
+    const fake = await makeFakeContext({
+      stripe: { prices: [{ id: 'price_team', product: PLANS_PRODUCT, lookup_key: TEAM, active: true, recurring: { interval: 'month' } }] },
+    })
+    await createCheckoutLink(fake.ctx, fake.stripe, {
+      productSku: PLANS_PRODUCT, planSku: TEAM, entityId: 'entity-1', service: 'app', successUrl: 'https://app.example.com/ok',
+      locale: 'fr', submitText: 'Comprend des crédits prépayés obligatoires.',
+    })
+    expect(fake.state.checkoutSessions[0]).toEqual(expect.objectContaining({
+      mode: 'subscription', line_items: [{ price: 'price_team', quantity: 1 }],
+      locale: 'fr', custom_text: { submit: { message: 'Comprend des crédits prépayés obligatoires.' } },
+    }))
+    expect(fake.state.checkoutSessions[0].subscription_data.metadata).toEqual(expect.objectContaining({ entityId: 'entity-1', planSku: TEAM }))
+    expect(fake.state.customers.cus_1.preferred_locales).toEqual(['fr'])
+
+    await expect(createCheckoutLink(fake.ctx, fake.stripe, {
+      productSku: PLANS_PRODUCT, planSku: FREE, entityId: 'entity-1', service: 'app',
+    })).rejects.toBeInstanceOf(ProductError)
+  })
+})
+
+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('does not fulfill an unpaid completion; asynchronous success does', async () => {
-    const h = harness()
-    const handler = createEventHandler(h.context as never, h.stripe as never)
-    await handler.process({
-      type: 'checkout.session.completed', data: { object: paid({ payment_status: 'unpaid' }) },
-    } as never)
-    expect(h.completions).toHaveLength(0)
-    await handler.process({ type: 'checkout.session.async_payment_succeeded', data: { object: paid() } } as never)
-    expect(h.completions).toHaveLength(1)
+  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('rejects currency/subtotal metadata mismatches and is idempotent on retries', async () => {
-    const h = harness()
-    const handler = createEventHandler(h.context as never, h.stripe as never)
-    await expect(handler.process({
-      type: 'checkout.session.completed', data: { object: paid({ amount_subtotal: 1020 }) },
-    } as never)).rejects.toThrow()
-    await handler.process({ type: 'checkout.session.completed', data: { object: paid() } } as never)
-    await handler.process({ type: 'checkout.session.completed', data: { object: paid() } } as never)
-    expect(h.completions).toHaveLength(1)
+  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('retries fulfillment when the application observer fails', async () => {
-    const h = harness()
-    let attempts = 0
-    ;(h.context.service(PAYMENT_OBSERVER) as never as { propagateTopUp: () => Promise<void> })
-      .propagateTopUp = async () => {
-        attempts++
-        if (attempts === 1) throw new Error('ledger unavailable')
-        h.completions.push({ mode: 'amount' } as never)
-      }
-    const handler = createEventHandler(h.context as never, h.stripe as never)
-    const event = { type: 'checkout.session.completed', data: { object: paid() } } as never
-    await expect(handler.process(event)).rejects.toThrow('ledger unavailable')
-    expect(h.records[0]?.fulfilledAt).toBeUndefined()
-    await handler.process(event)
-    expect(attempts).toBe(2)
-    expect(h.records[0]?.fulfilledAt).toBeInstanceOf(Date)
+  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())
+    await process(fake, 'checkout.session.completed', paid())
+    expect(fake.observed.topUp).toEqual([expect.objectContaining({
+      mode: 'amount', amountMinor: 1_000, chargeAmountMinor: 1_021, externalId: 'cs_amount', entityId: 'entity-1',
+    })])
+    expect(fulfillment(fake)[0]).toEqual(expect.objectContaining({
+      externalId: 'cs_amount', paymentIntentId: 'pi_1', invoiceId: 'in_1', mode: 'amount',
+    }))
+    expect(fulfillment(fake)[0].fulfilledAt).toBeInstanceOf(Date)
+    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' }))
+    expect(fake.observed.topUp).toHaveLength(0)
+    await process(fake, 'checkout.session.async_payment_succeeded', paid())
+    expect(fake.observed.topUp).toHaveLength(1)
+  })
+
+  test('rejects a currency or subtotal mismatch; retries after a failed observer', async () => {
+    const fake = await makeFakeContext()
+    await expect(process(fake, 'checkout.session.completed', paid({ amount_subtotal: 1020 }))).rejects.toThrow()
+
+    fake.observed.failTopUp = 1
+    await expect(process(fake, 'checkout.session.completed', paid())).rejects.toThrow('ledger unavailable')
+    expect(fulfillment(fake)[0]?.fulfilledAt).toBeUndefined()
+    await process(fake, 'checkout.session.completed', paid())
+    expect(fake.observed.topUp).toHaveLength(1)
+    expect(fulfillment(fake)[0].fulfilledAt).toBeInstanceOf(Date)
   })
 
-  test('legacy sessions without pricing metadata still fulfill by quantity', async () => {
-    const h = harness()
-    const legacy = paid({ id: 'cs_legacy', metadata: {
-      entityId: 'entity-1', service: 'app', productSku: 'credits', planSku: 'credits-unit',
-    } })
-    await createEventHandler(h.context as never, h.stripe as never).process({
-      type: 'checkout.session.completed', data: { object: legacy },
-    } as never)
-    expect(h.completions[0]).toEqual(expect.objectContaining({ mode: 'quantity', units: 7 }))
+  test('a legacy session without pricing metadata fulfills by quantity', async () => {
+    const fake = await makeFakeContext()
+    await process(fake, 'checkout.session.completed', paid({
+      id: 'cs_legacy', metadata: { entityId: 'entity-1', service: 'app', productSku: CREDITS_PRODUCT, planSku: 'app-credit-unit' },
+    }))
+    expect(fake.observed.topUp[0]).toEqual(expect.objectContaining({ mode: 'quantity', units: 7 }))
+    expect(fulfillment(fake)[0]).toEqual(expect.objectContaining({ mode: 'quantity', units: 7 }))
   })
 })

package/tests/consumer-events.spec.ts

@@ -0,0 +1,218 @@
+import { describe, expect, test } from 'bun:test'
+import { PurchaseKind, withdrawalDeadlineOf } from '@owlmeans/payment'
+import {
+  billingProfiles, consumerEvents, fulfillments, paygateCustomers, purchases, subscriptions,
+} from '../src/utils.js'
+import {
+  buyTopUp, ENTITY, invoiceOf, makeRightsContext, paidSession, PRO, requestStart, send,
+} from './consumer-fixtures.js'
+import { capturePaymentPurchase } from '../src/consumer/capture.js'
+import { subscriptionOf } from './fake-stripe.js'
+import type { FakeContext } from './fake-stripe.js'
+
+const proSubscription = (startRequestId?: string, overrides: Record<string, unknown> = {}) => {
+  const subscription = subscriptionOf({ id: 'sub_pro', customer: 'cus_1', latestInvoice: 'in_sub' }) as unknown as Record<string, any>
+  subscription.currency = 'eur'
+  subscription.items.data[0].price = { id: 'price_pro', lookup_key: PRO, unit_amount: 1_800, currency: 'eur', tax_behavior: 'exclusive' }
+  subscription.items.data[0].quantity = 1
+  subscription.metadata = {
+    entityId: ENTITY, planSku: PRO, productSku: 'app-plans', service: 'app', country: 'DE', language: 'de',
+    ...(startRequestId != null ? { startRequestId } : {}),
+  }
+  return { ...subscription, ...overrides }
+}
+
+const subscriptionSession = (overrides: Record<string, unknown> = {}) => paidSession({
+  id: 'cs_sub', mode: 'subscription', subscription: 'sub_pro', invoice: 'in_sub', payment_intent: null,
+  amount_subtotal: 1_800, amount_total: 2_142, total_details: { amount_tax: 342 },
+  customer_details: { address: { country: 'DE' }, email: 'owner@shop.eu', name: 'Anna', tax_ids: [] },
+  metadata: { pricingMode: 'quantity', planSku: PRO, productSku: 'app-plans', country: 'DE', language: 'de' },
+  ...overrides,
+})
+
+const withSubInvoice = (fake: FakeContext) => {
+  fake.state.invoices.in_sub = invoiceOf('in_sub', {
+    number: 'INV-SUB-1', subtotal: 1_800, tax: 342, total: 2_142, payment_intent: 'pi_sub',
+    lines: { object: 'list', data: [{ id: 'il_sub', amount: 1_800 }] }, customer_address: { country: 'DE' },
+  })
+}
+
+describe('webhook capture — one-time purchases', () => {
+  test('the purchase row exists before the credits are granted, with its window and evidence', async () => {
+    const fake = await makeRightsContext()
+    const seen: unknown[] = []
+    fake.observed.onTopUp = async () => { seen.push(await purchases(fake.ctx).load({ sessionId: 'cs_pl' })) }
+    const purchase = await buyTopUp(fake)
+
+    expect(seen[0]).toEqual(expect.objectContaining({ purchaseId: 'stripe:cs_pl' }))
+    expect(purchase).toEqual(expect.objectContaining({
+      purchaseId: 'stripe:cs_pl', kind: PurchaseKind.TopUp, entityId: ENTITY, country: 'PL', region: 'eu', inScope: true,
+      language: 'pl', currency: 'eur', amountSubtotalMinor: 919, amountTaxMinor: 211, amountTotalMinor: 1_130,
+      netAmountMinor: 1_000, amountCurrency: 'usd', paymentIntentId: 'pi_pl', invoiceId: 'in_pl',
+      invoiceNumber: 'INV-0001', invoiceLineId: 'il_pl', termsAccepted: true, ipCountry: 'PL', email: 'buyer@shop.eu',
+      textVersion: 'terms-v1',
+    }))
+    expect(purchase.contractRef).toMatch(/^CR-\d{6}-[2-9A-HJKMNP-Z]{6}$/)
+    expect(purchase.deadline).toEqual(withdrawalDeadlineOf(new Date(purchase.purchasedAt), { marginDays: 5 }))
+    expect((await fulfillments(fake.ctx).byExternalId('cs_pl', 'stripe'))).toEqual(expect.objectContaining({
+      country: 'PL', email: 'buyer@shop.eu', amountTotalMinor: 1_130, amountTaxMinor: 211, termsAccepted: true,
+      purchaseId: 'stripe:cs_pl',
+    }))
+  })
+
+  test('the first purchase locks the country; a later one elsewhere is only a lock-mismatch event', async () => {
+    const fake = await makeRightsContext()
+    await buyTopUp(fake)
+    expect(await billingProfiles(fake.ctx).byEntity(ENTITY)).toEqual(expect.objectContaining({
+      country: 'PL', region: 'eu', currency: 'eur', language: 'pl', source: 'checkout', ipCountry: 'PL',
+      email: 'buyer@shop.eu', sessionId: 'cs_pl',
+    }))
+    const second = await buyTopUp(fake, {
+      id: 'cs_de', invoice: 'in_de', customer_details: { address: { country: 'DE' }, email: 'buyer@shop.eu' },
+      metadata: { ipCountry: 'AT' },
+    })
+    expect(second.country).toBe('DE')
+    expect((await billingProfiles(fake.ctx).byEntity(ENTITY))?.country).toBe('PL')
+    const mismatch = (await consumerEvents(fake.ctx).list({ action: 'lock-mismatch' })).items
+    expect(mismatch).toHaveLength(1)
+    expect(JSON.parse(mismatch[0].detail ?? '{}')).toEqual(expect.objectContaining({ locked: 'PL', observed: 'DE', sessionId: 'cs_de' }))
+  })
+
+  test('the confirmation is mailed once, in the billing language, with the withdrawal information and an archive copy', async () => {
+    const fake = await makeRightsContext()
+    await buyTopUp(fake, { customer_details: { address: { country: 'PL' }, email: 'buyer@shop.eu', name: 'Jan <b>K</b>' } })
+    await send(fake, 'checkout.session.completed', paidSession())
+    const mails = fake.mails.filter(mail => mail.subject.includes('CR-'))
+    expect(mails.map(mail => mail.to)).toEqual(['buyer@shop.eu', 'archive@example.com'])
+    const [mail] = mails
+    expect(mail.from).toBe('billing@example.com')
+    expect(mail.text).toContain('Example Trading Ltd, 1 Example Street, 00-001 Example, support@example.com')
+    expect(mail.text).toContain('https://app.example.com/legal/withdraw')
+    expect(mail.text).toContain('Odstąp od umowy tutaj')
+    expect(mail.html).toContain('Jan &lt;b&gt;K&lt;/b&gt;')
+    expect(mail.html).not.toContain('<b>K</b>')
+  })
+
+  test('concurrent deliveries in several processes mail the confirmation once', async () => {
+    const fake = await makeRightsContext()
+    fake.state.invoices.in_pl = invoiceOf()
+    const session = paidSession() as never
+    // Not through the webhook handler, whose per-customer lock serializes one process: two processes race here.
+    await Promise.all([
+      capturePaymentPurchase(fake.ctx, fake.stripe, session), capturePaymentPurchase(fake.ctx, fake.stripe, session),
+    ])
+    await send(fake, 'checkout.session.completed', paidSession())
+    expect(fake.mails.filter(mail => mail.subject.includes('CR-')).map(mail => mail.to)).toEqual(['buyer@shop.eu', 'archive@example.com'])
+    expect(await consumerEvents(fake.ctx).count({ action: 'mail', step: 'purchase' })).toBe(1)
+    expect((await purchases(fake.ctx).load({ sessionId: 'cs_pl' }))?.confirmationMailAt).toBeInstanceOf(Date)
+  })
+
+  test('a checkout that collected no terms records no acceptance', async () => {
+    const fake = await makeRightsContext()
+    const purchase = await buyTopUp(fake, { consent: null, metadata: { termsCollected: 'false' } })
+    expect(purchase.termsAccepted).toBeUndefined()
+    expect((await fulfillments(fake.ctx).byExternalId('cs_pl', 'stripe'))?.termsAccepted).toBeUndefined()
+  })
+
+  test('a purchase outside the territories has no window and no confirmation', async () => {
+    const fake = await makeRightsContext()
+    const purchase = await buyTopUp(fake, {
+      id: 'cs_us', invoice: 'in_us', currency: 'usd', amount_subtotal: 1_021, amount_total: 1_021, total_details: { amount_tax: 0 },
+      customer_details: { address: { country: 'US' }, email: 'buyer@shop.us' },
+      metadata: { country: 'US', currency: 'usd', chargeAmountMinor: '1021', language: 'en' },
+    })
+    expect(purchase).toEqual(expect.objectContaining({ inScope: false, region: 'other', country: 'US' }))
+    expect(purchase.deadline).toBeUndefined()
+    expect(fake.mails).toHaveLength(0)
+    expect((await billingProfiles(fake.ctx).byEntity(ENTITY))?.currency).toBe('usd')
+  })
+
+  test('customer webhooks store the paygate country and currency', async () => {
+    const fake = await makeRightsContext()
+    await send(fake, 'customer.updated', { id: 'cus_9', email: 'a@shop.eu', address: { country: 'fr' }, currency: 'EUR', metadata: { entityId: ENTITY } })
+    expect(await paygateCustomers(fake.ctx).loadByPgId('cus_9', 'stripe')).toEqual(expect.objectContaining({ country: 'FR', currency: 'eur' }))
+  })
+})
+
+describe('webhook capture — subscriptions', () => {
+  test('the first commit writes the purchase before the created observers; the checkout refines it', async () => {
+    const fake = await makeRightsContext()
+    withSubInvoice(fake)
+    const startRequestId = await requestStart(fake)
+    const seen: unknown[] = []
+    fake.observed.onSubscription = async event => {
+      if (event.change === 'created') seen.push(await purchases(fake.ctx).byPurchaseId('stripe:sub_pro'))
+    }
+    const subscription = proSubscription(startRequestId)
+    fake.state.subscriptions.sub_pro = subscription as never
+    await send(fake, 'customer.subscription.created', subscription)
+
+    expect(seen[0]).toEqual(expect.objectContaining({
+      purchaseId: 'stripe:sub_pro', kind: PurchaseKind.Subscription, subscriptionId: 'sub_pro', invoiceId: 'in_sub',
+      invoiceNumber: 'INV-SUB-1', invoiceLineId: 'il_sub', paymentIntentId: 'pi_sub', currency: 'eur',
+      amountSubtotalMinor: 1_800, amountTaxMinor: 342, amountTotalMinor: 2_142, startRequestId, consentId: startRequestId,
+      country: 'DE', inScope: true,
+    }))
+    const stored = seen[0] as { servicesStartedAt: Date, consentedAt: Date }
+    expect(stored.servicesStartedAt).toBeInstanceOf(Date)
+    expect(stored.consentedAt).toEqual(stored.servicesStartedAt)
+
+    await send(fake, 'checkout.session.completed', subscriptionSession({ customer_details: { address: { country: 'AT' }, email: 'owner@shop.eu', name: 'Anna' } }))
+    expect(await purchases(fake.ctx).byPurchaseId('stripe:sub_pro')).toEqual(expect.objectContaining({
+      sessionId: 'cs_sub', country: 'AT', email: 'owner@shop.eu', termsAccepted: true, amountTotalMinor: 2_142,
+    }))
+    expect(await subscriptions(fake.ctx).byExternalId('sub_pro', 'stripe')).toEqual(expect.objectContaining({
+      checkoutSessionId: 'cs_sub', purchaseId: 'stripe:sub_pro', firstInvoiceId: 'in_sub', currency: 'eur', country: 'AT',
+      email: 'owner@shop.eu', amountTotalMinor: 2_142, amountTaxMinor: 342, termsAccepted: true, startRequestId,
+    }))
+    expect((await billingProfiles(fake.ctx).byEntity(ENTITY))?.country).toBe('AT')
+    const confirmation = fake.mails.find(mail => mail.to === 'owner@shop.eu' && mail.subject.includes('CR-'))
+    // The order confirmation is in the billing language; the start request is repeated verbatim, as shown (en).
+    expect(confirmation?.subject).toStartWith('Bestellbestätigung')
+    expect(confirmation?.text).toContain('I expressly request and agree that Example starts the Pro platform services')
+    expect(confirmation?.text).toContain('https://app.example.com/legal/cancel')
+  })
+
+  test('a completed subscription checkout that arrives first applies the subscription itself', async () => {
+    const fake = await makeRightsContext()
+    withSubInvoice(fake)
+    fake.state.subscriptions.sub_pro = proSubscription() as never
+    await send(fake, 'checkout.session.completed', subscriptionSession())
+    expect(fake.observed.subscription.map(event => event.change)).toEqual(['created'])
+    expect(await purchases(fake.ctx).byPurchaseId('stripe:sub_pro')).toEqual(expect.objectContaining({ sessionId: 'cs_sub', country: 'DE' }))
+    // Renewals are not purchases.
+    await send(fake, 'invoice.paid', { id: 'in_renew', object: 'invoice', subscription: 'sub_pro', customer: 'cus_1', billing_reason: 'subscription_cycle' })
+    expect(fake.stores['payment-purchase'].rows).toHaveLength(1)
+  })
+})
+
+describe('webhook capture — refunds', () => {
+  const charge = { id: 'ch_pl', amount: 1_130, amount_refunded: 1_130, payment_intent: 'pi_pl', invoice: null }
+
+  test('a withdrawal refund carries its id to the refund observers; a whole refund closes the window', async () => {
+    const fake = await makeRightsContext({ stripe: { charges: { ch_pl: charge } } })
+    await buyTopUp(fake)
+    await send(fake, 'refund.created', {
+      id: 're_w', object: 'refund', amount: 1_130, currency: 'eur', status: 'succeeded', payment_intent: 'pi_pl',
+      charge: 'ch_pl', metadata: { owlmeans: 'payment', withdrawalId: 'decl_1', purchaseId: 'stripe:cs_pl' },
+    })
+    expect(fake.observed.refund[0]).toEqual(expect.objectContaining({
+      withdrawalId: 'decl_1', metadata: expect.objectContaining({ withdrawalId: 'decl_1' }), partial: false,
+    }))
+    const purchase = await purchases(fake.ctx).byPurchaseId('stripe:cs_pl')
+    expect(purchase?.refundedMinor).toBe(1_130)
+    expect(purchase?.refundedAt).toBeInstanceOf(Date)
+  })
+
+  test('an ordinary partial refund carries no withdrawal id and keeps the window open', async () => {
+    const fake = await makeRightsContext({ stripe: { charges: { ch_pl: { ...charge, amount_refunded: 300 } } } })
+    await buyTopUp(fake)
+    await send(fake, 'refund.created', {
+      id: 're_p', object: 'refund', amount: 300, currency: 'eur', status: 'succeeded', payment_intent: 'pi_pl', charge: 'ch_pl',
+    })
+    expect(fake.observed.refund[0].withdrawalId).toBeUndefined()
+    const purchase = await purchases(fake.ctx).byPurchaseId('stripe:cs_pl')
+    expect(purchase?.refundedMinor).toBe(300)
+    expect(purchase?.refundedAt).toBeUndefined()
+  })
+})