Payment Retry Policy Contract

The running example throughout the book, and in the toolkit's own templates, is a capability called `payment/retry`, owned by a payments team. What it does sounds simple: decide whether a failed payment attempt is safe to retry. What makes it a good teaching example is that the simple description hides a constraint that isn't obvious from the code, and that constraint is exactly what a contract exists to preserve.

The minimum viable version states the capability plainly. It retries a failed payment attempt only after confirming the upstream payment processor has not yet received, or is not currently processing, the original request. It exists because the processor used in production doesn't honor idempotency keys until a transaction finishes processing, which means a naive retry fired while the original request is still in flight results in a duplicate charge. That sentence alone is the entire reason this capability needs to exist as its own contracted unit rather than a few lines buried inside a larger payment flow.

It needs a `payment_id`, which has to be the original ID from the failed attempt, never a freshly generated one, because the processor uses that field to detect duplicate attempts once idempotency keys are active. It needs a `retry_reason`, restricted to `network_timeout`, `processor_unavailable`, or `rate_limited`, explicitly excluding declined payments, which the contract states is a different capability's problem, not this one's. It promises a `retry_status` that only reports `confirmed_safe_to_retry` after explicit confirmation from the processor's status endpoint, never inferred from a timeout. And it draws a hard boundary: this capability assesses retry safety and returns a status. It does not initiate the retry itself, does not touch declined payments, and does not modify the original payment record. Three sentences, and a future engineer or agent now knows exactly where this capability's authority ends.

The extended version of the same contract is where the real story lives, in a field called `constraint_history`. On March 14, 2022, a production incident happened because the retry logic called the processor directly without checking in-flight status first. The processor was still processing the original request when the retry arrived. Forty-seven customers were charged twice. Refunds went out the same day. The revenue impact was twenty-three thousand dollars, and it triggered an SLA breach with two enterprise customers. The lesson, confirmed by the processor's own support team in ticket PRO-8821, is that the processor doesn't honor idempotency keys until processing completes, a fact that isn't in the processor's public documentation at all. Any retry implementation has to check in-flight status explicitly, and that requirement is now written into the contract instead of living only in the memory of whoever handled the incident.

The extended contract also declares the dependency this capability can't function without: `payment/processor/status` at version 2.1.0 or later, with the rationale attached directly. Earlier versions of that capability didn't expose in-flight transaction state, which made a safe retry decision impossible to make at all. Nobody is meant to relax that version constraint without first confirming an alternative detection method with the payments team, and the contract says so explicitly rather than leaving it to be rediscovered the hard way a second time.

Performance and rate limits carry their own reasoning too. The p99 response target is 500 milliseconds, bounded by the processor's own status-check latency, and the contract notes that the threshold assumes that check completes in under 400 milliseconds, so any renegotiation of processor latency has to happen before the timeout changes. The rate limit is set to thirty requests per minute with a burst allowance of five, deliberately half of the processor's own sixty-per-minute ceiling, to leave headroom for every other caller hitting that same status endpoint. And the error handling rule is asymmetric on purpose: if the processor's status can't be confirmed, the capability returns `unsafe` and blocks the retry. A false negative that blocks a safe retry is an acceptable cost. A false positive that allows an unsafe one is not, and the contract states that tradeoff instead of leaving it as an assumption baked into a conditional somewhere.

None of this is hypothetical or dressed up for the page. It's the actual worked example shipped in the toolkit's templates, the same one the appendix's schema reference walks through field by field. The point of showing it in full is that a contract isn't paperwork bolted onto working code after the fact. It's the incident, the dependency, and the boundary that were always true, made readable to whoever, or whatever, has to touch this capability next.