Payments API: a breaking change, a stale deprecation, and tokens in the logs
Your payments platform exposes a public REST API used by 3,100 integrators. The contract promises twelve months' notice before any breaking change. The field amount is currently a JSON number with two decimals, for example 12.34, and you need integer minor units to eliminate float rounding, which has produced 14 support tickets in six months and three real ledger corrections. A v1 endpoint was deprecated fourteen months ago; 8% of traffic still reaches it, and 40 integrators, accounting for about 61% of payment volume, are among those still calling it. Separately, three merchant accounts have debug logging enabled that writes full request bodies, including card tokens, into a log store with 90-day retention. Finance wants the amount change in the next release, six weeks out.
1. How would you sequence and communicate the change to the amount field?
Read the worked answer
Changing the meaning of amount in place is the worst option available. A client that ignores the change goes from charging 12.34 to charging 1234, a hundredfold error, and it happens silently. Six weeks also does not satisfy a twelve-month notice clause, so the schedule itself is a contract question before it is a technical one.
The workable path is additive. Introduce amount_minor plus an explicit currency alongside the existing amount, with the server translating for old clients, and deprecate amount on the contractual timeline. This keeps 3,100 integrators working, lets each one opt in per request, and, critically, lets you measure adoption before you switch anything off. A new major version is the alternative, but it forces every integrator through a migration at once for a field-level change.
Sequence: publish the spec diff and a machine-readable changelog, announce with dates, ship the new field, instrument adoption by integrator, remind at intervals, then schedule sunset. Note whether the three ledger corrections constitute a known defect that changes urgency. Even if it does, the response is add-and-migrate faster, not mutate in place.
2. How do you handle shutting down v1 when 40 large integrators are still on it?
Read the worked answer
Fourteen months past deprecation, with 8% of traffic and 61% of volume, means the notice was delivered but was not effective. Shutting v1 off on policy would strand the merchants who matter most, so the leverage here is commercial while the mechanism should stay technical.
First, get facts: instrument per-integrator and per-endpoint usage, and check whether the 40 are genuinely dependent or simply have v1 in a retry or health-check path. The remediation differs completely between those two cases. Second, run direct outreach with named contacts, a migration guide, a sandbox, and a written per-integrator sunset date. For the large ones, provide a supported translation shim that maps the v1 contract onto v2 internally, so they can move on their own schedule while you control the semantics. Third, keep the public deadline for the long tail, since those are cheap migrations, and publish remaining usage counts so the number visibly moves.
What must not happen is a quiet extension for the big accounts. Every exception gets a documented owner, date, and justification, otherwise the deprecation has no end.
3. What do you do about the debug logging of full request bodies, and how does it rank against the amount change?
Read the worked answer
The logging issue comes first, and not because it is easier. Writing full request bodies containing card tokens into a log store with 90-day retention expands the cardholder data environment into systems that were never in scope, and it is almost certainly a breach of your PCI DSS obligations.
Immediate actions: disable debug logging on the three accounts, then restrict and purge the affected log data. Treat it as a security incident: determine where those logs have travelled, including support exports, the logging vendor, and backups, because retention policies are usually only enforced on the live index. Assess whether any logged token is usable; if these are non-reversible tokens the direct exposure is narrower, but the data flow still needs review and the finding still needs reporting to your security function.
Then fix the cause rather than the symptom: redaction at the logging library using a field-name deny-list, plus an automated test that fails the build if a card-like pattern reaches the logging sink, plus a default-off guard on request-body logging.
Ranking: the logging exposure is live and unbounded; the amount change is on a twelve-month contractual clock. Run both, but do not let the finance deadline consume the week in which card data is sitting in a log store.