Chapter 7: Financial Document Layer
The financial document layer is what makes Capxul a financial operating system, not just a payment tool. It produces three distinct document types, powers real-time dashboards, and generates configurable periodic reports. The document layer is the engine. The dashboard is the steering wheel. The reports are the rearview mirror.
Competitive Context: Why Not Request Network
Section titled “Competitive Context: Why Not Request Network”Request Network is the most recognized name in crypto invoicing. Capxul builds a competing product, not integrating with theirs.
Where they fall short for Capxul’s market:
- Invoice-first, not workflow-first. No concept of employment relationships, payment streams, or invoices as part of a larger financial workflow.
- No payroll awareness. No payslips, pay periods, or stream-to-document reconciliation.
- No financial intelligence. No dashboards, burn rate, AP aging, or reporting.
- Over-indexed on decentralization. IPFS storage and on-chain request creation add latency. Users in Lagos and Accra care about “did I get paid,” not IPFS.
- No off-ramp story. Payments end in crypto with no fiat conversion.
Capxul’s differentiation: the full loop from document creation through approval, on-chain payment, claiming, off-ramp, verifiable receipt, and live financial intelligence.
Unified Document Model
Section titled “Unified Document Model”All financial documents share a single data model distinguished by a type field.
Why a single model: One set of indexes, one access control pattern, one real-time subscription layer, one PDF generator, one audit trail. Every cross-cutting feature (search, export, on-chain anchoring, dashboard aggregation, reporting) is built once.
Three Types
Section titled “Three Types”| Type | Purpose | Created By | Lifecycle |
|---|---|---|---|
invoice | Request for payment from external party | Vendor/contractor (or org on their behalf) | draft -> submitted -> under_review -> approved -> payment_pending -> paid |
payslip | Periodic compensation record | System (auto-generated) | generated -> available |
receipt | Proof of payment on claim or transfer | System (auto-generated) | generated -> available |
Shared Fields
Section titled “Shared Fields”Document ID, type, amount (USDC), fiat equivalent, fiat currency code, exchange rate at time of recording, issuer (org), recipient, line items, status, creation timestamp, on-chain tx hash (populated after payment), document hash (for on-chain anchoring), organization ID.
Invoice-Specific Fields
Section titled “Invoice-Specific Fields”Invoice number, due date, payment terms (e.g., Net 30), purchase order reference, submission date, approval chain (list of approvers and timestamps).
Payslip-Specific Fields
Section titled “Payslip-Specific Fields”Stream ID, period start/end dates, gross accrued amount, total claimed during period, unclaimed balance at period end, pay period configuration reference.
Receipt-Specific Fields
Section titled “Receipt-Specific Fields”Claim transaction hash, source document reference (links back to the payslip or invoice this receipt settles).
Invoice Lifecycle
Section titled “Invoice Lifecycle”draft -> submitted -> under_review -> approved -> payment_pending -> paid | | v v disputed disputed| Status | Description |
|---|---|
| draft | Vendor composing. Not visible to org. |
| submitted | Sent to org. Visible in AP queue. |
| under_review | Approved spender reviewing. |
| approved | Approved for payment. Auto-triggers if within spending limit, escalates otherwise. |
| payment_pending | Safe module transaction submitted, awaiting on-chain confirmation. |
| paid | On-chain confirmed. Tx hash and document hash recorded. Terminal state. |
| disputed | From under_review (org disputes) or paid (post-payment). Requires resolution. |
Payslip and Receipt Lifecycles
Section titled “Payslip and Receipt Lifecycles”Both are simple: generated -> available. Payslips are auto-generated at period end from stream data. Receipts are auto-generated when a claim or payment is confirmed on-chain.
Immutability and Amendments
Section titled “Immutability and Amendments”All financial documents are immutable once generated. Corrections create a new amendment document with a supersedes field referencing the original. The original remains with its content and on-chain hash intact. Both exist permanently. The amendment is the current version.
This preserves audit trail integrity and ensures on-chain document hashes remain verifiable.
Progressive Disclosure
Section titled “Progressive Disclosure”All user types follow the same pattern. The platform asks for the minimum information needed for the current action.
Vendor/Contractor Ladder
Section titled “Vendor/Contractor Ladder”| Level | What’s Required | What’s Unlocked |
|---|---|---|
| 0 - No account | Magic link from org | View purchase orders, invoice templates (read-only) |
| 1 - Basic account | Email sign-up | Submit invoices, view payment status, see history |
| 2 - Payment-ready | Smart account or bank details | Receive funds |
| 3 - Full compliance | KYC completed | Required by org policy, jurisdiction, or volume threshold |
Employee Ladder
Section titled “Employee Ladder”| Level | What’s Required | What’s Unlocked |
|---|---|---|
| 0 - Added by org | Nothing | View payslips, stream status, financial summary |
| 1 - Claim-ready | Smart account setup | Claim accrued funds |
| 2 - Off-ramp configured | Bank/MoMo connection | Route claimed funds to fiat |
| 3 - Full compliance | KYC completed | Required by volume threshold or jurisdiction |
Design principle: Viewing documents and dashboards requires zero setup. Submitting documents requires minimal setup. Friction gates are on receiving money, not on participating in documentation or visibility. See Chapter 10 for how verification tiers map to these levels.