Transfer approval requests

The payer API 0.11 adds optional synthetic approval request preparation. First obtain an immutable quote and complete its device-signed transfer consent. Then call POST /v1/payer/transfer-approval-requests with only consent_id, an Idempotency-Key UUID and fresh DPoP from the original session. The identity service resolves the original signed consent and protected destination itself.

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

The PREPARED / REQUEST_ONLY response confirms only that the switch retained the request. It confirms no issuer decision, no debit and no reservation of funds. CURRENT, EXPIRED and NOT_YET_CURRENT describe only the retained time window. No approval URL or secret issuer data is returned at this step.

Keep the exact mutation UUID and consent ID after a timeout or APPROVAL_OUTCOME_UNKNOWN. Retry them with a fresh DPoP proof. The original assertion is committed before transport; attempts are committed independently before each network effect. Retries preserve the source observation and deadline across both service restarts. A different key cannot bind the same consent again, and a changed consent under the same key conflicts. Ten admissions per payer/minute, sixty/hour and ten transport attempts per intent are the persistent limits.

GET /v1/payer/transfer-approval-requests/{id} returns the historical receipt to the original session while it is active. The source must stay VERIFIED. Another session, a revocation or a suspension of the source forbids access. Reads are passive: they contact no issuer and do not extend the session. An exact retry can recover a request already retained after its deadline; it never renews its authority.

The generated SDK supplies TransferApprovalRequest and TransferApprovalReceipt, plus preparePayerTransferApproval and readPayerTransferApproval. It serializes consentId to consent_id; clients still own device signing, DPoP and safe retry state. Display the receipt as a prepared request. The optional issuer status flow adds explicit refresh and synthetic handoff after this receipt. Monetary execution remains separate. Android and iOS implement their own native journeys independently.