Transfer history

Payer API 0.15 adds GET /v1/payer/transfer-history and GET /v1/payer/transfer-history/{id}. Both require a current active payer session and a fresh device-backed DPoP proof. A new session belonging to the same payer can inspect transfers after the original session expires or signs out. This grants historical access only: execution_permitted is always false. Original-session execution, refresh and status routes keep their existing restrictions.

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

Use an empty body and no content encoding. Responses are no-store; errors include stable error.code, message_en and message_fr. Foreign and unknown detail IDs both return 404. A rejected or expired current session returns 401. Handle DPoP-Nonce by making one new proof with a new proof ID, never by replaying the old proof. The proof target excludes the query string.

Query	Meaning
source_account_id	Canonical lowercase linked-account UUID.
currency	CDF or USD.
from / until	Inclusive / exclusive original creation dates, exactly YYYY-MM-DDTHH:mm:ssZ.
state	Retained monetary state at this read, including INVESTIGATION_REQUIRED.
limit	Candidate scan bound, 1–20, default 20.
cursor	Opaque continuation tied to the payer and the same canonical filters, including limit.

Unknown, duplicated, blank and noncanonical query values are rejected. Records are ordered by original creation time descending with a stable tie-breaker. The first page fixes membership with an insertion watermark; later insertions require a new first page. A cursor expires 15 minutes after the first page and continuation does not extend it.

An empty items array can still have a next_cursor. Status is checked against current retained evidence after scanning a bounded number of candidates, so a page may contain no matches. Continue only within a bounded client budget or an explicit “load more” action. Only next_cursor: null ends the candidates. Do not display global “no history” from one empty page with continuation. scanned_count, scan_limit and status_basis explain this behavior. Status can change across pages when new retained observations or conflicts arrive; this is not a frozen financial-state snapshot.

All history response timestamps are ISO 8601 UTC strings, with explicit nulls where evidence is absent. created_at dates the original request; monetary observation and participant confirmation dates retain their original meanings. Reading history does not call the switch or participant, advance money, refresh evidence, resume the original session or update session activity. A later source/issuer/delivery/history conflict overrides a retained success with INVESTIGATION_REQUIRED, suppresses usable accounting completion and nulls participant confirmation. Existing posting legs and dates remain historical evidence. An unavailable latest refresh can retain an older observation; show both its state and its date. UNAVAILABLE, REFRESH_PENDING, REVERSAL_PENDING and REVERSAL_FAILED prove neither a recent success nor a refund.

Amounts are exact integer minor units encoded as canonical decimal strings alongside currency. Keep them as strings or use integer arithmetic; never convert through floating point. Only masked source identifiers and recipient names are returned. No recipient selector, account token, issuer mandate or provider reference is exposed.

The list and detail share a durable allowance of 60 authenticated reads per payer in a fixed 60-second window, across sessions and devices. RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset (seconds) and RateLimit-Policy describe the committed measurement. HISTORY_RATE_LIMITED returns 429 plus Retry-After. Malformed input before authentication, nonce challenges and rolled-back storage failures do not invent quota values. The separate nonce-issuance limit can return RATE_LIMITED without history quota headers. Reads still consume proof replay and quota bookkeeping.

The generated PayerHistoryApi provides listPayerTransferHistory and readPayerTransferHistory. Use the Raw variants to access quota headers. Response dates decode to Date; filter dates remain canonical strings. The SDK does not automatically drain continuation pages, retry 429 responses, renew sessions or refresh monetary evidence. Supply a fresh DPoP proof per call.

The sandbox boundary defaults off. Enable IDENTITY_HISTORY_ENABLED=true with quote and approval prerequisites after the migration/writer rollout. Existing data requires explicit bounded maintenance; reads return HISTORY_INDEX_NOT_READY until the queue completes. Follow the identity repository’s history API runbook. This transfer source does not yet provide all transaction types, native receipts/share or problem reporting; APP-07 remains open. Live provider and production deployment gates remain external.