Historical transfer problem reports

API 0.16 adds explicit reporting from an owned historical transfer. This is a synthetic sandbox capability enabled by the operator. The current payer unlocks with device-bound DPoP; the original transfer session may already have ended. Reporting never executes a transfer, contacts a provider, requests a refund or renews session activity.

The payer API runs only in the local sandbox: the hosted sandbox does not serve it yet.

Submit POST /v1/payer/transfer-history/{id}/problems with a canonical UUID Idempotency-Key and exactly reason and description in a UTF-8 JSON object. Reasons are TRANSFER_NOT_RECEIVED, UNRECOGNIZED_TRANSFER, DUPLICATE_TRANSFER, AMOUNT_OR_FEE, or OTHER. A description must be trimmed, nonblank and at most 2,000 Unicode code points / 8,000 UTF-8 bytes. Internal LF is allowed; other control characters, Unicode format characters and unpaired surrogates are rejected. The encoded JSON body is limited to 32,768 bytes; unknown/duplicate fields, query parameters and content encodings are rejected. Never include issuer credentials.

The server derives ownership and immutable original facts. PayerTransferProblem includes an FR- support reference, SUBMITTED acknowledgement, canonical UTC submission/target dates and evidence_basis: AT_SUBMISSION. Exact money remains decimal strings in minor units. The dated monetary evidence is the snapshot at submission, even if the transfer later changes. Masked facts exclude account IDs and execution capabilities. Do not label the acknowledgement as a staff response, resolution, refund or current payment outcome.

Keep one idempotency UUID for one exact submission. An identical committed retry returns the same 201 record; changing the reason, description or transfer under that key returns 409. After a lost response, deliberately call GET /v1/payer/transfer-problems/by-idempotency-key/{key} to recover the committed record, or explicitly retry the identical submission. GET /v1/payer/transfer-problems/{id} reads an owned report. Both GET routes reject bodies, query strings and Idempotency-Key headers. Unknown and foreign references return indistinguishable 404 responses. Recovery 404 means absent at that read; it does not prove an earlier concurrent submission can never commit. Keep the original key while the outcome is uncertain. Read/recovery requires a current session; it grants no original execution authority.

The generated PayerProblemsApi provides submitPayerTransferProblem, readPayerTransferProblem and recoverPayerTransferProblem, with their Raw variants for status and headers. Submission takes {id, idempotencyKey, problemReportInput}. Supply fresh DPoP for the exact method and public URI on every attempt, and handle a nonce challenge explicitly. The client does not enqueue forms, retry mutations, renew sessions or generate authority. Clear private drafts on lock/sign-out/background boundaries; retain only the safe identifiers needed for explicit recovery.

Technical abuse limits are shared across the payer’s devices: 60 authenticated requests per minute and 10 new-key admission attempts per hour. Unknown/unavailable original transfer attempts count toward admission; exact committed retries and report reads skip that hourly bucket. Failed report transactions retain the committed request quota. New-report admission usage commits with completed processing; unexpected transaction rollback removes its uncommitted usage. RateLimit-* reports the request bucket on ordinary responses and the denied bucket on 429. Observe Retry-After; do not spin or silently retry. Independent nonce-issuance throttling may omit those report-budget headers.

The response target is submission +48 hours and the resolution target is +15 days. These retained targets do not prove operational fulfilment. Staff response/resolution events, native forms and support operations are subsequent work. Live support contacts, rulebook liability and production key rotation remain external requirements.