3neti/x-commerce

x-commerce

x-commerce is the commercial architecture and knowledge system for packaging, pricing, licensing, metering, and sustaining outcomes delivered through the x-change ecosystem.

This package is the source of truth for versioned Pay Code pricing and deterministic commercial allocation. It also owns the commercial vocabulary, stakeholder incentives, projection assumptions, money-flow categories, and software boundaries needed to turn value-bearing executions into sustainable commercial offerings.

Foundational Axioms

The instruction is the transaction.
The transaction is the product.
The product is the business.

The customer is purchasing an outcome, not a software feature.

What This Package Is

x-commerce is a reusable package for commercial architecture. Its runtime primitives own versioned catalogs, quote instruction items, expose a throttled read-only quote endpoint, capture immutable sale snapshots, and calculate a first-class Commercial Waterfall. Consuming applications remain responsible for authorization, quote acceptance, persistence, accounting entries, and money movement.

The first documented ecosystem is the proposed RBAP Digital Banking Program, a rural-bank digital services program introduced through the Rural Bankers Association of the Philippines. RBAP is the first subject, not the package boundary.

What This Package Is Not

x-commerce is not:

• a deployable customer application;
• a customer-facing cart, checkout, order, invoice, or billing application;
• a bank integration package;
• a NetBank integration package;
• a replacement for x-legal;
• a source of legal, regulatory, banking, accounting, or tax conclusions;
• evidence that RBAP, NetBank, ODTI, 3neti, or any rural bank has accepted a proposed arrangement.

Relationship To Adjacent Systems

The current commercial chain is documented as a proposed architecture:

3neti
    owns and develops the intellectual property
        |
ODTI
    licenses and commercially operates the technology
        |
Participating rural banks
    obtain licenses through ODTI
        |
Depositors, employers, remitters, merchants, government agencies,
and other customers consume rural-bank-branded digital services

x-change answers how a value-bearing instruction is represented, authorized, executed, completed, and evidenced.

x-commerce answers how an outcome is packaged, priced, licensed, sold, metered, commissioned, and made commercially sustainable.

x-legal owns legal characterization, regulatory dependencies, legal traceability, and counsel-facing questions. x-commerce records commercial assumptions and hands legal questions to x-legal instead of settling them locally.

Applications such as x-Payout assemble execution capabilities and approved commercial primitives, once they exist, into deployable products for specific customers.

Runtime Boundary

The package owns:

• the versioned Pay Code commercial catalog;
• deterministic instruction quotes;
• the structured quote contract and HTTP estimate endpoint;
• immutable commercial sale snapshots; and
• pure allocation plans for provider cost, product revenue, partner commission, commercial revenue, and beneficiary principal.

The package does not own:

• Account or Treasury Position posting;
• provider calls or settlement;
• mutable balances;
• issuance authorization; or
• delivery orchestration.

Those effects belong to the consuming settlement system. This keeps the same quote reproducible without allowing a pricing package to move money.

Quote API

Laravel applications that install the package receive a read-only estimate route:

POST /api/x/v1/quotes

The request supplies a catalog reference, currency, and catalog line references with quantities. The response includes the selected catalog version, deterministic snapshot hash, quote reference, line totals, and total minor-unit amount. The endpoint is throttled and cannot accept a quote, authorize payment, issue a Pay Code, or release funds.

x-change translates Pay Code instructions into this contract and preserves the returned quote metadata when it accepts a checkout. A host application may expose a different public prefix through x-commerce.routes.api_prefix, but the default is api/x/v1.

Installation

composer require 3neti/x-commerce:^1.0

Laravel discovers XCommerceServiceProvider automatically. Publish the catalog only when the application intentionally needs to override it:

php artisan vendor:publish --tag=x-commerce-config

Catalog versions become immutable once referenced by an accepted sale snapshot. Create a new catalog version instead of rewriting historical prices.

The consuming host owns the Payment Operations console and its protected pricing management surface. Publishing a complete catalog version makes it effective for new estimates immediately; historical quote and sale snapshots retain their original version and hash.

Compatibility

• PHP 8.2, 8.3, and 8.4
• Illuminate 11, 12, and 13

The calculation layer is framework-independent. Laravel integration is limited to package discovery and configuration.

Documentation Map

• Compass: canonical orientation.
• Architecture: knowledge architecture and future software boundaries.
• Commercial Component Offerings Functional Specification: target behavior for priced instruction components, recipient provisioning, accrual, and settlement.
• Grammar: commercial vocabulary and usage discipline.
• Assumptions Register: traceable working assumptions.
• Commercial Model Register: model inventory.
• RBAP Digital Banking Program: first ecosystem.
• Stakeholders: "What's in it for me?" views.
• Economics: pricing, revenue, cost, and projection models.
• Products: outcome-centered productization.
• Operations: deployment and managed operations.
• Legal Dependencies: handoffs to x-legal.
• Partner Participation: non-binding participation models.
• Decisions: commercial architecture decision records.
• Templates: reusable drafting formats.