Commission Payment Gateway

WooCommerce commission and merchant payout automation for a perfume store.

This plugin is designed around a strict accounting model:

• commission is locked from the original qualifying subtotal
• commission is not recalculated from later order edits, refunds, or chargebacks
• the plugin keeps an internal SQLite ledger as the source of truth for financial events
• merchant payout processing is separate from order state and is retryable
• sensitive ledger access is primarily operational and WP-CLI driven

Architecture

The intended implementation follows this layout:

• src/Bootstrap/ plugin bootstrapping and service wiring
• src/Admin/ settings and operational status pages
• src/CLI/ WP-CLI commands
• src/Database/ SQLite connection and migrations
• src/Domain/ commission, payout, and eligibility rules
• src/Ledger/ SQLite ledger repository and audit trail
• src/Payout/ payout coordinator and provider abstractions
• src/Security/ capabilities, roles, and permission checks
• src/WooCommerce/ WooCommerce hooks and order integration

The ledger is stored in a private SQLite database file controlled by the plugin. WooCommerce orders remain in WordPress/MySQL; only immutable financial events are persisted in SQLite.

Core Workflow

1. WooCommerce marks an order as paid.
2. The plugin checks whether the order is eligible for commission locking.
3. The original qualifying subtotal is captured and commission is locked.
4. A ledger entry is written to SQLite with immutable values.
5. The payout workflow is queued asynchronously.
6. The payout provider sends the merchant payout.
7. Every state transition is recorded in the SQLite audit trail.

Commission Rules

• Default commission rate: 8%
• Commission basis: original qualifying product subtotal at lock time
• Commission does not change because of:
  • discounts
  • returns
  • refunds
  • chargebacks
  • order edits
  • processing fees

Qualifying products are intended to support:

• all products
• products with a specific meta flag
• products in selected categories

Capabilities

The plugin is designed around custom capabilities instead of hardcoded administrator checks.

Expected capabilities include:

• manage_perfume_payout_settings
• view_perfume_ledger_summary
• view_perfume_ledger_detail
• manage_perfume_payouts
• run_perfume_reconciliation
• export_perfume_ledger
• use_perfume_cli_sensitive_ops

Admin pages, manual actions, and CLI-sensitive operations should enforce these capabilities plus nonce or confirmation checks where appropriate.

SQLite Ledger

The SQLite database is the authoritative store for:

• ledger entries
• payout attempts
• payout state transitions
• retry counters
• errors
• audit events
• reconciliation snapshots

Expected tables:

• ledger_entries
• payout_events
• audit_log

The SQLite store should be kept in a plugin-controlled private path and hardened against accidental web access.

Docker-Based Local Setup

The recommended local workflow is Docker-first so the same PHP and SQLite extensions are available everywhere.

Typical services:

• a custom WordPress PHP 8.2 Apache image with pdo_sqlite enabled for plugin runtime
• MariaDB for normal WordPress content storage
• a CLI/test container with Composer, Pest, WP-CLI, and PDO SQLite enabled

Typical flow:

1. Start the stack with Docker Compose.
2. Let the one-shot site-init container provision WordPress, WooCommerce, and activate this plugin into the shared volume.
3. Run Composer install inside the PHP/CLI container.
4. Run Pest inside the same container.
5. Use WP-CLI from the container for operational checks.

If this repository includes Docker files, the common pattern is:

docker compose up -d --build
docker compose run --rm tools composer install
docker compose run --rm tools vendor/bin/pest
docker compose run --rm tools wp plugin status commission-payment-gateway --path=/var/www/html

Default local site credentials after docker compose up -d --build:

• URL: http://localhost:8080
• Admin user: admin
• Admin password: admin1234

WP-CLI

The plugin is expected to expose a perfume-ledger command namespace.

Examples:

wp perfume-ledger status
wp perfume-ledger list
wp perfume-ledger show 123
wp perfume-ledger retry-payout 42
wp perfume-ledger export --format=csv
wp perfume-ledger reconcile
wp perfume-ledger lock-order 123
wp perfume-ledger payout-order 123
wp perfume-ledger audit-log --limit=100

Operational rules:

• all CLI actions should be recorded in the audit log
• sensitive operations should require capability checks or explicit confirmation flags
• command output should support table and JSON-friendly formats where useful

Payout Provider

The payout layer is built around a provider interface so payment rails can change later without rewriting ledger logic.

Expected abstractions:

• PayoutProviderInterface
• PayPalPayoutProvider

PayPal support should include:

• sandbox and live mode support
• credentials in plugin settings
• recipient configuration
• request/response logging with sanitization
• idempotency handling where possible
• clear retry and failure handling

Testing

Pest is the expected test framework.

Core test coverage should include:

• commission calculation
• order eligibility detection
• immutable ledger snapshots
• payout state transitions
• duplicate prevention and idempotency
• retry behavior
• capability enforcement
• CLI command behavior
• SQLite repository behavior
• payout provider abstraction behavior
• audit logging behavior

Suggested structure:

• tests/Unit
• tests/Feature
• tests/Integration

Run tests from the Docker container that has PHP extensions and SQLite enabled:

docker compose run --rm tools composer test

Production Notes

Before production use:

• verify the SQLite path is private and writable
• validate WooCommerce status hooks against the merchant's order flow
• confirm capability mapping for each delegated role
• verify PayPal credentials and sandbox/live environment settings
• test duplicate payout prevention with real retry scenarios
• confirm logs do not expose secrets or full payment payloads