API Development — PayFlow

Restructure the API around resources:

• GET/POST /customers, GET/PATCH/DELETE /customers/:id
• GET/POST /payments, GET /payments/:id, POST /payments/:id/refunds

URLs identify things (plural nouns); HTTP methods express actions. Remove the old RPC routes entirely — they must 404.

Behavior stays exactly as it is (yes, including the sloppy parts — later tickets fix those). This ticket is about the route surface only.

Give every response its honest status code:

• create → 201 Created + a Location header pointing at the new resource
• delete → 204 No Content, empty body
• missing resource → 404
• rejected business rule (e.g. refund exceeds payment) → an error status, never a 200

Apply this to customers, payments, and refunds. An error message riding inside a 200 is the single most common API smell — remove every instance.

Build /invoices:

• POST /invoices with { customerId, items: [{ description, quantity, unitPrice }] } → 201 + Location; the server computes total (never trust a client-sent total)
• GET /invoices/:id → invoice with its items; unknown id → 404
• unknown customer → 404; empty items → 4xx

Apply everything from TASK-001/BUG-002 without being told — that's the point of this ticket.

PATCH /customers/:id currently replaces every field with whatever arrived — absent fields become null.

Fix it to be a true partial update: only fields present in the request body change; everything else keeps its value. An empty patch changes nothing and doesn't crash.

In your PR description, explain the difference between PUT (full replace) and PATCH (partial merge) and why the old behavior loses data.

Introduce one error contract for the whole API:

• every error is application/problem+json: { type, title, status, detail? }
• type is a stable URI per error category (not-found, validation, …)
• handlers throw a typed ApiError; ONE error middleware turns it into the problem document
• unknown routes also answer with a problem document, not the framework's HTML default

Convert every existing error path (404s, refund-exceeds, invoice rejections).

When an unexpected error occurs:

• the client gets a generic 500 problem document — no message, no stack, no internals
• the server logs the full error (message + stack) so we can still debug it

The boundary rule: observability inward, opacity outward. Expected errors (ApiError) keep their helpful details; unexpected ones tell the client nothing.

Add a validation layer (zod) at the route boundary:

• schemas for creating customers, payments, refunds, invoices, and patching customers
• invalid input → 422 problem document with an errors array of { field, message } — reporting every invalid field at once, not just the first
• handlers only ever see parsed, valid data

Validation is middleware, not code sprinkled inside handlers.

Reproduce: pay ₹19.99 (1999 paise), refund 666 paise three times, then try to refund the final 1 paisa — the API refuses, because internally amounts are floats and 6.66 × 3 isn't 19.98.

Fix money end-to-end using integer minor units (paise):

