Payments — Payment events history

binding spec data-contracts/payments-events.odcs.yaml @ 1.2.0 — the spec of record. It states what must be; implementations converge on it, never the reverse.

Enforced by

• check:version — any change must bump the artifact and service versions; a silent edit fails CI
• datacontract-cli validation
• Spectral house rules for attribute and value naming

Version history

Version	First released	Service version
1.2.0	2026-08-24	2.1.0
1.1.0	2026-08-23	2.0.0
1.0.0	2026-08-23	1.1.0

Consume it

• Agents, over MCP: get_artifact('payments', 'data-contracts/payments-events.odcs.yaml')
• Raw spec: data-contracts/payments-events.odcs.yaml
• Implementations pin the release tag payments/v3.0.1 in their contracts.lock and fetch read-only — the full loop is on Drive an implementation.

Status: active · Domain: Commerce ·Data product: payments

Purpose

Append-only historical record of payment settlement events. One row per event, mirroring the AsyncAPI payload on payments.settled.v2 field for field - the stream is ephemeral, this table is the record.

Usage

Settlement analytics, audit, and replay/backfill for downstream consumers that joined after the fact. The daily reconciliation product (payments-daily) is derived from this record.

Limitations

Delivery upstream is at-least-once; rows are deduplicated on the CloudEvents envelope id, so exactly one row per settlement (settlement is terminal). Not a source for real-time balances - use the payments service API for that.

Schema

erDiagram
    payment_settled_events {
        string event_id PK
        string event_type
        string event_source
        date event_time
        string payment_id UK
        string order_id
        date settled_at
        integer amount_pence
    }

payment_settled_events — One row per PaymentSettled event on payments.settled.v2.

Field	Type	Required	Key	Constraints
event_id	string (uuid)	yes	primary key, unique	—
event_type	string (text)	yes	—	—
event_source	string (text)	yes	—	—
event_time	date (timestamp)	yes	—	—
payment_id	string (uuid)	yes	unique	—
order_id	string (uuid)	yes	—	—
settled_at	date (timestamp)	yes	partition	—
amount_pence	integer (bigint)	yes	—	≥ 0

SLA

• latency: 15m

Ownership & support

• team-payments (owner)
• slack: #payments-support