{ "openapi": "3.1.0", "info": { "title": "Futa Payer Identity API", "version": "0.18.0", "description": "Local synthetic payer phone verification, profile enrollment and device-bound Futa sessions. No issuer credentials, live SMS, recovery or live payment execution. Consent-bound synthetic issuer account linking; configured synthetic issuer handoff is available; live issuers remain disabled. Authenticated synthetic transfer quote previews are optional when enabled. Quotes are passive, scoped to their original device session, and never authorize a debit. Optional device-signed transfer consent records exact payer intent only; issuer debit approval remains separate. Optional consent-bound approval request preparation records REQUEST_ONLY authority; it does not deliver an issuer decision or authorize money movement. Optional explicit issuer refresh and passive status use identity-owned historical acceptance. They never grant monetary execution authority. Optional original-session execution delivery commits one local authorization and sends its exact protected command to switch storage. EXECUTION_STATUS_ONLY never claims debit, credit or completed transfer. Optional original-session monetary refresh reads independently verified synthetic switch observations. MONETARY_STATUS_ONLY preserves historical accounting, permanent investigation and dated participant confirmation; it never authorizes a payment or refreshes provider evidence by itself. Optional fresh device/passcode resumption restores an original still-active session without changing its authority or deadlines. Optional current-session historical transfer list/detail preserves exact masked terms, bounded opaque continuation, dated retained evidence and original execution restrictions. Optional current-session historical transfer problem reports retain encrypted immutable evidence and target dates; acknowledgement does not imply staff response or resolution. Optional default-off staff support routes require current MFA issuer introspection and explicit support permissions. Internal recorded responses and resolutions never claim delivery or execute monetary actions." }, "servers": [ { "url": "http://127.0.0.1:18190", "description": "Loopback sandbox only; production requires approved HTTPS deployment." } ], "paths": { "/v1/payer/phone-challenges": { "post": { "operationId": "createPayerPhoneChallenge", "tags": [ "PayerPhone" ], "summary": "Create a synthetic phone challenge", "security": [], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneChallengeRequest" } } } }, "responses": { "201": { "description": "Create a synthetic phone challenge", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneChallenge" } } } }, "400": { "description": "Invalid request or code", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "401": { "description": "Invalid device proof", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "404": { "description": "Unknown challenge", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "409": { "description": "Changed retry or unavailable challenge", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "410": { "description": "Expired challenge or replay", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "429": { "description": "Persistent rate limit", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "503": { "description": "Dependency unavailable; retain mutation identity", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } } }, "description": "Body maximum 4096 bytes. New mutation creates one random OTP record, encrypted delivery and five-minute device challenge. Exact retries return the original PENDING response without extending expiry or sending again; this is historical creation evidence, not a live status read. New challenges obey cooldown and rolling budgets, and supersede prior pending challenges for the phone. No OTP appears in this response." } }, "/v1/payer/phone-challenges/{id}/verify": { "post": { "operationId": "verifyPayerPhoneChallenge", "tags": [ "PayerPhone" ], "summary": "Verify phone possession and device proof", "security": [], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneVerificationRequest" } } } }, "responses": { "200": { "description": "Verify phone possession and device proof", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneVerified" } } } }, "400": { "description": "Invalid request or code", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "401": { "description": "Invalid device proof", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "404": { "description": "Unknown challenge", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "409": { "description": "Changed retry or unavailable challenge", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "410": { "description": "Expired challenge or replay", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "429": { "description": "Persistent rate limit", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "503": { "description": "Dependency unavailable; retain mutation identity", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } } }, "description": "Requires both valid OTP and a signature over the immutable server challenge. Exact retries retain the encrypted original response until its expiry. Wrong-code retries with the same body/key do not spend another guess; changed body conflicts. Successful verification produces one two-minute device-bound enrollment grant, never a payer session. Profile enrollment consumes the grant once through a fresh passcode-bound device challenge; it does not issue a session. Retain body and idempotency key after uncertain transport errors; never generate automatic replacement commands." } }, "/v1/payer/enrollment-challenges": { "post": { "operationId": "preparePayerEnrollment", "tags": [ "PayerEnrollment" ], "summary": "Prepare profile and passcode enrollment", "security": [], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentRequest" } } } }, "responses": { "201": { "description": "Prepare profile and passcode enrollment", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentChallenge" } } } }, "400": { "description": "Invalid bounded JSON request", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "401": { "description": "Invalid grant or device proof", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "404": { "description": "Challenge not found for this grant", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "409": { "description": "Idempotency conflict or enrollment unavailable", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "410": { "description": "Grant expired, including exact replay", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "429": { "description": "Persistent grant budget exhausted", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "503": { "description": "Dependency or hash capacity unavailable", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } } }, "description": "Sandbox only. Maximum JSON body 4096 bytes. Requires unexpired grant; exact retries never extend expiry. Five preparations and ten proof attempts per grant. Existing phone/device profiles cannot be reset or replaced through this flow. No session is issued." } }, "/v1/payer/enrollment-challenges/{id}/complete": { "post": { "operationId": "completePayerEnrollment", "tags": [ "PayerEnrollment" ], "summary": "Consume a grant and enroll a device-bound Futa profile", "security": [], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentCompletionRequest" } } } }, "responses": { "201": { "description": "Consume a grant and enroll a device-bound Futa profile", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayerEnrolled" } } } }, "400": { "description": "Invalid bounded JSON request", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "401": { "description": "Invalid grant or device proof", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "404": { "description": "Challenge not found for this grant", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "409": { "description": "Idempotency conflict or enrollment unavailable", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "410": { "description": "Grant expired, including exact replay", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "429": { "description": "Persistent grant budget exhausted", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "503": { "description": "Dependency or hash capacity unavailable", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } } }, "description": "Sandbox only. Maximum JSON body 4096 bytes. Requires unexpired grant; exact retries never extend expiry. Five preparations and ten proof attempts per grant. Existing phone/device profiles cannot be reset or replaced through this flow. No session is issued." } }, "/v1/payer/unlock-challenges": { "post": { "operationId": "preparePayerUnlock", "tags": [ "PayerSessions" ], "summary": "Prepare a fresh device and Futa passcode unlock", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [], "responses": { "201": { "description": "Prepare a fresh device and Futa passcode unlock", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnlockChallenge" } } } }, "400": { "description": "Invalid strict input", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "401": { "description": "Device, passcode, session or DPoP proof rejected; nonce challenge may be included", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "404": { "description": "Unlock challenge not found", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "409": { "description": "Idempotency conflict or challenge consumed", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "410": { "description": "Unlock challenge or retained result expired", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "423": { "description": "Persistent unlock retry lock is active", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "429": { "description": "Persistent rate budget exhausted", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "503": { "description": "Dependency or hash capacity unavailable", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnlockRequest" } } } }, "description": "Sandbox only; maximum strict JSON body 4096 bytes. Fresh enrolled-key proof and Futa passcode are both required. Five incorrect passcodes lock unlock for 15 minutes; UUID changes do not reset budgets. Exact completion replies are encrypted and expire with the two-minute challenge, and cannot retrieve a revoked session. No issuer credentials or SMS-only reset. Optional original-session resumption defaults off. Preparation does not reveal target existence. Completion requires fresh purpose-bound device proof and current passcode, then exact original payer/device ownership and active unrevoked session. Restores the original protected credential with a fresh DPoP nonce; never creates a session, changes last activity or extends original expiry. Ordinary unlock and resumption share all preparation/proof budgets and passcode lockouts. Same-key completion retries remain exact and require current original authority; unknown, foreign, revoked and expired targets return INVALID_SESSION." } }, "/v1/payer/unlock-challenges/{id}/complete": { "post": { "operationId": "completePayerUnlock", "tags": [ "PayerSessions" ], "summary": "Unlock with device proof and Futa passcode", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [], "responses": { "200": { "description": "Unlock with device proof and Futa passcode", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayerSessionIssued" } } } }, "400": { "description": "Invalid strict input", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "401": { "description": "Device, passcode, session or DPoP proof rejected; nonce challenge may be included", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "404": { "description": "Unlock challenge not found", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "409": { "description": "Idempotency conflict or challenge consumed", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "410": { "description": "Unlock challenge or retained result expired", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "423": { "description": "Persistent unlock retry lock is active", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "429": { "description": "Persistent rate budget exhausted", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "503": { "description": "Dependency or hash capacity unavailable", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnlockCompletionRequest" } } } }, "description": "Sandbox only; maximum strict JSON body 4096 bytes. Fresh enrolled-key proof and Futa passcode are both required. Five incorrect passcodes lock unlock for 15 minutes; UUID changes do not reset budgets. Exact completion replies are encrypted and expire with the two-minute challenge, and cannot retrieve a revoked session. No issuer credentials or SMS-only reset. Optional original-session resumption defaults off. Preparation does not reveal target existence. Completion requires fresh purpose-bound device proof and current passcode, then exact original payer/device ownership and active unrevoked session. Restores the original protected credential with a fresh DPoP nonce; never creates a session, changes last activity or extends original expiry. Ordinary unlock and resumption share all preparation/proof budgets and passcode lockouts. Same-key completion retries remain exact and require current original authority; unknown, foreign, revoked and expired targets return INVALID_SESSION." } }, "/v1/payer/session": { "get": { "operationId": "getPayerSession", "tags": [ "PayerSessions" ], "summary": "Read the current device-bound session", "parameters": [], "security": [ { "DpopSession": [], "DpopProof": [] } ], "responses": { "200": { "description": "Read the current device-bound session", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayerSession" } } } }, "400": { "description": "Invalid strict input", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "401": { "description": "Device, passcode, session or DPoP proof rejected; nonce challenge may be included", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "DPoP-Nonce": { "description": "Only returned for an otherwise valid signed request needing a new server nonce; retry with a fresh proof ID.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "404": { "description": "Unlock challenge not found", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "409": { "description": "Idempotency conflict or challenge consumed", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "410": { "description": "Unlock challenge or retained result expired", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "423": { "description": "Persistent unlock retry lock is active", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "429": { "description": "Persistent rate budget exhausted", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "503": { "description": "Dependency or hash capacity unavailable", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } } }, "description": "Requires one Authorization: DPoP token and one fresh DPoP proof. Five-minute idle and one-hour absolute expiry are checked server-side. Reads and nonce challenges do not extend idle. Activity requires explicit foreground user intent. Sign-out invalidates the token; later use, including an uncertain sign-out retry, returns INVALID_SESSION. Exact activity retries with fresh proofs retain the original result without extending idle again." } }, "/v1/payer/session/activity": { "post": { "operationId": "recordPayerActivity", "tags": [ "PayerSessions" ], "summary": "Record explicit foreground user activity", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "DpopSession": [], "DpopProof": [] } ], "responses": { "200": { "description": "Record explicit foreground user activity", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayerSession" } } } }, "400": { "description": "Invalid strict input", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "401": { "description": "Device, passcode, session or DPoP proof rejected; nonce challenge may be included", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "DPoP-Nonce": { "description": "Only returned for an otherwise valid signed request needing a new server nonce; retry with a fresh proof ID.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "404": { "description": "Unlock challenge not found", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "409": { "description": "Idempotency conflict or challenge consumed", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "410": { "description": "Unlock challenge or retained result expired", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "423": { "description": "Persistent unlock retry lock is active", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "429": { "description": "Persistent rate budget exhausted", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "503": { "description": "Dependency or hash capacity unavailable", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyIdentityMutation" } } } }, "description": "Requires one Authorization: DPoP token and one fresh DPoP proof. Five-minute idle and one-hour absolute expiry are checked server-side. Reads and nonce challenges do not extend idle. Activity requires explicit foreground user intent. Sign-out invalidates the token; later use, including an uncertain sign-out retry, returns INVALID_SESSION. Exact activity retries with fresh proofs retain the original result without extending idle again." } }, "/v1/payer/session/sign-out": { "post": { "operationId": "signOutPayerSession", "tags": [ "PayerSessions" ], "summary": "Revoke the current session", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "DpopSession": [], "DpopProof": [] } ], "responses": { "200": { "description": "Revoke the current session", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayerSignedOut" } } } }, "400": { "description": "Invalid strict input", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "401": { "description": "Device, passcode, session or DPoP proof rejected; nonce challenge may be included", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "DPoP-Nonce": { "description": "Only returned for an otherwise valid signed request needing a new server nonce; retry with a fresh proof ID.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "404": { "description": "Unlock challenge not found", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "409": { "description": "Idempotency conflict or challenge consumed", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "410": { "description": "Unlock challenge or retained result expired", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "423": { "description": "Persistent unlock retry lock is active", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "429": { "description": "Persistent rate budget exhausted", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "503": { "description": "Dependency or hash capacity unavailable", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyIdentityMutation" } } } }, "description": "Requires one Authorization: DPoP token and one fresh DPoP proof. Five-minute idle and one-hour absolute expiry are checked server-side. Reads and nonce challenges do not extend idle. Activity requires explicit foreground user intent. Sign-out invalidates the token; later use, including an uncertain sign-out retry, returns INVALID_SESSION. Exact activity retries with fresh proofs retain the original result without extending idle again." } }, "/v1/payer/security-alerts": { "get": { "operationId": "listPayerSecurityAlerts", "tags": [ "PayerSecurity" ], "summary": "Read the current payer security alert inbox", "parameters": [ { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "description": "Exclusive sequence cursor returned as next_cursor; omit for newest events." } ], "security": [ { "DpopSession": [], "DpopProof": [] } ], "responses": { "200": { "description": "Bounded payer security alert inbox", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayerSecurityAlerts" } } } }, "400": { "description": "Invalid strict input", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "401": { "description": "Device, passcode, session or DPoP proof rejected; nonce challenge may be included", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "DPoP-Nonce": { "description": "Only returned for an otherwise valid signed request needing a new server nonce; retry with a fresh proof ID.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "429": { "description": "Persistent rate budget exhausted", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "503": { "description": "Dependency or hash capacity unavailable", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } } }, "description": "Authenticated passive read with fresh DPoP proof; never extends idle. Descending immutable sequence cursor, at most 20 events. Delivery states are synthetic evidence only, never real SMS or push confirmation. No caller-selected payer identity." } }, "/v1/payer/devices": { "get": { "operationId": "listPayerDevices", "tags": [ "PayerDevices" ], "summary": "List current payer trusted and revoked devices", "parameters": [ { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Exclusive opaque UUID cursor from next_cursor." } ], "security": [ { "DpopSession": [], "DpopProof": [] } ], "responses": { "200": { "description": "Current payer device page", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayerDevices" } } } }, "400": { "description": "Invalid strict input", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "401": { "description": "Device, passcode, session or DPoP proof rejected; nonce challenge may be included", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "DPoP-Nonce": { "description": "Only returned for an otherwise valid signed request needing a new server nonce; retry with a fresh proof ID.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "429": { "description": "Persistent rate budget exhausted", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "503": { "description": "Dependency or hash capacity unavailable", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } } }, "description": "Passive authenticated read; at most 20 devices ordered by UUID descending. No keys or caller-selected payer identity. next_cursor is an exclusive UUID cursor; omitted starts newest UUID page." } }, "/v1/payer/device-revocations": { "post": { "operationId": "preparePayerDeviceRevocation", "tags": [ "PayerDevices" ], "summary": "Prepare purpose-bound remote device sign-out", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "DpopSession": [], "DpopProof": [] } ], "responses": { "201": { "description": "Prepare purpose-bound remote device sign-out", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceRevokeChallenge" } } } }, "400": { "description": "Invalid strict input", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "401": { "description": "Device, passcode, session or DPoP proof rejected; nonce challenge may be included", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "DPoP-Nonce": { "description": "Only returned for an otherwise valid signed request needing a new server nonce; retry with a fresh proof ID.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "404": { "description": "Target or challenge not available to this caller", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "409": { "description": "Idempotency conflict or challenge consumed", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "410": { "description": "Unlock challenge or retained result expired", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "429": { "description": "Persistent rate budget exhausted", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "503": { "description": "Dependency or hash capacity unavailable", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceRevokeRequest" } } } }, "description": "Active bound caller session and a fresh DPoP proof are required on every request. Completion additionally requires a DER signature of the fresh REVOKE_DEVICE challenge binding caller session, payer and exact target. Target must be another already-trusted device of the same payer. Self/foreign/unknown targets return 404. Two-minute challenge; five preparations per caller device/minute, ten proof attempts per challenge and fifty per caller device/minute. Exact completion retries retain outcome only while challenge and caller session remain valid; changed input conflicts. Revocation is permanent in this local lifecycle; additional trust/recovery is not provided. No implicit activity extension." } }, "/v1/payer/device-revocations/{id}/complete": { "post": { "operationId": "completePayerDeviceRevocation", "tags": [ "PayerDevices" ], "summary": "Revoke target device and all its sessions", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "DpopSession": [], "DpopProof": [] } ], "responses": { "200": { "description": "Revoke target device and all its sessions", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceRevoked" } } } }, "400": { "description": "Invalid strict input", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "401": { "description": "Device, passcode, session or DPoP proof rejected; nonce challenge may be included", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "DPoP-Nonce": { "description": "Only returned for an otherwise valid signed request needing a new server nonce; retry with a fresh proof ID.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "404": { "description": "Target or challenge not available to this caller", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "409": { "description": "Idempotency conflict or challenge consumed", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "410": { "description": "Unlock challenge or retained result expired", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "429": { "description": "Persistent rate budget exhausted", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "503": { "description": "Dependency or hash capacity unavailable", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceRevokeCompletion" } } } }, "description": "Active bound caller session and a fresh DPoP proof are required on every request. Completion additionally requires a DER signature of the fresh REVOKE_DEVICE challenge binding caller session, payer and exact target. Target must be another already-trusted device of the same payer. Self/foreign/unknown targets return 404. Two-minute challenge; five preparations per caller device/minute, ten proof attempts per challenge and fifty per caller device/minute. Exact completion retries retain outcome only while challenge and caller session remain valid; changed input conflicts. Revocation is permanent in this local lifecycle; additional trust/recovery is not provided. No implicit activity extension." } }, "/v1/payer/institutions": { "get": { "operationId": "listPayerInstitutions", "tags": [ "PayerAccounts" ], "summary": "List enabled synthetic institutions", "parameters": [], "security": [ { "DpopSession": [], "DpopProof": [] } ], "responses": { "200": { "description": "List enabled synthetic institutions", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkInstitutions" } } } }, "400": { "description": "Invalid strict input", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "401": { "description": "Device, passcode, session or DPoP proof rejected; nonce challenge may be included", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "DPoP-Nonce": { "description": "Only returned for an otherwise valid signed request needing a new server nonce; retry with a fresh proof ID.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "429": { "description": "Persistent rate budget exhausted", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "503": { "description": "Dependency or hash capacity unavailable", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } } }, "description": "List enabled synthetic institutions. All public calls require an active device-bound DPoP session and fresh proof. Reads and mutations do not extend idle expiry. Synthetic institutions appear only when issuer public keys are configured; only the explicitly configured synthetic issuer channel is available; live issuers remain disabled." } }, "/v1/payer/account-links": { "post": { "operationId": "preparePayerAccountLink", "tags": [ "PayerAccounts" ], "summary": "Prepare five-minute account link and two-minute device consent", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "DpopSession": [], "DpopProof": [] } ], "responses": { "201": { "description": "Prepare five-minute account link and two-minute device consent", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountLinkChallenge" } } } }, "400": { "description": "Invalid strict input", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "401": { "description": "Device, passcode, session or DPoP proof rejected; nonce challenge may be included", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "DPoP-Nonce": { "description": "Only returned for an otherwise valid signed request needing a new server nonce; retry with a fresh proof ID.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "404": { "description": "Target or challenge not available to this caller", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "409": { "description": "Idempotency conflict or challenge consumed", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "410": { "description": "Unlock challenge or retained result expired", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "429": { "description": "Persistent rate budget exhausted", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "503": { "description": "Dependency or hash capacity unavailable", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountLinkRequest" } } } }, "description": "Prepare five-minute account link and two-minute device consent. All public calls require an active device-bound DPoP session and fresh proof. Reads and mutations do not extend idle expiry. Synthetic institutions appear only when issuer public keys are configured; only the explicitly configured synthetic issuer channel is available; live issuers remain disabled." } }, "/v1/payer/account-links/{id}/consent": { "post": { "operationId": "consentPayerAccountLink", "tags": [ "PayerAccounts" ], "summary": "Consent with the original active session and fresh LINK_ACCOUNT signature", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "DpopSession": [], "DpopProof": [] } ], "responses": { "200": { "description": "Consent with the original active session and fresh LINK_ACCOUNT signature", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountLinkStatus" } } } }, "400": { "description": "Invalid strict input", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "401": { "description": "Device, passcode, session or DPoP proof rejected; nonce challenge may be included", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "DPoP-Nonce": { "description": "Only returned for an otherwise valid signed request needing a new server nonce; retry with a fresh proof ID.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "404": { "description": "Target or challenge not available to this caller", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "409": { "description": "Idempotency conflict or challenge consumed", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "410": { "description": "Unlock challenge or retained result expired", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "429": { "description": "Persistent rate budget exhausted", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "503": { "description": "Dependency or hash capacity unavailable", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountLinkConsent" } } } }, "description": "Consent with the original active session and fresh LINK_ACCOUNT signature. All public calls require an active device-bound DPoP session and fresh proof. Reads and mutations do not extend idle expiry. Synthetic institutions appear only when issuer public keys are configured; only the explicitly configured synthetic issuer channel is available; live issuers remain disabled." } }, "/v1/payer/account-links/{id}": { "get": { "operationId": "getPayerAccountLink", "tags": [ "PayerAccounts" ], "summary": "Read payer-scoped link status", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "DpopSession": [], "DpopProof": [] } ], "responses": { "200": { "description": "Read payer-scoped link status", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountLinkStatus" } } } }, "400": { "description": "Invalid strict input", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "401": { "description": "Device, passcode, session or DPoP proof rejected; nonce challenge may be included", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "DPoP-Nonce": { "description": "Only returned for an otherwise valid signed request needing a new server nonce; retry with a fresh proof ID.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "404": { "description": "Target or challenge not available to this caller", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "429": { "description": "Persistent rate budget exhausted", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "503": { "description": "Dependency or hash capacity unavailable", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } } }, "description": "Read payer-scoped link status. All public calls require an active device-bound DPoP session and fresh proof. Reads and mutations do not extend idle expiry. Synthetic institutions appear only when issuer public keys are configured; only the explicitly configured synthetic issuer channel is available; live issuers remain disabled. When WAITING, approval_url opens the simulated issuer channel for explicit approval or decline. Reads never approve or extend the request. Opening the URL does not approve. Protected status remains authoritative; a transport failure does not grant a link. New handoff fields are optional on old immutable mutation receipts." } }, "/v1/payer/accounts": { "get": { "operationId": "listPayerAccounts", "tags": [ "PayerAccounts" ], "summary": "List safe linked-account metadata, at most twenty rows by descending UUID", "parameters": [ { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Exclusive opaque UUID cursor from next_cursor." } ], "security": [ { "DpopSession": [], "DpopProof": [] } ], "responses": { "200": { "description": "List safe linked-account metadata, at most twenty rows by descending UUID", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkedAccounts" } } } }, "400": { "description": "Invalid strict input", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "401": { "description": "Device, passcode, session or DPoP proof rejected; nonce challenge may be included", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "DPoP-Nonce": { "description": "Only returned for an otherwise valid signed request needing a new server nonce; retry with a fresh proof ID.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "429": { "description": "Persistent rate budget exhausted", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "503": { "description": "Dependency or hash capacity unavailable", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } } }, "description": "List safe linked-account metadata, at most twenty rows by descending UUID. All public calls require an active device-bound DPoP session and fresh proof. Reads and mutations do not extend idle expiry. Synthetic institutions appear only when issuer public keys are configured; only the explicitly configured synthetic issuer channel is available; live issuers remain disabled." } }, "/v1/payer/transfer-quotes": { "post": { "operationId": "preparePayerTransferQuote", "tags": [ "PayerTransfers" ], "summary": "Prepare or retry an immutable synthetic transfer quote", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "DpopSession": [], "DpopProof": [] } ], "responses": { "200": { "description": "Immutable quote preview with current time status", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayerTransferQuote" } } } }, "400": { "description": "Invalid strict input", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "401": { "description": "Device, passcode, session or DPoP proof rejected; nonce challenge may be included", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "DPoP-Nonce": { "description": "Only returned for an otherwise valid signed request needing a new server nonce; retry with a fresh proof ID.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "404": { "description": "Target or challenge not available to this caller", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "409": { "description": "Idempotency conflict or challenge consumed", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "429": { "description": "Persistent rate budget exhausted", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "503": { "description": "Unknown quote outcome or unavailable dependency; retry original key and body with fresh DPoP", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayerTransferQuoteRequest" } } } }, "description": "Requires fresh DPoP and active original session. Does not extend idle time. Exact original idempotency key/body retries recover unknown results; changed bodies conflict. Original expired previews remain expired. Ten new intents per payer/minute, sixty/hour; ten unresolved dispatch attempts per intent/hour. No issuer approval, debit authority, reservation or transfer execution. HTTP 503 QUOTE_OUTCOME_UNKNOWN requires retrying the original key/body. Unavailable-name acknowledgement is disclosed but no consent is collected in this operation." } }, "/v1/payer/transfer-quotes/{id}": { "get": { "operationId": "getPayerTransferQuote", "tags": [ "PayerTransfers" ], "summary": "Read an original-session quote preview", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "DpopSession": [], "DpopProof": [] } ], "responses": { "200": { "description": "Immutable quote preview with current time status", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayerTransferQuote" } } } }, "400": { "description": "Invalid strict input", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "401": { "description": "Device, passcode, session or DPoP proof rejected; nonce challenge may be included", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "DPoP-Nonce": { "description": "Only returned for an otherwise valid signed request needing a new server nonce; retry with a fresh proof ID.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "404": { "description": "Target or challenge not available to this caller", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "429": { "description": "Persistent rate budget exhausted", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "503": { "description": "Dependency or hash capacity unavailable", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } } }, "description": "Passive read of immutable retained evidence. Requires the same payer, device and active session that prepared the quote and a currently VERIFIED source. Expired previews remain readable as EXPIRED. Never authorizes a debit or extends idle time." } }, "/v1/payer/transfer-consents": { "post": { "operationId": "preparePayerTransferConsent", "tags": [ "PayerTransfers" ], "summary": "Prepare original-quote device consent", "security": [ { "DpopSession": [], "DpopProof": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Prepare original-quote device consent", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferConsentChallenge" } } } }, "400": { "description": "Invalid strict input", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "401": { "description": "Device, passcode, session or DPoP proof rejected; nonce challenge may be included", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "DPoP-Nonce": { "description": "Only returned for an otherwise valid signed request needing a new server nonce; retry with a fresh proof ID.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "404": { "description": "Target or challenge not available to this caller", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "409": { "description": "Idempotency conflict or challenge consumed", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "410": { "description": "Original quote or consent challenge expired; no new consent was accepted", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "429": { "description": "Persistent rate budget exhausted", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "503": { "description": "Unknown quote outcome or unavailable dependency; retry original key and body with fresh DPoP", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferConsentRequest" } } } }, "description": "Original active payer/device/session only; passive idle behavior. One consent challenge per quote. Exact preparation UUID/body retries retain the same challenge and expiry. Unavailable names require true acknowledgement; matched names require false. Completion uses canonical FUTA-DEVICE-PROOF-V1 signing bytes with TRANSFER_CONSENT purpose and base64url DER ES256 signature. Ten preparations per payer/minute, sixty/hour; ten proof attempts per challenge and fifty/device/minute. Retry exact completion UUID/signature with fresh DPoP; accepted historical receipts remain recoverable after quote expiry or source hold, but always require the original active session. A changed signature conflicts and a different completion key cannot create another consent. No issuer credentials, approval, monetary reservation or dispatch." } }, "/v1/payer/transfer-consents/{id}/complete": { "post": { "operationId": "completePayerTransferConsent", "tags": [ "PayerTransfers" ], "summary": "Record device-signed payer intent", "security": [ { "DpopSession": [], "DpopProof": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Record device-signed payer intent", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferConsentReceipt" } } } }, "400": { "description": "Invalid strict input", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "401": { "description": "Device, passcode, session or DPoP proof rejected; nonce challenge may be included", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "DPoP-Nonce": { "description": "Only returned for an otherwise valid signed request needing a new server nonce; retry with a fresh proof ID.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "404": { "description": "Target or challenge not available to this caller", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "409": { "description": "Idempotency conflict or challenge consumed", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "410": { "description": "Original quote or consent challenge expired; no new consent was accepted", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "429": { "description": "Persistent rate budget exhausted", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "503": { "description": "Unknown quote outcome or unavailable dependency; retry original key and body with fresh DPoP", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferConsentProof" } } } }, "description": "Original active payer/device/session only; passive idle behavior. One consent challenge per quote. Exact preparation UUID/body retries retain the same challenge and expiry. Unavailable names require true acknowledgement; matched names require false. Completion uses canonical FUTA-DEVICE-PROOF-V1 signing bytes with TRANSFER_CONSENT purpose and base64url DER ES256 signature. Ten preparations per payer/minute, sixty/hour; ten proof attempts per challenge and fifty/device/minute. Retry exact completion UUID/signature with fresh DPoP; accepted historical receipts remain recoverable after quote expiry or source hold, but always require the original active session. A changed signature conflicts and a different completion key cannot create another consent. No issuer credentials, approval, monetary reservation or dispatch." } }, "/v1/payer/transfer-consents/{id}": { "get": { "operationId": "getPayerTransferConsent", "tags": [ "PayerTransfers" ], "summary": "Read historical consent receipt", "security": [ { "DpopSession": [], "DpopProof": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Read historical consent receipt", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferConsentReceipt" } } } }, "400": { "description": "Invalid strict input", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "401": { "description": "Device, passcode, session or DPoP proof rejected; nonce challenge may be included", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "DPoP-Nonce": { "description": "Only returned for an otherwise valid signed request needing a new server nonce; retry with a fresh proof ID.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "404": { "description": "Target or challenge not available to this caller", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "409": { "description": "Idempotency conflict or challenge consumed", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "410": { "description": "Original quote or consent challenge expired; no new consent was accepted", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "429": { "description": "Persistent rate budget exhausted", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "503": { "description": "Unknown quote outcome or unavailable dependency; retry original key and body with fresh DPoP", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } } }, "description": "Original active payer/device/session only; passive idle behavior. One consent challenge per quote. Exact preparation UUID/body retries retain the same challenge and expiry. Unavailable names require true acknowledgement; matched names require false. Completion uses canonical FUTA-DEVICE-PROOF-V1 signing bytes with TRANSFER_CONSENT purpose and base64url DER ES256 signature. Ten preparations per payer/minute, sixty/hour; ten proof attempts per challenge and fifty/device/minute. Retry exact completion UUID/signature with fresh DPoP; accepted historical receipts remain recoverable after quote expiry or source hold, but always require the original active session. A changed signature conflicts and a different completion key cannot create another consent. No issuer credentials, approval, monetary reservation or dispatch." } }, "/v1/payer/transfer-approval-requests": { "post": { "operationId": "preparePayerTransferApproval", "tags": [ "PayerTransfers" ], "summary": "Retain a consent-bound issuer approval request", "security": [ { "DpopSession": [], "DpopProof": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Historical approval request acknowledgement", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferApprovalReceipt" } } } }, "400": { "description": "Invalid strict input", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "401": { "description": "Device, passcode, session or DPoP proof rejected; nonce challenge may be included", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "DPoP-Nonce": { "description": "Only returned for an otherwise valid signed request needing a new server nonce; retry with a fresh proof ID.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "404": { "description": "Target or challenge not available to this caller", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "409": { "description": "Changed logical body, consent already bound, or switch admission conflict", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "410": { "description": "Original deadline passed before first dispatch, or no prior switch request can be recovered", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "429": { "description": "Persistent rate budget exhausted", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "503": { "description": "Approval request outcome unknown; retry the same UUID and consent with fresh DPoP", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferApprovalRequest" } } } }, "description": "Explicitly enabled synthetic bridge only. Supply an accepted original-session consent ID, stable UUID and fresh DPoP. Identity resolves signed consent and original encrypted quote/destination, durably commits the immutable source witness before dispatch, and reserves attempts before any peer effect. Exact retries recover original request/deadline without renewing authority. Ten admissions per payer/minute, sixty/hour, ten transport attempts per intent. Reads and retries are passive and require the original active session and VERIFIED source. Retry unknown outcomes with the same key/body and fresh DPoP; a new key cannot bind the same consent. PREPARED/REQUEST_ONLY is neither an issuer decision nor money movement." } }, "/v1/payer/transfer-approval-requests/{id}": { "get": { "operationId": "readPayerTransferApproval", "tags": [ "PayerTransfers" ], "summary": "Read a historical prepared approval request", "security": [ { "DpopSession": [], "DpopProof": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Historical prepared request", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferApprovalReceipt" } } } }, "400": { "description": "Invalid strict input", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "401": { "description": "Device, passcode, session or DPoP proof rejected; nonce challenge may be included", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "DPoP-Nonce": { "description": "Only returned for an otherwise valid signed request needing a new server nonce; retry with a fresh proof ID.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "404": { "description": "Target or challenge not available to this caller", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "409": { "description": "Idempotency conflict or challenge consumed", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "410": { "description": "Original quote or consent challenge expired; no new consent was accepted", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "429": { "description": "Persistent rate budget exhausted", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "503": { "description": "Unknown quote outcome or unavailable dependency; retry original key and body with fresh DPoP", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } } }, "description": "Passive original active-session and VERIFIED-source receipt read; status describes the stored time window only. No issuer status query, authority renewal or money movement." } }, "/v1/payer/transfer-approval-requests/{id}/issuer-refresh": { "post": { "operationId": "refreshPayerTransferIssuer", "tags": [ "PayerTransfers" ], "summary": "Explicitly refresh a synthetic issuer observation", "security": [ { "DpopSession": [], "DpopProof": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Safe historical issuer status; transport uncertainty is explicitly last_refresh UNKNOWN", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferIssuerStatus" } } } }, "400": { "description": "Invalid strict input", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "401": { "description": "Device, passcode, session or DPoP proof rejected; nonce challenge may be included", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "DPoP-Nonce": { "description": "Only returned for an otherwise valid signed request needing a new server nonce; retry with a fresh proof ID.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "404": { "description": "Target or challenge not available to this caller", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "409": { "description": "Mutation key belongs to another request, source unavailable, or evidence could not be accepted", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "410": { "description": "Original request not current or expired before any dispatch attempt", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "429": { "description": "Persistent rate budget exhausted", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "503": { "description": "Local dependency unavailable; preserve the original request and mutation key when retrying with fresh DPoP", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } } }, "description": "Disabled by default; requires quotes, approval admission and issuer refresh configuration. Original active DPoP session only; empty request body. No issuer token, compact proof or recipient selector is public. Each successful mutation key is permanently bound to its original request, including cache hits. Up to sixty commands and sixty dispatch attempts per request, and 120 of each per session/minute. Attempts commit before transport; no identity eligibility locks span network I/O. Repeat an uncertain command with the same key and fresh DPoP; a known pending response is passive for that key, so use a new key for a later explicit refresh. Terminal recovery is local and never re-dispatches. Acceptance reloads authoritative identity state in its own local transaction. Source holds, expiry or sign-out during transport cannot publish a pending capability or grant acceptance." } }, "/v1/payer/transfer-approval-requests/{id}/issuer-status": { "get": { "operationId": "readPayerTransferIssuerStatus", "tags": [ "PayerTransfers" ], "summary": "Read passive historical issuer status", "security": [ { "DpopSession": [], "DpopProof": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Safe historical issuer status; transport uncertainty is explicitly last_refresh UNKNOWN", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferIssuerStatus" } } } }, "400": { "description": "Invalid strict input", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "401": { "description": "Device, passcode, session or DPoP proof rejected; nonce challenge may be included", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "DPoP-Nonce": { "description": "Only returned for an otherwise valid signed request needing a new server nonce; retry with a fresh proof ID.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "404": { "description": "Target or challenge not available to this caller", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "409": { "description": "Mutation key belongs to another request, source unavailable, or evidence could not be accepted", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "410": { "description": "Original request not current or expired before any dispatch attempt", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "429": { "description": "Persistent rate budget exhausted", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "503": { "description": "Local dependency unavailable; preserve the original request and mutation key when retrying with fresh DPoP", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } } }, "description": "Disabled by default; requires quotes, approval admission and issuer refresh configuration. Original active DPoP session only; empty request body. No issuer token, compact proof or recipient selector is public. No transport, event acceptance, capability creation or idle-session renewal occurs. Historical accepted decisions may remain visible after later expiry or a source hold; the active original session is still required. AWAITING_ACCEPTANCE is resolved only by explicit refresh. Do not infer monetary execution from issuer approval." } }, "/v1/payer/transfer-approval-requests/{id}/execution": { "post": { "operationId": "deliverPayerTransferExecution", "tags": [ "PayerTransfers" ], "summary": "Admit and deliver one original execution command", "security": [ { "DpopSession": [], "DpopProof": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Safe historical execution delivery status; no monetary effects", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferExecutionStatus" } } } }, "400": { "description": "Invalid strict input", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "401": { "description": "Device, passcode, session or DPoP proof rejected; nonce challenge may be included", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "DPoP-Nonce": { "description": "Only returned for an otherwise valid signed request needing a new server nonce; retry with a fresh proof ID.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "404": { "description": "Target or challenge not available to this caller", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "409": { "description": "Original mandate is not eligible or approved, requires investigation, or mutation key belongs to another request", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "429": { "description": "Session request, execution key alias or durable delivery-attempt budget exhausted", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } } }, "description": "Disabled by default; requires quote, approval, issuer-refresh and execution configuration. Explicit empty-body command under original active-session DPoP. New admission revalidates current source, accepted issuer evidence and original deadlines in an owned identity transaction. Existing commands remain historical; later source holds do not erase the authorization commit. Attempt reservations commit before bounded private transport with no identity eligibility locks over I/O. Retry an unresolved outcome with the same key and a fresh DPoP proof. Known replies are cached per mutation key; another key explicitly redelivers the exact original command. At most sixty execution-key aliases and sixty transport attempts per execution, and 120 attempts per original session/minute. Sign-out prevents public access, including the final response after transport. Remote conflicts and contradictory verified receipts remain visible. No provider operation or posting occurs." } }, "/v1/payer/transfer-approval-requests/{id}/execution-status": { "get": { "operationId": "readPayerTransferExecutionStatus", "tags": [ "PayerTransfers" ], "summary": "Read passive original execution delivery status", "security": [ { "DpopSession": [], "DpopProof": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Safe historical execution delivery status; no monetary effects", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferExecutionStatus" } } } }, "400": { "description": "Invalid strict input", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "401": { "description": "Device, passcode, session or DPoP proof rejected; nonce challenge may be included", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "DPoP-Nonce": { "description": "Only returned for an otherwise valid signed request needing a new server nonce; retry with a fresh proof ID.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "404": { "description": "Target or challenge not available to this caller", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "409": { "description": "Original mandate is not eligible or approved, requires investigation, or mutation key belongs to another request", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "429": { "description": "Session request, execution key alias or durable delivery-attempt budget exhausted", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } } }, "description": "Disabled by default; requires quote, approval, issuer-refresh and execution configuration. Passive original active-session DPoP read. Never admits, dispatches, creates an attempt or renews a session. Reports local authorization and retained receiving evidence, with original expiry and permanent local/observed remote investigation. STORED is last observed receiving storage and never means funds moved. No issuer evidence, token, recipient or provider instruction is returned." } }, "/v1/payer/transfer-approval-requests/{id}/monetary-refresh": { "post": { "operationId": "refreshPayerTransferMonetaryStatus", "tags": [ "PayerTransfers" ], "summary": "Refresh original monetary observation", "security": [ { "DpopSession": [], "DpopProof": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Dated historical monetary observation with explicit availability and investigation", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferMonetaryStatus" } } } }, "400": { "description": "Invalid strict input", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "401": { "description": "Device, passcode, session or DPoP proof rejected; nonce challenge may be included", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "DPoP-Nonce": { "description": "Only returned for an otherwise valid signed request needing a new server nonce; retry with a fresh proof ID.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "404": { "description": "Target or challenge not available to this caller", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "409": { "description": "Mutation key belongs to another original request or protected local authority conflicts", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "429": { "description": "Session request or durable refresh budget exhausted", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "503": { "description": "Protected storage, clock or dependencies unavailable; no private diagnostic details", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } } }, "description": "Disabled by default; requires the explicit monetary flag plus quote, approval, issuer-refresh and execution prerequisites. Exact original active-session DPoP. Empty body, no query parameters or content encoding. Responses are no-store. Missing or foreign original scope is indistinguishable. No monetary instruction, provider POST, posting or session renewal occurs. Reserves at most sixty immutable attempts per original execution and 120 per session/minute before bounded private GET, with no database transaction or identity lock held during HTTP. Same-key retries are always passive, including pending or unavailable results; use a new mutation key for an explicit new bounded fetch. An interrupted attempt remains pending until another key obtains newer evidence. Persist authenticated encrypted results and permanent contradictions; recheck session authority before the final response. Local source/issuer/intake investigation overrides usability. Historical original admission remains readable after issuer-pin rotation and expiry." } }, "/v1/payer/transfer-approval-requests/{id}/monetary-status": { "get": { "operationId": "readPayerTransferMonetaryStatus", "tags": [ "PayerTransfers" ], "summary": "Read passive original monetary status", "security": [ { "DpopSession": [], "DpopProof": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Dated historical monetary observation with explicit availability and investigation", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferMonetaryStatus" } } } }, "400": { "description": "Invalid strict input", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "401": { "description": "Device, passcode, session or DPoP proof rejected; nonce challenge may be included", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "DPoP-Nonce": { "description": "Only returned for an otherwise valid signed request needing a new server nonce; retry with a fresh proof ID.", "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "404": { "description": "Target or challenge not available to this caller", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "409": { "description": "Mutation key belongs to another original request or protected local authority conflicts", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "429": { "description": "Session request or durable refresh budget exhausted", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } }, "503": { "description": "Protected storage, clock or dependencies unavailable; no private diagnostic details", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityError" } } } } }, "description": "Disabled by default; requires the explicit monetary flag plus quote, approval, issuer-refresh and execution prerequisites. Exact original active-session DPoP. Empty body, no query parameters or content encoding. Responses are no-store. Missing or foreign original scope is indistinguishable. No monetary instruction, provider POST, posting or session renewal occurs. Reads retained protected history only. Never creates a refresh attempt, calls the switch/provider, backfills accounting or refreshes confirmation dates. A latest unavailable or pending refresh remains visible beside any older observation. Investigation overrides completion; valid historical posting legs are preserved." } }, "/v1/payer/transfer-history": { "get": { "operationId": "listPayerTransferHistory", "tags": [ "PayerHistory" ], "summary": "List bounded payer-owned historical transfers", "description": "Default-off sandbox boundary requires history-enabled, quotes-enabled and approvals-enabled. Current-session DPoP, zero body/content encoding, no duplicate/unknown query keys. Reads change only proof replay/nonce and per-payer quota bookkeeping, never money, provider evidence or session activity. Limit is 60 authenticated reads per fixed 60-second window. Invalid input before authentication and rolled-back storage failures expose no invented quota values.", "security": [ { "DpopSession": [], "DpopProof": [] } ], "responses": { "200": { "description": "Authenticated historical projection", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "RateLimit-Limit": { "description": "Present only after an authenticated committed history quota measurement; shared by payer across devices and list/detail.", "schema": { "type": "integer", "enum": [ 60 ] } }, "RateLimit-Remaining": { "description": "Remaining allowed reads in this fixed window.", "schema": { "type": "integer", "minimum": 0, "maximum": 59 } }, "RateLimit-Reset": { "description": "Seconds until the current window ends; clock rollback cannot reset the allowance.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Policy": { "schema": { "type": "string", "enum": [ "60;w=60" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferHistoryPage" } } } }, "400": { "description": "Invalid strict request or cursor", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "RateLimit-Limit": { "description": "Present only after an authenticated committed history quota measurement; shared by payer across devices and list/detail.", "schema": { "type": "integer", "enum": [ 60 ] } }, "RateLimit-Remaining": { "description": "Remaining allowed reads in this fixed window.", "schema": { "type": "integer", "minimum": 0, "maximum": 59 } }, "RateLimit-Reset": { "description": "Seconds until the current window ends; clock rollback cannot reset the allowance.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Policy": { "schema": { "type": "string", "enum": [ "60;w=60" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoryError" } } } }, "401": { "description": "Current session or device proof invalid; nonce challenge may be included", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "RateLimit-Limit": { "description": "Present only after an authenticated committed history quota measurement; shared by payer across devices and list/detail.", "schema": { "type": "integer", "enum": [ 60 ] } }, "RateLimit-Remaining": { "description": "Remaining allowed reads in this fixed window.", "schema": { "type": "integer", "minimum": 0, "maximum": 59 } }, "RateLimit-Reset": { "description": "Seconds until the current window ends; clock rollback cannot reset the allowance.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Policy": { "schema": { "type": "string", "enum": [ "60;w=60" ] } }, "DPoP-Nonce": { "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoryError" } } } }, "404": { "description": "Foreign and unknown reference indistinguishable", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "RateLimit-Limit": { "description": "Present only after an authenticated committed history quota measurement; shared by payer across devices and list/detail.", "schema": { "type": "integer", "enum": [ 60 ] } }, "RateLimit-Remaining": { "description": "Remaining allowed reads in this fixed window.", "schema": { "type": "integer", "minimum": 0, "maximum": 59 } }, "RateLimit-Reset": { "description": "Seconds until the current window ends; clock rollback cannot reset the allowance.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Policy": { "schema": { "type": "string", "enum": [ "60;w=60" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoryError" } } } }, "429": { "description": "History allowance or DPoP nonce issuance limited", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "RateLimit-Limit": { "description": "Present only after an authenticated committed history quota measurement; shared by payer across devices and list/detail.", "schema": { "type": "integer", "enum": [ 60 ] } }, "RateLimit-Remaining": { "description": "Remaining allowed reads in this fixed window.", "schema": { "type": "integer", "minimum": 0, "maximum": 59 } }, "RateLimit-Reset": { "description": "Seconds until the current window ends; clock rollback cannot reset the allowance.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Policy": { "schema": { "type": "string", "enum": [ "60;w=60" ] } }, "Retry-After": { "description": "Seconds to wait when HISTORY_RATE_LIMITED; omitted for the independent nonce issuance budget.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoryError" } } } }, "503": { "description": "History unavailable or maintenance incomplete", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "RateLimit-Limit": { "description": "Present only after an authenticated committed history quota measurement; shared by payer across devices and list/detail.", "schema": { "type": "integer", "enum": [ 60 ] } }, "RateLimit-Remaining": { "description": "Remaining allowed reads in this fixed window.", "schema": { "type": "integer", "minimum": 0, "maximum": 59 } }, "RateLimit-Reset": { "description": "Seconds until the current window ends; clock rollback cannot reset the allowance.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Policy": { "schema": { "type": "string", "enum": [ "60;w=60" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoryError" } } } } }, "parameters": [ { "name": "source_account_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "CDF", "USD" ] } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$" }, "description": "Inclusive original creation time in canonical whole-second UTC." }, { "name": "until", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$" }, "description": "Exclusive original creation time in canonical whole-second UTC." }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "NOT_ADMITTED", "NOT_OBSERVED", "REFRESH_PENDING", "UNAVAILABLE", "INVESTIGATION_REQUIRED", "EXPIRED_BEFORE_START", "ACCOUNTING_INCOMPLETE", "COMPLETED_UNCONFIRMED", "REVERSED_UNCONFIRMED", "READY", "DEBIT_PENDING", "DEBIT_FAILED", "CREDIT_PENDING", "COMPLETED", "REVERSAL_PENDING", "REVERSAL_FAILED", "REVERSED" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{40,2048}$", "minLength": 40, "maxLength": 2048 } } ] } }, "/v1/payer/transfer-history/{id}": { "get": { "operationId": "readPayerTransferHistory", "tags": [ "PayerHistory" ], "summary": "Read a payer-owned historical transfer", "description": "Default-off sandbox boundary requires history-enabled, quotes-enabled and approvals-enabled. Current-session DPoP, zero body/content encoding, no duplicate/unknown query keys. Reads change only proof replay/nonce and per-payer quota bookkeeping, never money, provider evidence or session activity. Limit is 60 authenticated reads per fixed 60-second window. Invalid input before authentication and rolled-back storage failures expose no invented quota values.", "security": [ { "DpopSession": [], "DpopProof": [] } ], "responses": { "200": { "description": "Authenticated historical projection", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "RateLimit-Limit": { "description": "Present only after an authenticated committed history quota measurement; shared by payer across devices and list/detail.", "schema": { "type": "integer", "enum": [ 60 ] } }, "RateLimit-Remaining": { "description": "Remaining allowed reads in this fixed window.", "schema": { "type": "integer", "minimum": 0, "maximum": 59 } }, "RateLimit-Reset": { "description": "Seconds until the current window ends; clock rollback cannot reset the allowance.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Policy": { "schema": { "type": "string", "enum": [ "60;w=60" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferHistoryDetail" } } } }, "400": { "description": "Invalid strict request or cursor", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "RateLimit-Limit": { "description": "Present only after an authenticated committed history quota measurement; shared by payer across devices and list/detail.", "schema": { "type": "integer", "enum": [ 60 ] } }, "RateLimit-Remaining": { "description": "Remaining allowed reads in this fixed window.", "schema": { "type": "integer", "minimum": 0, "maximum": 59 } }, "RateLimit-Reset": { "description": "Seconds until the current window ends; clock rollback cannot reset the allowance.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Policy": { "schema": { "type": "string", "enum": [ "60;w=60" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoryError" } } } }, "401": { "description": "Current session or device proof invalid; nonce challenge may be included", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "RateLimit-Limit": { "description": "Present only after an authenticated committed history quota measurement; shared by payer across devices and list/detail.", "schema": { "type": "integer", "enum": [ 60 ] } }, "RateLimit-Remaining": { "description": "Remaining allowed reads in this fixed window.", "schema": { "type": "integer", "minimum": 0, "maximum": 59 } }, "RateLimit-Reset": { "description": "Seconds until the current window ends; clock rollback cannot reset the allowance.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Policy": { "schema": { "type": "string", "enum": [ "60;w=60" ] } }, "DPoP-Nonce": { "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoryError" } } } }, "404": { "description": "Foreign and unknown reference indistinguishable", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "RateLimit-Limit": { "description": "Present only after an authenticated committed history quota measurement; shared by payer across devices and list/detail.", "schema": { "type": "integer", "enum": [ 60 ] } }, "RateLimit-Remaining": { "description": "Remaining allowed reads in this fixed window.", "schema": { "type": "integer", "minimum": 0, "maximum": 59 } }, "RateLimit-Reset": { "description": "Seconds until the current window ends; clock rollback cannot reset the allowance.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Policy": { "schema": { "type": "string", "enum": [ "60;w=60" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoryError" } } } }, "429": { "description": "History allowance or DPoP nonce issuance limited", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "RateLimit-Limit": { "description": "Present only after an authenticated committed history quota measurement; shared by payer across devices and list/detail.", "schema": { "type": "integer", "enum": [ 60 ] } }, "RateLimit-Remaining": { "description": "Remaining allowed reads in this fixed window.", "schema": { "type": "integer", "minimum": 0, "maximum": 59 } }, "RateLimit-Reset": { "description": "Seconds until the current window ends; clock rollback cannot reset the allowance.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Policy": { "schema": { "type": "string", "enum": [ "60;w=60" ] } }, "Retry-After": { "description": "Seconds to wait when HISTORY_RATE_LIMITED; omitted for the independent nonce issuance budget.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoryError" } } } }, "503": { "description": "History unavailable or maintenance incomplete", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "RateLimit-Limit": { "description": "Present only after an authenticated committed history quota measurement; shared by payer across devices and list/detail.", "schema": { "type": "integer", "enum": [ 60 ] } }, "RateLimit-Remaining": { "description": "Remaining allowed reads in this fixed window.", "schema": { "type": "integer", "minimum": 0, "maximum": 59 } }, "RateLimit-Reset": { "description": "Seconds until the current window ends; clock rollback cannot reset the allowance.", "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Policy": { "schema": { "type": "string", "enum": [ "60;w=60" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoryError" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } } ] } }, "/v1/payer/transfer-history/{id}/problems": { "post": { "tags": [ "PayerProblems" ], "operationId": "submitPayerTransferProblem", "security": [ { "DpopSession": [], "DpopProof": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } } ], "responses": { "201": { "description": "Report created or identical committed retry recovered", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "RateLimit-Limit": { "description": "Present only after committed authenticated quota measurement, which survives report rollback. Reports use 60 requests/minute and 10 new-key admission attempts/hour; committed-key retries skip the latter. Denied bucket is reported on 429, otherwise the request bucket.", "schema": { "type": "integer", "enum": [ 60, 10 ] } }, "RateLimit-Remaining": { "schema": { "type": "integer", "minimum": 0, "maximum": 59 } }, "RateLimit-Reset": { "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Policy": { "schema": { "type": "string", "enum": [ "60;w=60", "10;w=3600" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayerTransferProblem" } } } }, "400": { "description": "Invalid strict request", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "RateLimit-Limit": { "description": "Present only after committed authenticated quota measurement, which survives report rollback. Reports use 60 requests/minute and 10 new-key admission attempts/hour; committed-key retries skip the latter. Denied bucket is reported on 429, otherwise the request bucket.", "schema": { "type": "integer", "enum": [ 60, 10 ] } }, "RateLimit-Remaining": { "schema": { "type": "integer", "minimum": 0, "maximum": 59 } }, "RateLimit-Reset": { "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Policy": { "schema": { "type": "string", "enum": [ "60;w=60", "10;w=3600" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemReportError" } } } }, "401": { "description": "Current session or device proof required", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "RateLimit-Limit": { "description": "Present only after committed authenticated quota measurement, which survives report rollback. Reports use 60 requests/minute and 10 new-key admission attempts/hour; committed-key retries skip the latter. Denied bucket is reported on 429, otherwise the request bucket.", "schema": { "type": "integer", "enum": [ 60, 10 ] } }, "RateLimit-Remaining": { "schema": { "type": "integer", "minimum": 0, "maximum": 59 } }, "RateLimit-Reset": { "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Policy": { "schema": { "type": "string", "enum": [ "60;w=60", "10;w=3600" ] } }, "DPoP-Nonce": { "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemReportError" } } } }, "404": { "description": "Unknown and foreign references indistinguishable", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "RateLimit-Limit": { "description": "Present only after committed authenticated quota measurement, which survives report rollback. Reports use 60 requests/minute and 10 new-key admission attempts/hour; committed-key retries skip the latter. Denied bucket is reported on 429, otherwise the request bucket.", "schema": { "type": "integer", "enum": [ 60, 10 ] } }, "RateLimit-Remaining": { "schema": { "type": "integer", "minimum": 0, "maximum": 59 } }, "RateLimit-Reset": { "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Policy": { "schema": { "type": "string", "enum": [ "60;w=60", "10;w=3600" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemReportError" } } } }, "409": { "description": "Key already bound to different report content", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "RateLimit-Limit": { "description": "Present only after committed authenticated quota measurement, which survives report rollback. Reports use 60 requests/minute and 10 new-key admission attempts/hour; committed-key retries skip the latter. Denied bucket is reported on 429, otherwise the request bucket.", "schema": { "type": "integer", "enum": [ 60, 10 ] } }, "RateLimit-Remaining": { "schema": { "type": "integer", "minimum": 0, "maximum": 59 } }, "RateLimit-Reset": { "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Policy": { "schema": { "type": "string", "enum": [ "60;w=60", "10;w=3600" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemReportError" } } } }, "413": { "description": "Body exceeds 32768 bytes", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "RateLimit-Limit": { "description": "Present only after committed authenticated quota measurement, which survives report rollback. Reports use 60 requests/minute and 10 new-key admission attempts/hour; committed-key retries skip the latter. Denied bucket is reported on 429, otherwise the request bucket.", "schema": { "type": "integer", "enum": [ 60, 10 ] } }, "RateLimit-Remaining": { "schema": { "type": "integer", "minimum": 0, "maximum": 59 } }, "RateLimit-Reset": { "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Policy": { "schema": { "type": "string", "enum": [ "60;w=60", "10;w=3600" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemReportError" } } } }, "415": { "description": "Expected UTF-8 application/json", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "RateLimit-Limit": { "description": "Present only after committed authenticated quota measurement, which survives report rollback. Reports use 60 requests/minute and 10 new-key admission attempts/hour; committed-key retries skip the latter. Denied bucket is reported on 429, otherwise the request bucket.", "schema": { "type": "integer", "enum": [ 60, 10 ] } }, "RateLimit-Remaining": { "schema": { "type": "integer", "minimum": 0, "maximum": 59 } }, "RateLimit-Reset": { "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Policy": { "schema": { "type": "string", "enum": [ "60;w=60", "10;w=3600" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemReportError" } } } }, "429": { "description": "Durable request or admission attempt budget denied", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "RateLimit-Limit": { "description": "Present only after committed authenticated quota measurement, which survives report rollback. Reports use 60 requests/minute and 10 new-key admission attempts/hour; committed-key retries skip the latter. Denied bucket is reported on 429, otherwise the request bucket.", "schema": { "type": "integer", "enum": [ 60, 10 ] } }, "RateLimit-Remaining": { "schema": { "type": "integer", "minimum": 0, "maximum": 59 } }, "RateLimit-Reset": { "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Policy": { "schema": { "type": "string", "enum": [ "60;w=60", "10;w=3600" ] } }, "Retry-After": { "description": "Seconds until the denied report bucket can admit work; absent for independent nonce issuance limits.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemReportError" } } } }, "503": { "description": "Protected report or original history unavailable", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "RateLimit-Limit": { "description": "Present only after committed authenticated quota measurement, which survives report rollback. Reports use 60 requests/minute and 10 new-key admission attempts/hour; committed-key retries skip the latter. Denied bucket is reported on 429, otherwise the request bucket.", "schema": { "type": "integer", "enum": [ 60, 10 ] } }, "RateLimit-Remaining": { "schema": { "type": "integer", "minimum": 0, "maximum": 59 } }, "RateLimit-Reset": { "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Policy": { "schema": { "type": "string", "enum": [ "60;w=60", "10;w=3600" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemReportError" } } } } }, "requestBody": { "required": true, "description": "Strict single UTF-8 JSON object, no duplicate or unknown fields; maximum encoded body 32768 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemReportInput" } } } }, "description": "Explicit current-payer report for an owned historical transfer. Server derives all original facts. Exact committed retry returns the same report; conflicting content returns 409. No monetary action, notification or automatic retry. Up to 10 new-key admission attempts/hour; invalid or unavailable originals also consume an attempt. Existing keys and passive recovery use only the 60/minute request budget." } }, "/v1/payer/transfer-problems/{id}": { "get": { "tags": [ "PayerProblems" ], "operationId": "readPayerTransferProblem", "security": [ { "DpopSession": [], "DpopProof": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } } ], "responses": { "200": { "description": "Owned immutable report", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "RateLimit-Limit": { "description": "Present only after committed authenticated quota measurement, which survives report rollback. Reports use 60 requests/minute and 10 new-key admission attempts/hour; committed-key retries skip the latter. Denied bucket is reported on 429, otherwise the request bucket.", "schema": { "type": "integer", "enum": [ 60, 10 ] } }, "RateLimit-Remaining": { "schema": { "type": "integer", "minimum": 0, "maximum": 59 } }, "RateLimit-Reset": { "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Policy": { "schema": { "type": "string", "enum": [ "60;w=60", "10;w=3600" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayerTransferProblem" } } } }, "400": { "description": "Invalid strict request", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "RateLimit-Limit": { "description": "Present only after committed authenticated quota measurement, which survives report rollback. Reports use 60 requests/minute and 10 new-key admission attempts/hour; committed-key retries skip the latter. Denied bucket is reported on 429, otherwise the request bucket.", "schema": { "type": "integer", "enum": [ 60, 10 ] } }, "RateLimit-Remaining": { "schema": { "type": "integer", "minimum": 0, "maximum": 59 } }, "RateLimit-Reset": { "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Policy": { "schema": { "type": "string", "enum": [ "60;w=60", "10;w=3600" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemReportError" } } } }, "401": { "description": "Current session or device proof required", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "RateLimit-Limit": { "description": "Present only after committed authenticated quota measurement, which survives report rollback. Reports use 60 requests/minute and 10 new-key admission attempts/hour; committed-key retries skip the latter. Denied bucket is reported on 429, otherwise the request bucket.", "schema": { "type": "integer", "enum": [ 60, 10 ] } }, "RateLimit-Remaining": { "schema": { "type": "integer", "minimum": 0, "maximum": 59 } }, "RateLimit-Reset": { "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Policy": { "schema": { "type": "string", "enum": [ "60;w=60", "10;w=3600" ] } }, "DPoP-Nonce": { "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemReportError" } } } }, "404": { "description": "Unknown and foreign references indistinguishable", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "RateLimit-Limit": { "description": "Present only after committed authenticated quota measurement, which survives report rollback. Reports use 60 requests/minute and 10 new-key admission attempts/hour; committed-key retries skip the latter. Denied bucket is reported on 429, otherwise the request bucket.", "schema": { "type": "integer", "enum": [ 60, 10 ] } }, "RateLimit-Remaining": { "schema": { "type": "integer", "minimum": 0, "maximum": 59 } }, "RateLimit-Reset": { "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Policy": { "schema": { "type": "string", "enum": [ "60;w=60", "10;w=3600" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemReportError" } } } }, "429": { "description": "Durable request or admission attempt budget denied", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "RateLimit-Limit": { "description": "Present only after committed authenticated quota measurement, which survives report rollback. Reports use 60 requests/minute and 10 new-key admission attempts/hour; committed-key retries skip the latter. Denied bucket is reported on 429, otherwise the request bucket.", "schema": { "type": "integer", "enum": [ 60, 10 ] } }, "RateLimit-Remaining": { "schema": { "type": "integer", "minimum": 0, "maximum": 59 } }, "RateLimit-Reset": { "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Policy": { "schema": { "type": "string", "enum": [ "60;w=60", "10;w=3600" ] } }, "Retry-After": { "description": "Seconds until the denied report bucket can admit work; absent for independent nonce issuance limits.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemReportError" } } } }, "503": { "description": "Protected report or original history unavailable", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "RateLimit-Limit": { "description": "Present only after committed authenticated quota measurement, which survives report rollback. Reports use 60 requests/minute and 10 new-key admission attempts/hour; committed-key retries skip the latter. Denied bucket is reported on 429, otherwise the request bucket.", "schema": { "type": "integer", "enum": [ 60, 10 ] } }, "RateLimit-Remaining": { "schema": { "type": "integer", "minimum": 0, "maximum": 59 } }, "RateLimit-Reset": { "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Policy": { "schema": { "type": "string", "enum": [ "60;w=60", "10;w=3600" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemReportError" } } } } }, "description": "Passive current-payer read with fresh DPoP. Reject query parameters, bodies and Idempotency-Key headers. Does not renew session activity or inspect providers. Retained evidence remains at-submission evidence." } }, "/v1/payer/transfer-problems/by-idempotency-key/{key}": { "get": { "tags": [ "PayerProblems" ], "operationId": "recoverPayerTransferProblem", "security": [ { "DpopSession": [], "DpopProof": [] } ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } } ], "responses": { "200": { "description": "Owned immutable report", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "RateLimit-Limit": { "description": "Present only after committed authenticated quota measurement, which survives report rollback. Reports use 60 requests/minute and 10 new-key admission attempts/hour; committed-key retries skip the latter. Denied bucket is reported on 429, otherwise the request bucket.", "schema": { "type": "integer", "enum": [ 60, 10 ] } }, "RateLimit-Remaining": { "schema": { "type": "integer", "minimum": 0, "maximum": 59 } }, "RateLimit-Reset": { "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Policy": { "schema": { "type": "string", "enum": [ "60;w=60", "10;w=3600" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayerTransferProblem" } } } }, "400": { "description": "Invalid strict request", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "RateLimit-Limit": { "description": "Present only after committed authenticated quota measurement, which survives report rollback. Reports use 60 requests/minute and 10 new-key admission attempts/hour; committed-key retries skip the latter. Denied bucket is reported on 429, otherwise the request bucket.", "schema": { "type": "integer", "enum": [ 60, 10 ] } }, "RateLimit-Remaining": { "schema": { "type": "integer", "minimum": 0, "maximum": 59 } }, "RateLimit-Reset": { "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Policy": { "schema": { "type": "string", "enum": [ "60;w=60", "10;w=3600" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemReportError" } } } }, "401": { "description": "Current session or device proof required", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "RateLimit-Limit": { "description": "Present only after committed authenticated quota measurement, which survives report rollback. Reports use 60 requests/minute and 10 new-key admission attempts/hour; committed-key retries skip the latter. Denied bucket is reported on 429, otherwise the request bucket.", "schema": { "type": "integer", "enum": [ 60, 10 ] } }, "RateLimit-Remaining": { "schema": { "type": "integer", "minimum": 0, "maximum": 59 } }, "RateLimit-Reset": { "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Policy": { "schema": { "type": "string", "enum": [ "60;w=60", "10;w=3600" ] } }, "DPoP-Nonce": { "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemReportError" } } } }, "404": { "description": "Unknown and foreign references indistinguishable", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "RateLimit-Limit": { "description": "Present only after committed authenticated quota measurement, which survives report rollback. Reports use 60 requests/minute and 10 new-key admission attempts/hour; committed-key retries skip the latter. Denied bucket is reported on 429, otherwise the request bucket.", "schema": { "type": "integer", "enum": [ 60, 10 ] } }, "RateLimit-Remaining": { "schema": { "type": "integer", "minimum": 0, "maximum": 59 } }, "RateLimit-Reset": { "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Policy": { "schema": { "type": "string", "enum": [ "60;w=60", "10;w=3600" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemReportError" } } } }, "429": { "description": "Durable request or admission attempt budget denied", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "RateLimit-Limit": { "description": "Present only after committed authenticated quota measurement, which survives report rollback. Reports use 60 requests/minute and 10 new-key admission attempts/hour; committed-key retries skip the latter. Denied bucket is reported on 429, otherwise the request bucket.", "schema": { "type": "integer", "enum": [ 60, 10 ] } }, "RateLimit-Remaining": { "schema": { "type": "integer", "minimum": 0, "maximum": 59 } }, "RateLimit-Reset": { "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Policy": { "schema": { "type": "string", "enum": [ "60;w=60", "10;w=3600" ] } }, "Retry-After": { "description": "Seconds until the denied report bucket can admit work; absent for independent nonce issuance limits.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemReportError" } } } }, "503": { "description": "Protected report or original history unavailable", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "no-store" ] } }, "RateLimit-Limit": { "description": "Present only after committed authenticated quota measurement, which survives report rollback. Reports use 60 requests/minute and 10 new-key admission attempts/hour; committed-key retries skip the latter. Denied bucket is reported on 429, otherwise the request bucket.", "schema": { "type": "integer", "enum": [ 60, 10 ] } }, "RateLimit-Remaining": { "schema": { "type": "integer", "minimum": 0, "maximum": 59 } }, "RateLimit-Reset": { "schema": { "type": "integer", "minimum": 1 } }, "RateLimit-Policy": { "schema": { "type": "string", "enum": [ "60;w=60", "10;w=3600" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemReportError" } } } } }, "description": "Passive current-payer read with fresh DPoP. Reject query parameters, bodies and Idempotency-Key headers. Does not renew session activity or inspect providers. Retained evidence remains at-submission evidence." } } }, "components": { "schemas": { "PhoneChallengeRequest": { "type": "object", "additionalProperties": false, "required": [ "phone", "public_key", "locale" ], "properties": { "phone": { "type": "string", "pattern": "^\\+243[0-9]{9}$", "description": "Only configured synthetic fixtures accepted." }, "public_key": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Named P-256 DER SPKI in canonical unpadded base64url." }, "locale": { "type": "string", "enum": [ "fr", "ln", "sw", "en" ] } } }, "PhoneVerificationRequest": { "type": "object", "additionalProperties": false, "required": [ "code", "signature" ], "properties": { "code": { "type": "string", "pattern": "^[0-9]{6}$", "writeOnly": true }, "signature": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Unpadded base64url DER SHA256withECDSA signature over returned signing_bytes." } } }, "DeviceChallengeBinding": { "type": "object", "additionalProperties": false, "required": [ "purpose", "subject", "key_fingerprint", "request_digest" ], "properties": { "purpose": { "type": "string", "enum": [ "ENROLL", "UNLOCK", "REVOKE_DEVICE", "LINK_ACCOUNT", "TRANSFER_CONSENT", "RESUME_SESSION" ] }, "subject": { "type": "string", "pattern": "^(-|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$" }, "key_fingerprint": { "type": "string", "pattern": "^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$" }, "request_digest": { "type": "string", "pattern": "^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$" } } }, "DeviceChallengeTiming": { "type": "object", "additionalProperties": false, "required": [ "issued_at", "expires_at" ], "properties": { "issued_at": { "type": "integer", "format": "int64", "minimum": 0 }, "expires_at": { "type": "integer", "format": "int64", "minimum": 1 } } }, "DeviceChallenge": { "type": "object", "additionalProperties": false, "required": [ "id", "nonce", "binding", "timing" ], "properties": { "id": { "type": "string", "format": "uuid" }, "nonce": { "type": "string", "pattern": "^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$" }, "binding": { "$ref": "#/components/schemas/DeviceChallengeBinding" }, "timing": { "$ref": "#/components/schemas/DeviceChallengeTiming" } } }, "PhoneChallenge": { "type": "object", "additionalProperties": false, "required": [ "id", "masked_phone", "state", "expires_at", "locale", "retry_after", "device_challenge", "signing_bytes", "sandbox" ], "properties": { "id": { "type": "string", "format": "uuid" }, "masked_phone": { "type": "string" }, "state": { "type": "string", "enum": [ "PENDING" ] }, "expires_at": { "type": "string", "format": "date-time" }, "locale": { "type": "string", "enum": [ "fr", "ln", "sw", "en" ] }, "retry_after": { "type": "string", "format": "date-time" }, "device_challenge": { "$ref": "#/components/schemas/DeviceChallenge" }, "signing_bytes": { "type": "string", "description": "Canonical unpadded base64url of the exact bytes to sign. No final newline." }, "sandbox": { "type": "boolean", "enum": [ true ] } } }, "EnrollmentGrant": { "type": "object", "additionalProperties": false, "required": [ "id", "token", "expires_at", "device_fingerprint" ], "properties": { "id": { "type": "string", "format": "uuid" }, "token": { "type": "string", "pattern": "^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$" }, "expires_at": { "type": "string", "format": "date-time" }, "device_fingerprint": { "type": "string", "pattern": "^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$" } } }, "PhoneVerified": { "type": "object", "additionalProperties": false, "required": [ "challenge_id", "state", "enrollment_grant", "sandbox" ], "properties": { "challenge_id": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "VERIFIED" ] }, "enrollment_grant": { "$ref": "#/components/schemas/EnrollmentGrant" }, "sandbox": { "type": "boolean", "enum": [ true ] } } }, "IdentityError": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "object", "additionalProperties": false, "required": [ "code" ], "properties": { "code": { "type": "string", "enum": [ "INVALID_REQUEST", "SYNTHETIC_PHONE_REQUIRED", "RATE_LIMITED", "IDEMPOTENCY_CONFLICT", "NOT_FOUND", "REPLAY_EXPIRED", "CHALLENGE_UNAVAILABLE", "CHALLENGE_EXPIRED", "INVALID_DEVICE_PROOF", "INVALID_CODE", "DEPENDENCY_UNAVAILABLE", "INVALID_GRANT", "GRANT_EXPIRED", "ENROLLMENT_UNAVAILABLE", "INVALID_DEVICE", "INVALID_PASSCODE", "UNLOCK_LOCKED", "INVALID_SESSION", "PROOF_REPLAYED", "DPOP_NONCE_REQUIRED", "LINK_EXPIRED", "LINK_UNAVAILABLE", "LINK_CONFLICT", "INVALID_ISSUER_EVIDENCE", "UNAUTHORIZED", "SOURCE_ACCOUNT_NOT_FOUND", "INSTITUTION_UNAVAILABLE", "QUOTE_NOT_FOUND", "QUOTE_OUTCOME_UNKNOWN", "QUOTE_NOT_AVAILABLE", "QUOTE_EXPIRED", "NAME_ACKNOWLEDGEMENT_REQUIRED", "CONSENT_NOT_FOUND", "CONSENT_NOT_CURRENT", "CONSENT_ALREADY_BOUND", "APPROVAL_REQUEST_NOT_FOUND", "APPROVAL_NOT_AVAILABLE", "APPROVAL_OUTCOME_UNKNOWN", "APPROVAL_EXPIRED", "APPROVAL_NOT_CURRENT", "SOURCE_UNAVAILABLE", "REFRESH_RATE_LIMITED", "ELIGIBILITY_CHANGED", "APPROVAL_NOT_ACCEPTED", "APPROVAL_NOT_APPROVED", "APPROVAL_REQUIRES_INVESTIGATION", "EXECUTION_DELIVERY_RATE_LIMITED", "EXECUTION_KEY_LIMIT", "EXECUTION_NOT_ELIGIBLE" ] } } } } }, "EnrollmentRequest": { "type": "object", "additionalProperties": false, "required": [ "grant_token", "passcode" ], "properties": { "grant_token": { "type": "string", "pattern": "^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$", "writeOnly": true }, "passcode": { "type": "string", "pattern": "^[0-9]{6}$", "writeOnly": true } } }, "EnrollmentCompletionRequest": { "type": "object", "additionalProperties": false, "required": [ "grant_token", "passcode", "signature" ], "properties": { "grant_token": { "type": "string", "pattern": "^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$", "writeOnly": true }, "passcode": { "type": "string", "pattern": "^[0-9]{6}$", "writeOnly": true }, "signature": { "type": "string", "minLength": 1, "maxLength": 100 } } }, "EnrollmentChallenge": { "type": "object", "additionalProperties": false, "required": [ "id", "grant_id", "device_challenge", "signing_bytes", "expires_at", "sandbox" ], "properties": { "id": { "type": "string", "format": "uuid" }, "grant_id": { "type": "string", "format": "uuid" }, "device_challenge": { "$ref": "#/components/schemas/DeviceChallenge" }, "signing_bytes": { "type": "string", "maxLength": 2048 }, "expires_at": { "type": "string", "format": "date-time" }, "sandbox": { "type": "boolean", "enum": [ true ] } } }, "PayerEnrolled": { "type": "object", "additionalProperties": false, "required": [ "payer_id", "device_id", "locale", "state", "session_issued", "sandbox" ], "properties": { "payer_id": { "type": "string", "format": "uuid" }, "device_id": { "type": "string", "format": "uuid" }, "locale": { "type": "string", "enum": [ "fr", "ln", "sw", "en" ] }, "state": { "type": "string", "enum": [ "ENROLLED" ] }, "session_issued": { "type": "boolean", "enum": [ false ] }, "sandbox": { "type": "boolean", "enum": [ true ] } } }, "UnlockRequest": { "type": "object", "additionalProperties": false, "required": [ "device_id", "passcode" ], "properties": { "device_id": { "type": "string", "format": "uuid" }, "passcode": { "type": "string", "pattern": "^[0-9]{6}$", "writeOnly": true }, "resume_session_id": { "type": [ "string", "null" ], "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Optional original session to resume after local credential loss. Defaults off. Requires a separate RESUME_SESSION challenge and fresh device/passcode proof; never creates a replacement or extends original idle/absolute expiry." } } }, "UnlockCompletionRequest": { "type": "object", "additionalProperties": false, "required": [ "passcode", "signature" ], "properties": { "passcode": { "type": "string", "pattern": "^[0-9]{6}$", "writeOnly": true }, "signature": { "type": "string", "minLength": 1, "maxLength": 100 } } }, "UnlockChallenge": { "type": "object", "additionalProperties": false, "required": [ "id", "device_challenge", "signing_bytes", "expires_at", "sandbox" ], "properties": { "id": { "type": "string", "format": "uuid" }, "device_challenge": { "$ref": "#/components/schemas/DeviceChallenge" }, "signing_bytes": { "type": "string", "maxLength": 2048 }, "expires_at": { "type": "string", "format": "date-time" }, "sandbox": { "type": "boolean", "enum": [ true ] }, "resume_session_id": { "type": "string", "format": "uuid", "description": "Present only for RESUME_SESSION; must exactly match the requested original session before signing." } } }, "PayerSessionIssued": { "type": "object", "additionalProperties": false, "required": [ "session_id", "payer_id", "device_id", "access_token", "token_type", "idle_expires_at", "absolute_expires_at", "dpop_nonce", "nonce_expires_at", "sandbox" ], "properties": { "session_id": { "type": "string", "format": "uuid" }, "payer_id": { "type": "string", "format": "uuid" }, "device_id": { "type": "string", "format": "uuid" }, "access_token": { "type": "string", "pattern": "^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$" }, "token_type": { "type": "string", "enum": [ "DPoP" ] }, "idle_expires_at": { "type": "string", "format": "date-time" }, "absolute_expires_at": { "type": "string", "format": "date-time" }, "dpop_nonce": { "type": "string", "pattern": "^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$" }, "nonce_expires_at": { "type": "string", "format": "date-time" }, "sandbox": { "type": "boolean", "enum": [ true ] } } }, "PayerSession": { "type": "object", "additionalProperties": false, "required": [ "session_id", "payer_id", "device_id", "state", "idle_expires_at", "absolute_expires_at", "sandbox" ], "properties": { "session_id": { "type": "string", "format": "uuid" }, "payer_id": { "type": "string", "format": "uuid" }, "device_id": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "ACTIVE" ] }, "idle_expires_at": { "type": "string", "format": "date-time" }, "absolute_expires_at": { "type": "string", "format": "date-time" }, "sandbox": { "type": "boolean", "enum": [ true ] } } }, "PayerSignedOut": { "type": "object", "additionalProperties": false, "required": [ "state", "sandbox" ], "properties": { "state": { "type": "string", "enum": [ "SIGNED_OUT" ] }, "sandbox": { "type": "boolean", "enum": [ true ] } } }, "EmptyIdentityMutation": { "type": "object", "additionalProperties": false, "required": [], "properties": {} }, "PayerSecurityAlert": { "type": "object", "additionalProperties": false, "required": [ "id", "device_id", "kind", "created_at", "delivery_state" ], "properties": { "id": { "type": "string", "format": "uuid" }, "device_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "NEW_DEVICE_LOGIN" ] }, "created_at": { "type": "string", "format": "date-time" }, "delivery_state": { "type": "string", "enum": [ "SYNTHETIC_PENDING", "SYNTHETIC_RECORDED" ] } } }, "PayerSecurityAlerts": { "type": "object", "additionalProperties": false, "required": [ "events", "next_cursor", "sandbox" ], "properties": { "events": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/PayerSecurityAlert" } }, "next_cursor": { "type": [ "string", "null" ], "pattern": "^[1-9][0-9]{0,18}$" }, "sandbox": { "type": "boolean", "enum": [ true ] } } }, "PayerDevice": { "type": "object", "additionalProperties": false, "required": [ "id", "created_at", "last_login_at", "state", "current" ], "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "last_login_at": { "type": [ "string", "null" ], "format": "date-time" }, "state": { "type": "string", "enum": [ "TRUSTED", "REVOKED" ] }, "current": { "type": "boolean" } } }, "PayerDevices": { "type": "object", "additionalProperties": false, "required": [ "devices", "next_cursor", "sandbox" ], "properties": { "devices": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/PayerDevice" } }, "next_cursor": { "type": [ "string", "null" ], "format": "uuid" }, "sandbox": { "type": "boolean", "enum": [ true ] } } }, "DeviceRevokeRequest": { "type": "object", "additionalProperties": false, "required": [ "target_device_id" ], "properties": { "target_device_id": { "type": "string", "format": "uuid" } } }, "DeviceRevokeCompletion": { "type": "object", "additionalProperties": false, "required": [ "signature" ], "properties": { "signature": { "type": "string", "minLength": 1, "maxLength": 100 } } }, "DeviceRevokeChallenge": { "type": "object", "additionalProperties": false, "required": [ "id", "device_challenge", "signing_bytes", "expires_at", "sandbox", "target_device_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "device_challenge": { "$ref": "#/components/schemas/DeviceChallenge" }, "signing_bytes": { "type": "string", "maxLength": 2048 }, "expires_at": { "type": "string", "format": "date-time" }, "sandbox": { "type": "boolean", "enum": [ true ] }, "target_device_id": { "type": "string", "format": "uuid" } } }, "DeviceRevoked": { "type": "object", "additionalProperties": false, "required": [ "device_id", "state", "sessions_revoked", "revoked_at", "sandbox" ], "properties": { "device_id": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "REVOKED" ] }, "sessions_revoked": { "type": "integer", "minimum": 0 }, "revoked_at": { "type": "string", "format": "date-time" }, "sandbox": { "type": "boolean", "enum": [ true ] } } }, "LinkInstitution": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "currencies", "approval_channel" ], "properties": { "id": { "type": "string", "enum": [ "sim-wallet", "sim-bank" ] }, "name": { "type": "string" }, "currencies": { "type": "array", "items": { "type": "string", "enum": [ "CDF", "USD" ] }, "maxItems": 2 }, "approval_channel": { "type": "string", "enum": [ "SYNTHETIC_PENDING", "SYNTHETIC_ISSUER" ] } } }, "LinkInstitutions": { "type": "object", "additionalProperties": false, "required": [ "institutions", "sandbox" ], "properties": { "institutions": { "type": "array", "items": { "$ref": "#/components/schemas/LinkInstitution" }, "maxItems": 2 }, "sandbox": { "type": "boolean", "enum": [ true ] } } }, "AccountLinkRequest": { "type": "object", "additionalProperties": false, "required": [ "institution", "currency", "account_selector" ], "properties": { "institution": { "type": "string", "enum": [ "sim-wallet", "sim-bank" ] }, "currency": { "type": "string", "enum": [ "CDF", "USD" ] }, "account_selector": { "type": "string", "pattern": "^synthetic-sim-(wallet|bank)-(approved|declined|pending)$", "writeOnly": true } } }, "AccountLinkConsent": { "type": "object", "additionalProperties": false, "required": [ "signature" ], "properties": { "signature": { "type": "string", "minLength": 1, "maxLength": 100 } } }, "AccountLinkChallenge": { "type": "object", "additionalProperties": false, "required": [ "id", "device_challenge", "signing_bytes", "expires_at", "sandbox", "institution", "currency", "state", "consent_expires_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "device_challenge": { "$ref": "#/components/schemas/DeviceChallenge" }, "signing_bytes": { "type": "string", "maxLength": 2048 }, "expires_at": { "type": "string", "format": "date-time" }, "sandbox": { "type": "boolean", "enum": [ true ] }, "institution": { "type": "string", "enum": [ "sim-wallet", "sim-bank" ] }, "currency": { "type": "string", "enum": [ "CDF", "USD" ] }, "state": { "type": "string", "enum": [ "AWAITING_CONSENT" ] }, "consent_expires_at": { "type": "string", "format": "date-time" } } }, "AccountLinkStatus": { "type": "object", "additionalProperties": false, "required": [ "id", "institution", "currency", "state", "expires_at", "account_id", "approval_channel", "sandbox" ], "properties": { "id": { "type": "string", "format": "uuid" }, "institution": { "type": "string", "enum": [ "sim-wallet", "sim-bank" ] }, "currency": { "type": "string", "enum": [ "CDF", "USD" ] }, "state": { "type": "string", "enum": [ "AWAITING_CONSENT", "PENDING", "VERIFIED", "DECLINED", "EXPIRED" ] }, "expires_at": { "type": "string", "format": "date-time" }, "account_id": { "type": [ "string", "null" ], "format": "uuid" }, "approval_channel": { "type": "string", "enum": [ "SYNTHETIC_PENDING", "SYNTHETIC_ISSUER" ] }, "sandbox": { "type": "boolean", "enum": [ true ] }, "approval_url": { "type": [ "string", "null" ], "maxLength": 160, "description": "Short-lived capability fragment on the configured loopback synthetic issuer origin. Sensitive: do not log or persist outside protected storage. Open only for explicit payer approval; its absence may mean dispatch is queued, expired or unavailable." }, "issuer_channel": { "type": "string", "enum": [ "AWAITING_CONSENT", "QUEUED", "WAITING", "DELIVERED", "UNAVAILABLE", "EXPIRED" ], "description": "Current transport status. Optional on immutable receipts produced before API 0.7; poll the protected status endpoint for current state." } } }, "LinkedAccount": { "type": "object", "additionalProperties": false, "required": [ "id", "institution", "currency", "masked_identifier", "holder_name", "state", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "institution": { "type": "string", "enum": [ "sim-wallet", "sim-bank" ] }, "currency": { "type": "string", "enum": [ "CDF", "USD" ] }, "masked_identifier": { "type": "string", "pattern": "^••••[A-Za-z0-9]{2,4}$" }, "holder_name": { "type": "string", "minLength": 1, "maxLength": 120 }, "state": { "type": "string", "enum": [ "VERIFIED", "REVIEW_REQUIRED" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "LinkedAccounts": { "type": "object", "additionalProperties": false, "required": [ "accounts", "next_cursor", "sandbox" ], "properties": { "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedAccount" }, "maxItems": 20 }, "next_cursor": { "type": [ "string", "null" ], "format": "uuid" }, "sandbox": { "type": "boolean", "enum": [ true ] } } }, "TransferQuotePreview": { "type": "object", "additionalProperties": false, "required": [ "version", "authority", "id", "source_account_id", "source_kind", "recipient_kind", "currency", "amount_minor", "fee_minor", "total_debit_minor", "fee_version", "limit_basis", "remaining_limit_minor", "source_snapshot_id", "recipient_snapshot_id", "limit_snapshot_id", "created_at_epoch_seconds", "expires_at_epoch_seconds", "name_check", "source_institution", "recipient_institution" ], "properties": { "version": { "const": 1 }, "authority": { "const": "PREVIEW_ONLY" }, "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "source_account_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "source_kind": { "enum": [ "BANK", "WALLET" ] }, "recipient_kind": { "enum": [ "BANK", "WALLET" ] }, "currency": { "enum": [ "CDF", "USD" ] }, "amount_minor": { "type": "string", "pattern": "^([1-9][0-9]{0,11}|[1-8][0-9]{12}|9000000000000)$" }, "fee_minor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-6]|9223372036854775807)$" }, "total_debit_minor": { "type": "string", "pattern": "^([1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-6]|9223372036854775807)$" }, "fee_version": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$" }, "limit_basis": { "enum": [ "PRINCIPAL", "TOTAL_DEBIT" ] }, "remaining_limit_minor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-6]|9223372036854775807)$" }, "source_snapshot_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "recipient_snapshot_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "limit_snapshot_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "created_at_epoch_seconds": { "type": "integer", "minimum": 0, "maximum": 253402300799 }, "expires_at_epoch_seconds": { "type": "integer", "minimum": 1, "maximum": 253402300799 }, "name_check": { "$ref": "#/components/schemas/TransferQuoteNameCheck" }, "source_institution": { "type": "string", "pattern": "^[a-z][a-z0-9-]{1,63}$" }, "recipient_institution": { "type": "string", "pattern": "^[a-z][a-z0-9-]{1,63}$" } } }, "PayerTransferQuote": { "type": "object", "additionalProperties": false, "required": [ "quote", "status", "sandbox" ], "properties": { "quote": { "$ref": "#/components/schemas/TransferQuotePreview" }, "status": { "type": "string", "enum": [ "CURRENT", "EXPIRED" ] }, "sandbox": { "type": "boolean", "const": true } } }, "PayerTransferQuoteRequest": { "type": "object", "additionalProperties": false, "required": [ "source_account_id", "recipient_institution", "recipient_selector", "currency", "amount_minor" ], "properties": { "source_account_id": { "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "recipient_institution": { "type": "string", "enum": [ "sim-bank", "sim-wallet" ] }, "recipient_selector": { "type": "string", "enum": [ "synthetic-recipient-matched", "synthetic-recipient-unavailable", "synthetic-recipient-cdf-only", "synthetic-recipient-usd-only" ] }, "currency": { "type": "string", "enum": [ "CDF", "USD" ] }, "amount_minor": { "type": "string", "pattern": "^([1-9][0-9]{0,11}|[1-8][0-9]{12}|9000000000000)$" } }, "description": "Synthetic preview only. CDF amount minor units must be divisible by 100. Source must be currently VERIFIED and owned by the active DPoP payer." }, "TransferQuoteNameCheck": { "type": "object", "additionalProperties": false, "required": [ "status", "masked_name", "acknowledgement_required" ], "properties": { "status": { "type": "string", "enum": [ "MATCHED", "UNAVAILABLE" ] }, "masked_name": { "type": [ "string", "null" ] }, "acknowledgement_required": { "type": "boolean" } }, "if": { "properties": { "status": { "const": "MATCHED" } } }, "then": { "properties": { "status": { "const": "MATCHED" }, "masked_name": { "type": "string", "minLength": 2, "maxLength": 80, "pattern": "^[^\\u0000-\\u001f\\u007f]*\\*[^\\u0000-\\u001f\\u007f]*$" }, "acknowledgement_required": { "const": false } } }, "else": { "properties": { "status": { "const": "UNAVAILABLE" }, "masked_name": { "type": "null" }, "acknowledgement_required": { "const": true } } }, "description": "MATCHED requires a masked name and false acknowledgement_required. UNAVAILABLE requires null name and true acknowledgement_required; consent is a separate operation." }, "TransferConsentRequest": { "type": "object", "additionalProperties": false, "required": [ "quote_id", "name_unavailable_acknowledged" ], "properties": { "quote_id": { "type": "string", "format": "uuid" }, "name_unavailable_acknowledged": { "type": "boolean" } } }, "TransferConsentProof": { "type": "object", "additionalProperties": false, "required": [ "signature" ], "properties": { "signature": { "type": "string", "minLength": 1, "maxLength": 100 } } }, "TransferConsentChallenge": { "type": "object", "additionalProperties": false, "required": [ "id", "quote_id", "quote", "name_unavailable_acknowledged", "device_challenge", "signing_bytes", "expires_at", "sandbox" ], "properties": { "id": { "type": "string", "format": "uuid" }, "quote_id": { "type": "string", "format": "uuid" }, "quote": { "$ref": "#/components/schemas/TransferQuotePreview" }, "name_unavailable_acknowledged": { "type": "boolean" }, "device_challenge": { "$ref": "#/components/schemas/DeviceChallenge" }, "signing_bytes": { "type": "string", "maxLength": 2048 }, "expires_at": { "type": "string", "format": "date-time" }, "sandbox": { "type": "boolean", "enum": [ true ] } } }, "TransferConsentReceipt": { "type": "object", "additionalProperties": false, "required": [ "id", "quote_id", "state", "authority", "accepted_at", "quote_expires_at", "sandbox" ], "properties": { "id": { "type": "string", "format": "uuid" }, "quote_id": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "CONSENT_RECORDED" ] }, "authority": { "type": "string", "enum": [ "PAYER_INTENT_ONLY" ] }, "accepted_at": { "type": "string", "format": "date-time" }, "quote_expires_at": { "type": "integer", "minimum": 1, "maximum": 253402300799 }, "sandbox": { "type": "boolean", "enum": [ true ] } }, "description": "Historical immutable payer intent only. This receipt never implies current execution eligibility, issuer debit approval, reserved funds or transferred money." }, "TransferApprovalRequest": { "type": "object", "additionalProperties": false, "required": [ "consent_id" ], "properties": { "consent_id": { "type": "string", "format": "uuid" } } }, "TransferApprovalReceipt": { "type": "object", "additionalProperties": false, "required": [ "id", "quote_id", "consent_id", "state", "authority", "status", "created_at_epoch_seconds", "expires_at_epoch_seconds", "sandbox" ], "properties": { "id": { "type": "string", "format": "uuid" }, "quote_id": { "type": "string", "format": "uuid" }, "consent_id": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "PREPARED" ] }, "authority": { "type": "string", "enum": [ "REQUEST_ONLY" ] }, "status": { "type": "string", "enum": [ "CURRENT", "EXPIRED", "NOT_YET_CURRENT" ] }, "created_at_epoch_seconds": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799 }, "expires_at_epoch_seconds": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799 }, "sandbox": { "type": "boolean", "enum": [ true ] } }, "description": "Historical acknowledgement that the switch retained an approval request. CURRENT is time-only, never live execution eligibility or issuer approval. Original active session and VERIFIED source required. No issuer token or protected destination is exposed." }, "TransferIssuerDecision": { "type": "object", "additionalProperties": false, "required": [ "classification", "decision", "recorded_at_epoch_seconds", "requires_investigation" ], "properties": { "classification": { "type": "string", "enum": [ "ACCEPTED", "LATE", "INELIGIBLE", "CONFLICT" ] }, "decision": { "type": "string", "enum": [ "APPROVED", "DECLINED" ] }, "recorded_at_epoch_seconds": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799 }, "requires_investigation": { "type": "boolean" } }, "description": "Historical local classification. ACCEPTED records eligibility at that prior commit only; later execution requires new authoritative checks. A permanent investigation overrides any usable approval." }, "TransferIssuerStatus": { "type": "object", "additionalProperties": false, "required": [ "id", "authority", "state", "status", "approval_url", "expires_at_epoch_seconds", "last_refresh", "sandbox" ], "properties": { "id": { "type": "string", "format": "uuid" }, "authority": { "type": "string", "enum": [ "APPROVAL_STATUS_ONLY" ] }, "state": { "type": "string", "enum": [ "UNKNOWN", "PENDING", "AWAITING_ACCEPTANCE", "APPROVED", "DECLINED", "EXPIRED", "NOT_YET_CURRENT", "UNAVAILABLE", "CONFLICT" ] }, "status": { "type": "string", "enum": [ "CURRENT", "EXPIRED", "NOT_YET_CURRENT", "UNAVAILABLE" ] }, "approval_url": { "type": [ "string", "null" ], "maxLength": 512, "description": "Only a currently eligible pending request exposes its configured synthetic issuer capability. Treat as sensitive: do not log it, store it in analytics, or display it as payment completion." }, "expires_at_epoch_seconds": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799 }, "decision": { "$ref": "#/components/schemas/TransferIssuerDecision" }, "last_refresh": { "type": "string", "enum": [ "NONE", "OBSERVATION", "UNKNOWN", "REJECTED", "EXPIRED" ] }, "sandbox": { "type": "boolean", "enum": [ true ] } }, "description": "Original active session only. Passive historical issuer/acceptance status, never money movement. CURRENT checks original time window and linked source; it is not debit authority. APPROVED/DECLINED require a retained local accepted decision. AWAITING_ACCEPTANCE means terminal issuer evidence is stored but explicit refresh has not completed its local acceptance step. GET never performs that step. The decision member is absent until authenticated issuer evidence has a retained local classification." }, "TransferExecutionStatus": { "type": "object", "additionalProperties": false, "required": [ "id", "authority", "state", "status", "execution_id", "admitted_at_epoch_seconds", "expires_at_epoch_seconds", "received_at_epoch_seconds", "last_delivery", "sandbox" ], "properties": { "id": { "type": "string", "format": "uuid" }, "authority": { "type": "string", "enum": [ "EXECUTION_STATUS_ONLY" ] }, "state": { "type": "string", "enum": [ "NOT_ADMITTED", "ADMITTED", "UNKNOWN", "STORED", "UNAVAILABLE", "INVESTIGATION_REQUIRED" ] }, "status": { "type": "string", "enum": [ "CURRENT", "EXPIRED", "NOT_YET_CURRENT", "INVESTIGATION_REQUIRED" ] }, "execution_id": { "type": [ "string", "null" ], "format": "uuid" }, "admitted_at_epoch_seconds": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0, "maximum": 253402300799 }, "expires_at_epoch_seconds": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799 }, "received_at_epoch_seconds": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0, "maximum": 253402300799 }, "last_delivery": { "type": "string", "enum": [ "NONE", "RECEIPT", "UNKNOWN", "REJECTED", "CONFLICT" ] }, "sandbox": { "type": "boolean", "enum": [ true ] } }, "description": "Original active session only. Local admission and last observed receiving storage, never monetary success. CURRENT is only the original time window; it is not live remote eligibility or dispatch authority. STORED records a confirmed historical receiving receipt. UNKNOWN means the latest attempt has no trustworthy outcome; a prior received_at can remain visible. EXPIRED never extends or reverses a mandate. Investigation is permanent and overrides other states. Nullable fields are explicit until admission or receiving evidence exists." }, "TransferMonetaryObservation": { "type": "object", "additionalProperties": false, "required": [ "progress", "accounting_complete", "accounted_legs", "expired_before_start", "provider_attempts_exhausted", "switch_received_at_epoch_seconds", "inspected_at_epoch_seconds", "provider_confirmed_at_epoch_seconds", "credit_due_at_epoch_seconds", "reversal_due_at_epoch_seconds", "credit_overdue", "reversal_overdue", "terminal_window_ends_at_epoch_seconds" ], "properties": { "progress": { "type": "string", "enum": [ "READY", "DEBIT_PENDING", "DEBIT_FAILED", "CREDIT_PENDING", "COMPLETED", "REVERSAL_PENDING", "REVERSAL_FAILED", "REVERSED" ] }, "accounting_complete": { "type": "boolean" }, "accounted_legs": { "type": "array", "items": { "type": "string", "enum": [ "DEBIT", "CREDIT", "REVERSAL" ] }, "uniqueItems": true, "maxItems": 3 }, "expired_before_start": { "type": "boolean" }, "provider_attempts_exhausted": { "type": "boolean" }, "switch_received_at_epoch_seconds": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799 }, "inspected_at_epoch_seconds": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799 }, "provider_confirmed_at_epoch_seconds": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0, "maximum": 253402300799 }, "credit_due_at_epoch_seconds": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799 }, "reversal_due_at_epoch_seconds": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0, "maximum": 253402300799 }, "credit_overdue": { "type": "boolean" }, "reversal_overdue": { "type": "boolean" }, "terminal_window_ends_at_epoch_seconds": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0, "maximum": 253402300799 } }, "description": "Nullable historical observation. Accounting completion and dated participant confirmation are independent. Inspection/fetch times never renew confirmation. Failed debit and failed reversal remain failures even if provider confirmation is present. Local investigation suppresses usable accounting_complete and provider confirmation while preserving historical postings/progress. No amount, recipient reference, issuer token or provider command is exposed." }, "TransferMonetaryStatus": { "type": "object", "additionalProperties": false, "required": [ "id", "authority", "sandbox", "state", "investigation_required", "execution_id", "admitted_at_epoch_seconds", "expires_at_epoch_seconds", "last_refresh", "refresh_requested_at_epoch_seconds", "refresh_received_at_epoch_seconds", "observation_received_at_epoch_seconds", "observation" ], "properties": { "id": { "type": "string", "format": "uuid" }, "authority": { "type": "string", "enum": [ "MONETARY_STATUS_ONLY" ] }, "sandbox": { "type": "boolean", "enum": [ true ] }, "state": { "type": "string", "enum": [ "NOT_ADMITTED", "NOT_OBSERVED", "REFRESH_PENDING", "UNAVAILABLE", "INVESTIGATION_REQUIRED", "EXPIRED_BEFORE_START", "ACCOUNTING_INCOMPLETE", "COMPLETED_UNCONFIRMED", "REVERSED_UNCONFIRMED", "READY", "DEBIT_PENDING", "DEBIT_FAILED", "CREDIT_PENDING", "COMPLETED", "REVERSAL_PENDING", "REVERSAL_FAILED", "REVERSED" ] }, "investigation_required": { "type": "boolean" }, "execution_id": { "type": [ "string", "null" ], "format": "uuid" }, "admitted_at_epoch_seconds": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0, "maximum": 253402300799 }, "expires_at_epoch_seconds": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799 }, "last_refresh": { "type": "string", "enum": [ "NONE", "PENDING", "UNAVAILABLE", "OBSERVED", "STALE", "CONTRADICTION" ] }, "refresh_requested_at_epoch_seconds": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0, "maximum": 253402300799 }, "refresh_received_at_epoch_seconds": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0, "maximum": 253402300799 }, "observation_received_at_epoch_seconds": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0, "maximum": 253402300799 }, "observation": { "anyOf": [ { "$ref": "#/components/schemas/TransferMonetaryObservation" }, { "type": "null" } ] } }, "description": "Original active session only. State describes the retained monetary observation, subject to latest refresh availability and permanent investigation. All nullable fields are explicit. UNAVAILABLE/REFRESH_PENDING can retain older observations; show their dates rather than a fresh success. A stored execution does not imply monetary completion. Original expiry after a start preserves historical outcomes. No finite confirmation window or passive read establishes perpetual finality." }, "HistoryMonetaryObservation": { "type": "object", "additionalProperties": false, "required": [ "progress", "accounting_complete", "accounted_legs", "expired_before_start", "provider_attempts_exhausted", "switch_received_at", "inspected_at", "provider_confirmed_at", "credit_due_at", "reversal_due_at", "credit_overdue", "reversal_overdue", "terminal_window_ends_at" ], "properties": { "progress": { "type": "string", "enum": [ "READY", "DEBIT_PENDING", "DEBIT_FAILED", "CREDIT_PENDING", "COMPLETED", "REVERSAL_PENDING", "REVERSAL_FAILED", "REVERSED" ] }, "accounting_complete": { "type": "boolean" }, "accounted_legs": { "type": "array", "items": { "type": "string", "enum": [ "DEBIT", "CREDIT", "REVERSAL" ] }, "uniqueItems": true, "maxItems": 3 }, "expired_before_start": { "type": "boolean" }, "provider_attempts_exhausted": { "type": "boolean" }, "switch_received_at": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$" }, "inspected_at": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$" }, "provider_confirmed_at": { "type": [ "string", "null" ], "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$" }, "credit_due_at": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$" }, "reversal_due_at": { "type": [ "string", "null" ], "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$" }, "credit_overdue": { "type": "boolean" }, "reversal_overdue": { "type": "boolean" }, "terminal_window_ends_at": { "type": [ "string", "null" ], "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$" } }, "description": "Nullable historical observation. Accounting completion and dated participant confirmation are independent. Inspection/fetch times never renew confirmation. Failed debit and failed reversal remain failures even if provider confirmation is present. Local investigation suppresses usable accounting_complete and provider confirmation while preserving historical postings/progress. No amount, recipient reference, issuer token or provider command is exposed." }, "HistoryMonetaryStatus": { "type": "object", "additionalProperties": false, "required": [ "id", "authority", "sandbox", "state", "investigation_required", "execution_id", "admitted_at", "expires_at", "last_refresh", "refresh_requested_at", "refresh_received_at", "observation_received_at", "observation" ], "properties": { "id": { "type": "string", "format": "uuid" }, "authority": { "type": "string", "enum": [ "MONETARY_STATUS_ONLY" ] }, "sandbox": { "type": "boolean", "enum": [ true ] }, "state": { "type": "string", "enum": [ "NOT_ADMITTED", "NOT_OBSERVED", "REFRESH_PENDING", "UNAVAILABLE", "INVESTIGATION_REQUIRED", "EXPIRED_BEFORE_START", "ACCOUNTING_INCOMPLETE", "COMPLETED_UNCONFIRMED", "REVERSED_UNCONFIRMED", "READY", "DEBIT_PENDING", "DEBIT_FAILED", "CREDIT_PENDING", "COMPLETED", "REVERSAL_PENDING", "REVERSAL_FAILED", "REVERSED" ] }, "investigation_required": { "type": "boolean" }, "execution_id": { "type": [ "string", "null" ], "format": "uuid" }, "admitted_at": { "type": [ "string", "null" ], "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$" }, "expires_at": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$" }, "last_refresh": { "type": "string", "enum": [ "NONE", "PENDING", "UNAVAILABLE", "OBSERVED", "STALE", "CONTRADICTION" ] }, "refresh_requested_at": { "type": [ "string", "null" ], "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$" }, "refresh_received_at": { "type": [ "string", "null" ], "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$" }, "observation_received_at": { "type": [ "string", "null" ], "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$" }, "observation": { "anyOf": [ { "$ref": "#/components/schemas/HistoryMonetaryObservation" }, { "type": "null" } ] } }, "description": "Current payer-owned retained monetary history. Original execution restrictions remain unchanged; current fresh sessions may inspect only. All dates are UTC, all nullable fields explicit; investigation suppresses completion and confirmation." }, "HistoryDelivery": { "type": "object", "additionalProperties": false, "required": [ "state", "execution_id", "admitted_at", "expires_at", "received_at", "last_delivery" ], "properties": { "state": { "type": "string", "enum": [ "NOT_ADMITTED", "ADMITTED", "UNKNOWN", "STORED", "UNAVAILABLE", "INVESTIGATION_REQUIRED" ] }, "execution_id": { "type": [ "string", "null" ], "format": "uuid" }, "admitted_at": { "type": [ "string", "null" ], "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$" }, "expires_at": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$" }, "received_at": { "type": [ "string", "null" ], "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$" }, "last_delivery": { "type": "string", "enum": [ "NONE", "RECEIPT", "UNKNOWN", "REJECTED", "CONFLICT" ] } }, "description": "Retained delivery metadata only. No current eligibility or execution authority." }, "HistoryTerms": { "type": "object", "additionalProperties": false, "required": [ "source_account_id", "source_masked_identifier", "source_institution", "recipient_institution", "recipient_name_status", "recipient_masked_name", "currency", "fee_version", "amount_minor", "fee_minor", "total_debit_minor" ], "properties": { "source_account_id": { "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "source_masked_identifier": { "type": "string", "pattern": "^••••[A-Za-z0-9]{2,4}$" }, "source_institution": { "type": "string", "enum": [ "sim-bank", "sim-wallet" ] }, "recipient_institution": { "type": "string", "enum": [ "sim-bank", "sim-wallet" ] }, "recipient_name_status": { "type": "string", "enum": [ "MATCHED", "UNAVAILABLE" ] }, "recipient_masked_name": { "type": [ "string", "null" ] }, "currency": { "type": "string", "enum": [ "CDF", "USD" ] }, "fee_version": { "type": "string" }, "amount_minor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,18})$", "description": "Exact integer minor units encoded as a canonical decimal string; never parse through floating point." }, "fee_minor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,18})$", "description": "Exact integer minor units encoded as a canonical decimal string; never parse through floating point." }, "total_debit_minor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,18})$", "description": "Exact integer minor units encoded as a canonical decimal string; never parse through floating point." } } }, "TransferHistoryDetail": { "type": "object", "additionalProperties": false, "required": [ "id", "authority", "sandbox", "execution_permitted", "created_at", "terms", "delivery", "monetary" ], "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "authority": { "type": "string", "enum": [ "HISTORICAL_TRANSFER_ONLY" ] }, "sandbox": { "type": "boolean", "enum": [ true ] }, "execution_permitted": { "type": "boolean", "enum": [ false ] }, "created_at": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$" }, "terms": { "$ref": "#/components/schemas/HistoryTerms" }, "delivery": { "$ref": "#/components/schemas/HistoryDelivery" }, "monetary": { "$ref": "#/components/schemas/HistoryMonetaryStatus" } }, "description": "Payer-owned historical transfer, readable with a fresh current DPoP session after original-session expiry/revocation. No payment, refresh or session renewal." }, "TransferHistoryPage": { "type": "object", "additionalProperties": false, "required": [ "authority", "sandbox", "execution_permitted", "items", "next_cursor", "scanned_count", "scan_limit", "status_basis" ], "properties": { "authority": { "type": "string", "enum": [ "HISTORICAL_TRANSFER_PAGE_ONLY" ] }, "sandbox": { "type": "boolean", "enum": [ true ] }, "execution_permitted": { "type": "boolean", "enum": [ false ] }, "items": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/TransferHistoryDetail" } }, "next_cursor": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9_-]{40,2048}$", "minLength": 40, "maxLength": 2048 }, "scanned_count": { "type": "integer", "minimum": 0, "maximum": 20 }, "scan_limit": { "type": "integer", "minimum": 1, "maximum": 20 }, "status_basis": { "type": "string", "enum": [ "RETAINED_OBSERVATIONS_AT_READ" ] } }, "description": "At most scan_limit candidates examined. State filters can yield empty items with a non-null advancing cursor. Only null next_cursor ends candidates; callers must bound continuation. Stable membership watermark, current retained status per page. Cursor expires 15 minutes after first page; continuation never renews expiry." }, "HistoryError": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message_en", "message_fr" ], "properties": { "code": { "type": "string", "enum": [ "INVALID_REQUEST", "INVALID_HISTORY_FILTER", "INVALID_HISTORY_CURSOR", "INVALID_SESSION", "INVALID_DEVICE_PROOF", "PROOF_REPLAYED", "DPOP_NONCE_REQUIRED", "RATE_LIMITED", "HISTORY_RATE_LIMITED", "TRANSFER_HISTORY_NOT_FOUND", "HISTORY_INDEX_NOT_READY", "TRANSFER_HISTORY_UNAVAILABLE" ] }, "message_en": { "type": "string" }, "message_fr": { "type": "string" } } } } }, "ProblemReportReason": { "type": "string", "enum": [ "TRANSFER_NOT_RECEIVED", "UNRECOGNIZED_TRANSFER", "DUPLICATE_TRANSFER", "AMOUNT_OR_FEE", "OTHER" ] }, "ProblemReportInput": { "type": "object", "additionalProperties": false, "required": [ "reason", "description" ], "properties": { "reason": { "$ref": "#/components/schemas/ProblemReportReason" }, "description": { "type": "string", "minLength": 1, "maxLength": 2000, "pattern": "^(?![\\s\\S]*[\\x00-\\x09\\x0B-\\x1F\\x7F-\\x9F])\\S(?:[\\s\\S]*\\S)?$", "description": "Trimmed nonblank narrative, at most 2000 Unicode code points and 8000 UTF-8 bytes. LF is allowed internally; other ISO control characters, Unicode FORMAT characters and unpaired surrogates are rejected by the server. Never include issuer credentials." } } }, "ProblemReportTerms": { "type": "object", "additionalProperties": false, "required": [ "source_masked_identifier", "source_institution", "recipient_institution", "recipient_name_status", "recipient_masked_name", "currency", "fee_version", "amount_minor", "fee_minor", "total_debit_minor" ], "properties": { "source_masked_identifier": { "type": "string", "pattern": "^••••[A-Za-z0-9]{2,4}$" }, "source_institution": { "type": "string", "enum": [ "sim-bank", "sim-wallet" ] }, "recipient_institution": { "type": "string", "enum": [ "sim-bank", "sim-wallet" ] }, "recipient_name_status": { "type": "string", "enum": [ "MATCHED", "UNAVAILABLE" ] }, "recipient_masked_name": { "type": [ "string", "null" ] }, "currency": { "type": "string", "enum": [ "CDF", "USD" ] }, "fee_version": { "type": "string" }, "amount_minor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,18})$", "description": "Exact integer minor units encoded as a canonical decimal string; never parse through floating point." }, "fee_minor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,18})$", "description": "Exact integer minor units encoded as a canonical decimal string; never parse through floating point." }, "total_debit_minor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,18})$", "description": "Exact integer minor units encoded as a canonical decimal string; never parse through floating point." } } }, "ProblemReportMonetarySnapshot": { "type": "object", "additionalProperties": false, "required": [ "state", "investigation_required", "last_refresh", "refresh_requested_at", "refresh_received_at", "observation_received_at", "observation" ], "properties": { "state": { "type": "string", "enum": [ "NOT_ADMITTED", "NOT_OBSERVED", "REFRESH_PENDING", "UNAVAILABLE", "INVESTIGATION_REQUIRED", "EXPIRED_BEFORE_START", "ACCOUNTING_INCOMPLETE", "COMPLETED_UNCONFIRMED", "REVERSED_UNCONFIRMED", "READY", "DEBIT_PENDING", "DEBIT_FAILED", "CREDIT_PENDING", "COMPLETED", "REVERSAL_PENDING", "REVERSAL_FAILED", "REVERSED" ] }, "investigation_required": { "type": "boolean" }, "last_refresh": { "type": "string", "enum": [ "NONE", "PENDING", "UNAVAILABLE", "OBSERVED", "STALE", "CONTRADICTION" ] }, "refresh_requested_at": { "type": [ "string", "null" ], "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$" }, "refresh_received_at": { "type": [ "string", "null" ], "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$" }, "observation_received_at": { "type": [ "string", "null" ], "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$" }, "observation": { "anyOf": [ { "$ref": "#/components/schemas/HistoryMonetaryObservation" }, { "type": "null" } ] } }, "description": "Immutable dated monetary evidence captured at report submission. Later transfer changes do not update this snapshot. All dates are UTC and nullable fields are explicit; investigation at submission suppresses completion and confirmation." }, "ProblemReportTransferSnapshot": { "type": "object", "additionalProperties": false, "required": [ "id", "created_at", "terms", "delivery_state", "monetary" ], "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "created_at": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$" }, "terms": { "$ref": "#/components/schemas/ProblemReportTerms" }, "delivery_state": { "type": "string", "enum": [ "NOT_ADMITTED", "ADMITTED", "UNKNOWN", "STORED", "UNAVAILABLE", "INVESTIGATION_REQUIRED" ] }, "monetary": { "$ref": "#/components/schemas/ProblemReportMonetarySnapshot" } } }, "PayerTransferProblem": { "type": "object", "additionalProperties": false, "required": [ "id", "reference", "authority", "sandbox", "status", "reason", "description", "created_at", "response_due_at", "resolution_due_at", "evidence_basis", "transfer" ], "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "reference": { "type": "string", "pattern": "^FR(-[A-F0-9]{4}){5}$" }, "authority": { "type": "string", "enum": [ "PAYER_PROBLEM_REPORT_ONLY" ] }, "sandbox": { "type": "boolean", "enum": [ true ] }, "status": { "type": "string", "enum": [ "SUBMITTED" ], "description": "Acknowledgement only; no substantive staff response or resolution is represented." }, "reason": { "$ref": "#/components/schemas/ProblemReportReason" }, "description": { "type": "string", "minLength": 1, "maxLength": 2000, "pattern": "^(?![\\s\\S]*[\\x00-\\x09\\x0B-\\x1F\\x7F-\\x9F])\\S(?:[\\s\\S]*\\S)?$", "description": "Trimmed nonblank narrative, at most 2000 Unicode code points and 8000 UTF-8 bytes. LF is allowed internally; other ISO control characters, Unicode FORMAT characters and unpaired surrogates are rejected by the server. Never include issuer credentials." }, "created_at": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$" }, "response_due_at": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$" }, "resolution_due_at": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$" }, "evidence_basis": { "type": "string", "enum": [ "AT_SUBMISSION" ], "description": "Immutable dated evidence at report submission, not current transfer status." }, "transfer": { "$ref": "#/components/schemas/ProblemReportTransferSnapshot" } } }, "ProblemReportError": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message_en", "message_fr" ], "properties": { "code": { "type": "string", "enum": [ "INVALID_REQUEST", "INVALID_PROBLEM_REPORT", "UNSUPPORTED_MEDIA_TYPE", "PROBLEM_REPORT_TOO_LARGE", "INVALID_SESSION", "INVALID_DEVICE_PROOF", "PROOF_REPLAYED", "DPOP_NONCE_REQUIRED", "RATE_LIMITED", "TRANSFER_HISTORY_NOT_FOUND", "TRANSFER_HISTORY_UNAVAILABLE", "PROBLEM_REPORT_NOT_FOUND", "PROBLEM_REPORT_UNAVAILABLE", "IDEMPOTENCY_CONFLICT", "PROBLEM_REPORT_RATE_LIMITED", "PROBLEM_REPORT_CREATE_LIMITED" ] }, "message_en": { "type": "string" }, "message_fr": { "type": "string" } } } } } }, "securitySchemes": { "DpopSession": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "DPoP followed by one space and the opaque access token; bearer fallback is rejected." }, "DpopProof": { "type": "apiKey", "in": "header", "name": "DPoP", "description": "Fresh RFC9449 ES256 proof bound to token, method, trusted URI and server nonce. Never reuse a proof ID. The SDK does not generate device signatures." } } } }