Nguyano Escrow Manager

Description

Nguyano Escrow Manager adds a structured escrow workflow to WordPress for marketplaces, agencies, and private transaction portals. Payers and earners can agree to contracts, fund milestones, submit work, request revisions, open disputes, and release approved funds while administrators retain operational oversight.

The plugin tracks contract state, reserved balances, invoices, wallet entries, notifications, and audit activity. Payment movement is handled through the site owner’s configured manual, PayPal, or NOWPayments processes. Nguyano Escrow Manager does not itself act as a bank, payment processor, licensed escrow provider, or legal adviser.

Nguyano Escrow Manager uses WordPress administration, shortcodes, AJAX, cron, REST routes, roles and capabilities, settings, mail, users, and privacy tooling while storing escrow-specific operational records in custom database tables managed by the plugin migration layer.

How Nguyano Escrow Manager works

1. Users register and complete any email, KYC, or administrator approval requirements enabled by the site owner.
2. A payer creates an escrow contract, invites an earner, and defines the work, amount, and milestone terms.
3. The earner accepts the contract, and the payer funds it through an available deposit method or wallet balance.
4. Nguyano Escrow Manager records the funded amount as reserved, creates the related accounting records, and tracks the contract through delivery.
5. The earner submits work. The payer can approve a release, request a revision, open a dispute, or follow the configured cancellation process.
6. Approved releases credit the earner’s wallet, while notifications, invoices, activity records, and audit entries preserve the transaction history.

Core escrow workflow

• Contract creation for payer/earner transactions.
• Payer and earner acceptance tracking.
• Milestone creation, funding, delivery, release, revision request, cancellation, refund, and dispute states.
• Configurable setup fees, platform fees, dispute controls, auto-release timing, acceptance windows, and cancellation response windows.
• Admin override actions for controlled operational intervention.
• Contract conversations with attachment metadata.
• Scoped exports and audit views.

Payments, wallets, and accounting

• Manual deposits with proof submission and admin review.
• PayPal deposit order creation, capture, verification, webhook handling, reconciliation, and raw response cleanup.
• NOWPayments crypto deposits with invoice creation, payment status polling, webhook processing, IPN secret validation, and supported coin settings.
• Manual, PayPal, and crypto withdrawal request workflows with admin approval and processing states.
• Shared invoice records for deposit and withdrawal flows.
• Per-user wallet balances, reserved funds, and total withdrawal tracking.
• Wallet ledger entries with before/after balances, reserved balance changes, invoice linkage, and optional immutable hash-chain audit fields.
• Admin accounting screens for revenue, escrow transactions, wallet ledger, user wallets, and invoices.

User onboarding and compliance controls

• Frontend registration, login, password reset, profile, email verification, and KYC upload screens.
• Admin approval as the final platform access barrier.
• Optional email verification and KYC requirements before admin approval.
• Configurable KYC document categories.
• Tokenized KYC upload access for pending users who still need to complete verification.
• Admin user review screens and user-scoped contract/accounting views.

Admin tools

• Nguyano Escrow Manager dashboard and metrics.
• DataTable-powered admin tables for contracts, users, deposits, withdrawals, invoices, accounting, disputes, activity logs, notifications, Recovery Backups, and REST API keys.
• Public page creation helper for required frontend shortcode pages.
• Settings modules for general, appearance, email, payment, fees, disputes, withdrawals, deposits, escrow flow, advanced, and security controls.
• Selectable, self-contained Recovery Backups with frontend Nguyano Escrow Manager users, settings, KYC documents, managed uploads, checksums, logs, and guided restore progress.
• Optional AI writing assistant powered by the site’s configured WordPress AI Client provider.

Recovery Backups

Nguyano Escrow Manager Recovery Backups are versioned .zip packages for same-site Nguyano Escrow Manager recovery. They are not general WordPress hosting backups.

Plugin database tables are always included. Before creation, administrators can choose whether to also include:

• Frontend Nguyano Escrow Manager user identities and plugin-owned user metadata.
• Nguyano Escrow Manager settings.
• Protected KYC documents.
• Managed uploads such as avatars, dispute evidence, message attachments, and deposit receipts.

Only users with the nguyano_escrow_manager_user role are included in the user identity component. Internal platform accounting uses a plugin wallet actor rather than a recoverable WordPress user account, and unrelated WordPress users are not included as recoverable user identities. KYC documents require included user identities and metadata so ownership can be restored correctly. WordPress passwords remain one-way hashes and are never decrypted.

Creation and restore show a percentage bar with current and recent step messages. Archives include a manifest, selected component map, file counts, and SHA-256 checksums. Restore accepts only current Nguyano Escrow Manager .zip recovery packages; standalone SQL and arbitrary ZIP files are rejected.

Existing WordPress users are reused only when the username matches and the live account is already an Nguyano Escrow Manager user. If an archived user ID collides with a different live account, Nguyano Escrow Manager restores the backed-up user at a safe ID and reconnects plugin records to the remapped identity. If a matching username exists but that live account is not an Nguyano Escrow Manager user, restore stops without changing that WordPress account.

Recovery packages may contain sensitive personal, financial, authentication, and KYC data. Restrict administrator access, protect downloaded/off-site copies, define a retention policy, and securely delete expired archives.

REST API

Nguyano Escrow Manager includes a custom WordPress REST API namespace: nguyano-escrow-manager/v1.

Available routes include:

