Payments & Monetization
Relevant source files
The following files were used as context for generating this wiki page:
The Payments & Monetization system in the TAMV ecosystem manages the economic lifecycle of users, ranging from fiat currency transactions via Stripe to the internal circulation of TAU credits. This module is a critical component of the DM-X4-05 Economy domain, ensuring that subscriptions, one-time purchases, and peer-to-peer transfers are handled with strict idempotency and architectural isolation.
The system facilitates the conversion of external currency into TAU credits, which are used for premium features such as gifts, special access, and ecosystem services. It integrates directly with Supabase Edge Functions for secure payment processing and utilizes a unified API for internal wallet management.
Sources: 02_MODULOS/M04_ECONOMIA/INTERNO/MARKETPLACE-TAU-SPEC.md:1-5, PLAN-TAMV-MODULAR.md:104-108
Economic Architecture & TAU Credits
The economy is built around the TCEP (Transversal Civilizatory Economy Protocol), which governs wallets and transactions. The primary internal currency is TAU. Users acquire TAU through the Marketplace via Stripe integrations or earn it through ecosystem participation.
Sources: supabase/functions/tamv-unified-api/index.ts:108-112, PLAN-TAMV-MODULAR.md:109-113
Transaction Lifecycle
The flow of funds follows a strict path from external payment providers to the internal ledger.
Payment Processing Integration
The system uses Stripe for both recurring subscriptions (memberships) and one-time credit purchases.
Stripe Checkout Configuration
The create-checkout Edge Function acts as the secure bridge. It performs user verification, retrieves or creates a Stripe Customer ID associated with the user's profile, and generates a dynamic checkout session.
Sources: supabase/functions/create-checkout/index.ts:15-85
| Parameter | Type | Description |
|---|---|---|
priceId | string | The identifier for the product/package (e.g., price_starter, price_pro). |
credits | number | The amount of TAU credits to be granted upon successful purchase. |
packageName | string | Human-readable name of the package. |
userId | uuid | The unique identifier of the user making the purchase. |
| Sources: supabase/functions/create-checkout/index.ts:60-65 |
Tiered Pricing Structures
The system defines specific pricing tiers for TAU credit packages:
- Starter: $4.99
- Popular: $19.99
- Pro: $49.99
- Elite: $144.99
Sources: supabase/functions/create-checkout/index.ts:109-115
Internal Economy Management
Internal movements of TAU are handled via the tamv-unified-api. This includes peer-to-peer transfers, gift consumption, and commission calculations.
Peer-to-Peer Transfers
Users can transfer TAU credits to other users. The system checks the sender's balance, generates a unique evidence hash for the transaction, and logs the event in the MSR (Master System Registry).
Sources: supabase/functions/tamv-unified-api/index.ts:117-142
Commission Logic
The platform applies variable commission rates based on the user's membership level. These rates are used for secondary transactions like marketplace sales or gift rewards.
| Membership Level | Commission Rate |
|---|---|
| Free | 30% |
| Premium / Gold Plus | 10% |
| VIP | 20% |
| Elite / Gold | 12% - 15% |
| Celestial / Enterprise | 8% - 10% |
| Sources: supabase/functions/tamv-unified-api/index.ts:155-161 |
Idempotency and Reliability
To prevent duplicate processing of payments, the system implements a strict idempotency check for Stripe webhooks using a dedicated table processed_stripe_events.
Sources: 02_MODULOS/M04_ECONOMIA/INTERNO/MARKETPLACE-TAU-SPEC.md:46-52
Security and Governance Restrictions
The economic system is subject to "Hardening" and Constitutional restrictions defined in QC-TAMV-01.
- DAO Exclusion: DAOs (Decentralized Autonomous Organizations) are explicitly prohibited from modifying economic parameters such as commissions, TAU distribution algorithms, or membership prices.
- Auditability: All economic logic must provide explicit UI transparency to avoid "Hidden Economy" violations.
Sources: 02_MODULOS/M04_ECONOMIA/INTERNO/MARKETPLACE-TAU-SPEC.md:79-88, eslint-plugin-tamv/index.js:314-330
Implementation Status
| Feature | Status | Target Metric |
|---|---|---|
| Stripe Webhook Idempotency | ✅ Implemented | 0% Duplicate Processing |
| TAU peer-to-peer Transfer | ✅ Implemented | Transaction < 500ms |
| Membership Tier Updates | ✅ Implemented | 100% Ledger Consistency |
| TEE Audit for Payments | ❌ Pending | Mandatory Attestation |
| Sources: PLAN-TAMV-MODULAR.md:162-175, 02_MODULOS/M04_ECONOMIA/INTERNO/MARKETPLACE-TAU-SPEC.md:70-76 |
The Payments & Monetization module provides the foundation for the TAMV digital economy by bridging fiat currency with the internal TAU credit system through secure, idempotent processing and strict architectural governance.