INV

Without an invoicing module, the gap between "did the work" and "got paid" lives in a spreadsheet, a Stripe dashboard, and somebody's memory. Multi-currency makes that gap worse (which rate? when? rounded how?). Vietnamese e-invoice requirements make it worse still (which Mẫu? which line item code? was the MST validated?). INV closes that gap with a single source of truth — one invoice row per billable event, one payment row per receipt, one aging report per close, and one webhook handler per payment rail — and exposes the same primitives as reusable skills so the patterns generalise.

INV is also part of the CyberSkill margin story: faster collection compresses DSO; multi-rail payment options improve customer experience; e-invoice automation avoids the 3-day round trip via the old VN paper-stamp process. Each is a small win that compounds.

Every cell traces back to PRD §9.16 and SRS §4.16.

INV composes three external systems (Stripe, Wise, Vietnamese payment stack), one e-invoice issuer (GDT via the vn-vat-invoice skill), and one rate source (SBV daily snapshot) into a single AR ledger. The diagram below shows the canonical invoice → payment lifecycle.

Internal components

Invoice + line items + payment + credit note are the core rows. Reminders are a side-table. FX rate snapshots are daily. Webhook event IDs carry a UNIQUE constraint so duplicate webhooks are no-ops.

Payment-rail comparison (P2 launch set)

Three surfaces: GraphQL subgraph for invoice/payment reads, REST admin for send/credit/void operations, MCP tool catalogue for the CUO/CFO-skill (draft dunning, narrate aging — never send without human approval).

GraphQL subgraph

extend schema
  @link(url: "https://specs.apollo.dev/federation/v2.5", import: ["@key", "@requiresScopes"])

type Invoice @key(fields: "id") {
  id: ID!
  number: String!
  customer: Customer!
  engagement: Engagement
  currency: String!
  subtotal: Money!
  vat: Money!
  total: Money!
  outstanding: Money!
  issuedAt: Date!
  dueAt: Date!
  status: InvoiceStatus!
  lineItems: [LineItem!]!
  payments: [Payment!]! @requiresScopes(scopes: [["inv.payment_read"]])
  pdfUrl: String!  # pre-signed S3
}

type Payment @key(fields: "id") {
  id: ID!
  invoiceId: ID!
  rail: PaymentRail!
  amount: Money!
  receivedAt: DateTime!
  status: PaymentStatus!
}

type CreditNote @key(fields: "id") {
  id: ID!
  invoiceId: ID!
  amount: Money!
  reason: String!
  issuedAt: Date!
}

type AgingReport {
  bucket0_30: Money!
  bucket31_60: Money!
  bucket61_90: Money!
  bucket90Plus: Money!
  total: Money!
  byCustomer: [CustomerAging!]!
}

enum InvoiceStatus { DRAFT SENT VIEWED PAID OVERDUE LATE ESCALATED VOID }
enum PaymentStatus { RECEIVED MATCHED RECONCILED REVERSED }
enum PaymentRail { STRIPE WISE VIETQR MOMO ZALOPAY VNPAY MANUAL }

type Query {
  invoice(id: ID!): Invoice
  invoices(customerId: ID, status: InvoiceStatus, since: Date): [Invoice!]!
  agingReport(asOf: Date): AgingReport!
    @requiresScopes(scopes: [["inv.aging_read"]])
}

type Mutation {
  draftInvoice(input: DraftInvoiceInput!): Invoice!
  sendInvoice(id: ID!): Invoice!
    @requiresScopes(scopes: [["inv.send"]])
  voidInvoice(id: ID!, reason: String!): Invoice!
    @requiresScopes(scopes: [["inv.void"]])
  issueCreditNote(input: CreditNoteInput!): CreditNote!
    @requiresScopes(scopes: [["inv.credit"]])
  approveDunning(reminderId: ID!): Reminder!
    @requiresScopes(scopes: [["inv.dunning_approve"]])
}

REST + webhook surface

MCP tool catalogue (CUO/CFO-skill)

Flow 1 — Draft invoice from TIME entries

Flow 2 — Send (with VN e-invoice via vn-vat-invoice skill)

Flow 3 — Stripe payment received + cash application

Flow 4 — VietQR collection (VN customer paying via bank)

Flow 5 — Dunning automation (drafts only · human send)

An invoice traverses up to eight states. Once sent, the invoice row is append-only — corrections happen via credit_note or by voiding and reissuing.

AR aging buckets

