suaveplan/openspec/changes/enterprise-payment/proposal.md

# OpenSpec Change: enterprise-payment

- **Change ID**: enterprise-payment
- **Package**: `@suaveplan/payment`
- **Category**: universal
- **Target path**: `universal/commerce/payment`
- **Status**: IN PROGRESS
- **Date**: 2026-04-24
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/payment.md`

---

## Summary

Deliver `@suaveplan/payment` on the genesis branch from scratch at enterprise quality. The package provides payment intent lifecycle primitives: a state machine covering `created` → `authorised` → `captured` / `refunded` / `failed` transitions, webhook signature verification with bounded clock-skew (default 300s), idempotency-key enforcement via `@suaveplan/idempotency` (replay returns the recorded outcome, never re-executes), receipt generation (structured data, not HTML), amount arithmetic (integer cents, multi-currency), and a provider-agnostic `PaymentAdapter` interface. Concrete provider adapters live in `@suaveplan/payment-providers`. PCI scope is minimised: the package never stores or transports raw card data; only tokens, intent IDs, and last-four-digit fragments pass through.

---

## Current-state audit (genesis)

The package does not exist on genesis yet — this is a fresh build.

---

## Available workspace deps on genesis

| Package | Role |
|---|---|
| `@suaveplan/error` (`workspace:^`) | `PaymentError`; `PAYMENT.*` error codes |
| `@suaveplan/types` (`workspace:^`) | `LoggerLike`, `Clock`, `EventBusLike` |
| `@suaveplan/events` (`workspace:^`) | Payment lifecycle event bus |
| `@suaveplan/idempotency` (`workspace:^`) | Per-transition idempotency key guard |
| `@suaveplan/crypto` (`workspace:^`) | Constant-time HMAC for webhook verification |
| `@suaveplan/fsm` (`workspace:^`) | FSM interpreter for payment state machine |
| `zod` (`catalog:forms`) | Schema validation |
| `@opentelemetry/api` (`catalog:observability`) | Spans + counters |

Dev deps: `vitest`, `@vitest/coverage-istanbul`, `fast-check` (all `catalog:testing`).

---

## Public API surface

### Core types

```ts
type PaymentStatus =
  | 'created' | 'authorised' | 'captured'
  | 'refunded' | 'partially_refunded' | 'failed' | 'cancelled'

interface PaymentIntent {
  id: string
  status: PaymentStatus
  amount: number         // integer cents
  currency: string       // ISO 4217 e.g. 'GBP'
  description?: string
  token?: string         // provider payment method token; no raw card data
  lastFour?: string
  metadata: Record<string, unknown>
  createdAt: Date
  updatedAt: Date
  history: PaymentTransition[]
}

interface PaymentTransition {
  from: PaymentStatus
  to: PaymentStatus
  idempotencyKey: string
  timestamp: Date
  actor?: string
}

interface Receipt {
  intentId: string
  amount: number
  currency: string
  formattedAmount: string   // e.g. '£12.50'
  status: PaymentStatus
  transitions: PaymentTransition[]
  issuedAt: Date
}
```

### `PaymentAdapter` interface

```ts
interface PaymentAdapter {
  readonly provider: string
  create(options: CreatePaymentOptions): Promise<PaymentIntent>
  authorise(intentId: string, token: string, idempotencyKey: string): Promise<PaymentIntent>
  capture(intentId: string, amount: number, idempotencyKey: string): Promise<PaymentIntent>
  refund(intentId: string, amount: number, idempotencyKey: string): Promise<PaymentIntent>
  cancel(intentId: string, idempotencyKey: string): Promise<PaymentIntent>
  verifyWebhook(body: string, headers: Record<string, string>, secret: string): boolean
  normalizeWebhook(body: unknown): PaymentWebhookEvent[]
}
```

### `PaymentService`

```ts
class PaymentService {
  constructor(options: PaymentServiceOptions)
  create(options: CreatePaymentOptions): Promise<PaymentIntent>
  authorise(intentId: string, token: string): Promise<PaymentIntent>
  capture(intentId: string, amount?: number): Promise<PaymentIntent>
  refund(intentId: string, amount?: number): Promise<PaymentIntent>
  cancel(intentId: string): Promise<PaymentIntent>
  getReceipt(intentId: string): Receipt
}

