Athenian OwlPay

Developer starting point

This baseline documents OwlPay’s financial architecture and integration seams. It does not claim that any payment, payout, provider callback, or ledger mutation has been exercised.

Admin Workflow

Operator Payout Workflow

1. Review payees under OwlPay > Payees.
2. Confirm each payee has the correct email, currency, default method, and payout method record.
3. Review payable entries under OwlPay > Ledger.
4. Use vendor or affiliate views for specialized payout context.
5. Queue payouts for eligible balances.
6. Execute queued payouts from OwlPay > Payouts.
7. Review status, external reference, and error metadata after execution.
8. Use logs, ledger rows, payout items, and provider metadata for reconciliation.

Vendor PO Workflow

1. A dropship/vendor PO reaches an eligible state, such as shipped or closed.
2. OwlPay resolves or creates the vendor payee.
3. OwlPay credits the vendor payable amount to the ledger.
4. The credit becomes available immediately or after hold/eligibility logic.
5. Operator queues a vendor payout from the vendor screen or payout workflow.
6. OwlPay reserves ledger rows and creates a payout batch.
7. Operator executes the payout manually or through an adapter.

Frontend Payee Workflow

1. User visits a page containing an OwlPay payout setup shortcode or the WooCommerce My Account OwlPay endpoint.
2. User logs in or registers if shortcode registration is allowed.
3. OwlPay ensures a linked People record and person payee context.
4. User provides contact, billing, legal, tax classification, and payout method data.
5. OwlPay saves the payment profile through the Social Users integration.
6. User can review balances, transfer activity, payout history, and request payout when eligible.

Subscription Renewal Payment Workflow

1. APS owns subscription scheduling and renewal order generation.
2. APS emits renewal payment hooks.
3. OwlPay validates the stored WooCommerce token against the order customer.
4. A configured recurring payment processor attempts the off-session charge.
5. OwlPay records payment result metadata on the renewal order and subscription.
6. Successful orders are marked paid; failed subscription payments can move to payment-failed status.

---

Technical Architecture

Boot Flow

The root plugin file defines plugin constants, loads the PSR-like autoloader, registers activation/deactivation hooks, and boots the singleton Athenian\OwlPay\Plugin on plugins_loaded.

During boot, the plugin:

1. Defines ATH_OWLPAY_LOADED.
2. Loads optional Secure API credential integration.
3. Instantiates settings and database services.
4. Installs/upgrades database tables idempotently.
5. Instantiates payee, method, ledger, payout, adapter, finance, admin, REST, frontend, and CLI services.
6. Seeds finance default accounts.
7. Registers optional integrations for Subscriptions, WC Dropship, Affiliates, and Social Users.
8. Registers ledger credit/debit hooks.
9. Fires ath_owlpay_loaded for downstream extensions.

Main Services

| Service/Class | Purpose | | --- | --- | | Plugin | Singleton service container and boot coordinator. | | Settings | Stores plugin settings under ath_owlpay_settings. | | DB | Defines and installs legacy payout tables and finance-core tables. | | Payees | Resolves, lists, and updates payee records. | | PayeeMethods | Manages per-payee payout methods and defaults. | | Ledger | Creates, updates, deletes, lists, and balances payee ledger entries. | | Payouts | Creates payout batches, reserves ledger items, executes adapters, finalizes/releases entries. | | Adapters | Registry for payout execution adapters. | | Admin | WordPress admin menu, dashboard, settings, payees, ledger, payouts, vendors, affiliates. | | Frontend | WooCommerce My Account endpoint, payout profile shortcodes, user dashboard, payout request handler. | | REST | Health route and generic webhook entry points. | | CLI | WP-CLI commands for installation, diagnostics, finance sync, balance refresh, and payout execution. | | Finance\Accounts | Chart of accounts and account mappings. | | Finance\Entities | Financial entity records and external references. | | Finance\Journals | Balanced journal entry creation. | | Finance\PostingEngine | Posting-rule orchestration for finance events. | | Finance\Balances | Materialized account/entity balance refresh. | | Finance\LegacyBridge | Mirrors legacy ledger/payout records into financial-core journals. |

---

Database Model

OwlPay creates a fairly broad database footprint because it includes both current payout-operation tables and Phase 1 finance-core tables.

Operational Payout Tables

