{"openapi":"3.1.0","info":{"title":"BillBene API","description":"BillBene v1 API — one swipe, one less bill. Authoritative for identity, permissions, payment policy, money state and privacy projections. Live payments are disabled unless every server-side gate holds (env flag, compiled approved adapter, signed provider approval, two-person country launch). Demo/sandbox endpoints never move real money.","license":{"name":"UNLICENSED","identifier":"UNLICENSED"},"version":"1.0.0"},"servers":[{"url":"/api/v1","description":"Versioned API base"}],"paths":{"/auth/logout":{"post":{"tags":["Auth"],"summary":"Sign out of this session.","operationId":"logout","responses":{"204":{"description":""}},"security":[{"session":[]}]}},"/auth/logout-all":{"post":{"tags":["Auth"],"summary":"Sign out everywhere (BB-004). Revoked sessions fail on the next call.","operationId":"logout_all","responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokedCount"}}}}},"security":[{"session":[]}]}},"/auth/magic-link":{"post":{"tags":["Auth"],"summary":"Request a single-use sign-in link. Always answers the same way so the\nresponse never reveals whether an account exists (BB-002).","operationId":"request_magic_link","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MagicLinkRequest"}}},"required":true},"responses":{"202":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptedMessage"}}}},"429":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/auth/magic-link/consume":{"post":{"tags":["Auth"],"summary":"Consume a magic link exactly once and start a session. New addresses get\na new member account (requester + donor capabilities, BB-001).","operationId":"consume_magic_link","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsumeRequest"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignInResponse"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/auth/mfa/passkey":{"post":{"tags":["Auth"],"summary":"Verify MFA for this session with a passkey. The session token rotates.","operationId":"passkey_mfa_verify","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PasskeyAssertionInput"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignInResponse"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/auth/mfa/totp/confirm":{"post":{"tags":["Auth"],"summary":"Confirm enrolment with a first code; elevates and rotates the session.","operationId":"totp_confirm","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TotpCode"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignInResponse"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/auth/mfa/totp/enroll":{"post":{"tags":["Auth"],"summary":"Begin TOTP enrolment (replaces an unconfirmed pending factor).","operationId":"totp_enroll","responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TotpEnrollment"}}}},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/auth/mfa/verify":{"post":{"tags":["Auth"],"summary":"Verify MFA for this session. The session token rotates on elevation.","operationId":"mfa_verify","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TotpCode"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignInResponse"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/auth/passkey/login/options":{"post":{"tags":["Auth"],"summary":"Start a usernameless passkey sign-in (also used for browser autofill).","operationId":"passkey_login_options","responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PasskeyOptions"}}}},"429":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/auth/passkey/login/verify":{"post":{"tags":["Auth"],"summary":"Finish a passkey sign-in. A user-verified passkey counts as multi-factor,\nso the new session is MFA-verified (staff included).","operationId":"passkey_login_verify","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PasskeyAssertionInput"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignInResponse"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/auth/passkey/register/options":{"post":{"tags":["Auth"],"summary":"Start adding a passkey to the signed-in account (recent sign-in or step-up required).","operationId":"passkey_register_options","responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PasskeyOptions"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/auth/passkey/register/verify":{"post":{"tags":["Auth"],"summary":"Finish adding a passkey: verify the authenticator's attestation response.","operationId":"passkey_register_verify","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PasskeyRegistrationInput"}}},"required":true},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PasskeyView"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/auth/passkey/session/options":{"post":{"tags":["Auth"],"summary":"Challenge the signed-in user's own passkeys (for MFA or step-up).","operationId":"passkey_session_options","responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PasskeyOptions"}}}},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/auth/password":{"post":{"tags":["Auth"],"summary":"Set or change the optional password (requires a recent sign-in).","operationId":"set_password","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetPasswordRequest"}}},"required":true},"responses":{"204":{"description":""},"422":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/auth/password/login":{"post":{"tags":["Auth"],"summary":"Optional password sign-in (Argon2id). Generic failure, rate limited.","operationId":"password_login","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PasswordLoginRequest"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignInResponse"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/auth/step-up":{"post":{"tags":["Auth"],"summary":"Fresh second-factor proof for sensitive actions (valid 10 minutes).","operationId":"step_up","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TotpCode"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StepUpResult"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/auth/step-up/passkey":{"post":{"tags":["Auth"],"summary":"Fresh proof for sensitive actions with a passkey (valid 10 minutes).","operationId":"passkey_step_up","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PasskeyAssertionInput"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StepUpResult"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/basket":{"get":{"tags":["Basket"],"operationId":"get_basket","responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Basket"}}}}},"security":[{"session":[]}]}},"/basket/lines":{"post":{"tags":["Basket"],"summary":"Add/replace an intent line. Does NOT start a charge (BB-076).","operationId":"add_line","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddLine"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Basket"}}}},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/basket/lines/{id}":{"delete":{"tags":["Basket"],"operationId":"remove_line","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Basket"}}}}},"security":[{"session":[]}]},"patch":{"tags":["Basket"],"operationId":"update_line","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateLine"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Basket"}}}}},"security":[{"session":[]}]}},"/campaigns":{"get":{"tags":["Campaigns"],"summary":"Public, sanitised campaigns (no applicant data).","operationId":"list_campaigns","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicCampaign"}}}}}},"security":[{}]}},"/campaigns/benedrop/{id}/selection-proof":{"get":{"tags":["Campaigns"],"operationId":"benedrop_proof","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BeneDropProof"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{}]}},"/campaigns/circles":{"post":{"tags":["Campaigns"],"operationId":"create_circle","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCircle"}}},"required":true},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CircleView"}}}}},"security":[{"session":[]}]}},"/campaigns/circles/join":{"post":{"tags":["Campaigns"],"operationId":"join_circle","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JoinCircle"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CircleView"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/campaigns/circles/{id}":{"get":{"tags":["Campaigns"],"operationId":"get_circle","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CircleView"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/campaigns/circles/{id}/invites":{"post":{"tags":["Campaigns"],"operationId":"create_invite","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInvite"}}},"required":true},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteCreated"}}}}},"security":[{"session":[]}]}},"/campaigns/circles/{id}/invites/{invite_id}":{"delete":{"tags":["Campaigns"],"operationId":"revoke_invite","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"invite_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":""}},"security":[{"session":[]}]}},"/checkout/attempts":{"post":{"tags":["Checkout"],"summary":"Create the idempotent payment attempt (requires `Idempotency-Key`).","operationId":"create_attempt","parameters":[{"name":"Idempotency-Key","in":"header","description":"8-128 chars; same key + same body replays the original result","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAttemptRequest"}}},"required":true},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttemptView"}}}},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/checkout/attempts/{id}":{"get":{"tags":["Checkout"],"summary":"Authoritative, owner-only attempt state. A `?paid=true` style redirect\nis never trusted (BB-QA-06): only provider-verified events move state.","operationId":"get_attempt","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttemptView"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/checkout/attempts/{id}/cancel":{"post":{"tags":["Checkout"],"operationId":"cancel_attempt","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttemptView"}}}},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/checkout/policy-evaluate":{"post":{"tags":["Checkout"],"summary":"No-money-movement policy decision (country, caps, KYC, anonymity).","operationId":"policy_evaluate","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolicyEvaluateRequest"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolicyDecision"}}}}},"security":[{"session":[]}]}},"/checkout/privacy-preview":{"post":{"tags":["Checkout"],"summary":"Exactly what the recipient and public will see, plus route disclosures,\nbefore any charge (BB-190, BB-197).","operationId":"privacy_preview","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrivacyPreviewRequest"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrivacyPreview"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/checkout/quote":{"post":{"tags":["Checkout"],"summary":"Server-calculated quote: amount, fee, optional tip (zero by default),\ntotal, provider, route and privacy snapshot preview.","operationId":"quote","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteRequest"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteView"}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/cms/{slug}":{"get":{"tags":["Meta"],"summary":"Published legal/help page (BB-142).","operationId":"cms_page","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CmsDocument"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{}]}},"/control/approvals":{"get":{"tags":["Control"],"operationId":"approvals","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":["string","null"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ApprovalView"}}}}}},"security":[{"session":[]}]}},"/control/approvals/{id}/decide":{"post":{"tags":["Control"],"summary":"Decide an approval: different person than the proposer, role-specific,\nwith step-up MFA. Execution happens in the same transaction.","operationId":"decide_approval","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApprovalDecision"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApprovalView"}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/control/audit":{"get":{"tags":["Control"],"operationId":"audit_search","parameters":[{"name":"action","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"resource_type","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"actor_id","in":"query","required":false,"schema":{"type":["string","null"],"format":"uuid"}},{"name":"limit","in":"query","required":false,"schema":{"type":["integer","null"],"format":"int64"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AuditRow"}}}}}},"security":[{"session":[]}]}},"/control/benedrop/{id}/commit":{"post":{"tags":["Campaigns"],"summary":"Commit to a secret seed BEFORE the draw (published commitment).","operationId":"benedrop_commit","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrawKey"}}},"required":true},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommitResult"}}}}},"security":[{"session":[]}]}},"/control/benedrop/{id}/draw":{"post":{"tags":["Campaigns"],"summary":"Execute the committed draw. Idempotent for the same key; a different key\nwhile a draw exists is rejected (no secret reroll — BBT-025).","operationId":"benedrop_draw","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrawKey"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BeneDropProof"}}}},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/control/benedrop/{id}/snapshot":{"post":{"tags":["Campaigns"],"summary":"Lock an objective eligibility snapshot (one entry per eligible verified\nbill; no paid/referral/activity multipliers exist anywhere — BBT-026).","operationId":"benedrop_snapshot","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SnapshotResult"}}}},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/control/cms/{slug}/revisions":{"post":{"tags":["Control"],"operationId":"propose_cms","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CmsRevisionInput"}}},"required":true},"responses":{"202":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApprovalRef"}}}}},"security":[{"session":[]}]}},"/control/compliance/countries":{"get":{"tags":["Compliance"],"operationId":"country_launches","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CountryLaunch"}}}}}},"security":[{"session":[]}]}},"/control/compliance/countries/{country}/activation":{"post":{"tags":["Compliance"],"summary":"Country launch checklist: all five sign-offs + a second approver.\nEven when approved, live money still needs the env flag and a compiled,\nreviewed provider adapter (none exists in this build).","operationId":"propose_country","parameters":[{"name":"country","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountryLaunchProposal"}}},"required":true},"responses":{"202":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProposalResult"}}}},"422":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/control/compliance/policies":{"get":{"tags":["Compliance"],"operationId":"policies","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PolicyVersion"}}}}}},"security":[{"session":[]}]},"post":{"tags":["Compliance"],"summary":"Propose a corridor rule version. It has no effect until a DIFFERENT\ncompliance officer approves it with step-up MFA (BB-215, BBT-018).","operationId":"propose_policy","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolicyProposal"}}},"required":true},"responses":{"202":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProposalResult"}}}},"422":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/control/compliance/simulate":{"post":{"tags":["Compliance"],"summary":"Policy simulator: hypothetical payment, no money movement (BB-216).","operationId":"simulate","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationInput"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationResult"}}}}},"security":[{"session":[]}]}},"/control/emergency/payment-resume":{"post":{"tags":["Control"],"summary":"Resuming payments always needs a second person (approval).","operationId":"payment_resume","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReasonBody"}}},"required":true},"responses":{"202":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApprovalRef"}}}}},"security":[{"session":[]}]}},"/control/emergency/payment-stop":{"post":{"tags":["Control"],"summary":"Emergency stop: one authorised operator can halt NEW payment sessions\nimmediately (fail closed, BB-157, BB-QA-24). Browsing keeps working.","operationId":"payment_stop","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReasonBody"}}},"required":true},"responses":{"204":{"description":""}},"security":[{"session":[]}]}},"/control/flags":{"get":{"tags":["Control"],"operationId":"flags","responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlagsResponse"}}}}},"security":[{"session":[]}]}},"/control/flags/{key}":{"post":{"tags":["Control"],"operationId":"propose_flag","parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlagChange"}}},"required":true},"responses":{"202":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApprovalRef"}}}}},"security":[{"session":[]}]}},"/control/identity/{user_id}/unmask":{"post":{"tags":["Control"],"summary":"Unmask private identity: compliance role + purpose + reason + step-up\nMFA, always logged (BB-195, BBT-039).","operationId":"unmask_identity","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnmaskRequest"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnmaskedIdentity"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/control/incidents":{"get":{"tags":["Control"],"operationId":"incidents","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/IncidentView"}}}}}},"security":[{"session":[]}]},"post":{"tags":["Control"],"operationId":"open_incident","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewIncident"}}},"required":true},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IncidentView"}}}}},"security":[{"session":[]}]}},"/control/incidents/{id}/events":{"post":{"tags":["Control"],"operationId":"incident_event","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IncidentUpdate"}}},"required":true},"responses":{"204":{"description":""}},"security":[{"session":[]}]}},"/control/moderation/queue":{"get":{"tags":["Control"],"operationId":"moderation_queue","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ModerationItem"}}}}}},"security":[{"session":[]}]}},"/control/moderation/{kind}/{id}/decision":{"post":{"tags":["Control"],"operationId":"moderate","parameters":[{"name":"kind","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModerationDecision"}}},"required":true},"responses":{"204":{"description":""}},"security":[{"session":[]}]}},"/control/overview":{"get":{"tags":["Control"],"operationId":"overview","responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Overview"}}}}},"security":[{"session":[]}]}},"/control/privacy/identity-access-log":{"get":{"tags":["Control"],"operationId":"identity_access_log","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/IdentityAccessRow"}}}}}},"security":[{"session":[]}]}},"/control/privacy/requests":{"get":{"tags":["Control"],"operationId":"privacy_queue","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PrivacyQueueItem"}}}}}},"security":[{"session":[]}]}},"/control/privacy/requests/{id}/transition":{"post":{"tags":["Control"],"summary":"Move a DSR through its lifecycle. Completing a deletion pseudonymises the\naccount and hides public content while legally required financial\nrecords are retained with restricted access (BBT-009, BBT-042).","operationId":"privacy_transition","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrivacyTransition"}}},"required":true},"responses":{"204":{"description":""},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/control/role-grants":{"post":{"tags":["Control"],"summary":"Propose a role grant (maker-checker, BB-151). Privileged roles can only\nbe proposed and approved by superadmins — two different people.","operationId":"propose_role","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleChange"}}},"required":true},"responses":{"202":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApprovalRef"}}}}},"security":[{"session":[]}]}},"/control/role-grants/revoke":{"post":{"tags":["Control"],"summary":"Revoke a role immediately (containment is single-person; audited).","operationId":"revoke_role","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleChange"}}},"required":true},"responses":{"204":{"description":""}},"security":[{"session":[]}]}},"/control/security":{"get":{"tags":["Control"],"operationId":"security","responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SecurityPosture"}}}}},"security":[{"session":[]}]}},"/control/staff":{"get":{"tags":["Control"],"operationId":"staff_list","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/StaffRow"}}}}}},"security":[{"session":[]}]}},"/control/system":{"get":{"tags":["Control"],"operationId":"system","responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SystemHealth"}}}}},"security":[{"session":[]}]}},"/control/users":{"get":{"tags":["Control"],"summary":"Masked user directory (no emails or legal names).","operationId":"users","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":["string","null"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/UserRow"}}}}}},"security":[{"session":[]}]}},"/control/users/{id}/reactivate":{"post":{"tags":["Control"],"operationId":"reactivate_user","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReasonBody"}}},"required":true},"responses":{"202":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApprovalRef"}}}}},"security":[{"session":[]}]}},"/control/users/{id}/suspend":{"post":{"tags":["Control"],"summary":"Suspend immediately (containment) and revoke sessions.","operationId":"suspend_user","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReasonBody"}}},"required":true},"responses":{"204":{"description":""}},"security":[{"session":[]}]}},"/demo-psp/sessions/{session_id}":{"get":{"tags":["Demo"],"summary":"DEMO PSP: hosted checkout page data. Session ids are unguessable.","operationId":"demo_session","parameters":[{"name":"session_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DemoCheckoutSession"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{}]}},"/demo-psp/sessions/{session_id}/complete":{"post":{"tags":["Demo"],"summary":"DEMO PSP: simulate the donor approving/declining at the provider. The\nprovider then sends signed webhooks; the return URL never asserts success.","operationId":"demo_complete","parameters":[{"name":"session_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DemoComplete"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DemoCompleteResult"}}}}},"security":[{}]}},"/demo/access":{"get":{"tags":["Demo"],"summary":"Whether this browser may use the demo sign-in helpers. Demo only.","operationId":"access_status","responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DemoAccessStatus"}}}}},"security":[{}]},"post":{"tags":["Demo"],"summary":"Unlock the demo sign-in helpers for this browser with the shared access\ncode (DEMO_ACCESS=code). Ten attempts per hour per address.","operationId":"unlock","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DemoAccessRequest"}}},"required":true},"responses":{"204":{"description":""},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{}]}},"/demo/mailbox":{"get":{"tags":["Demo"],"summary":"Demo mailbox for an address (sign-in links land here; nothing is sent).","operationId":"mailbox","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/DemoMail"}}}}}},"security":[{}]}},"/demo/personas":{"get":{"tags":["Demo"],"operationId":"personas","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PersonaView"}}}}}},"security":[{}]}},"/demo/personas/{key}/login":{"post":{"tags":["Demo"],"summary":"Sign in as a fictional demo persona. Staff personas still have to pass\nreal TOTP MFA afterwards.","operationId":"persona_login","parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignInResponse"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{}]}},"/demo/personas/{key}/totp":{"get":{"tags":["Demo"],"summary":"Current TOTP code for a demo staff persona's seeded authenticator, so the\nreal MFA path can be exercised without a phone. Demo only.","operationId":"persona_totp","parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DemoTotp"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{}]}},"/discovery/bills":{"get":{"tags":["Discovery"],"summary":"Sanitised, verified public bills with keyset pagination.","operationId":"list_bills","parameters":[{"name":"category","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"country","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"currency","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"max_remaining_minor","in":"query","description":"Only bills whose remaining need is at most this (same currency).","required":false,"schema":{"type":["integer","null"],"format":"int64"}},{"name":"sort","in":"query","description":"`due_soon` (default, transparent rule) or `newest`.","required":false,"schema":{"type":["string","null"]}},{"name":"exclude_skipped","in":"query","required":false,"schema":{"type":["boolean","null"]}},{"name":"cursor","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"limit","in":"query","required":false,"schema":{"type":["integer","null"],"format":"int64"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillPage"}}}}},"security":[{}]}},"/discovery/bills/{id}":{"get":{"tags":["Discovery"],"operationId":"bill_detail","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicBillDetail"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{}]}},"/discovery/bills/{id}/report":{"post":{"tags":["Discovery"],"summary":"Report a suspicious card (BB-024). Reporter identity stays private.","operationId":"report_bill","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportRequest"}}},"required":true},"responses":{"202":{"description":""},"429":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{}]}},"/eligibility/check":{"get":{"tags":["Meta"],"summary":"Privacy-friendly eligibility checker (no account required).","operationId":"eligibility_check","parameters":[{"name":"country","in":"query","required":true,"schema":{"type":"string"}},{"name":"category","in":"query","required":true,"schema":{"type":"string"}},{"name":"currency","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EligibilityResult"}}}}},"security":[{}]}},"/me":{"get":{"tags":["Me"],"operationId":"me","responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/me/achievements":{"get":{"tags":["Me"],"summary":"Opt-in cosmetic achievements only (BB-239): no odds, no money, no pressure.","operationId":"achievements","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Achievement"}}}}}},"security":[{"session":[]}]}},"/me/circles":{"get":{"tags":["Campaigns"],"operationId":"my_circles","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MyCircle"}}}}}},"security":[{"session":[]}]}},"/me/consents":{"get":{"tags":["Me"],"operationId":"consents","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ConsentView"}}}}}},"security":[{"session":[]}]},"post":{"tags":["Me"],"summary":"Record a consent (unbundled, versioned; withdrawal is a new record).","operationId":"record_consent","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsentChange"}}},"required":true},"responses":{"201":{"description":""}},"security":[{"session":[]}]}},"/me/contributions":{"get":{"tags":["Me"],"operationId":"my_contributions","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Contribution"}}}}}},"security":[{"session":[]}]}},"/me/contributions/{id}":{"get":{"tags":["Me"],"operationId":"receipt","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Receipt"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/me/contributions/{id}/public-visibility":{"patch":{"tags":["Me"],"summary":"Change PUBLIC visibility of a past contribution (BB-196). The recipient\nsnapshot and legal records are unchanged.","operationId":"change_visibility","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisibilityChange"}}},"required":true},"responses":{"204":{"description":""},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/me/impact":{"get":{"tags":["Me"],"summary":"Donor overview with status-separated truthful totals (BB-117, BB-123).","operationId":"my_impact","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ImpactSummary"}}}}}},"security":[{"session":[]}]}},"/me/notifications":{"get":{"tags":["Me"],"operationId":"notifications","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/NotificationView"}}}}}},"security":[{"session":[]}]}},"/me/notifications/read-all":{"post":{"tags":["Me"],"operationId":"read_all","responses":{"204":{"description":""}},"security":[{"session":[]}]}},"/me/onboarding":{"post":{"tags":["Me"],"operationId":"onboarding","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Onboarding"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}}},"security":[{"session":[]}]}},"/me/orgs":{"get":{"tags":["Organizations"],"operationId":"my_orgs","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/OrgView"}}}}}},"security":[{"session":[]}]}},"/me/passkeys":{"get":{"tags":["Me"],"summary":"The signed-in member's passkeys.","operationId":"list_passkeys","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PasskeyView"}}}}}},"security":[{"session":[]}]}},"/me/passkeys/{id}":{"delete":{"tags":["Me"],"summary":"Remove one of the member's passkeys (recent sign-in or step-up required).","operationId":"remove_passkey","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":""},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/me/privacy":{"get":{"tags":["Me"],"operationId":"privacy","responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrivacyCenter"}}}}},"security":[{"session":[]}]},"put":{"tags":["Me"],"summary":"Update future defaults only; past per-payment snapshots never change.","operationId":"update_privacy","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrivacySettings"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrivacyCenter"}}}}},"security":[{"session":[]}]}},"/me/privacy-export":{"get":{"tags":["Me"],"summary":"Machine-readable export of the member's OWN data (BB-013, BBT-010).\nRequires a recent sign-in or MFA step-up. Excludes other users'\nidentities and internal risk rules.","operationId":"privacy_export","responses":{"200":{"description":"JSON export attachment"},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/me/privacy-requests":{"get":{"tags":["Me"],"operationId":"privacy_requests","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PrivacyRequestView"}}}}}},"security":[{"session":[]}]},"post":{"tags":["Me"],"operationId":"create_privacy_request","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrivacyRequestInput"}}},"required":true},"responses":{"202":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrivacyRequestView"}}}}},"security":[{"session":[]}]}},"/me/saved-bills":{"get":{"tags":["Discovery"],"operationId":"saved_bills","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicBill"}}}}}},"security":[{"session":[]}]},"post":{"tags":["Discovery"],"summary":"Save a bill (right-swipe intent). Never creates a payment (BB-076).","operationId":"save_bill","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntentRequest"}}},"required":true},"responses":{"204":{"description":""}},"security":[{"session":[]}]}},"/me/saved-bills/{bill_id}":{"delete":{"tags":["Discovery"],"operationId":"unsave_bill","parameters":[{"name":"bill_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":""}},"security":[{"session":[]}]}},"/me/sessions":{"get":{"tags":["Me"],"operationId":"sessions","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SessionView"}}}}}},"security":[{"session":[]}]}},"/me/sessions/{id}":{"delete":{"tags":["Me"],"operationId":"revoke_session","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":""}},"security":[{"session":[]}]}},"/me/skipped-bills":{"post":{"tags":["Discovery"],"summary":"Skip a bill (left swipe) — reversible with undo.","operationId":"skip_bill","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntentRequest"}}},"required":true},"responses":{"204":{"description":""}},"security":[{"session":[]}]}},"/me/skipped-bills/{bill_id}":{"delete":{"tags":["Discovery"],"operationId":"unskip_bill","parameters":[{"name":"bill_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":""}},"security":[{"session":[]}]}},"/me/verification/demo":{"post":{"tags":["Me"],"summary":"DEMO ONLY: simulate an identity-provider result (verified residence,\nadult, basic tier). Real KYC uses a vetted provider handoff; raw ID\ndocuments are never stored by BillBene (BB-059).","operationId":"demo_kyc","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DemoKyc"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/meta/categories":{"get":{"tags":["Meta"],"operationId":"categories","responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoriesResponse"}}}}},"security":[{}]}},"/meta/countries":{"get":{"tags":["Meta"],"summary":"Countries with an ACTIVE approved corridor rule in this environment.","operationId":"countries","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CountryMeta"}}}}}},"security":[{}]}},"/meta/currencies":{"get":{"tags":["Meta"],"operationId":"currencies","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CurrencyMeta"}}}}}},"security":[{}]}},"/meta/impact":{"get":{"tags":["Meta"],"summary":"True metrics only, per currency, with environment label (BB-026).","operationId":"public_impact","responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicImpact"}}}}},"security":[{}]}},"/meta/mode":{"get":{"tags":["Meta"],"operationId":"mode","responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModeInfo"}}}}},"security":[{}]}},"/mystery/select":{"post":{"tags":["Campaigns"],"operationId":"mystery_select","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MysteryRequest"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MysterySelection"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/mystery/{id}/decision":{"post":{"tags":["Campaigns"],"operationId":"mystery_decide","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MysteryDecision"}}},"required":true},"responses":{"204":{"description":""}},"security":[{"session":[]}]}},"/orgs":{"post":{"tags":["Organizations"],"operationId":"create_org","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewOrg"}}},"required":true},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgView"}}}}},"security":[{"session":[]}]}},"/orgs/invites/accept":{"post":{"tags":["Organizations"],"summary":"Accept an invite. The signed-in account's verified email must match.","operationId":"accept_invite","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptInvite"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgView"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/orgs/{id}":{"get":{"tags":["Organizations"],"operationId":"get_org","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgView"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/orgs/{id}/budgets":{"get":{"tags":["Organizations"],"operationId":"budgets","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BudgetView"}}}}}},"security":[{"session":[]}]},"post":{"tags":["Organizations"],"summary":"Propose a budget; a different owner/approver must approve (BB-133).","operationId":"propose_budget","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewBudget"}}},"required":true},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BudgetView"}}}}},"security":[{"session":[]}]}},"/orgs/{id}/budgets/{budget_id}/approve":{"post":{"tags":["Organizations"],"operationId":"approve_budget","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"budget_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":""},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/orgs/{id}/campaigns":{"get":{"tags":["Organizations"],"operationId":"campaigns","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/OrgCampaign"}}}}}},"security":[{"session":[]}]},"post":{"tags":["Organizations"],"summary":"Draft a sponsor campaign and submit it for platform approval. Requires a\nKYB-verified organization; BeneDrop additionally needs legal sign-off.","operationId":"create_campaign","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewCampaign"}}},"required":true},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgCampaign"}}}},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/orgs/{id}/invites":{"post":{"tags":["Organizations"],"operationId":"invite","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteMember"}}},"required":true},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgInviteCreated"}}}}},"security":[{"session":[]}]}},"/orgs/{id}/members":{"get":{"tags":["Organizations"],"operationId":"members","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MemberView"}}}}}},"security":[{"session":[]}]}},"/orgs/{id}/members/{user_id}":{"patch":{"tags":["Organizations"],"summary":"Owners manage roles; nobody can escalate themselves (BB-130).","operationId":"update_member","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"user_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleUpdate"}}},"required":true},"responses":{"204":{"description":""},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/orgs/{id}/reports":{"get":{"tags":["Organizations"],"summary":"Privacy-safe aggregate report: no donor or requester identities.","operationId":"report","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgReport"}}}}},"security":[{"session":[]}]}},"/requests":{"get":{"tags":["Requests"],"operationId":"list_requests","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RequestSummary"}}}}}},"security":[{"session":[]}]},"post":{"tags":["Requests"],"operationId":"create_draft","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DraftInput"}}},"required":true},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequesterBill"}}}},"422":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/requests/{id}":{"get":{"tags":["Requests"],"operationId":"get_request","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequesterBill"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]},"patch":{"tags":["Requests"],"summary":"Edit the mutable draft (optimistic concurrency via `If-Match: <draft_revision>`).\nApproved/published snapshots are never edited in place (BB-045).","operationId":"update_draft","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"If-Match","in":"header","required":false,"schema":{"type":["string","null"]}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DraftInput"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequesterBill"}}}},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/requests/{id}/appeals":{"post":{"tags":["Requests"],"operationId":"appeal","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppealRequest"}}},"required":true},"responses":{"201":{"description":""},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/requests/{id}/contributions":{"get":{"tags":["Requests"],"summary":"Recipient view built from an explicit allowlist (BB-192, BBT-001/002).","operationId":"recipient_contributions","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RecipientContribution"}}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/requests/{id}/contributions/{contribution_id}/block":{"post":{"tags":["Requests"],"summary":"Block further notes from the supporter behind this contribution and\nreport it — without learning who they are (BB-203).","operationId":"block_sender","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"contribution_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlockRequest"}}},"required":true},"responses":{"204":{"description":""}},"security":[{"session":[]}]}},"/requests/{id}/contributions/{contribution_id}/thanks":{"post":{"tags":["Requests"],"summary":"Mediated thank-you (BB-201, BBT-007/038): no contact details either way.","operationId":"send_thanks","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"contribution_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThanksRequest"}}},"required":true},"responses":{"202":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThanksResult"}}}},"422":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/requests/{id}/evidence":{"post":{"tags":["Requests"],"summary":"Upload private evidence (PDF/PNG/JPEG). Content is sniffed from bytes,\nencrypted at rest and quarantined until scanned (BB-039, BB-171).","operationId":"upload_evidence","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"description":"Field `file`","content":{"multipart/form-data":{"schema":{"type":"string"}}},"required":true},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvidenceView"}}}},"413":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/requests/{id}/evidence/sample":{"post":{"tags":["Requests"],"summary":"Attach the built-in fictional sample bill (demo mode only). Public demos\naccept nothing else (`DEMO_UPLOADS=samples`), so no real financial\ndocument is ever stored there; it still goes through encryption, the scan\nand review like any upload.","operationId":"upload_sample_evidence","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvidenceView"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/requests/{id}/evidence/{evidence_id}":{"get":{"tags":["Requests"],"summary":"Owner download of their own CLEAN document, as an attachment, logged.","operationId":"download_own_evidence","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"evidence_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"File bytes (attachment)"},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/requests/{id}/stories":{"post":{"tags":["Requests"],"summary":"Opt-in BeneStory after biller confirmation; always human-moderated.","operationId":"submit_story","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoryRequest"}}},"required":true},"responses":{"202":{"description":""},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/requests/{id}/submit":{"post":{"tags":["Requests"],"summary":"Submit: snapshot the draft immutably, run deterministic checks and queue\nfor human review. Never auto-publishes (BB-043, BB-061).","operationId":"submit","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequesterBill"}}}},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/requests/{id}/timeline":{"get":{"tags":["Requests"],"operationId":"timeline","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TimelineEvent"}}}}}},"security":[{"session":[]}]}},"/requests/{id}/withdraw":{"post":{"tags":["Requests"],"summary":"Withdraw. Money already captured is never silently erased (BB-049).","operationId":"withdraw","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequesterBill"}}}},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/staff/appeals":{"get":{"tags":["Reviews"],"operationId":"appeals","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AppealView"}}}}}},"security":[{"session":[]}]}},"/staff/appeals/{id}/decision":{"post":{"tags":["Reviews"],"operationId":"decide_appeal","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppealDecision"}}},"required":true},"responses":{"204":{"description":""},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/staff/finance/allocations/{id}/simulate-biller-confirmation":{"post":{"tags":["Finance"],"summary":"DEMO ONLY: the fake biller partner confirms application of an allocation\nthrough the real signed partner-webhook path.","operationId":"simulate_biller","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulateBillerRequest"}}},"required":true},"responses":{"202":{"description":"","content":{"text/plain":{"schema":{"type":"string"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/staff/finance/events":{"get":{"tags":["Finance"],"operationId":"events","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":["string","null"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/EventSummary"}}}}}},"security":[{"session":[]}]}},"/staff/finance/events/{id}/retry":{"post":{"tags":["Finance"],"operationId":"retry_event","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"","content":{"text/plain":{"schema":{"type":"string"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/staff/finance/exceptions":{"get":{"tags":["Finance"],"operationId":"exceptions","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":["string","null"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ExceptionView"}}}}}},"security":[{"session":[]}]}},"/staff/finance/exceptions/{id}/resolve":{"post":{"tags":["Finance"],"summary":"Resolve an exception record. This changes only the case status; any\nmoney correction must be a separate appended journal (no overwrite).","operationId":"resolve_exception","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolveRequest"}}},"required":true},"responses":{"204":{"description":""},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/staff/finance/payments":{"get":{"tags":["Finance"],"operationId":"payments","parameters":[{"name":"state","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"limit","in":"query","required":false,"schema":{"type":["integer","null"],"format":"int64"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/FinancePaymentRow"}}}}}},"security":[{"session":[]}]}},"/staff/finance/payments/{id}":{"get":{"tags":["Finance"],"operationId":"payment_detail","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinancePaymentDetail"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/staff/finance/payments/{id}/simulate":{"post":{"tags":["Finance"],"summary":"DEMO ONLY: inject adversarial provider behaviour through the real\nwebhook path to demonstrate the controls (replay, forgery, ordering).","operationId":"simulate_scenario","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulateRequest"}}},"required":true},"responses":{"200":{"description":"","content":{"text/plain":{"schema":{"type":"string"}}}}},"security":[{"session":[]}]}},"/staff/finance/reconciliation/runs":{"get":{"tags":["Finance"],"operationId":"list_runs","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ReconRun"}}}}}},"security":[{"session":[]}]},"post":{"tags":["Finance"],"operationId":"start_reconciliation","responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReconRun"}}}}},"security":[{"session":[]}]}},"/staff/finance/refunds":{"get":{"tags":["Finance"],"operationId":"list_refunds","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":["string","null"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RefundView"}}}}}},"security":[{"session":[]}]}},"/staff/finance/refunds/proposals":{"post":{"tags":["Finance"],"summary":"Propose a refund. Support agents may only propose (BB-QA-11); finance\napproval by a different operator is always required (BB-QA-12).","operationId":"propose_refund","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundProposal"}}},"required":true},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundView"}}}},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/staff/finance/refunds/{id}/approve":{"post":{"tags":["Finance"],"summary":"Approve a refund proposal: different finance operator + step-up MFA.","operationId":"approve_refund","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundView"}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/staff/finance/refunds/{id}/reject":{"post":{"tags":["Finance"],"operationId":"reject_refund","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolveRequest"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundView"}}}}},"security":[{"session":[]}]}},"/staff/finance/summary":{"get":{"tags":["Finance"],"operationId":"summary","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CurrencySummary"}}}}}},"security":[{"session":[]}]}},"/staff/finance/trial-balance":{"get":{"tags":["Finance"],"operationId":"trial_balance","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TrialBalanceRow"}}}}}},"security":[{"session":[]}]}},"/staff/reports":{"get":{"tags":["Risk"],"operationId":"reports","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ReportView"}}}}}},"security":[{"session":[]}]}},"/staff/reports/{id}/resolve":{"post":{"tags":["Risk"],"operationId":"resolve_report","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolveReport"}}},"required":true},"responses":{"204":{"description":""}},"security":[{"session":[]}]}},"/staff/reviews":{"get":{"tags":["Reviews"],"operationId":"review_queue","parameters":[{"name":"scope","in":"query","description":"`queue` (default) or `mine`.","required":false,"schema":{"type":["string","null"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ReviewQueueItem"}}}}}},"security":[{"session":[]}]}},"/staff/reviews/{case_id}":{"get":{"tags":["Reviews"],"summary":"Case detail — only for the reviewer currently holding the assignment.","operationId":"detail","parameters":[{"name":"case_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaseDetail"}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/staff/reviews/{case_id}/claim":{"post":{"tags":["Reviews"],"operationId":"claim","parameters":[{"name":"case_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":""},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/staff/reviews/{case_id}/decision":{"post":{"tags":["Reviews"],"summary":"Record a decision bound to the snapshot version (BB-061). High-risk cases\nneed two independent approvals (BB-063). Self-review is impossible.","operationId":"decide","parameters":[{"name":"case_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecisionRequest"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecisionResult"}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/staff/reviews/{case_id}/evidence/{evidence_id}":{"get":{"tags":["Reviews"],"summary":"Secure evidence view for the assigned reviewer (BB-058).","operationId":"evidence","parameters":[{"name":"case_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"evidence_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"purpose","in":"query","description":"Required access purpose, recorded in the evidence access ledger.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"File (attachment)"},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/staff/reviews/{case_id}/release":{"post":{"tags":["Reviews"],"operationId":"release","parameters":[{"name":"case_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":""}},"security":[{"session":[]}]}},"/staff/reviews/{case_id}/reveal-reference":{"post":{"tags":["Reviews"],"summary":"Unmask the biller reference for verification against the biller, with\nreason + audit (never shown on public cards).","operationId":"reveal_reference","parameters":[{"name":"case_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevealRequest"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevealedReference"}}}}},"security":[{"session":[]}]}},"/staff/risk/cases":{"get":{"tags":["Risk"],"operationId":"cases","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":["string","null"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RiskCase"}}}}}},"security":[{"session":[]}]},"post":{"tags":["Risk"],"operationId":"open_case","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewCase"}}},"required":true},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskCase"}}}}},"security":[{"session":[]}]}},"/staff/risk/cases/{id}/hold":{"post":{"tags":["Risk"],"summary":"Freeze a bill immediately (BB-065): new payment sessions are denied at\nonce; browsing elsewhere continues.","operationId":"hold","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReasonBody"}}},"required":true},"responses":{"204":{"description":""}},"security":[{"session":[]}]}},"/staff/risk/cases/{id}/release":{"post":{"tags":["Risk"],"summary":"Request release of a freeze — executes only after a second person\napproves in the control console (maker-checker).","operationId":"request_release","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReasonBody"}}},"required":true},"responses":{"202":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApprovalCreated"}}}}},"security":[{"session":[]}]}},"/staff/risk/signals":{"get":{"tags":["Risk"],"operationId":"signals","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RiskSignal"}}}}}},"security":[{"session":[]}]}},"/staff/support/tickets":{"get":{"tags":["Support"],"operationId":"support_queue","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":["string","null"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TicketSummary"}}}}}},"security":[{"session":[]}]}},"/staff/support/tickets/{id}":{"get":{"tags":["Support"],"operationId":"staff_ticket","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketDetail"}}}}},"security":[{"session":[]}]}},"/staff/support/tickets/{id}/messages":{"post":{"tags":["Support"],"operationId":"staff_reply","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewMessage"}}},"required":true},"responses":{"201":{"description":""}},"security":[{"session":[]}]}},"/staff/support/tickets/{id}/status":{"post":{"tags":["Support"],"operationId":"set_status","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusChange"}}},"required":true},"responses":{"204":{"description":""}},"security":[{"session":[]}]}},"/stories":{"get":{"tags":["Meta"],"operationId":"stories","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicStory"}}}}}},"security":[{}]}},"/support/tickets":{"get":{"tags":["Support"],"operationId":"my_tickets","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TicketSummary"}}}}}},"security":[{"session":[]}]},"post":{"tags":["Support"],"operationId":"create_ticket","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewTicket"}}},"required":true},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketSummary"}}}}},"security":[{"session":[]}]}},"/support/tickets/{id}":{"get":{"tags":["Support"],"operationId":"my_ticket","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketDetail"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"session":[]}]}},"/support/tickets/{id}/messages":{"post":{"tags":["Support"],"operationId":"reply","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewMessage"}}},"required":true},"responses":{"201":{"description":""}},"security":[{"session":[]}]}},"/webhooks/partners/{partner}":{"post":{"tags":["Webhooks"],"summary":"Biller / partner webhook (signed with the partner secret).","operationId":"partner_webhook","parameters":[{"name":"partner","in":"path","description":"Partner key","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Raw signed partner event","content":{"application/json":{"schema":{"type":"string"}}},"required":true},"responses":{"202":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookAck"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/webhooks/payments/{provider}":{"post":{"tags":["Webhooks"],"summary":"Payment provider webhook (raw signed body).","operationId":"payment_webhook","parameters":[{"name":"provider","in":"path","description":"Provider key","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Raw signed provider event","content":{"application/json":{"schema":{"type":"string"}}},"required":true},"responses":{"202":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookAck"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}},"components":{"schemas":{"AcceptInvite":{"type":"object","required":["token"],"properties":{"token":{"type":"string"}}},"AcceptedMessage":{"type":"object","required":["message","demo_mailbox"],"properties":{"message":{"type":"string"},"demo_mailbox":{"type":"boolean","description":"True only in demo mode, where emails go to the demo mailbox."}}},"Achievement":{"type":"object","required":["key","label"],"properties":{"key":{"type":"string"},"label":{"type":"string"},"earned_at":{"type":["string","null"],"format":"date"}}},"AddLine":{"type":"object","required":["bill_id","amount_minor"],"properties":{"bill_id":{"type":"string","format":"uuid"},"amount_minor":{"type":"integer","format":"int64"}}},"AllocationState":{"type":"string","description":"Allocation of captured funds to a bill (independent of payment state).","enum":["captured_unsettled","biller_processing","partial_applied","fully_applied","refund_pending","reversed","exception"]},"AppealDecision":{"type":"object","required":["outcome","reason"],"properties":{"outcome":{"type":"string","description":"`uphold` keeps the rejection; `overturn` reopens review."},"reason":{"type":"string"}}},"AppealRequest":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string"}}},"AppealView":{"type":"object","required":["id","bill_id","reason","status","created_at","i_made_original_decision"],"properties":{"id":{"type":"string","format":"uuid"},"bill_id":{"type":"string","format":"uuid"},"reason":{"type":"string"},"status":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"i_made_original_decision":{"type":"boolean"}}},"ApprovalCreated":{"type":"object","required":["approval_id","status"],"properties":{"approval_id":{"type":"string","format":"uuid"},"status":{"type":"string"}}},"ApprovalDecision":{"type":"object","required":["approve","note"],"properties":{"approve":{"type":"boolean"},"note":{"type":"string"}}},"ApprovalRef":{"type":"object","required":["approval_id","status"],"properties":{"approval_id":{"type":"string","format":"uuid"},"status":{"type":"string"}}},"ApprovalView":{"type":"object","required":["id","kind","payload","reason","status","proposed_by_me","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string"},"target_id":{"type":["string","null"],"format":"uuid"},"payload":{},"reason":{"type":"string"},"status":{"type":"string"},"proposed_by_me":{"type":"boolean"},"decision_note":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}}},"AttemptView":{"type":"object","required":["id","bill_id","state","environment","currency","amount_minor","fee_minor","tip_minor","total_minor","refunded_minor","biller_applied_minor","status_label","is_demo","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"bill_id":{"type":"string","format":"uuid"},"state":{"$ref":"#/components/schemas/PaymentState"},"environment":{"type":"string"},"currency":{"type":"string"},"amount_minor":{"type":"integer","format":"int64"},"fee_minor":{"type":"integer","format":"int64"},"tip_minor":{"type":"integer","format":"int64"},"total_minor":{"type":"integer","format":"int64"},"refunded_minor":{"type":"integer","format":"int64"},"hosted_checkout_url":{"type":["string","null"]},"allocation_state":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/AllocationState"}]},"biller_applied_minor":{"type":"integer","format":"int64"},"status_label":{"type":"string","description":"Truthful, state-derived label (never \"bill paid\" on capture)."},"is_demo":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"AuditRow":{"type":"object","required":["seq","id","actor_roles","action","resource_type","metadata","recorded_at","mac_valid"],"properties":{"seq":{"type":"integer","format":"int64"},"id":{"type":"string","format":"uuid"},"actor_id":{"type":["string","null"],"format":"uuid"},"actor_roles":{"type":"array","items":{"type":"string"}},"action":{"type":"string"},"resource_type":{"type":"string"},"resource_id":{"type":["string","null"],"format":"uuid"},"reason":{"type":["string","null"]},"request_id":{"type":["string","null"]},"metadata":{},"recorded_at":{"type":"string","format":"date-time"},"mac_valid":{"type":"boolean","description":"Tamper evidence: recomputed HMAC matches the stored one."}}},"Basket":{"type":"object","required":["lines","totals","checkout_mode"],"properties":{"lines":{"type":"array","items":{"$ref":"#/components/schemas/BasketLine"}},"totals":{"type":"array","items":{"$ref":"#/components/schemas/CurrencyTotal"},"description":"Per-currency totals; currencies are never summed together."},"checkout_mode":{"type":"string"}}},"BasketLine":{"type":"object","required":["id","bill_id","currency","amount_minor","available_minor","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"bill_id":{"type":"string","format":"uuid"},"title":{"type":["string","null"]},"category":{"type":["string","null"]},"public_alias":{"type":["string","null"]},"currency":{"type":"string"},"amount_minor":{"type":"integer","format":"int64"},"available_minor":{"type":"integer","format":"int64"},"stale_reason":{"type":["string","null"],"description":"`bill_unavailable`, `snapshot_changed`, `amount_exceeds_available`, or null."},"updated_at":{"type":"string","format":"date-time"}}},"BeneDropProof":{"type":"object","required":["campaign_id","campaign_name","status","demo_only","legal_gate","verification"],"properties":{"campaign_id":{"type":"string","format":"uuid"},"campaign_name":{"type":"string"},"status":{"type":"string"},"demo_only":{"type":"boolean","description":"Always true in this build: live random selection is legally gated."},"legal_gate":{"type":"string"},"pool_size":{"type":["integer","null"],"format":"int32"},"candidate_set_hash":{"type":["string","null"]},"seed_commitment":{"type":["string","null"]},"revealed_seed":{"type":["string","null"]},"selected_index":{"type":["integer","null"],"format":"int32"},"selected_bill":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/PublicBill","description":"Public card of the selected bill, only if it is publicly listed."}]},"verification":{"type":"string"}}},"BillPage":{"type":"object","required":["items","ordering_rule"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PublicBill"}},"next_cursor":{"type":["string","null"]},"ordering_rule":{"type":"string","description":"Plain-language description of the ordering rule (BB-029)."}}},"BillerConfirmationView":{"type":"object","required":["id","partner","applied_minor","currency","confirmed_at","provenance_ref"],"properties":{"id":{"type":"string","format":"uuid"},"partner":{"type":"string"},"applied_minor":{"type":"integer","format":"int64"},"currency":{"type":"string"},"confirmed_at":{"type":"string","format":"date-time"},"provenance_ref":{"type":"string"}}},"BlockRequest":{"type":"object","properties":{"reason":{"type":["string","null"]}}},"BudgetView":{"type":"object","required":["id","currency","amount_minor","period_start","period_end","status","proposed_by_me"],"properties":{"id":{"type":"string","format":"uuid"},"currency":{"type":"string"},"amount_minor":{"type":"integer","format":"int64"},"period_start":{"type":"string","format":"date"},"period_end":{"type":"string","format":"date"},"category":{"type":["string","null"]},"status":{"type":"string"},"proposed_by_me":{"type":"boolean"}}},"Cap":{"type":"object","required":["kind","window","currency","amount_minor","source"],"properties":{"kind":{"$ref":"#/components/schemas/CapKind"},"window":{"$ref":"#/components/schemas/CapWindow"},"currency":{"type":"string"},"amount_minor":{"type":"integer","format":"int64"},"source":{"type":"string","description":"Evidence/source for this cap (document reference, contract clause)."},"applies_below_tier":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/KycTier","description":"Identity-tier caps apply only when the donor tier is below this tier."}]}}},"CapKind":{"type":"string","enum":["legal","provider","product_risk","identity_tier"]},"CapWindow":{"type":"string","enum":["per_transaction","rolling24h","rolling30d"]},"CaseDetail":{"type":"object","required":["case_id","bill_id","status","snapshot_version","high_risk","high_risk_reasons","first_approval_given","assigned_to_me","category","country_code","currency","total_minor","due_date","biller_name","biller_reference_masked","public_title","public_alias","public_story","show_location","sensitive_flags","requester_alias","requester_account_age_days","requester_prior_requests","evidence","signals","decisions","checklist_items"],"properties":{"case_id":{"type":"string","format":"uuid"},"bill_id":{"type":"string","format":"uuid"},"status":{"type":"string"},"snapshot_version":{"type":"integer","format":"int32"},"high_risk":{"type":"boolean"},"high_risk_reasons":{"type":"array","items":{"type":"string"}},"first_approval_given":{"type":"boolean"},"assigned_to_me":{"type":"boolean"},"category":{"type":"string"},"country_code":{"type":"string"},"currency":{"type":"string"},"total_minor":{"type":"integer","format":"int64"},"due_date":{"type":"string","format":"date"},"biller_name":{"type":"string"},"biller_reference_masked":{"type":"string"},"public_title":{"type":"string"},"public_alias":{"type":"string"},"public_story":{"type":"string"},"location_coarse":{"type":["string","null"]},"show_location":{"type":"boolean"},"sensitive_flags":{"type":"array","items":{"type":"string"}},"requester_alias":{"type":"string"},"requester_account_age_days":{"type":"integer","format":"int64"},"requester_prior_requests":{"type":"integer","format":"int64"},"evidence":{"type":"array","items":{"$ref":"#/components/schemas/EvidenceMeta"}},"signals":{"type":"array","items":{"$ref":"#/components/schemas/SignalView"}},"decisions":{"type":"array","items":{"$ref":"#/components/schemas/DecisionView"}},"checklist_items":{"type":"array","items":{"type":"string"}}}},"CategoriesResponse":{"type":"object","required":["categories","excluded"],"properties":{"categories":{"type":"array","items":{"$ref":"#/components/schemas/CategoryInfo"}},"excluded":{"type":"array","items":{"type":"string"},"description":"Never payable on BillBene (loans, credit cards, gambling, …)."}}},"CategoryInfo":{"type":"object","required":["key","label","description","sensitive"],"properties":{"key":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"},"sensitive":{"type":"boolean","description":"Sensitive categories get enhanced review, redaction and consent."}}},"CircleMemberView":{"type":"object","required":["public_alias","role"],"properties":{"public_alias":{"type":"string"},"role":{"type":"string"}}},"CircleView":{"type":"object","required":["id","name","status","my_role","bill","members","circle_captured_minor","circle_contributions"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"string"},"my_role":{"type":"string"},"bill":{"$ref":"#/components/schemas/PublicBill"},"members":{"type":"array","items":{"$ref":"#/components/schemas/CircleMemberView"}},"circle_captured_minor":{"type":"integer","format":"int64","description":"Aggregate of provider-confirmed contributions made through the circle."},"circle_contributions":{"type":"integer","format":"int64"}}},"CmsDocument":{"type":"object","required":["slug","title","version","body_markdown"],"properties":{"slug":{"type":"string"},"title":{"type":"string"},"version":{"type":"integer","format":"int32"},"body_markdown":{"type":"string"},"published_at":{"type":["string","null"],"format":"date-time"}}},"CmsRevisionInput":{"type":"object","required":["body_markdown","reason"],"properties":{"body_markdown":{"type":"string"},"reason":{"type":"string"}}},"CommitResult":{"type":"object","required":["draw_id","seed_commitment","demo_only"],"properties":{"draw_id":{"type":"string","format":"uuid"},"seed_commitment":{"type":"string"},"demo_only":{"type":"boolean"}}},"ConsentChange":{"type":"object","required":["consent_type","granted"],"properties":{"consent_type":{"type":"string","description":"terms | privacy_notice | document_processing | public_story | marketing | donor_message_public | analytics_aggregate"},"granted":{"type":"boolean"}}},"ConsentView":{"type":"object","required":["consent_type","version","granted","recorded_at"],"properties":{"consent_type":{"type":"string"},"version":{"type":"string"},"granted":{"type":"boolean"},"recorded_at":{"type":"string","format":"date-time"}}},"ConsumeRequest":{"type":"object","required":["token"],"properties":{"token":{"type":"string"},"client":{"type":["string","null"],"description":"`web` (cookie session) or `mobile` (bearer token for the Flutter app)."}}},"Contribution":{"type":"object","required":["attempt_id","bill_id","currency","amount_minor","fee_minor","tip_minor","total_minor","refunded_minor","state","biller_applied_minor","status_label","recipient_sees","public_sees","environment","created_at"],"properties":{"attempt_id":{"type":"string","format":"uuid"},"bill_id":{"type":"string","format":"uuid"},"bill_title":{"type":["string","null"]},"bill_category":{"type":["string","null"]},"requester_alias":{"type":["string","null"]},"currency":{"type":"string"},"amount_minor":{"type":"integer","format":"int64"},"fee_minor":{"type":"integer","format":"int64"},"tip_minor":{"type":"integer","format":"int64"},"total_minor":{"type":"integer","format":"int64"},"refunded_minor":{"type":"integer","format":"int64"},"state":{"$ref":"#/components/schemas/PaymentState"},"allocation_state":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/AllocationState"}]},"biller_applied_minor":{"type":"integer","format":"int64"},"status_label":{"type":"string"},"recipient_sees":{"type":"string","description":"What the recipient sees for this payment (immutable snapshot)."},"public_sees":{"type":"string","description":"What the public currently sees (latest retroactive change)."},"note_visibility":{"type":["string","null"]},"note_status":{"type":["string","null"]},"thank_you":{"type":["string","null"]},"environment":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"captured_at":{"type":["string","null"],"format":"date-time"}}},"CorridorRuleBody":{"type":"object","description":"The JSON body stored in `compliance_policy_versions.rule_json`.","required":["categories"],"properties":{"categories":{"type":"array","items":{"type":"string"}},"min_age":{"type":"integer","format":"int32","minimum":0},"kyc_required_above_minor":{"type":["integer","null"],"format":"int64"},"caps":{"type":"array","items":{"$ref":"#/components/schemas/Cap"}},"requires_legal_cap_evidence":{"type":"boolean","description":"When true, a Legal cap with evidence must be present or the corridor\nfails closed (`LEGAL_LIMIT_EVIDENCE_MISSING`)."},"anonymity_supported":{"type":"boolean","description":"Whether the provider/biller route can preserve recipient-facing donor\nanonymity (descriptors, biller records). If false, anonymous checkout\nis blocked before any PSP session (BB-197, BB-212)."},"route_disclosure":{"type":"string","description":"Human-readable route disclosure shown before checkout."},"review_required_categories":{"type":"array","items":{"type":"string"},"description":"Categories that always require human review before payment."},"partial_payments_supported":{"type":"boolean","description":"Whether the biller accepts partial (multi-donor) payments on this route."},"platform_fee_bps":{"type":"integer","format":"int32","description":"Platform fee in basis points (0 unless provider/legal approved).","minimum":0}}},"CountryLaunch":{"type":"object","required":["id","environment","legal_entity_code","country_code","route_type","provider","category","legal_signoff_ref","provider_contract_ref","privacy_signoff_ref","security_signoff_ref","finance_signoff_ref","status","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"environment":{"type":"string"},"legal_entity_code":{"type":"string"},"country_code":{"type":"string"},"route_type":{"type":"string"},"provider":{"type":"string"},"category":{"type":"string"},"legal_signoff_ref":{"type":"string"},"provider_contract_ref":{"type":"string"},"privacy_signoff_ref":{"type":"string"},"security_signoff_ref":{"type":"string"},"finance_signoff_ref":{"type":"string"},"status":{"type":"string"},"effective_until":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"CountryLaunchProposal":{"type":"object","required":["environment","legal_entity_code","route_type","provider","category","legal_signoff_ref","provider_contract_ref","privacy_signoff_ref","security_signoff_ref","finance_signoff_ref"],"properties":{"environment":{"type":"string"},"legal_entity_code":{"type":"string"},"route_type":{"type":"string"},"provider":{"type":"string"},"category":{"type":"string"},"legal_signoff_ref":{"type":"string"},"provider_contract_ref":{"type":"string"},"privacy_signoff_ref":{"type":"string"},"security_signoff_ref":{"type":"string"},"finance_signoff_ref":{"type":"string"},"effective_until":{"type":["string","null"],"format":"date-time"}}},"CountryMeta":{"type":"object","required":["code","name","currency","categories","environment","evidence_ref"],"properties":{"code":{"type":"string"},"name":{"type":"string"},"currency":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}},"environment":{"type":"string","description":"Environment of the approved rule (demo rules are fictional)."},"evidence_ref":{"type":"string"}}},"CreateAttemptRequest":{"type":"object","required":["quote_id","accepted_terms_version"],"properties":{"quote_id":{"type":"string","format":"uuid"},"accepted_terms_version":{"type":"string"}}},"CreateCircle":{"type":"object","required":["bill_id","name"],"properties":{"bill_id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"CreateInvite":{"type":"object","properties":{"role":{"type":["string","null"]},"max_uses":{"type":["integer","null"],"format":"int32"},"ttl_hours":{"type":["integer","null"],"format":"int64"}}},"CurrencyMeta":{"type":"object","required":["code","exponent","name"],"properties":{"code":{"type":"string"},"exponent":{"type":"integer","format":"int32","minimum":0},"name":{"type":"string"}}},"CurrencySummary":{"type":"object","required":["currency","reserved_active_minor","captured_gross_minor","refunded_minor","captured_net_minor","biller_applied_minor","awaiting_biller_minor","open_exceptions"],"properties":{"currency":{"type":"string"},"reserved_active_minor":{"type":"integer","format":"int64"},"captured_gross_minor":{"type":"integer","format":"int64"},"refunded_minor":{"type":"integer","format":"int64"},"captured_net_minor":{"type":"integer","format":"int64"},"biller_applied_minor":{"type":"integer","format":"int64"},"awaiting_biller_minor":{"type":"integer","format":"int64"},"open_exceptions":{"type":"integer","format":"int64"}}},"CurrencyTotal":{"type":"object","required":["currency","amount_minor"],"properties":{"currency":{"type":"string"},"amount_minor":{"type":"integer","format":"int64"}}},"Decision":{"type":"string","enum":["ALLOW","BLOCK","REQUIRES_KYC","REQUIRES_REVIEW","NOT_SUPPORTED","TEMPORARILY_UNAVAILABLE"]},"DecisionRequest":{"type":"object","required":["decision","reason_code","reason","snapshot_version"],"properties":{"decision":{"type":"string","description":"approve | reject | needs_info | escalate"},"reason_code":{"type":"string"},"reason":{"type":"string","description":"Internal rationale (staff only)."},"requester_message":{"type":["string","null"],"description":"Plain-language message shown to the requester (required for\nneeds_info and reject)."},"checklist":{},"snapshot_version":{"type":"integer","format":"int32"}}},"DecisionResult":{"type":"object","required":["outcome","bill_status"],"properties":{"outcome":{"type":"string"},"bill_status":{"type":"string"}}},"DecisionView":{"type":"object","required":["decision","reason_code","reason","is_second_approval","reviewer_is_me","snapshot_version","created_at"],"properties":{"decision":{"type":"string"},"reason_code":{"type":"string"},"reason":{"type":"string"},"requester_message":{"type":["string","null"]},"is_second_approval":{"type":"boolean"},"reviewer_is_me":{"type":"boolean"},"snapshot_version":{"type":"integer","format":"int32"},"created_at":{"type":"string","format":"date-time"}}},"DemoAccessRequest":{"type":"object","required":["code"],"properties":{"code":{"type":"string"}}},"DemoAccessStatus":{"type":"object","required":["mode","unlocked"],"properties":{"mode":{"type":"string","description":"`open`, `code` or `off`."},"unlocked":{"type":"boolean","description":"Whether this browser may use the demo sign-in helpers now."}}},"DemoCheckoutSession":{"type":"object","required":["provider_session_id","amount_minor","currency","status","environment","merchant","notice"],"properties":{"provider_session_id":{"type":"string"},"amount_minor":{"type":"integer","format":"int64"},"currency":{"type":"string"},"status":{"type":"string"},"environment":{"type":"string"},"merchant":{"type":"string"},"notice":{"type":"string"}}},"DemoComplete":{"type":"object","required":["outcome"],"properties":{"outcome":{"$ref":"#/components/schemas/FakeOutcome"}}},"DemoCompleteResult":{"type":"object","required":["return_url"],"properties":{"return_url":{"type":"string"}}},"DemoKyc":{"type":"object","required":["legal_name","residence_country"],"properties":{"legal_name":{"type":"string"},"residence_country":{"type":"string"}}},"DemoMail":{"type":"object","required":["subject","body_text","created_at"],"properties":{"subject":{"type":"string"},"body_text":{"type":"string"},"link":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}}},"DemoTotp":{"type":"object","required":["code","valid_for_seconds","notice"],"properties":{"code":{"type":"string"},"valid_for_seconds":{"type":"integer","format":"int64"},"notice":{"type":"string"}}},"DraftInput":{"type":"object","properties":{"category":{"type":["string","null"]},"country_code":{"type":["string","null"]},"currency":{"type":["string","null"]},"amount_due_minor":{"type":["integer","null"],"format":"int64"},"due_date":{"type":["string","null"],"format":"date"},"biller_name":{"type":["string","null"]},"biller_account_ref":{"type":["string","null"],"description":"Stored encrypted + keyed-hashed; never returned or shown publicly."},"public_title":{"type":["string","null"]},"public_alias":{"type":["string","null"]},"story":{"type":["string","null"]},"location_coarse":{"type":["string","null"],"description":"Coarse area only (e.g. \"Pune, MH\"); street-level details are refused."},"show_location":{"type":["boolean","null"]}}},"DrawKey":{"type":"object","required":["draw_run_key"],"properties":{"draw_run_key":{"type":"string","description":"Idempotency key for this draw run."}}},"EligibilityResult":{"type":"object","required":["decision","reason_code","guidance"],"properties":{"decision":{"$ref":"#/components/schemas/Decision"},"reason_code":{"type":"string"},"guidance":{"type":"string"}}},"EventSummary":{"type":"object","required":["id","provider","provider_event_id","event_type","processing_status","processing_attempts","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"provider":{"type":"string"},"provider_event_id":{"type":"string"},"event_type":{"type":"string"},"processing_status":{"type":"string"},"processing_attempts":{"type":"integer","format":"int32"},"last_error":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}}},"EvidenceMeta":{"type":"object","required":["id","filename","content_type","size_bytes","scan_status"],"properties":{"id":{"type":"string","format":"uuid"},"filename":{"type":"string"},"content_type":{"type":"string"},"size_bytes":{"type":"integer","format":"int64"},"scan_status":{"type":"string"},"scan_reason":{"type":["string","null"]}}},"EvidenceView":{"type":"object","required":["id","filename","content_type","size_bytes","scan_status","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"filename":{"type":"string"},"content_type":{"type":"string"},"size_bytes":{"type":"integer","format":"int64"},"scan_status":{"type":"string"},"scan_reason":{"type":["string","null"]},"ocr_suggestion":{},"created_at":{"type":"string","format":"date-time"}}},"ExceptionView":{"type":"object","required":["id","reason_code","status","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"run_id":{"type":["string","null"],"format":"uuid"},"attempt_id":{"type":["string","null"],"format":"uuid"},"provider_ref":{"type":["string","null"]},"reason_code":{"type":"string"},"expected_minor":{"type":["integer","null"],"format":"int64"},"actual_minor":{"type":["integer","null"],"format":"int64"},"currency":{"type":["string","null"]},"status":{"type":"string"},"resolution_note":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}}},"FakeOutcome":{"type":"string","enum":["approve","decline","cancel"]},"FieldError":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}},"FinancePaymentDetail":{"type":"object","required":["payment","events","journal","refunds","biller_confirmations"],"properties":{"payment":{"$ref":"#/components/schemas/FinancePaymentRow"},"events":{"type":"array","items":{"$ref":"#/components/schemas/EventSummary"}},"journal":{"type":"array","items":{"$ref":"#/components/schemas/JournalLineView"}},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/RefundView"}},"biller_confirmations":{"type":"array","items":{"$ref":"#/components/schemas/BillerConfirmationView"}}}},"FinancePaymentRow":{"type":"object","required":["id","public_contribution_id","donor_ref","bill_id","currency","amount_minor","total_minor","refunded_minor","state","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"public_contribution_id":{"type":"string","format":"uuid"},"donor_ref":{"type":"string"},"bill_id":{"type":"string","format":"uuid"},"bill_title":{"type":["string","null"]},"currency":{"type":"string"},"amount_minor":{"type":"integer","format":"int64"},"total_minor":{"type":"integer","format":"int64"},"refunded_minor":{"type":"integer","format":"int64"},"state":{"type":"string"},"allocation_id":{"type":["string","null"],"format":"uuid"},"allocation_state":{"type":["string","null"]},"applied_minor":{"type":["integer","null"],"format":"int64"},"created_at":{"type":"string","format":"date-time"}}},"FlagChange":{"type":"object","required":["value","reason"],"properties":{"value":{},"reason":{"type":"string"}}},"FlagView":{"type":"object","required":["key","value","description","updated_at"],"properties":{"key":{"type":"string"},"value":{},"description":{"type":"string"},"updated_at":{"type":"string","format":"date-time"}}},"FlagsResponse":{"type":"object","required":["flags","immutable_gates"],"properties":{"flags":{"type":"array","items":{"$ref":"#/components/schemas/FlagView"}},"immutable_gates":{"description":"Environment-only gates that no admin UI can change."}}},"IdentityAccessRow":{"type":"object","required":["subject_user_id","accessed_by","purpose_code","reason","recorded_at"],"properties":{"subject_user_id":{"type":"string","format":"uuid"},"accessed_by":{"type":"string","format":"uuid"},"purpose_code":{"type":"string"},"reason":{"type":"string"},"case_ref":{"type":["string","null"]},"recorded_at":{"type":"string","format":"date-time"}}},"IdentityMode":{"type":"string","enum":["anonymous","alias","named"]},"ImpactRow":{"type":"object","required":["currency","bills_published","bills_biller_confirmed","captured_net_minor","biller_confirmed_minor"],"properties":{"currency":{"type":"string"},"bills_published":{"type":"integer","format":"int64"},"bills_biller_confirmed":{"type":"integer","format":"int64"},"captured_net_minor":{"type":"integer","format":"int64","description":"Provider-confirmed contributions net of refunds."},"biller_confirmed_minor":{"type":"integer","format":"int64","description":"Biller-confirmed amounts only."}}},"ImpactSummary":{"type":"object","required":["currency","contributions","pending_minor","captured_net_minor","refunded_minor","biller_confirmed_minor","bills_supported","bills_confirmed_paid"],"properties":{"currency":{"type":"string"},"contributions":{"type":"integer","format":"int64"},"pending_minor":{"type":"integer","format":"int64"},"captured_net_minor":{"type":"integer","format":"int64"},"refunded_minor":{"type":"integer","format":"int64"},"biller_confirmed_minor":{"type":"integer","format":"int64"},"bills_supported":{"type":"integer","format":"int64"},"bills_confirmed_paid":{"type":"integer","format":"int64"}}},"IncidentUpdate":{"type":"object","required":["note"],"properties":{"note":{"type":"string"},"status":{"type":["string","null"]},"customer_notice":{"type":["string","null"]}}},"IncidentView":{"type":"object","required":["id","severity","title","status","summary","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"severity":{"type":"string"},"title":{"type":"string"},"status":{"type":"string"},"summary":{"type":"string"},"customer_notice":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"IntentRequest":{"type":"object","required":["bill_id"],"properties":{"bill_id":{"type":"string","format":"uuid"}}},"InviteCreated":{"type":"object","required":["invite_id","token","join_url","expires_at"],"properties":{"invite_id":{"type":"string","format":"uuid"},"token":{"type":"string","description":"Shown once. Links expire and can be revoked."},"join_url":{"type":"string"},"expires_at":{"type":"string","format":"date-time"}}},"InviteMember":{"type":"object","required":["email","role"],"properties":{"email":{"type":"string"},"role":{"type":"string","description":"admin | finance | analyst | approver | member (never owner)"}}},"JoinCircle":{"type":"object","required":["token"],"properties":{"token":{"type":"string"}}},"JournalLineView":{"type":"object","required":["journal_id","journal_kind","line_no","account_code","currency","side","amount_minor","created_at"],"properties":{"journal_id":{"type":"string","format":"uuid"},"journal_kind":{"type":"string"},"line_no":{"type":"integer","format":"int32"},"account_code":{"type":"string"},"currency":{"type":"string"},"side":{"type":"string"},"amount_minor":{"type":"integer","format":"int64"},"created_at":{"type":"string","format":"date-time"}}},"KycTier":{"type":"string","enum":["none","basic","enhanced"]},"MagicLinkRequest":{"type":"object","required":["email"],"properties":{"email":{"type":"string"}}},"Me":{"type":"object","required":["id","display_alias","roles","is_staff","mfa_enrolled","passkeys","mfa_verified_this_session","onboarding_completed","verification","is_demo_account","org_memberships"],"properties":{"id":{"type":"string","format":"uuid"},"display_alias":{"type":"string"},"roles":{"type":"array","items":{"$ref":"#/components/schemas/Role"}},"is_staff":{"type":"boolean"},"mfa_enrolled":{"type":"boolean","description":"A confirmed TOTP authenticator."},"passkeys":{"type":"integer","format":"int64","description":"Active passkeys (each is phishing-resistant MFA on its own)."},"mfa_verified_this_session":{"type":"boolean"},"onboarding_completed":{"type":"boolean"},"declared_country":{"type":["string","null"]},"verification":{"$ref":"#/components/schemas/Verification"},"is_demo_account":{"type":"boolean"},"org_memberships":{"type":"array","items":{"$ref":"#/components/schemas/OrgMembership"}}}},"MemberView":{"type":"object","required":["user_id","display_alias","role","created_at"],"properties":{"user_id":{"type":"string","format":"uuid"},"display_alias":{"type":"string"},"role":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"ModeInfo":{"type":"object","required":["mode","environment","demo","contributions_possible","payments_halted","live_payments_enabled","provider_display","benedrop_live","notices","terms_version","privacy_notice_version","demo_access","demo_uploads"],"properties":{"mode":{"type":"string"},"environment":{"type":"string"},"demo":{"type":"boolean"},"contributions_possible":{"type":"boolean"},"payments_halted":{"type":"boolean"},"live_payments_enabled":{"type":"boolean","description":"True only when every live gate holds. Always false in this build."},"provider_display":{"type":"string"},"benedrop_live":{"type":"boolean"},"notices":{"type":"array","items":{"type":"string"}},"terms_version":{"type":"string","description":"Current terms version a member must accept at onboarding."},"privacy_notice_version":{"type":"string","description":"Current privacy notice version a member must accept at onboarding."},"demo_access":{"type":"string","description":"Demo sign-in helpers: `open`, `code` (private demo) or `off`."},"demo_uploads":{"type":"string","description":"Demo evidence uploads: `any`, or `samples` (only the fictional sample bill)."}}},"ModerationDecision":{"type":"object","required":["decision","reason_code"],"properties":{"decision":{"type":"string","description":"approve_private | approve_public | reject"},"reason_code":{"type":"string"}}},"ModerationItem":{"type":"object","required":["kind","id","text","state","reasons","wants_public","created_at"],"properties":{"kind":{"type":"string"},"id":{"type":"string","format":"uuid"},"text":{"type":"string"},"state":{"type":"string"},"reasons":{"type":"array","items":{"type":"string"}},"wants_public":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}},"MyCircle":{"type":"object","required":["id","name","role","bill_id","status"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"role":{"type":"string"},"bill_id":{"type":"string","format":"uuid"},"status":{"type":"string"}}},"MysteryDecision":{"type":"object","required":["accept"],"properties":{"accept":{"type":"boolean"}}},"MysteryRequest":{"type":"object","required":["currency","max_amount_minor"],"properties":{"currency":{"type":"string"},"category":{"type":["string","null"]},"max_amount_minor":{"type":"integer","format":"int64"}}},"MysterySelection":{"type":"object","required":["selection_id","rule","candidates_considered","bill"],"properties":{"selection_id":{"type":"string","format":"uuid"},"rule":{"type":"string"},"candidates_considered":{"type":"integer","format":"int64"},"bill":{"$ref":"#/components/schemas/PublicBill","description":"Inspect before deciding; nothing is charged by selection."}}},"NewBudget":{"type":"object","required":["currency","amount_minor","period_start","period_end"],"properties":{"currency":{"type":"string"},"amount_minor":{"type":"integer","format":"int64"},"period_start":{"type":"string","format":"date"},"period_end":{"type":"string","format":"date"},"category":{"type":["string","null"]}}},"NewCampaign":{"type":"object","required":["campaign_type","name","description","region_code","currency","max_budget_minor","categories"],"properties":{"campaign_type":{"type":"string","description":"bene_match | bene_goal | bene_together | bene_drop"},"name":{"type":"string"},"description":{"type":"string"},"region_code":{"type":"string"},"currency":{"type":"string"},"max_budget_minor":{"type":"integer","format":"int64"},"categories":{"type":"array","items":{"type":"string"}},"ratio_basis_points":{"type":["integer","null"],"format":"int32","description":"BeneMatch only: 10000 = 1:1."},"max_match_per_donation_minor":{"type":["integer","null"],"format":"int64"},"max_bill_minor":{"type":["integer","null"],"format":"int64","description":"BeneDrop only."}}},"NewCase":{"type":"object","required":["case_type","severity","summary"],"properties":{"bill_id":{"type":["string","null"],"format":"uuid"},"case_type":{"type":"string"},"severity":{"type":"string"},"summary":{"type":"string"}}},"NewIncident":{"type":"object","required":["severity","title","summary"],"properties":{"severity":{"type":"string"},"title":{"type":"string"},"summary":{"type":"string"}}},"NewMessage":{"type":"object","required":["body"],"properties":{"body":{"type":"string"},"internal":{"type":["boolean","null"],"description":"Staff only: internal note invisible to the customer."}}},"NewOrg":{"type":"object","required":["name","country_code","registration_ref"],"properties":{"name":{"type":"string"},"country_code":{"type":"string"},"registration_ref":{"type":"string","description":"Company registration number (stored encrypted)."}}},"NewTicket":{"type":"object","required":["subject","body"],"properties":{"subject":{"type":"string"},"body":{"type":"string"},"category":{"type":["string","null"],"description":"general | payment | refund | request | privacy | safety | technical"},"attempt_id":{"type":["string","null"],"format":"uuid"},"bill_id":{"type":["string","null"],"format":"uuid"}}},"NoteVisibility":{"type":"string","enum":["none","recipient_only","public_after_moderation"]},"NotificationView":{"type":"object","required":["id","kind","title","body","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string"},"title":{"type":"string"},"body":{"type":"string"},"link":{"type":["string","null"]},"read_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"Onboarding":{"type":"object","required":["display_alias","declared_country","age_confirmed_18plus","accept_terms_version","accept_privacy_version"],"properties":{"display_alias":{"type":"string"},"declared_country":{"type":"string"},"age_confirmed_18plus":{"type":"boolean","description":"Must be true; minors cannot use BillBene (BB-006)."},"accept_terms_version":{"type":"string"},"accept_privacy_version":{"type":"string"},"marketing_opt_in":{"type":["boolean","null"],"description":"Optional, unbundled marketing consent (defaults false)."}}},"OrgCampaign":{"type":"object","required":["id","campaign_type","name","state","currency","max_budget_minor","claimed_minor","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"campaign_type":{"type":"string"},"name":{"type":"string"},"state":{"type":"string"},"currency":{"type":"string"},"max_budget_minor":{"type":"integer","format":"int64"},"claimed_minor":{"type":"integer","format":"int64"},"created_at":{"type":"string","format":"date-time"}}},"OrgInviteCreated":{"type":"object","required":["invite_id","token","expires_at"],"properties":{"invite_id":{"type":"string","format":"uuid"},"token":{"type":"string"},"expires_at":{"type":"string","format":"date-time"}}},"OrgMembership":{"type":"object","required":["org_id","name","role"],"properties":{"org_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"role":{"type":"string"}}},"OrgReport":{"type":"object","required":["org_id","by_currency","methodology"],"properties":{"org_id":{"type":"string","format":"uuid"},"by_currency":{"type":"array","items":{"$ref":"#/components/schemas/OrgReportRow"}},"methodology":{"type":"string"}}},"OrgReportRow":{"type":"object","required":["currency","matched_pending_minor","matched_applied_minor","matched_reversed_minor","contributions_matched"],"properties":{"currency":{"type":"string"},"matched_pending_minor":{"type":"integer","format":"int64"},"matched_applied_minor":{"type":"integer","format":"int64"},"matched_reversed_minor":{"type":"integer","format":"int64"},"contributions_matched":{"type":"integer","format":"int64"}}},"OrgView":{"type":"object","required":["id","name","country_code","kyb_status","status","my_role","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"country_code":{"type":"string"},"kyb_status":{"type":"string"},"status":{"type":"string"},"my_role":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"Overview":{"type":"object","required":["environment","mode","payments_halted","live_payments_enabled","users_total","staff_total","bills_by_status","review_queue_open","high_risk_open","risk_holds","open_reports","open_recon_exceptions","pending_approvals","privacy_requests_open","money_by_currency","as_of"],"properties":{"environment":{"type":"string"},"mode":{"type":"string"},"payments_halted":{"type":"boolean"},"live_payments_enabled":{"type":"boolean"},"users_total":{"type":"integer","format":"int64"},"staff_total":{"type":"integer","format":"int64"},"bills_by_status":{"type":"array","items":{"$ref":"#/components/schemas/StatusCount"}},"review_queue_open":{"type":"integer","format":"int64"},"high_risk_open":{"type":"integer","format":"int64"},"risk_holds":{"type":"integer","format":"int64"},"open_reports":{"type":"integer","format":"int64"},"open_recon_exceptions":{"type":"integer","format":"int64"},"pending_approvals":{"type":"integer","format":"int64"},"privacy_requests_open":{"type":"integer","format":"int64"},"money_by_currency":{"type":"array","items":{"$ref":"#/components/schemas/CurrencySummary"}},"as_of":{"type":"string","format":"date-time"}}},"PasskeyAssertionInput":{"type":"object","required":["ceremony_id","credential"],"properties":{"ceremony_id":{"type":"string","format":"uuid"},"credential":{"type":"object","description":"The `PublicKeyCredential` from `navigator.credentials.get()`,\nwith binary fields base64url-encoded (WebAuthn JSON form).","additionalProperties":{},"propertyNames":{"type":"string"}},"client":{"type":["string","null"],"description":"Sign-in only: `web` (cookie session) or `mobile` (bearer token)."}}},"PasskeyOptions":{"type":"object","required":["ceremony_id","options","expires_at"],"properties":{"ceremony_id":{"type":"string","format":"uuid","description":"Pass back unchanged with the authenticator's response."},"options":{"type":"object","description":"WebAuthn options: `publicKey` holds the members for\n`navigator.credentials.create()` / `get()`; binary fields are base64url.","additionalProperties":{},"propertyNames":{"type":"string"}},"expires_at":{"type":"string","format":"date-time"}}},"PasskeyRegistrationInput":{"type":"object","required":["ceremony_id","credential"],"properties":{"ceremony_id":{"type":"string","format":"uuid"},"credential":{"type":"object","description":"The `PublicKeyCredential` from `navigator.credentials.create()`,\nwith binary fields base64url-encoded (WebAuthn JSON form).","additionalProperties":{},"propertyNames":{"type":"string"}},"nickname":{"type":["string","null"],"description":"Optional label shown only to the account owner, e.g. \"Work laptop\"."}}},"PasskeyView":{"type":"object","required":["id","nickname","backup_eligible","backup_state","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"nickname":{"type":"string"},"backup_eligible":{"type":"boolean","description":"The passkey can be synced/backed up by its provider (e.g. a password manager)."},"backup_state":{"type":"boolean","description":"The passkey is currently backed up/synced."},"created_at":{"type":"string","format":"date-time"},"last_used_at":{"type":["string","null"],"format":"date-time"}}},"PasswordLoginRequest":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string"},"password":{"type":"string"},"client":{"type":["string","null"]}}},"PaymentEnvironment":{"type":"string","enum":["demo","sandbox","live"]},"PaymentState":{"type":"string","description":"Payment attempt lifecycle (provider-driven).","enum":["created","checkout_ready","pending","authorized","captured","failed","canceled","expired","refund_pending","partially_refunded","refunded","disputed","dispute_won","dispute_lost"]},"PersonaView":{"type":"object","required":["key","label","description","roles","staff"],"properties":{"key":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"},"roles":{"type":"array","items":{"type":"string"}},"staff":{"type":"boolean"}}},"PolicyDecision":{"type":"object","required":["decision","reason_code","public_message","currency","platform_fee_bps","evaluated_at","expires_at"],"properties":{"decision":{"$ref":"#/components/schemas/Decision"},"reason_code":{"type":"string","description":"Public-safe reason code (never sanctions/risk internals)."},"public_message":{"type":"string"},"internal_hits":{"type":"array","items":{"type":"string"},"description":"Internal control hits for auditors (not returned to the public)."},"policy_version_id":{"type":["string","null"],"format":"uuid"},"policy_version_no":{"type":["integer","null"],"format":"int32"},"effective_max_minor":{"type":["integer","null"],"format":"int64"},"currency":{"type":"string"},"anonymity_supported":{"type":["boolean","null"]},"route_disclosure":{"type":["string","null"]},"platform_fee_bps":{"type":"integer","format":"int32","minimum":0},"evaluated_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"}}},"PolicyEvaluateRequest":{"type":"object","required":["bill_id","amount_minor","recipient_identity_mode"],"properties":{"bill_id":{"type":"string","format":"uuid"},"amount_minor":{"type":"integer","format":"int64"},"recipient_identity_mode":{"$ref":"#/components/schemas/IdentityMode"}}},"PolicyProposal":{"type":"object","required":["environment","legal_entity_code","origin_country","recipient_country","biller_country","provider","route_type","currency","rule","evidence_ref","effective_from","change_reason"],"properties":{"environment":{"$ref":"#/components/schemas/PaymentEnvironment"},"legal_entity_code":{"type":"string"},"origin_country":{"type":"string"},"recipient_country":{"type":"string"},"biller_country":{"type":"string"},"provider":{"type":"string"},"route_type":{"type":"string"},"currency":{"type":"string"},"rule":{"$ref":"#/components/schemas/CorridorRuleBody"},"evidence_ref":{"type":"string","description":"Source document / counsel memo / contract clause. Required."},"provider_approval_ref":{"type":["string","null"]},"provider_approval_expires_at":{"type":["string","null"],"format":"date-time"},"effective_from":{"type":"string","format":"date-time"},"effective_until":{"type":["string","null"],"format":"date-time"},"change_reason":{"type":"string"}}},"PolicyVersion":{"type":"object","required":["id","corridor_key","version_no","environment","legal_entity_code","origin_country","recipient_country","biller_country","provider","route_type","currency","rule_json","evidence_ref","effective_from","status","change_reason","proposed_by_me","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"corridor_key":{"type":"string"},"version_no":{"type":"integer","format":"int32"},"environment":{"type":"string"},"legal_entity_code":{"type":"string"},"origin_country":{"type":"string"},"recipient_country":{"type":"string"},"biller_country":{"type":"string"},"provider":{"type":"string"},"route_type":{"type":"string"},"currency":{"type":"string"},"rule_json":{},"evidence_ref":{"type":"string"},"provider_approval_ref":{"type":["string","null"]},"provider_approval_expires_at":{"type":["string","null"],"format":"date-time"},"effective_from":{"type":"string","format":"date-time"},"effective_until":{"type":["string","null"],"format":"date-time"},"status":{"type":"string"},"change_reason":{"type":"string"},"proposed_by_me":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}},"PrivacyCenter":{"type":"object","required":["settings","recipient_preview","public_preview","notice_version","explanation"],"properties":{"settings":{"$ref":"#/components/schemas/PrivacySettings"},"recipient_preview":{"type":"string"},"public_preview":{"type":"string"},"notice_version":{"type":"string"},"explanation":{"type":"string"}}},"PrivacyPreview":{"type":"object","required":["recipient_sees","public_sees","note_visibility","compatible","warnings","retained_by_billbene"],"properties":{"recipient_sees":{"type":"string","description":"Exactly what the bill recipient will see."},"public_sees":{"type":"string","description":"Exactly what the public will see."},"note_visibility":{"$ref":"#/components/schemas/NoteVisibility"},"route_disclosure":{"type":["string","null"]},"anonymity_supported":{"type":["boolean","null"]},"compatible":{"type":"boolean","description":"False when the chosen recipient-facing mode is impossible on this route."},"warnings":{"type":"array","items":{"type":"string"}},"retained_by_billbene":{"type":"string"}}},"PrivacyPreviewRequest":{"type":"object","required":["bill_id","recipient_identity_mode"],"properties":{"bill_id":{"type":"string","format":"uuid"},"recipient_identity_mode":{"$ref":"#/components/schemas/IdentityMode"},"public_identity_mode":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/IdentityMode"}]},"display_alias":{"type":["string","null"]},"note_visibility":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/NoteVisibility"}]}}},"PrivacyQueueItem":{"type":"object","required":["id","subject_user_id","subject_alias","request_type","state","due_at","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"subject_user_id":{"type":"string","format":"uuid"},"subject_alias":{"type":"string"},"request_type":{"type":"string"},"state":{"type":"string"},"due_at":{"type":"string","format":"date-time"},"details":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}}},"PrivacyRequestInput":{"type":"object","required":["request_type"],"properties":{"request_type":{"type":"string","description":"access | correct | delete | export | restrict | object"},"details":{"type":["string","null"]}}},"PrivacyRequestState":{"type":"string","description":"Data-subject request lifecycle (docs/21 §21.3).","enum":["requested","identity_verification","triaged","in_progress","completed","partially_fulfilled","rejected_with_reason"]},"PrivacyRequestView":{"type":"object","required":["id","request_type","state","due_at","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"request_type":{"type":"string"},"state":{"type":"string"},"due_at":{"type":"string","format":"date-time"},"resolution_reason":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}}},"PrivacySettings":{"type":"object","required":["default_recipient_identity_mode","default_public_identity_mode","show_coarse_location","allow_thank_you_messages","achievements_opt_in","ask_amount_on_swipe","lockscreen_previews"],"properties":{"default_recipient_identity_mode":{"type":"string"},"default_public_identity_mode":{"type":"string"},"donor_public_alias":{"type":["string","null"]},"requester_public_alias":{"type":["string","null"]},"show_coarse_location":{"type":"boolean"},"allow_thank_you_messages":{"type":"boolean"},"achievements_opt_in":{"type":"boolean"},"ask_amount_on_swipe":{"type":"boolean"},"lockscreen_previews":{"type":"boolean"}}},"PrivacyTransition":{"type":"object","required":["to","note"],"properties":{"to":{"$ref":"#/components/schemas/PrivacyRequestState"},"note":{"type":"string"}}},"Problem":{"type":"object","description":"Problem details returned for every error (`application/problem+json`).","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer","format":"int32","minimum":0},"code":{"type":"string"},"detail":{"type":["string","null"]},"request_id":{"type":"string"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/FieldError"}},"decision":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/PolicyDecision","description":"Public-safe policy decision (internal control hits are stripped)."}]}}},"ProposalResult":{"type":"object","required":["policy_version_id","approval_id","version_no"],"properties":{"policy_version_id":{"type":"string","format":"uuid"},"approval_id":{"type":"string","format":"uuid"},"version_no":{"type":"integer","format":"int32"}}},"PublicBill":{"type":"object","required":["id","category","title","public_alias","public_story","country_code","currency","total_minor","eligible_captured_minor","biller_applied_minor","remaining_minor","available_minor","verification_status","verified_at","due_date","urgent_verified","supporters_count","review_status","biller_status","is_demo"],"properties":{"id":{"type":"string","format":"uuid"},"category":{"type":"string"},"title":{"type":"string"},"public_alias":{"type":"string"},"public_story":{"type":"string"},"location_coarse":{"type":["string","null"]},"country_code":{"type":"string"},"currency":{"type":"string"},"total_minor":{"type":"integer","format":"int64","description":"Verified bill amount (immutable approved snapshot)."},"eligible_captured_minor":{"type":"integer","format":"int64","description":"Provider-confirmed contributions net of refunds (\"payment received\")."},"biller_applied_minor":{"type":"integer","format":"int64","description":"Amount the biller confirmed as applied (\"paid to biller\")."},"remaining_minor":{"type":"integer","format":"int64","description":"Still needed: total − eligible captured."},"available_minor":{"type":"integer","format":"int64","description":"What can be pledged right now (excludes in-flight reservations)."},"verification_status":{"type":"string"},"verified_at":{"type":"string","format":"date-time"},"due_date":{"type":"string","format":"date"},"urgent_verified":{"type":"boolean","description":"Due within 7 days on verified evidence (BeneRescue, no timers)."},"supporters_count":{"type":"integer","format":"int64"},"review_status":{"type":"string"},"biller_status":{"type":"string"},"is_demo":{"type":"boolean"}}},"PublicBillDetail":{"type":"object","required":["bill","supporters","stories"],"properties":{"bill":{"$ref":"#/components/schemas/PublicBill"},"supporters":{"type":"array","items":{"$ref":"#/components/schemas/PublicSupporter"},"description":"Public projection: labels by each donor's *public* choice; notes only\nwith consent + human moderation (BB-199)."},"stories":{"type":"array","items":{"type":"string"}}}},"PublicCampaign":{"type":"object","required":["id","campaign_type","name","description","region_code","currency","max_budget_minor","claimed_minor","categories","state","is_demo"],"properties":{"id":{"type":"string","format":"uuid"},"campaign_type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"region_code":{"type":"string"},"currency":{"type":"string"},"max_budget_minor":{"type":"integer","format":"int64"},"claimed_minor":{"type":"integer","format":"int64"},"categories":{"type":"array","items":{"type":"string"}},"state":{"type":"string"},"sponsor_name":{"type":["string","null"]},"ratio_basis_points":{"type":["integer","null"],"format":"int32"},"max_match_per_donation_minor":{"type":["integer","null"],"format":"int64"},"draw_at":{"type":["string","null"],"format":"date-time"},"is_demo":{"type":"boolean"}}},"PublicImpact":{"type":"object","required":["environment","is_demo","as_of","by_currency","methodology"],"properties":{"environment":{"type":"string"},"is_demo":{"type":"boolean"},"as_of":{"type":"string","format":"date-time"},"by_currency":{"type":"array","items":{"$ref":"#/components/schemas/ImpactRow"}},"methodology":{"type":"string"}}},"PublicStory":{"type":"object","required":["body","public_alias","category"],"properties":{"body":{"type":"string"},"public_alias":{"type":"string"},"category":{"type":"string"},"published_at":{"type":["string","null"],"format":"date-time"}}},"PublicSupporter":{"type":"object","required":["label","date"],"properties":{"label":{"type":"string"},"note":{"type":["string","null"]},"date":{"type":"string","format":"date"}}},"QuoteRequest":{"type":"object","required":["bill_id","amount_minor","recipient_identity_mode"],"properties":{"bill_id":{"type":"string","format":"uuid"},"amount_minor":{"type":"integer","format":"int64"},"tip_minor":{"type":["integer","null"],"format":"int64","description":"Optional platform tip. Defaults to zero and is never pre-selected."},"recipient_identity_mode":{"$ref":"#/components/schemas/IdentityMode"},"public_identity_mode":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/IdentityMode"}]},"display_alias":{"type":["string","null"]},"note":{"type":["string","null"]},"note_visibility":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/NoteVisibility"}]},"public_note_consent":{"type":["boolean","null"],"description":"Separate, unticked-by-default consent for a public note."},"circle_id":{"type":["string","null"],"format":"uuid"}}},"QuoteView":{"type":"object","required":["id","bill_id","bill_title","currency","amount_minor","fee_minor","tip_minor","total_minor","mode","provider_display","expires_at","recipient_sees","public_sees","terms_version"],"properties":{"id":{"type":"string","format":"uuid"},"bill_id":{"type":"string","format":"uuid"},"bill_title":{"type":"string"},"currency":{"type":"string"},"amount_minor":{"type":"integer","format":"int64"},"fee_minor":{"type":"integer","format":"int64"},"tip_minor":{"type":"integer","format":"int64"},"total_minor":{"type":"integer","format":"int64"},"mode":{"type":"string","description":"`demo`, `sandbox` or `live_approved`."},"provider_display":{"type":"string"},"expires_at":{"type":"string","format":"date-time"},"recipient_sees":{"type":"string"},"public_sees":{"type":"string"},"route_disclosure":{"type":["string","null"]},"note_status":{"type":["string","null"]},"match_preview_minor":{"type":["integer","null"],"format":"int64"},"match_campaign_name":{"type":["string","null"]},"terms_version":{"type":"string"},"demo_notice":{"type":["string","null"]}}},"ReasonBody":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string"}}},"Receipt":{"type":"object","required":["contribution","biller_confirmations","refunds","disclaimer"],"properties":{"contribution":{"$ref":"#/components/schemas/Contribution"},"payment_receipt":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ReceiptPart","description":"Payment receipt: provider-confirmed money movement only."}]},"biller_confirmations":{"type":"array","items":{"$ref":"#/components/schemas/ReceiptPart"},"description":"Biller confirmation: separate document, only with partner evidence."},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/ReceiptPart"}},"disclaimer":{"type":"string"}}},"ReceiptPart":{"type":"object","required":["label","amount_minor","currency","at","reference"],"properties":{"label":{"type":"string"},"amount_minor":{"type":"integer","format":"int64"},"currency":{"type":"string"},"at":{"type":"string","format":"date-time"},"reference":{"type":"string"}}},"RecipientContribution":{"type":"object","required":["public_contribution_id","donor_label","amount_minor","currency","status_label","received_on","thank_you_sent","can_thank"],"properties":{"public_contribution_id":{"type":"string","format":"uuid","description":"Opaque id that cannot be used to enumerate donors."},"donor_label":{"type":"string","description":"`A Kind Stranger`, the donor's alias, or their chosen display name."},"amount_minor":{"type":"integer","format":"int64"},"currency":{"type":"string"},"status_label":{"type":"string"},"note":{"type":["string","null"]},"received_on":{"type":"string","format":"date"},"thank_you_sent":{"type":"boolean"},"can_thank":{"type":"boolean"}}},"ReconRun":{"type":"object","required":["id","provider","period_start","period_end","status","matched_count","exception_count","started_at"],"properties":{"id":{"type":"string","format":"uuid"},"provider":{"type":"string"},"period_start":{"type":"string","format":"date-time"},"period_end":{"type":"string","format":"date-time"},"status":{"type":"string"},"matched_count":{"type":"integer","format":"int32"},"exception_count":{"type":"integer","format":"int32"},"started_at":{"type":"string","format":"date-time"},"ended_at":{"type":["string","null"],"format":"date-time"}}},"RefundProposal":{"type":"object","required":["attempt_id","amount_minor","reason"],"properties":{"attempt_id":{"type":"string","format":"uuid"},"amount_minor":{"type":"integer","format":"int64"},"reason":{"type":"string"}}},"RefundView":{"type":"object","required":["id","attempt_id","amount_minor","currency","reason","status","proposed_by_system","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"attempt_id":{"type":"string","format":"uuid"},"amount_minor":{"type":"integer","format":"int64"},"currency":{"type":"string"},"reason":{"type":"string"},"status":{"type":"string"},"proposed_by_system":{"type":"boolean"},"proposed_by":{"type":["string","null"],"format":"uuid"},"approved_by":{"type":["string","null"],"format":"uuid"},"decision_note":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}}},"ReportRequest":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","description":"suspected_fraud | privacy | harassment | inappropriate | other"},"details":{"type":["string","null"]}}},"ReportView":{"type":"object","required":["id","bill_id","reason","status","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"bill_id":{"type":"string","format":"uuid"},"bill_title":{"type":["string","null"]},"reason":{"type":"string"},"details":{"type":["string","null"]},"status":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"RequestSummary":{"type":"object","required":["id","category","currency","review_status","funding_status","biller_status","risk_hold","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"category":{"type":"string"},"currency":{"type":"string"},"title":{"type":["string","null"]},"amount_due_minor":{"type":["integer","null"],"format":"int64"},"due_date":{"type":["string","null"],"format":"date"},"review_status":{"type":"string"},"funding_status":{"type":"string"},"biller_status":{"type":"string"},"risk_hold":{"type":"boolean"},"updated_at":{"type":"string","format":"date-time"}}},"RequesterBill":{"type":"object","required":["id","review_status","funding_status","biller_status","paused_for_review","category","country_code","currency","show_location","draft_revision","current_version","captured_minor","biller_applied_minor","remaining_minor","evidence","can_edit","can_submit","can_withdraw","can_appeal","sensitive_flags","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"review_status":{"$ref":"#/components/schemas/ReviewStatus"},"funding_status":{"type":"string"},"biller_status":{"type":"string"},"paused_for_review":{"type":"boolean"},"category":{"type":"string"},"country_code":{"type":"string"},"currency":{"type":"string"},"amount_due_minor":{"type":["integer","null"],"format":"int64"},"due_date":{"type":["string","null"],"format":"date"},"biller_name":{"type":["string","null"]},"biller_account_masked":{"type":["string","null"],"description":"Masked (last 4) — the full reference is never returned."},"public_title":{"type":["string","null"]},"public_alias":{"type":["string","null"]},"story":{"type":["string","null"]},"location_coarse":{"type":["string","null"]},"show_location":{"type":"boolean"},"draft_revision":{"type":"integer","format":"int32"},"current_version":{"type":"integer","format":"int32"},"captured_minor":{"type":"integer","format":"int64"},"biller_applied_minor":{"type":"integer","format":"int64"},"remaining_minor":{"type":"integer","format":"int64"},"evidence":{"type":"array","items":{"$ref":"#/components/schemas/EvidenceView"}},"latest_message":{"type":["string","null"]},"can_edit":{"type":"boolean"},"can_submit":{"type":"boolean"},"can_withdraw":{"type":"boolean"},"can_appeal":{"type":"boolean"},"sensitive_flags":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ResolveReport":{"type":"object","required":["action_taken","note"],"properties":{"action_taken":{"type":"boolean"},"note":{"type":"string"}}},"ResolveRequest":{"type":"object","required":["note"],"properties":{"note":{"type":"string"}}},"RevealRequest":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string"}}},"RevealedReference":{"type":"object","required":["biller_reference"],"properties":{"biller_reference":{"type":"string"}}},"ReviewQueueItem":{"type":"object","required":["case_id","bill_id","title","category","currency","total_minor","status","high_risk","high_risk_reasons","assigned_to_me","awaiting_my_second_approval","created_at","sla_due_at"],"properties":{"case_id":{"type":"string","format":"uuid"},"bill_id":{"type":"string","format":"uuid"},"title":{"type":"string"},"category":{"type":"string"},"currency":{"type":"string"},"total_minor":{"type":"integer","format":"int64"},"status":{"type":"string"},"high_risk":{"type":"boolean"},"high_risk_reasons":{"type":"array","items":{"type":"string"}},"assigned_to_me":{"type":"boolean"},"awaiting_my_second_approval":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"sla_due_at":{"type":"string","format":"date-time"}}},"ReviewStatus":{"type":"string","description":"Requester bill moderation lifecycle.","enum":["draft","submitted","auto_check","in_review","needs_info","rejected","approved","published","suspended","expired","withdrawn","completed"]},"RevokedCount":{"type":"object","required":["revoked"],"properties":{"revoked":{"type":"integer","format":"int64","minimum":0}}},"RiskCase":{"type":"object","required":["id","case_type","severity","status","summary","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"bill_id":{"type":["string","null"],"format":"uuid"},"case_type":{"type":"string"},"severity":{"type":"string"},"status":{"type":"string"},"summary":{"type":"string"},"hold_reason":{"type":["string","null"]},"bill_title":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}}},"RiskSignal":{"type":"object","required":["id","signal_type","severity","details","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"bill_id":{"type":["string","null"],"format":"uuid"},"signal_type":{"type":"string"},"severity":{"type":"string"},"details":{},"created_at":{"type":"string","format":"date-time"}}},"Role":{"type":"string","enum":["donor","requester","support_agent","reviewer","risk_analyst","finance_operator","compliance_officer","platform_admin","superadmin"]},"RoleChange":{"type":"object","required":["user_id","role","reason"],"properties":{"user_id":{"type":"string","format":"uuid"},"role":{"$ref":"#/components/schemas/Role"},"reason":{"type":"string"}}},"RoleUpdate":{"type":"object","required":["role"],"properties":{"role":{"type":"string"}}},"Scenario":{"type":"string","enum":["duplicate_capture","forged_signature","wrong_environment","refund_before_capture","dispute","dispute_lost","statement_drift"]},"SecurityPosture":{"type":"object","required":["staff_total","staff_with_mfa","failed_sign_ins_24h","mfa_failures_24h","security_events_24h","identity_unmasks_7d","csp_and_headers"],"properties":{"staff_total":{"type":"integer","format":"int64"},"staff_with_mfa":{"type":"integer","format":"int64"},"failed_sign_ins_24h":{"type":"integer","format":"int64"},"mfa_failures_24h":{"type":"integer","format":"int64"},"security_events_24h":{"type":"array","items":{"$ref":"#/components/schemas/StatusCount"}},"identity_unmasks_7d":{"type":"integer","format":"int64"},"csp_and_headers":{"type":"string"}}},"SessionView":{"type":"object","required":["id","client_kind","created_at","last_seen_at","mfa_verified","current"],"properties":{"id":{"type":"string","format":"uuid"},"client_kind":{"type":"string"},"user_agent_summary":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"last_seen_at":{"type":"string","format":"date-time"},"mfa_verified":{"type":"boolean"},"current":{"type":"boolean"}}},"SetPasswordRequest":{"type":"object","required":["new_password"],"properties":{"new_password":{"type":"string"}}},"SignInResponse":{"type":"object","required":["user_id","display_alias","onboarding_required","mfa_required","expires_at"],"properties":{"user_id":{"type":"string","format":"uuid"},"display_alias":{"type":"string"},"onboarding_required":{"type":"boolean"},"mfa_required":{"type":"boolean"},"csrf_token":{"type":["string","null"],"description":"Web clients send this back as `X-CSRF-Token` on writes."},"access_token":{"type":["string","null"],"description":"Mobile clients store this in Keychain/Keystore; never returned to web."},"expires_at":{"type":"string","format":"date-time"}}},"SignalView":{"type":"object","required":["signal_type","severity","details","created_at"],"properties":{"signal_type":{"type":"string"},"severity":{"type":"string"},"details":{},"created_at":{"type":"string","format":"date-time"}}},"SimulateBillerRequest":{"type":"object","properties":{"applied_minor":{"type":["integer","null"],"format":"int64"}}},"SimulateRequest":{"type":"object","required":["scenario"],"properties":{"scenario":{"$ref":"#/components/schemas/Scenario"}}},"SimulationInput":{"type":"object","required":["recipient_country","category","currency","amount_minor"],"properties":{"environment":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/PaymentEnvironment"}]},"donor_verified_residence":{"type":["string","null"]},"donor_ip_country":{"type":["string","null"]},"donor_verified_adult":{"type":["boolean","null"]},"donor_kyc_tier":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/KycTier"}]},"donor_sanctions_hit":{"type":["boolean","null"]},"recipient_country":{"type":"string"},"biller_country":{"type":["string","null"]},"category":{"type":"string"},"currency":{"type":"string"},"amount_minor":{"type":"integer","format":"int64"},"provider":{"type":["string","null"]},"recipient_identity_mode":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/IdentityMode"}]},"donor_spent_24h_minor":{"type":["integer","null"],"format":"int64"},"donor_spent_30d_minor":{"type":["integer","null"],"format":"int64"},"bill_remaining_minor":{"type":["integer","null"],"format":"int64"},"risk_hold":{"type":["boolean","null"]}}},"SimulationResult":{"type":"object","required":["decision","rules_considered","note"],"properties":{"decision":{"$ref":"#/components/schemas/PolicyDecision","description":"Full decision including internal control hits (compliance only)."},"rules_considered":{"type":"integer","minimum":0},"note":{"type":"string"}}},"SnapshotResult":{"type":"object","required":["snapshot_id","pool_size","candidate_set_hash"],"properties":{"snapshot_id":{"type":"string","format":"uuid"},"pool_size":{"type":"integer","format":"int32"},"candidate_set_hash":{"type":"string"}}},"StaffRow":{"type":"object","required":["id","display_alias","roles","mfa_enrolled","active_sessions"],"properties":{"id":{"type":"string","format":"uuid"},"display_alias":{"type":"string"},"roles":{"type":"array","items":{"type":"string"}},"mfa_enrolled":{"type":"boolean"},"active_sessions":{"type":"integer","format":"int64"}}},"StatusChange":{"type":"object","required":["status"],"properties":{"status":{"type":"string","description":"open | pending_customer | pending_internal | escalated | resolved | closed"},"note":{"type":["string","null"]}}},"StatusCount":{"type":"object","required":["status","count"],"properties":{"status":{"type":"string"},"count":{"type":"integer","format":"int64"}}},"StepUpResult":{"type":"object","required":["step_up_valid_until"],"properties":{"step_up_valid_until":{"type":"string","format":"date-time"}}},"StoryRequest":{"type":"object","required":["body","consent"],"properties":{"body":{"type":"string"},"consent":{"type":"boolean","description":"Explicit opt-in to public sharing (never required)."}}},"SystemHealth":{"type":"object","required":["database_ok","outbox_pending","outbox_dead_lettered","provider_events_pending","provider_events_deferred","provider_events_exception","open_recon_exceptions"],"properties":{"database_ok":{"type":"boolean"},"outbox_pending":{"type":"integer","format":"int64"},"outbox_dead_lettered":{"type":"integer","format":"int64"},"oldest_pending_seconds":{"type":["integer","null"],"format":"int64"},"provider_events_pending":{"type":"integer","format":"int64"},"provider_events_deferred":{"type":"integer","format":"int64"},"provider_events_exception":{"type":"integer","format":"int64"},"worker_last_beat":{"type":["string","null"],"format":"date-time"},"open_recon_exceptions":{"type":"integer","format":"int64"}}},"ThanksRequest":{"type":"object","required":["message"],"properties":{"message":{"type":"string"}}},"ThanksResult":{"type":"object","required":["status"],"properties":{"status":{"type":"string","description":"`delivered` or `pending_review`. Never reveals the donor."}}},"TicketDetail":{"type":"object","required":["ticket","messages"],"properties":{"ticket":{"$ref":"#/components/schemas/TicketSummary"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/TicketMessage"}},"linked_payment":{"description":"Masked transaction context (staff view only)."}}},"TicketMessage":{"type":"object","required":["id","author_kind","body","internal","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"author_kind":{"type":"string"},"body":{"type":"string"},"internal":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}},"TicketSummary":{"type":"object","required":["id","subject","category","priority","status","sla_due_at","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"subject":{"type":"string"},"category":{"type":"string"},"priority":{"type":"string"},"status":{"type":"string"},"sla_due_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"TimelineEvent":{"type":"object","required":["event_type","actor_kind","created_at"],"properties":{"event_type":{"type":"string"},"from_status":{"type":["string","null"]},"to_status":{"type":["string","null"]},"actor_kind":{"type":"string"},"public_note":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}}},"TotpCode":{"type":"object","required":["code"],"properties":{"code":{"type":"string"}}},"TotpEnrollment":{"type":"object","required":["secret_base32","otpauth_uri"],"properties":{"secret_base32":{"type":"string","description":"Base32 secret, shown once for manual entry."},"otpauth_uri":{"type":"string"}}},"TrialBalanceRow":{"type":"object","required":["account_code","currency","debit_minor","credit_minor"],"properties":{"account_code":{"type":"string"},"currency":{"type":"string"},"debit_minor":{"type":"integer","format":"int64"},"credit_minor":{"type":"integer","format":"int64"}}},"UnmaskRequest":{"type":"object","required":["purpose_code","reason"],"properties":{"purpose_code":{"type":"string","description":"e.g. legal_request, fraud_investigation, chargeback_evidence, dsr_verification"},"reason":{"type":"string"},"case_ref":{"type":["string","null"]}}},"UnmaskedIdentity":{"type":"object","required":["user_id","verification_tier","access_logged_at"],"properties":{"user_id":{"type":"string","format":"uuid"},"email":{"type":["string","null"]},"email_masked":{"type":["string","null"]},"legal_name":{"type":["string","null"]},"verified_residence_country":{"type":["string","null"]},"verification_tier":{"type":"string"},"access_logged_at":{"type":"string","format":"date-time"}}},"UpdateLine":{"type":"object","required":["amount_minor"],"properties":{"amount_minor":{"type":"integer","format":"int64"}}},"UserRow":{"type":"object","required":["id","display_alias","status","roles","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"display_alias":{"type":"string"},"status":{"type":"string"},"declared_country":{"type":["string","null"]},"roles":{"type":"array","items":{"type":"string"}},"verification_tier":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}}},"Verification":{"type":"object","required":["tier","verified_adult"],"properties":{"tier":{"type":"string"},"verified_residence_country":{"type":["string","null"]},"verified_adult":{"type":"boolean"},"verified_at":{"type":["string","null"],"format":"date-time"}}},"VisibilityChange":{"type":"object","required":["public_identity_mode","acknowledge_prior_disclosure"],"properties":{"public_identity_mode":{"$ref":"#/components/schemas/IdentityMode"},"display_alias":{"type":["string","null"]},"acknowledge_prior_disclosure":{"type":"boolean","description":"Must be true: earlier public disclosures may already have occurred."}}},"WebhookAck":{"type":"object","required":["received","duplicate"],"properties":{"received":{"type":"boolean"},"duplicate":{"type":"boolean"}}}},"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Mobile (Flutter): session token from /auth/magic-link/consume with client=mobile, stored in Keychain/Keystore."},"session":{"type":"apiKey","in":"cookie","name":"bb_session","description":"Web: HttpOnly session cookie. Unsafe methods also require the X-CSRF-Token header (value of the bb_csrf cookie)."}}},"tags":[{"name":"Auth","description":"Magic link, password, sessions, TOTP MFA"},{"name":"Me","description":"Profile, privacy center, consents, giving history, DSR"},{"name":"Meta","description":"Public metadata, eligibility, verified impact, CMS"},{"name":"Discovery","description":"Sanitised public deck and intents"},{"name":"Basket","description":"Non-binding contribution intents"},{"name":"Checkout","description":"Privacy preview, policy evaluation, quotes, idempotent attempts"},{"name":"Requests","description":"Requester portal, evidence, recipient-safe contributions"},{"name":"Reviews","description":"Verification workspace and appeals"},{"name":"Risk","description":"Risk cases, freezes and reports"},{"name":"Finance","description":"Ledger, reconciliation, maker-checker refunds"},{"name":"Support","description":"Tickets"},{"name":"Compliance","description":"Country/corridor policy engine administration"},{"name":"Control","description":"Superadmin control plane"},{"name":"Organizations","description":"Sponsor organisations"},{"name":"Campaigns","description":"BeneMatch, BeneDrop, BeneCircle, Mystery Kindness"},{"name":"Webhooks","description":"Signed provider/partner inbox"},{"name":"Demo","description":"DEMO MODE ONLY helpers"}]}