interface PaymentServiceOptions {
  adapter: PaymentAdapter
  store?: PaymentStore
  idempotency?: IdempotencyGuard
  logger?: LoggerLike
  clock?: Clock
  bus?: EventBusLike
}
```

### Amount utilities

```ts
function formatAmount(amount: number, currency: string, locale?: string): string
function toMinorUnits(major: number, currency: string): number
function fromMinorUnits(minor: number, currency: string): number
function addAmounts(a: number, b: number): number
function subtractAmounts(a: number, b: number): number   // throws if negative
```

### Error codes

```ts
type PaymentErrorCode =
  | 'PAYMENT_NOT_FOUND'
  | 'PAYMENT_INVALID_TRANSITION'
  | 'PAYMENT_SIGNATURE_FAILED'
  | 'PAYMENT_REPLAY_DETECTED'
  | 'PAYMENT_IDEMPOTENCY_CONFLICT'
  | 'PAYMENT_AMOUNT_INVALID'
  | 'PAYMENT_PROVIDER_ERROR'
  | 'PAYMENT_ABORTED'
```

---

## Genesis additions

1. **`PaymentError`** extends `SuaveplanError` with eight stable codes.
2. **Zod schemas** for `PaymentIntent`, `PaymentTransition`, `Receipt`, `CreatePaymentOptions`, `PaymentWebhookEvent`.
3. **State machine** — implemented via `@suaveplan/fsm`; illegal transitions surface `PAYMENT_INVALID_TRANSITION` with full history in the error context.
4. **Idempotency enforcement** — every state-altering method requires an idempotency key passed through `@suaveplan/idempotency`; replay returns the cached `PaymentIntent` without re-executing the provider call.
5. **Webhook verification** — constant-time HMAC via `@suaveplan/crypto`; bounded clock-skew rejects webhooks older than 300s (configurable); nonce dedup window prevents replay.
6. **PCI minimisation** — `token` and `lastFour` fields only; no `pan`, `cvv`, `expiry` in any type.
7. **OTel instrumentation** — span `payment.transition` with attributes `payment.from_status`, `payment.to_status`, `payment.provider`; counter `payment.transition_total`; histogram `payment.transition_duration_ms`.
8. **Property-based tests** — state machine reachability: every valid transition chain from `created` eventually reaches a terminal state; amount arithmetic properties (commutativity of add, non-negativity of subtract).

---

## File layout

```text
universal/commerce/payment/
  package.json
  tsconfig.json
  vitest.config.ts
  src/
    index.ts
    error-codes.ts
    constants/
      index.ts              # ALLOWED_TRANSITIONS, TERMINAL_STATUSES, DEFAULT_SKEW_MS
    types/
      common.ts
      common.md
    core/
      payment-service/
        payment-service.ts
        payment-service.md
        payment-service.types.ts
        payment-service.test.ts
        index.ts
      payment-fsm/
        payment-fsm.ts
        payment-fsm.md
        payment-fsm.test.ts
        index.ts
    webhook/
      webhook-verifier/
        webhook-verifier.ts
        webhook-verifier.md
        webhook-verifier.test.ts
        index.ts
    receipt/
      receipt-generator/
        receipt-generator.ts
        receipt-generator.md
        receipt-generator.test.ts
        index.ts
    utils/
      amount.ts
      amount.md
      amount.test.ts
    __benchmarks__/
      payment.bench.ts
  tests/
    integration.test.ts
    property.test.ts
```

---

## Impact

**Downstream consumers**: `@suaveplan/payment-providers`, `@suaveplan/booking`.

**Workspace dep prerequisites**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/idempotency`, `@suaveplan/crypto`, `@suaveplan/fsm`.