| Table | Purpose | | --- | --- | | wp_ath_owlpay_payees | Canonical payee registry keyed by payee type and foreign ID. | | wp_ath_owlpay_payee_methods | Canonical per-payee payout method records. | | wp_ath_owlpay_methods | Legacy method table retained for backwards compatibility and migration. | | wp_ath_owlpay_ledger | Payee payable ledger entries, including credits/debits, availability, source references, and status. | | wp_ath_owlpay_payouts | Payout batch/execution records with method, totals, status, external ref, errors, and meta. | | wp_ath_owlpay_payout_items | Join table between payout rows and consumed/reserved ledger rows. | | wp_ath_owlpay_logs | Operational logging for payout, webhook, finance, and bridge events. |

Finance-Core Tables

| Table | Purpose | | --- | --- | | wp_ath_owlpay_financial_accounts | Chart of accounts with codes, slugs, account types, normal balance, hierarchy, and system keys. | | wp_ath_owlpay_financial_account_mappings | Maps plugins/events/entities/integrations to default accounts. | | wp_ath_owlpay_financial_entities | General financial actors beyond payout-only payees. | | wp_ath_owlpay_financial_entity_refs | External/source references for financial entities. | | wp_ath_owlpay_journal_entries | Journal entry headers with UUID, status, source provenance, idempotency key, and metadata. | | wp_ath_owlpay_journal_lines | Balanced debit/credit lines by account and financial entity. | | wp_ath_owlpay_account_balances | Materialized balances per account/entity/currency. |

---

Payout States and Ledger Behavior

Ledger Concepts

• credit entries increase payee payable balance.
• debit entries reduce payee payable balance.
• available_at determines when a ledger row can be included in a payout.
• source_type and source_id preserve provenance, such as a PO/vendor payable source.
• Mutable entries can be updated or deleted only when they are not already linked to payout items.

Payout Concepts

• Payout rows are grouped by batch_key.
• A payout stores method, funding source, subtotal, fee, total, currency, status, external reference, error message, and metadata.
• Payout items link payout rows to ledger rows.
• Successful execution marks payout status sent and finalizes linked ledger rows.
• Failed execution marks payout status failed and releases reserved ledger rows.

---

Shortcodes and Frontend Surface

| Shortcode | Purpose | | --- | --- | | [ath_owlpay_people_account] | Inline or modal People-linked payout account form. | | [ath_owlpay_payment_profile] | Alias for People payout profile setup. | | [ath_owlpay_payout_onboarding] | Alias for payout onboarding. | | [ath_owlpay_user_dashboard] | Logged-in payout/account dashboard. |

Useful Shortcode Patterns

[ath_owlpay_people_account]

[ath_owlpay_people_account modal="1" button_label="Set up payouts"]

[ath_owlpay_people_account methods="paypal_payouts,manual" show_balance="1"]

[ath_owlpay_user_dashboard]

Common Shortcode Attributes

| Attribute | Notes | | --- | --- | | modal | 1 renders a button/modal flow; default is inline. | | button_label | Controls modal button label. | | title | Controls form title. | | allow_registration | Allows logged-out user registration when enabled. | | show_balance | Shows available balance for logged-in users. | | methods | Comma-separated allowed methods, such as paypal_payouts,manual. |

---

REST Routes and Webhooks

Registered REST Routes

| Route | Method | Purpose | | --- | --- | --- | | /wp-json/ath-owlpay/v1/health | GET | Returns status, plugin version, and current GMT time. | | /wp-json/ath-owlpay/v1/webhook/stripe | POST | Generic Stripe webhook action bridge. | | /wp-json/ath-owlpay/v1/webhook/paypal | POST | Generic PayPal webhook action bridge. |

Included PayPal Webhook Receiver

The package includes Athenian\OwlPay\Webhooks\PayPal, which is designed to register the same PayPal webhook path, verify webhook signatures through PayPal, extract payout_batch_id, update matching OwlPay payout rows by external_ref, and log outcomes.

Implementation note: confirm whether Webhooks\PayPal::boot() is invoked in the target deployment, because the current main plugin boot path visibly registers generic webhook routes through REST, while the dedicated signature-verifying receiver is packaged separately.

---

WP-CLI Commands

OwlPay registers a wp owlpay command group when WP-CLI is available.

Notable commands include:

wp owlpay doctor
wp owlpay install
wp owlpay finance-seed
wp owlpay finance-sync-payees --limit=500
wp owlpay finance-sync-ledger --limit=100 --dry-run
wp owlpay finance-sync-payouts --limit=100
wp owlpay finance-refresh-balances
wp owlpay paypal:ping
wp owlpay paypal:diag
wp owlpay credit
wp owlpay balance
wp owlpay create
wp owlpay exec

CLI Use Cases

• Validate database tables.
• Install or upgrade OwlPay tables.
• Seed finance-core accounts and mappings.
• Backfill legacy payees into financial entities.
• Backfill legacy ledger entries into journals.
• Backfill sent payouts into settlement journals.
• Refresh materialized account balances.
• Test PayPal OAuth connectivity without sending money.
• Create test credits, check balances, create payouts, and execute payout rows.

