English · Русский

CommerceXL

Composable commerce backend foundation for the Orcestr ecosystem.

CommerceXL provides reusable catalog, order, balance and payment primitives for FastAPI, Pydantic 2 and SQLAlchemy 2 applications. The host application owns the database engine, sessions, users, authentication, CSRF policy, migrations and provider-specific callback routes.

Status

What Is Included

CommerceXL does not include a frontend, wallet integration, blockchain verifier or payment-provider credentials. Those belong in separate provider packages and host adapters.

Installation

pip install commercexl

Optional development dependencies:

pip install "commercexl[test]"
pip install "commercexl[dev]"

Quick Start

from decimal import Decimal

from commercexl import (
    BaseConfig,
    CommerceModule,
    DefaultOrderItemService,
    HandMadePaymentService,
    PaymentConfigBuilder,
    PaymentProviderRegistration,
    ProductOrderConfig,
    ProductOrderConfigBuilder,
)


class ProjectCommerceConfig(BaseConfig):
    PAYMENT_SYSTEMS = {"USD": ("handmade",)}
    MIN_TOP_UP_AMOUNTS = {"USD": Decimal("1")}
    CREDITS_CONVERTERS = {"USD": Decimal("10000")}


commerce = CommerceModule(
    config_class=ProjectCommerceConfig,
    product_orders=ProductOrderConfigBuilder(
        ProductOrderConfig(MyProductService, DefaultOrderItemService),
    ),
    payments=PaymentConfigBuilder(
        PaymentProviderRegistration(
            system="handmade",
            provider_kind="handmade",
            factory=HandMadePaymentService,
        ),
    ),
    public_base_url="https://commerce.example.com",
)

Provider registration is strict. A duplicate normalized system, a missing provider referenced by PAYMENT_SYSTEMS, or a factory returning the wrong service type fails during module construction.

FastAPI Integration

The host supplies an authenticated actor dependency and a mandatory mutation guard. For cookie-authenticated applications, the mutation guard is the host CSRF dependency.

from fastapi import Depends
from commercexl import CommerceHTTPConfig, CommerceUserActorDTO, create_router


async def get_commerce_actor(user=Depends(get_current_user)) -> CommerceUserActorDTO:
    return CommerceUserActorDTO(id=user.id, permissions=frozenset(user.permissions))


app.include_router(
    create_router(
        CommerceHTTPConfig(
            get_db_session_dependency=get_db_session,
            get_current_actor_dependency=get_commerce_actor,
            get_mutation_guard_dependency=check_csrf,
            get_commerce_module=lambda: commerce,
        ),
    ),
    prefix="/api/v1",
)

The checkout is intentionally two-phase:

1. POST /orders/ creates a server-priced order and requires Idempotency-Key.
2. GET /orders/{order_id}/payment-options/ returns options available to that actor and order.
3. POST /orders/{order_id}/payment-attempts/ accepts only payment_option_id and another Idempotency-Key.
4. GET /payments/{payment_public_id}/ returns authoritative state without issuing a secret.
5. POST /payments/{payment_public_id}/checkout-action/ issues a fresh provider action.

Amounts are Decimal in Python and decimal strings in JSON. The client cannot submit the final payment amount, commercial currency or arbitrary provider system when creating an attempt.

Provider Contract

Provider packages implement AbstractPaymentService or AbstractCallbackPaymentService and are registered through PaymentProviderRegistration. The stable provider-facing imports include PaymentCreateContext, PaymentCreateResult, PaymentOption, CheckoutAction, PaymentVerificationResult and PaymentState.

The canonical PaymentORM is the extension root for provider child tables. Providers do not mutate orders or mark them paid directly. A trusted callback/reconciliation adapter returns a typed verification result and passes it to PaymentRuntime.apply_verification(...) in the current DB session.

Checkout capability URLs and transaction-request bearer values must be issued by get_action(...); CommerceXL persists only non-secret action metadata. Safe provider evidence is claimed globally and payment changes write PaymentOutboxEventORM in the same transaction.

Database Migrations

CommerceXL does not ship application migrations. Add its metadata to the host Alembic setup and generate/review migrations in the host repository:

from commercexl import CommerceBase
from my_project.db import Base

target_metadata = [Base.metadata, CommerceBase.metadata]

Version 0.3 is a deliberate breaking schema/API release. Follow the 0.2 to 0.3 migration guide before upgrading production data.

Documentation

• Integration guide
• 0.3 migration guide
• Promocodes
• Gift certificates
• Release guide

Development

uv sync --all-extras
uv run pytest -q
uv build

License

Licensed under the Mozilla Public License 2.0. Commercial use is permitted; changes to MPL-covered files remain subject to the MPL. See NOTICE and TRADEMARKS.md.

Orcestr Ecosystem

• Orcestr
• Orcestr Auth
• Orcestr UI
• Orcestr OS