Specification-Driven Development

# Payment Service Specification

## Goal
Process payments and refunds via Stripe.

## Non-Goals
- Subscription management (separate service)
- Invoice generation

## Interface
- processPayment(amount, currency, token) → PaymentResult
- refundPayment(transactionId, amount?) → RefundResult

## Invariants
- No payment without valid token
- Refund cannot exceed original amount
- All amounts in cents (no decimals)

## Error Cases
- INSUFFICIENT_FUNDS → decline, no charge
- CARD_DECLINED → decline, log reason
- DUPLICATE_IDEMPOTENCY → return original result

## Acceptance Tests
1. Valid card with funds → success + transactionId
2. Insufficient funds → INSUFFICIENT_FUNDS error
3. Duplicate request → same result, no double charge
4. Partial refund → success + remaining balance
5. Refund > original → REFUND_EXCEEDS_ORIGINAL error

A good specification includes: goal/non-goals, interface, invariants, error cases, and acceptance tests. If the spec does not define failure behavior, AI will guess.

openapi: 3.0.0
info:
  title: Payment API
  version: 1.0.0
paths:
  /payments:
    post:
      operationId: processPayment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRequest'
      responses:
        '200':
          description: Payment processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResult'
        '402':
          description: Payment declined
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentError'
components:
  schemas:
    PaymentRequest:
      type: object
      required: [amount, currency, token]
      properties:
        amount:
          type: integer
          minimum: 1
        currency:
          type: string
          enum: [USD, EUR, GBP]
        token:
          type: string
    PaymentResult:
      type: object
      properties:
        transactionId:
          type: string
        status:
          type: string
          enum: [success]
    PaymentError:
      type: object
      properties:
        code:
          type: string
          enum: [INSUFFICIENT_FUNDS, CARD_DECLINED, INVALID_TOKEN]
        message:
          type: string

Generate code from schema, not from prose alone. OpenAPI, Zod, Proto—the contract is executable and unambiguous. Frontend and backend stay in sync.

import { describe, it, expect } from 'vitest';
import { processPayment, refundPayment } from './payment';

describe('Payment Contract Tests', () => {
  it('processes valid payment', async () => {
    const result = await processPayment({
      amount: 1000,
      currency: 'USD',
      token: 'tok_visa',
    });
    expect(result.status).toBe('success');
    expect(result.transactionId).toBeDefined();
  });

  it('rejects insufficient funds', async () => {
    await expect(
      processPayment({
        amount: 1000,
        currency: 'USD',
        token: 'tok_insufficient_funds',
      })
    ).rejects.toMatchObject({
      code: 'INSUFFICIENT_FUNDS',
    });
  });

  it('returns same result for duplicate request', async () => {
    const idempotencyKey = 'test-123';
    const first = await processPayment({
      amount: 1000,
      currency: 'USD',
      token: 'tok_visa',
      idempotencyKey,
    });
    const second = await processPayment({
      amount: 1000,
      currency: 'USD',
      token: 'tok_visa',
      idempotencyKey,
    });
    expect(second.transactionId).toBe(first.transactionId);
  });

  it('rejects refund exceeding original', async () => {
    const payment = await processPayment({
      amount: 1000,
      currency: 'USD',
      token: 'tok_visa',
    });
    await expect(
      refundPayment(payment.transactionId, 2000)
    ).rejects.toMatchObject({
      code: 'REFUND_EXCEEDS_ORIGINAL',
    });
  });
});

Tests generated from spec acceptance criteria. These are the judge. AI implements until they pass. If a behavior is not tested, AI will not implement it.