PRD §11.2.1 (performance) and §11.2.4 (reliability) bind on INV — especially payment reconciliation correctness.

INV reads from TIME, CRM, and AUTH; bridges to three skills (vn-vat-invoice, vn-mst-validate, vn-bank-transfer); integrates with four external rails (Stripe, Wise, VietQR/Napas247, GDT). Events flow to CRM via NATS.

INV is the tax-and-financial-records front door. Decree 123, Circular 78, and 10-year retention are non-negotiable for VN tenants.

INV's risks are largely about reconciliation correctness and webhook spoofing. The cash-application false-match risk is the highest single-incident risk.

INV health rolls up into 9 KPIs across AR efficiency, reconciliation accuracy, and compliance.

INV is operationally owned by CFO; AM drives per-engagement billing; CFO approves dunning; CTO owns reliability.

Admin CLI cyberos-inv for CFO/AM.

1. Draft an invoice

$ cyberos-inv invoice draft \
    --engagement acme-q2-2026 \
    --period 2026-04

[draft]   reading TIME entries for engagement acme-q2-2026 (2026-04)
[time]    47 entries · 168 hours
[engagement] rate=$150/hr · currency=USD · cap=N/A
[draft]   subtotal: $25,200.00
[draft]   vat:      $0.00 (USD invoice · no VN VAT)
[draft]   total:    $25,200.00
[invoice] INV-2026-04-001 · status=draft
[audit]   brain seq=16001

2. Send an invoice (VN tenant · e-invoice)

$ cyberos-inv invoice send --id INV-2026-04-005

[mst]     validating tenant MST: 0301234567 ✓
[mst]     validating customer MST: 0307654321 ✓
[vn-vat]  generating Mẫu 01/GTGT XML (Circular 78)
[gdt]     submitting to Tổng cục Thuế…
[gdt]     accepted · message_id = GDT-2026-04-9F3E2A1B
[pdf]     deterministic render via tectonic
[s3]      archived to s3://inv/2026/04/INV-2026-04-005.pdf (immutable 10y)
[email]   sent to ke-toan@acme.vn
[nats]    inv.invoice.sent published
[status]  sent
[audit]   brain seq=16011

3. Generate VietQR for an invoice

$ cyberos-inv vietqr --invoice INV-2026-04-005

[vn-bank-transfer skill]
  account:    0307654321 @ BIDV
  amount:     45,000,000 VND
  addInfo:    INV-2026-04-005
  qr:         00020101021238…6304abcd
[image]     vietqr-INV-2026-04-005.png (240×240)
[expected_settlement] instant via Napas247

4. AR aging report

$ cyberos-inv aging --as-of 2026-05-14

[AR aging report · 2026-05-14]

bucket          amount (USD eq)   invoices
  current       $48,200            12
  0-30 overdue  $12,400             3
  31-60         $ 4,800             1
  61-90         $   800             1
  90+           $   200             1
  ─────────    ────────────       ───
  total         $66,400            18

[top overdue]
  INV-2026-02-003 acme corp        $4,800   45 days
  INV-2025-12-007 globex industries $800   71 days
  INV-2025-11-012 initech           $200  120 days

5. Approve dunning emails

$ cyberos-inv dunning list --status drafted

[3 reminders awaiting approval]
  rem-id    invoice          kind   amount   age
  R-001     INV-2026-04-001  T+7    $25,200   8d
  R-002     INV-2026-03-007  T+30   $ 8,400  34d
  R-003     INV-2025-11-012  esc.   $   200 120d

$ cyberos-inv dunning approve --reminder R-001 --cfo-sign

[approved]  cfo: hoa@cyberskill.com ✓
[sent]      email delivered to ar@acme.com
[audit]     brain seq=16031

6. Manual cash application

$ cyberos-inv cash-app match \
    --payment pay_01HZJ8… \
    --invoice INV-2026-04-005 \
    --reason "addInfo missing but bank ref matches"

[match]    payment pay_01HZJ8… → INV-2026-04-005
[update]   invoice.outstanding 45M VND → 0
[update]   invoice.status     sent → paid
[nats]     inv.payment.received published
[audit]    brain seq=16041

7. Issue credit note

$ cyberos-inv credit-note issue \
    --invoice INV-2026-04-001 \
    --amount 1200 \
    --currency USD \
    --reason "scope reduction agreed with customer"

[credit-note] CN-2026-04-001 issued
[invoice]     INV-2026-04-001 outstanding: $25,200 → $24,000
[audit]       brain seq=16051