Zeko Pay

Centralized wallet and payment ecosystem for the Zeko platform, built on a lightweight, ACID-compliant ledger.

Description

Zeko Pay is a wallet and payment management system for the Zeko WordPress platform. It provides a ledger-based financial layer that Zeko modules (Jobs, Freelance, Learn, Shop, Mentor) share.

Key Features

• ACID Ledger Engine — Every balance change is an atomic ledger transaction with row-level locking
• Multi-gateway Support — PayPal, crypto, and extensible gateway framework
• Fee Engine — Flat, percent, and tiered fee rules with minimum thresholds
• REST API — Full wallet management via /wp-json/zeko-pay/v1/
• SDK — Standalone PHP client for external plugin integration
• Webhooks — Signed incoming gateway verification (signature + replay window + event-ID dedup) and HMAC-signed outgoing notifications with retry logic
• Loyalty & Rewards — Points accrual, tier system (Bronze/Silver/Gold), and redemption
• Subscriptions — Recurring billing with retry logic and cancellation
• Promo Codes — Flat and percentage discounts with usage limits
• Referral System — Unique codes, first-deposit bonuses, and stats tracking
• Gift Cards — Generate, redeem, and track balances
• Event Ticketing — Capacity-managed ticket sales with QR codes
• Donations & Crowdfunding — Campaign goals, donor walls, progress tracking
• Memberships — Plan-based access with auto-grant/revoke roles
• Invoices & Receipts — Auto-generated on completed transactions
• Tax Calculation — Country/state-based tax rules
• Scheduled Payouts — Automated payout processing with approval workflow
• Reports & Analytics — Revenue stats, top users, transaction summaries
• In-app Notifications — Mark read, mark all read, delete
• Currency Handling — Live exchange rates with 1-hour caching
• Import Bridge — Migration tool for WooCommerce order data

Developer API

Zeko Pay provides a clean SDK for other plugins:

$sdk = new Zeko_Pay_SDK(); $result = $sdk->charge( $user_id, 25.00, 'Job posting fee', array( 'job_id' => 123 ) ); $balance = $sdk->get_balance( $user_id ); $sdk->hold( $client_id, $amount, $reference, array( 'escrow' => true ) ); $sdk->release( $freelancer_id, $amount, $reference );

Integration Contracts

Each Zeko module registers its payment flows through Zeko_Pay_Integrations:

• Zeko_Pay_Integrations::instance()->jobs_charge_posting_fee()
• Zeko_Pay_Integrations::instance()->freelance_fund_milestone()
• Zeko_Pay_Integrations::instance()->learn_purchase_course()
• Zeko_Pay_Integrations::instance()->mentor_book_session()
• Zeko_Pay_Integrations::instance()->shop_process_order()
• Zeko_Pay_Integrations::instance()->rewards_convert_to_credit()

Shortcodes

• [zeko_pay_wallet] — User wallet dashboard
• [zeko_pay_checkout amount="25" type="job_posting"] — Payment button
• [zeko_pay_balance] — Display user's current balance

Theme Integration

Zeko Pay hooks into theme actions automatically:

• zeko_theme_dashboard_widgets — Wallet balance widget
• zeko_theme_profile_stats — Balance on user profile
• zeko_theme_header_actions — Notification bell with unread count

Installation

1. Upload the zeko-pay folder to /wp-content/plugins/
2. Activate the plugin through the 'Plugins' menu
3. The database schema is created automatically on activation
4. Configure settings under Zeko Pay > Settings

Frequently Asked Questions

Do I need WooCommerce?

No. Zeko Pay is a self-contained wallet and payment system and does not require WooCommerce. It provides all payment, wallet, and transaction management features the Zeko ecosystem needs.

What happens to my data when I delete the plugin?

Deleting Zeko Pay removes all of its data — tables, options, transients, cron events, user meta, and the membership role. To keep the data (e.g. during a migration), define ZEKO_PAY_KEEP_DATA_ON_UNINSTALL as true in wp-config.php before deleting.

How are ledger and input safeguards implemented?

Yes. Balance changes use ACID transactions with row-level locking. Input is sanitized, output is escaped, nonces protect AJAX and form submissions, and withdrawal details are validated against per-provider allow-lists.

Can I use it outside the Zeko ecosystem?

Yes. The SDK works as a standalone PHP client. You can use it in any WordPress plugin by calling Zeko_Pay_SDK methods directly.

What payment gateways are supported?

PayPal and cryptocurrency are built in. The gateway framework is extensible — you can add any gateway by extending Zeko_Pay_Gateway.

Who is responsible for compliance?

You, the site owner. Zeko Pay is a payment and wallet toolkit, not a bank, money transmitter, escrow agent, or licensed financial institution, and activating it does not make your site legally compliant for financial activity. You are solely responsible for the legal, tax, payment, anti-money-laundering (AML), consumer-protection, and marketplace obligations that apply to the money movement the plugin enables in your jurisdiction — including identity checks (KYC), whether escrow is legally available where you operate, fee disclosures, refund and chargeback handling, and any licensing requirements. WordPress.org does not certify or endorse financial compliance.

How long are financial records kept?

Transaction and wallet records are append-only and retained while the associated wallet exists so your site can produce statements and satisfy record-keeping obligations. They are never rewritten or pruned automatically. You can export all transactions (admin reports) or a per-user statement CSV at any time. Final removal happens only when the plugin is deleted (all of its tables, options, transients, cron events, user meta, and the membership role are removed unless you define ZEKO_PAY_KEEP_DATA_ON_UNINSTALL as true before deleting).

How are incoming webhooks verified?