• GET /status
• GET /stats
• GET /escrow-contracts
• GET /escrow-contracts/{id}
• GET /users
• GET /invoices
• GET /wallet/balance
• GET /transactions
• GET /disputes/{id}
• GET /disputes/{id}/messages
• POST /escrow-contract
• DELETE /escrows/{id}

REST access is controlled by plugin settings, API keys, scopes, optional HMAC signatures, per-key rate limits, CORS origin settings, request logging, and dataset permissions.

Security model

Nguyano Escrow Manager is designed around WordPress security practices:

• Capability checks for admin and privileged actions.
• Nonce checks for form, AJAX, and admin-post mutations.
• Sanitized and validated input before processing.
• Escaped output in admin and frontend templates.
• Prepared SQL for dynamic database queries.
• Explicit REST permission callbacks.
• API keys stored as hashed credentials with scope, expiry, status, prefix lookup, optional signatures, and rate limiting.
• Gateway-specific validation for payment status and webhook handling.
• Financial state changes recorded through invoices, transactions, activity logs, wallet records, and ledger rows.

Nguyano Escrow Manager helps site owners operate an escrow workflow, but it does not replace legal, tax, banking, money-transmission, fraud, or jurisdiction-specific compliance advice.

Required frontend pages and shortcodes

Nguyano Escrow Manager can create these pages for you from the admin tools screen:

• Login: [ngesc_user_login]
• Signup: [ngesc_user_signup]
• Dashboard: [ngesc_dashboard]
• Contracts Paying: [ngesc_contracts_paying]
• Contracts Earning: [ngesc_contracts_earning]
• View Contract: [ngesc_view_contract]
• Contract Milestones: [ngesc_view_contract_milestones]
• Activity Log: [ngesc_activity_log]
• Notifications: [ngesc_notifications]
• Deposits: [ngesc_deposits]
• Withdrawals: [ngesc_withdrawals]
• Payment Options: [ngesc_payment_options]
• Disputes: [ngesc_disputes]
• View Dispute: [ngesc_view_dispute]
• Profile: [ngesc_user_profile]
• Invoice: [ngesc_invoice]
• Reset Password: [ngesc_reset_password]
• Password Reset Link: [ngesc_password_reset_link]
• Terms of Service: [ngesc_terms_of_service]
• KYC Upload: [ngesc_kyc_upload]

Backward-compatible shortcode aliases remain registered for existing pages: [ngesc_escrows], [ngesc_view_escrow], [ngesc_earnings], and [ngesc_transaction_log].

Privacy

Nguyano Escrow Manager may store and process personal, financial, account, KYC, transaction, API, and activity data depending on enabled features and site configuration.

Data may include WordPress user account details, profile metadata, email verification state, KYC document metadata/uploads, API key metadata, contract and milestone records, dispute messages, wallet balances, wallet ledger rows, invoices, deposit and withdrawal metadata, payment gateway records, IP addresses, user agents, notifications, activity logs, and Recovery Backup records or archives.

Site owners should disclose Nguyano Escrow Manager data handling in their privacy policy, configure retention policies appropriate to their jurisdiction, and decide which financial/audit records must be retained for legal, tax, fraud-prevention, dispute, or accounting reasons.

Third-party services

Nguyano Escrow Manager connects to the following external services only when the corresponding feature is enabled and configured:

• PayPal Commerce Platform creates deposit orders, captures approved PayPal payments, verifies capture status, and receives webhook updates. Transaction, order, account, and callback data required for those operations may be sent to PayPal. Review the PayPal legal agreements and PayPal privacy statement.
• NOWPayments creates cryptocurrency deposit payment requests, checks payment status, and receives IPN callbacks. Invoice, payment, wallet, and callback data required for those operations may be sent to NOWPayments. Review the NOWPayments terms and NOWPayments privacy policy.
• WordPress AI Client powers the optional administrator writing assistant. Administrator-submitted prompts and related content are sent only when an administrator uses that feature and are handled by the site’s configured AI provider.

Each provider’s terms and privacy policy apply. Review and disclose every enabled integration in your site’s privacy policy before collecting live user data.

Developer Notes

Official release packages include production Composer dependencies. Developers working from a source checkout should run composer install --no-dev before activation.

Nguyano Escrow Manager is organized around bootstraps, controllers, services, models, migrations, settings modules, templates, assets, and helpers.

Important architecture entry points:

• nguyano-escrow-manager.php loads the plugin and initializes services.
• includes/NgescInit.php lists the service bootstraps.
• includes/Core/DBMigrator.php installs the canonical custom database schema during activation.
• includes/Core/EscrowBootstrap.php wires escrow services and controllers.
• includes/Core/FinanceBootstrap.php wires manual, PayPal, and crypto finance handlers.
• includes/Core/RestApiBootstrap.php registers REST, CORS, and logging behavior.
• includes/Api/RestApi/RestApiEndpoints.php defines REST routes and response shapes.
• includes/Api/RestApi/RestApiAuth.php validates API keys, scopes, signatures, and rate limits.
• includes/Settings/SettingsRegistry.php registers settings modules.
• includes/Core/Shortcodes.php registers frontend shortcodes.
• includes/Services/DBBackup/DBBackupService.php creates and validates Recovery Backup packages.

When extending Nguyano Escrow Manager, keep business rules in services, reusable data access in models, request handling in controllers, and rendering in templates. New or updated PHP files and class methods should include meaningful, concise comments that match the plugin style.