• API accepts integer paise only — 19.99 is rejected with 422 (that's what 1999 is for)
• storage columns become INTEGER; all arithmetic is integer arithmetic
• money responses carry an explicit currency: "INR"
• invoices (unitPrice, total) follow the same rule

Standardize every response body:

• camelCase field names, everywhere, including nested objects
• timestamps are ISO-8601 UTC (2026-08-04T10:30:00.000Z)
• database rows never leak directly into responses — introduce serializers, the one place response shapes are defined

Store timestamps as ISO strings too (the clock seam's toISOString()), so sorting works lexicographically.

Paginate GET /payments:

• ?limit= (default 10, hard cap 100) and ?cursor=
• response envelope { data: [...], nextCursor }; nextCursor is null on the last page
• the cursor is opaque (e.g. base64 JSON) — clients must never parse it
• a garbage cursor → 422 problem
• order: newest first

Walking pages must visit every payment exactly once.

Extend GET /payments:

• ?status=succeeded|refunded (a fully refunded payment now flips to status refunded)
• ?created[gte]= / ?created[lte]= ISO date-range filters
• ?sort=createdAt|-createdAt|amount|-amount (default -createdAt); any other field → 422
• filters and sorting compose with cursor pagination

Only whitelisted fields are ever interpolated into SQL — values always go through parameters.

Reproduce: several payments created in the same clock instant share a createdAt. Walking pages with a cursor that compares only createdAt < cursor skips the tied rows at each page boundary.

Fix with a compound cursor (createdAt, id) giving a total order: WHERE createdAt < ? OR (createdAt = ? AND id < ?).

The exhaustive-walk test (freeze the clock, create ties, walk with limit 2) must show every payment exactly once.

Support an Idempotency-Key header on POST /payments:

• first request with a key: execute normally, store the response against the key
• replay (same key + same body): return the stored response — same status, same body, Idempotent-Replay: true header — and execute nothing (no second charge)
• same key + different body: 422 problem (a key identifies one logical request)
• no key: behaves as before

Fingerprint the body (hash) to detect mismatches.

The new concurrency test fires two simultaneous requests with the same key: exactly one charge must happen, and both callers must receive the same payment.

Fix by reserving the key before the side effect: insert the key row (status pending) first — the primary-key constraint makes exactly one concurrent request win. The loser waits for the winner's stored response and replays it. If the winner fails, release the key so a retry can execute cleanly.

The database constraint is the lock. An in-memory flag would not survive multiple processes.

Introduce versioned prefixes:

• /v1/... = the current contract, byte-stable forever; bare unversioned paths remain an alias of v1
• /v2/customers: accepts/returns firstName + lastName (no name); v1-created customers readable through v2 and vice versa
• /v2/payments: description replaces desc
• no business-logic duplication: shared routers take the version differences (wire schema, input mapper, serializer) as options — versions are thin wrappers

Storage does not change.

Every /v1 (and unversioned) response carries:

• Deprecation: true
• Sunset: <HTTP date> — from configuration (option/env), never hardcoded
• Link: <migration-guide-url>; rel="deprecation"

/v2 responses carry none of these.

Add key auth:

• Authorization: Bearer <key>; missing/unknown key → 401 problem; landing page (and docs/health) stay public
• scopes: read (GET) and write (everything else); a key without the needed scope → 403 problem — know the difference: 401 = who are you, 403 = you may not
• POST /api-keys creates a key: the raw key appears in that response once; only its SHA-256 hash is stored
• GET /api-keys lists metadata (name, prefix, scopes) — never key material
• two demo keys ship seeded (see the test helpers)

Token-bucket rate limiting per API key:

• bucket of limit tokens refilling continuously over windowMs (a fixed window allows 2× bursts across the boundary — the brief explains why bucket beats window)
• every response carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset — successes too, not just rejections
• over the limit → 429 problem + Retry-After seconds
• limits configurable (rateLimit option); time comes from the clock seam so tests can drive refills

Two fixes in the auth middleware:

1. Redaction: the Authorization header (or any key material) must never be written to any log line.
2. Constant-time compare: use crypto.timingSafeEqual on the hash buffers instead of ===.

Small diff, big habits — these two details mark security-literate engineers.

Build the provider side of webhooks:

• POST /webhook-endpoints { url } → register; response contains the signing secret (whsec_…) exactly once
• on every successful payment, deliver a payment.succeeded event (JSON) to each registered endpoint via the transport seam
• sign each delivery: PayFlow-Signature: t=<unix>,v1=<HMAC-SHA256(secret, "t.payload")> — the timestamp is inside the signed content
• failures retry (3 attempts, backoff 1s → 5s via the delays seam); webhook failure never fails the payment
• GET /webhook-endpoints/:id/deliveries shows the attempt log
• ship src/webhook-verify.js, the merchant-side verification helper we'll publish in the docs

Author openapi.json (OpenAPI 3.1) covering the core surface: customers (CRUD), payments (+pagination params, Idempotency-Key), refunds, invoices, webhook-endpoints, api-keys — including the Problem schema for errors.

• serve it publicly at GET /openapi.json
• upgrade the landing page / to list the documented endpoints (the deploy demo becomes an API console)
• schemas use $ref reuse, and the response schemas are strict (additionalProperties: false) so drift between spec and code turns the build red — the test suite validates real responses against your schemas

On customers:

• GET /customers/:id returns an ETag (versioned); If-None-Match with the current tag → 304 with no body (caching)
• PATCH accepts If-Match: if the tag is stale → 412 Precondition Failed problem, and the record is untouched — the client must re-read and re-apply
• every successful update changes the ETag exactly once
• requests without preconditions keep working

Fix src/webhook-verify.js (the merchant-side helper we ship):

• reject any delivery whose signed timestamp is outside a freshness window (default 300s) of the current time — the timestamp is inside the signed payload, so an attacker cannot forge a fresher one
• compare signatures with timingSafeEqual, not ===
• keep the API: verifySignature({ secret, header, payload, now?, toleranceSeconds? })

In the PR, explain why the tolerance window closes the replay attack and what clock skew has to do with choosing its size.

Two observability primitives:

1. Request IDs: accept the caller's X-Request-Id or generate one; echo it on every response; include it in every log line; problem documents carry it as their instance (RFC 7807), so an error response names the exact request to search for.
2. GET /health (public): reports { status, db } after actually probing the database — a health check that doesn't check anything is decoration. DB unreachable → 503.