---

Key Hooks and Extension Points

Payout and Ledger Hooks

| Hook | Purpose | | --- | --- | | ath_owlpay/ledger/credit | Allows upstream plugins to credit a payee ledger entry. | | ath_owlpay/ledger/debit | Allows upstream plugins to debit a payee ledger entry. | | ath_owlpay/ledger/entry_created | Fires after ledger entry creation. | | ath_owlpay/ledger/entry_updated | Fires after ledger entry update. | | ath_owlpay/ledger/entry_deleted | Fires after ledger entry deletion. | | ath_owlpay/payout/created | Fires when a payout has been queued/created. | | ath_owlpay/payout/sent | Fires after successful payout execution. |

Adapter and Processor Hooks

| Hook | Purpose | | --- | --- | | ath_owlpay/register_adapters | Register custom payout execution adapters. | | ath_owlpay/register_recurring_payment_processors | Register custom recurring payment processors. | | ath_owlpay/recurring_payment/process | Override recurring payment processing. | | ath_owlpay/recurring_payment/succeeded | Listen for successful recurring payments. | | ath_owlpay/recurring_payment/failed | Listen for failed recurring payments. |

Platform Integration Hooks

| Hook/Filter | Purpose | | --- | --- | | ath_owlpay_loaded | Fires after OwlPay service container is booted. | | ath_owlpay/capability | Override required capability, default manage_woocommerce. | | asakm/services_meta | Registers OwlPay credential groups in Athenian Secure API. | | asu_owl_pay_account_snapshot | Extends Social Users account snapshot data. | | asu_sync_owl_pay_account | Syncs Social Users/People payout data into OwlPay. | | athenian_user_dashboard_integrations | Adds OwlPay integration to Athenian user dashboard. | | athenian_user_dashboard_cards | Adds OwlPay cards to Athenian user dashboard. | | ab_wcds_po_settlement_updated | Responds to dropship PO settlement updates. | | ab_wcds_vendor_shipment_confirmed | Responds to vendor shipment confirmation events. |

---

Integrations

Athenian WC Dropship

OwlPay can convert dropship PO/vendor payable data into payout-ready ledger credits. It adds vendor and PO metaboxes, row actions, payable crediting, balance display, and payout queueing support.

Athenian Social Users Core

OwlPay can link People records to payee records, collect payout profile data, update person score/payment readiness data, and expose dashboard integrations.

Affiliate Workflows

OwlPay supports affiliate payee discovery, affiliate profile panels, and payout queue actions for affiliate earnings.

Athenian Product Subscriptions & Bundles

OwlPay can act as the recurring payment execution bridge for APS-generated renewal orders using stored WooCommerce payment tokens.

Athenian Secure API / Secure API Key Manager

OwlPay registers provider credential groups and fetches provider secrets through the secure credential layer when available.

WooCommerce

WooCommerce is used for My Account endpoint integration, stored payment token support, renewal order charging, customer/payment context, wc_price() formatting, and broader commerce workflow integration.

---

Technical Implementation Notes

Strengths Observed

• Clear separation between payee identity, payout methods, ledger entries, payout batches, payout items, and logs.
• Adapter registry supports future payout rails without rewriting payout orchestration.
• PayPal Payouts adapter includes thoughtful idempotency behavior and audit metadata.
• Frontend dashboard and account setup shortcodes make payout onboarding usable outside wp-admin.
• Finance-core tables and services indicate a forward path toward formal double-entry traceability.
• Legacy bridge supports additive migration rather than destructive payout history changes.
• WP-CLI support is unusually strong for diagnostics, setup, finance sync, balance refresh, and provider testing.

Implementation Items to Confirm Before Production

• Confirm the dedicated PayPal webhook receiver is actively booted if signature-verified PayPal reconciliation is required.
• Confirm Stripe Connect payout execution is still treated as a stub before marketing automated ACH/Instant payouts as live.
• Confirm provider credentials are stored through ASAKM/Secure API rather than plaintext settings in production.
• Confirm WooCommerce, APS, Athenian Social Users Core, WC Dropship, and Secure API plugin dependencies are installed where those integrations are expected.
• Review frontend dashboard rendering paths; the current dashboard method returns the account ledger dashboard before an older dashboard block, leaving part of the method unreachable.
• Confirm legal/tax collection requirements before using OwlPay as a compliance-facing payout onboarding system.
• Confirm PayPal Payouts account approval and API permissions before enabling live provider execution.

---