Monetary status
Payer API 0.13 adds POST /v1/payer/transfer-approval-requests/{id}/monetary-refresh and GET /v1/payer/transfer-approval-requests/{id}/monetary-status. Both require fresh device-backed DPoP from the original active payer/device/session, an empty body, no query parameters and no content encoding. The POST also requires one UUID Idempotency-Key. Responses are no-store. Foreign original scope returns 404; a revoked or signed-out session returns 401. Neither route renews session activity or authorizes money movement.
The payer API runs only in the local sandbox: the hosted sandbox does not serve it yet.
An explicit refresh commits an immutable attempt before a bounded private switch GET. Identity independently verifies the original execution and retains encrypted observations. It releases its database transaction and authority locks before HTTP, and rechecks current authority before returning payer data. Reads only restore retained history; they cannot call the switch or participant, retry a payment, repair postings or renew a confirmation date. Existing EXECUTION_STATUS_ONLY / STORED responses still describe command storage only.
| Public state | Meaning |
|---|---|
| NOT_ADMITTED / NOT_OBSERVED | No original execution / no trustworthy monetary observation retained. |
| REFRESH_PENDING / UNAVAILABLE | Latest refresh is interrupted or in flight / has no trustworthy observation. An older dated observation may still be present. |
| READY / EXPIRED_BEFORE_START | Original execution has not begun; an observation may show its original start authority expired. |
| DEBIT_PENDING / DEBIT_FAILED | Debit remains unresolved / definitive original debit failure. |
| CREDIT_PENDING | Original debit has posted; recipient credit remains unresolved. |
| COMPLETED_UNCONFIRMED / COMPLETED | Original debit and credit are accounted; dated terminal participant confirmation is absent / present. |
| ACCOUNTING_INCOMPLETE | Terminal progress exists but required original postings are incomplete. |
| REVERSAL_PENDING / REVERSAL_FAILED | Full refund remains unresolved / failed and needs operational follow-up. Neither means refunded. |
| REVERSED_UNCONFIRMED / REVERSED | Full original refund is accounted; dated terminal participant confirmation is absent / present. |
| INVESTIGATION_REQUIRED | Permanent remote/history conflict or local source/issuer/intake hold overrides usability. Valid historical posting legs remain visible. |
Always read the top-level state, investigation_required and last_refresh alongside observation. The observation is explicitly null before verified evidence exists. accounted_legs identifies retained postings; it is not a new instruction. An investigation forces accounting_complete false and provider_confirmed_at_epoch_seconds null without erasing valid postings.
The timestamps answer separate questions: refresh_requested_at_epoch_seconds and refresh_received_at_epoch_seconds describe the latest requested fetch; observation_received_at_epoch_seconds dates the selected retained observation; inspected_at_epoch_seconds dates switch inspection; provider_confirmed_at_epoch_seconds dates participant evidence: provider_confirmed_at_epoch_seconds: null means no usable dated terminal confirmation exists. A newer inspection, identity restart or read never makes an older participant confirmation fresh. An unavailable refresh can retain an earlier completed observation with its original dates. No freshness lifetime or perpetual finality is promised. terminal_window_ends_at_epoch_seconds describes a finite reconciliation window.
Same-key retries are always passive, including interrupted or unavailable attempts. A process crash after reservation can leave that attempt pending; use a new key for an explicit new bounded fetch. Never replace the original transfer, amount or deadline. Limits are sixty refresh attempts per execution and 120 per original session per minute; 429 leaves passive status available. Compatible stale replies cannot replace newer observations. Original execution history remains available after transfer expiry and issuer-pin rotation while the original session remains active. Expiry after debit begins does not mean cancellation or refund.
The SDK exposes refreshPayerTransferMonetaryStatus, readPayerTransferMonetaryStatus, TransferMonetaryStatus and nullable TransferMonetaryObservation. Supply a fresh DPoP proof per call. Retain the mutation key until the response is known; a deliberate subsequent observation request gets a new key.
This synthetic feature defaults off. Identity requires the quote, approval, issuer-refresh and execution prerequisites plus IDENTITY_MONETARY_ENABLED=true, literal loopback IDENTITY_MONETARY_SWITCH_ORIGIN, dedicated canonical IDENTITY_MONETARY_SERVICE_KEY and IDENTITY_MONETARY_PERIMETER_KEY. The switch requires PAYER_MONETARY_OBSERVATION_ENABLED=true and matching dedicated credentials. Live participant integrations and production release gates remain external.