NAiOS Wallet
walletv0.2.0Payments as a service (Connect-as-a-service): connected Stripe accounts, split charging (commission + net), payouts, and ledger. Payment engine for the NAiOS Academy marketplace.
Description
NAiOS Wallet is the payment engine of the platform: a payment service like Stripe Connect-as-a-service that other plugins consume in process (currently NAiOS Academy). What it does: • Connected accounts (Stripe Connect Express): onboarding via AccountLink and real-time status synchronized from Stripe (charges/payouts enabled → active). • Split charging: each sale points to the platform's commission and the net amount for the beneficiary; supports multi-actor split (co-teachers of a course, speakers of an event). • Payouts: the seller withdraws their available balance via transfer to the connected account. • Ledger in cents: earned / available / paid balance, with configurable default commission. • Traceability: each payment retains a readable origin and a URL to the source resource (the panel links to the sale). • Provider stitching: 'simulated' in dev (works without keys, instant onboarding) ↔ 'stripe-connect' real; if it doesn't have its own key, it reuses the one from the billing plugin. Security: keys never reach the browser and payouts require an active payment account. In-process API: recordSale / recordSaleSplit / payeeBalance / onboard / accountStatus. Web/QR TPV and Tap to Pay are reserved for later phases.
Features (8)
Onboarding via AccountLink and real-time status synchronized from Stripe: the account becomes active when charges and payouts are enabled.
Each sale separates the platform's commission from the net amount for the beneficiary; supports multi-actor split among several payees.
The seller withdraws their available balance via transfer to the connected account; in dev, it settles instantly.
Earned / available / paid balance per beneficiary, with configurable default commission.
Each payment retains a readable origin (e.g. 'Course: ...') and a URL to the source resource; the panel links to the sale.
'simulated' in dev (without keys) ↔ 'stripe-connect' real. If it doesn't have its own key, it reuses the one from billing.
Other plugins consume recordSale / recordSaleSplit / payeeBalance / onboard / accountStatus without HTTP.
Keys never reach the browser; payouts require an active payment account.
Changelog
- REAL 'stripe-connect' provider: Express onboarding (accounts.create + AccountLink), accountStatus via accounts.retrieve and payout via transfer to the connected account
- Key fallback: if the wallet does not have stripe_secret_key, it reuses the one from the billing plugin (same sandbox/production account, without duplication)
- Account status synchronization upon returning from onboarding (pending → active) and real redirection to Stripe from the UI
- Traceability: new ref_url column in the ledger; the Origin column in the panel links to the source resource of each sale
- Smoke tests of the provider + key resolution (mock of the SDK, without network)
- F1 lean: Connect-as-a-service in 'simulated' mode — connected accounts, split charging (commission + net) and payouts ledger
- In-process service API consumed by NAiOS Academy
- Seller panel: account status, balance (earned/available/paid), payout, and sales