treasury API

Treasury management canister for payment records and payout proposals.

Candid file: treasury/src/treasury.did

Types

PaymentType

type PaymentType = variant {
  Initial;   // First membership payment
  Renewal;   // Annual renewal payment
};

PaymentStatus

type PaymentStatus = variant {
  Succeeded;
  Failed;
  Pending;
};

PaymentRecord

type PaymentRecord = record {
  id: nat64;
  user_id: principal;
  amount: nat;
  currency: text;
  payment_type: PaymentType;
  status: PaymentStatus;
  stripe_payment_intent_id: text;
  receipt_number: opt text;
  payment_method_last4: text;
  timestamp: nat64;
};

Payment History

record_payment

Record a payment (called by oracle-bridge after Stripe confirmation).

"record_payment": (
  user_id: principal,
  amount: nat,
  payment_type: PaymentType,
  stripe_payment_intent_id: text,
  payment_method_last4: text,
  receipt_number: opt text
) -> (payment_id: nat64);

get_payment_history (query)

Get paginated payment history.

"get_payment_history": (
  user_id: principal,
  page: nat32,
  page_size: nat32,
  payment_type: opt PaymentType,
  from_date: opt nat64,
  to_date: opt nat64
) -> (vec PaymentRecord) query;

TypeScript Example:

const payments = await treasuryActor.get_payment_history(
  Principal.fromText(userId),
  0,    // page
  10,   // page size
  [],   // all payment types
  [],   // no from date filter
  []    // no to date filter
);

get_payment_count (query)

"get_payment_count": (
  user_id: principal,
  payment_type: opt PaymentType,
  from_date: opt nat64,
  to_date: opt nat64
) -> (nat64) query;

Session-Based Methods

For email/password authenticated users:

get_payment_history_with_session

"get_payment_history_with_session": (
  session_token: text,
  page: nat32,
  page_size: nat32,
  payment_type: opt PaymentType,
  from_date: opt nat64,
  to_date: opt nat64
) -> (variant { Ok: vec PaymentRecord; Err: text });

get_payment_count_with_session

"get_payment_count_with_session": (
  session_token: text,
  payment_type: opt PaymentType,
  from_date: opt nat64,
  to_date: opt nat64
) -> (variant { Ok: nat64; Err: text });

Payout Management

propose_payout

Create a payout proposal (governance required for execution).

"propose_payout": (recipient: principal, amount: nat, reason: text) -> (proposal_id: nat64);

approve_payout

Approve a pending payout (controller only).

"approve_payout": (proposal_id: nat64) -> ();

execute_payout

Execute an approved payout.

"execute_payout": (proposal_id: nat64) -> ();

Configuration

set_auth_service

Configure auth-service for session validation.

"set_auth_service": (principal) -> (variant { Ok; Err: text });

GDPR Compliance

cleanup_old_payments

Remove payments older than retention period (7 years).

"cleanup_old_payments": () -> (deleted_count: nat64);

Health Check

health (query)

"health": () -> (text) query;

Error Messages

Error	Cause	Resolution
Invalid session	Session token expired/invalid	Re-authenticate
Unauthorized	Not controller	Use authorized identity
Payment not found	Invalid payment ID	Check payment exists
Payout not approved	Trying to execute unapproved	Get approval first