API Contract Enforcer

# API Contract Diff — `/v1` surface

**Reference:** tag `v1.3.0`
**Current:** HEAD (branch `feat/refactor-payments-surface`)
**API type:** REST, OpenAPI 3.1
**Stability commitment:** public-versioned (external consumers)

<div data-callout="critical" data-label="Verdict">

**Do not merge as written.** Three breaking changes detected against the `/v1` surface that external consumers depend on. Two are silent (no error response, just changed shape) and would cascade through consumer SDKs within minutes of deploy. The third tightens a validation rule that previously accepted-and-coerced legacy inputs.

</div>

---

## Violations summary

| # | Endpoint | Change | Severity |
|---|---|---|---|
| V-01 | `GET /v1/charges/{id}` | Field rename: `captured_amount` → `amount_captured` | <span data-pill="critical">breaking</span> |
| V-02 | `POST /v1/charges` | Field removed from response: `charge_url` | <span data-pill="critical">breaking</span> |
| V-03 | `POST /v1/refunds` | Request validation tightened: `reason` now required (was optional) | <span data-pill="critical">breaking</span> |
| V-04 | `GET /v1/charges` | New optional query param `expand` added | <span data-pill="positive">additive</span> |
| V-05 | `POST /v1/charges` | Response: new field `risk_score` added | <span data-pill="positive">additive</span> |
| V-06 | `GET /v1/charges/{id}` | Field `status` enum gained value `disputed` | <span data-pill="caution">forward-additive</span> |

---

<div data-callout="critical" data-label="V-01 — silent field rename">

Renaming `captured_amount` → `amount_captured` is a **client-breaking change**. External SDKs and consumer code reading the old field will read `undefined` after deploy, with no error. The Stripe-flavored convention argues for `amount_captured` (matches `amount_refunded`, `amount_received`), but the rename must be **additive** on `/v1`:

1. Add `amount_captured` alongside the existing `captured_amount`.
2. Mark `captured_amount` as deprecated in the OpenAPI doc.
3. Communicate the deprecation window (recommended: 6 months on a public-versioned surface).
4. Remove `captured_amount` only in `/v2` — never in `/v1`.

</div>

<div data-callout="critical" data-label="V-02 — field removed without v-bump">

`charge_url` was returned by `POST /v1/charges` since v0.4.0. Removing it in a non-major version is a breaking change. **Either** restore the field (have it return a deterministic URL or null), **or** bump to `/v2`. Removing fields is the most-cited cause of cross-service outages in this codebase's incident history — do not ship.

</div>

<div data-callout="critical" data-label="V-03 — validation tightened">

`reason` on `POST /v1/refunds` is now declared `required` in the schema. Existing consumer code that omits `reason` (currently treated as `"requested_by_customer"` by default) will see `400 Bad Request` after deploy. If the requirement is genuinely needed, keep the field optional in the schema and apply the default server-side — which is in fact what the current behavior does.

</div>

<div data-stack data-stack-title="Recommended fixes — minimum to merge">
<div data-row data-value="V-01">Re-add `captured_amount` as a deprecated alias of `amount_captured`</div>
<div data-row data-value="V-02">Re-add `charge_url` to the response shape — compute server-side if no longer stored</div>
<div data-row data-value="V-03">Make `reason` optional in the OpenAPI schema; keep the server-side default</div>
<div data-row data-value="docs">Update `docs/api/CHANGELOG.md` with the deprecation timeline for V-01</div>
<div data-row data-value="tests">Add contract tests that assert the old field names are still present in responses</div>
</div>

<div data-callout="info" data-label="Additive changes — safe to ship">

V-04, V-05, and V-06 are backward-compatible. Note that V-06 (new enum value) is **forward-additive** — older consumers may not have a code path for `disputed` and may default to "unknown" handling. Communicate the new enum value in release notes and the changelog, but it does not block merge.

</div>

*This contract check runs against every PR that touches the `/v1` surface. Merging requires zero `breaking` findings, or an approved `v2` migration plan referenced in the PR description.*

This sample illustrates the skill's output format. Names, metrics, and operational details are illustrative unless the artifact explicitly analyzes public information.