Skip to main content

Invoices Lifecycle

This page defines invoice behavior shared across product layers.

Invoice Status​

  • pending: waiting for payment
  • completed: payment detected (balance >= requiredRaw)
  • cancelled: manually deleted or expired without payment
  • withdrawn: funds moved from payment address to owner

Lifecycle Flow​

  1. Create invoice
  • Client flow: POST /invoices
  • Integration flow: POST /integration/invoices
  1. Payment tracking
  • Background monitor checks balances periodically.
  • Manual status checks can trigger immediate re-check.
  1. Completion and withdrawal
  • When funds satisfy required amount, invoice becomes completed.
  • Invoice may enter withdrawal queue based on backend policy.
  • After confirmed transfer to owner, invoice is withdrawn.
  1. Cancel or expiration
  • Soft delete sets invoice to cancelled and removes active monitoring.

Important Fields​

  • requiredRaw: required amount in raw token units
  • balanceRaw: current paid amount in raw token units
  • metaBalance: human-readable balance snapshot
  • lastCheckedAt: last on-chain check timestamp

Operational Notes​

  • A previously withdrawn invoice can be re-queued if new qualifying funds arrive.
  • Always use string/BigInt for on-chain values in clients.