Every balance-changing webhook is verified before any money moves. PayPal webhooks are validated against PayPal's verify-webhook-signature endpoint and their signed transmission time must fall inside the configured freshness window; Coinbase webhooks are validated with HMAC-SHA256, and the signed event created_at must fall inside the same window. Each event is processed at most once via its signed event ID, and every ledger write uses a deterministic reference code with a unique constraint, so a replayed or duplicated webhook can never double-credit an account.

External Services

Zeko Pay talks to payment gateways only when you use them. Nothing is enabled by default and no balance-changing request is ever processed from an unverified source.

• PayPal (REST API + webhooks) — What is sent: your configured REST API credentials, and the order/payment details for transactions you or your users start (amount, currency, reference). Webhooks from PayPal deliver payment and capture events. When: only after you configure API credentials in Zeko Pay, and a user pays for a boosted listing, premium feature, or withdrawal to a PayPal address. Why: to authorize/settle payments and payouts. Retention: PayPal's own policies apply; locally, only transaction metadata created by the processor callback is stored in the immutable ledger. Incoming webhooks are signature-verified, time-stamped, and de-duplicated (see FAQ).
• Coinbase Commerce (crypto payments + webhooks) — What is sent: your configured API key and the payment/withdrawal details for cryptocurrency transactions you or your users initiate. Webhooks from Coinbase deliver charge/webhook events (HMAC-SHA256 signed). When: only after you configure the Coinbase key and a user uses the crypto payout or payment path. Retention: the Coinbase Commerce privacy policy applies to the charge data; locally only signed event metadata + immutable ledger rows are stored. Unverified webhooks fail closed and cannot move funds.
• ExchangeRate-API (currency conversion) — What is sent: the base currency ISO code only, to https://api.exchangerate-api.com/v4/latest/{base}. When: only when a configured exchange rate is needed and the cache (1 hour) is empty. Retention: rates are cached in a transient; nothing personal is sent.
• Outbound ecosystem webhooks (admin-configured) — If you configure outbound webhook URLs, queued ledger/payment events are POSTed to those URLs with an X-ZekoPay-Signature HMAC-SHA256 header (secret: option zeko_pay_webhook_secret) and an X-ZekoPay-Event type header. Destinations are SSRF-allow-listed (HTTPS required, private/loopback hosts blocked). What is sent: the queued event JSON (ledger transaction metadata). When: only when you configure and use outbound webhooks. Retention: destinations and their handling are under your control as site owner.
• Same-site REST (SDK) — The standalone SDK may POST deposit/refund calls to this site's own /wp-json/zeko-pay/v1/ endpoints (same origin; not a third party).

Full endpoint/payload detail with file:line citations is in REMOTE-SERVICES.txt in this plugin folder. No other outbound HTTP requests are made by this plugin.

Dependencies

Zeko Pay has no required dependencies and works standalone. Other Zeko modules (Jobs, Freelance, Learn, Shop, Mentor, Rewards, Love) integrate through the SDK and Zeko_Pay_Integrations when they are installed.

Privacy

Data stored includes wallet and ledger transactions, withdrawal details (e.g. a PayPal email or crypto address), invoices, payouts, and webhook logs. Financial records are retained while the associated wallet exists for record-keeping; you can export per-user statement CSVs from the admin. Payment data is processed by the gateways you configure (see External Services).

Uninstall

Deleting the plugin removes all Zeko Pay data — tables, options, transients, cron events, user meta, and the zeko_member role — unless ZEKO_PAY_KEEP_DATA_ON_UNINSTALL is defined as true in wp-config.php before deletion.

Troubleshooting

• Wallet balance not updating? Check the transient cache and that the ledger write returned a transaction code.
• Webhook not arriving? Confirm your gateway dashboard URL matches /wp-json/zeko-pay/v1/webhook and the freshness window allows the delay.
• Exchange rates stale? The rates transient lives 1 hour; force-refresh by saving Zeko Pay settings.

Screenshots

1. Payments dashboard with wallet and transactions

Changelog

1.2.0

• Wallet dashboard redesign — two-column card layout, balance hero, dark-mode currency selector, QR payments, aliases & address book, quick actions, standing orders, statement export
• Trust & Safety (16.7) — wallet freeze/hold, per-user daily caps, OTP-protected withdrawals, admin account reassignment (park-then-swap) with audit log
• Engineering (16.8) — PHPUnit suite
• Cross-module money-flow fixes — freelance commission journaling, love withdrawal OTP regression, learn instructor payouts
• Idempotency hardening on checkout, refunds, and releases (row-level locking via SELECT ... FOR UPDATE, deterministic reference codes, signed-webhook replay windows, event-ID dedup)

1.1.0

• Ledger, gateway, and account hardening (roadmap 16.1–16.6)
• Recipient aliases & address book
• QR code payments
• Payment requests & pay links
• Standing orders (recurring transfers)
• Idempotency & anti-double-submit guards
• Memos & statement export

1.0.0

• Initial release
• ACID ledger engine with row-level locking
• REST API with rate limiting
• Fee engine (flat, percent, tiered)
• Gateway framework (PayPal, crypto)
• Loyalty & rewards system
• Subscriptions & recurring billing
• Promo codes & coupons
• Referral & affiliate system
• Gift cards & store credit
• Donations & crowdfunding
• Event ticketing
• In-app notifications
• Memberships
• Invoices & receipts
• Tax calculation
• Scheduled payouts
• Reports & analytics
• WooCommerce data migration tool
• Currency exchange rates
• Webhook dispatcher with HMAC + retry
• Integration contracts for all Zeko modules
• Theme integration (widgets, profile, notifications)
• PHPCS compliant with WordPress Coding Standards

Upgrade Notice

1.2.0

Wallet dashboard redesign, Trust & Safety (freeze/hold, caps, OTP), and money-flow hardening.

1.0.0

Initial release of Zeko Pay.