=== PayStage - Milestone Payments & Buyer Protection for Dokan, WCFM, MultiVendorX, and WooCommerce Product Vendors ===
Contributors: swapnil, anooanand, ibkr2024
Tags: dokan, wcfm, multivendorx, buyer protection, woocommerce
Requires at least: 6.2
Tested up to: 6.9
Stable tag: 1.1.2
Requires PHP: 7.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Hold vendor payments until buyers confirm delivery. Buyer protection for Dokan, WCFM and MultiVendorX.

== Description ==

PayStage helps marketplace operators protect buyers and vendors by holding online payments until the buyer confirms delivery. When an order is paid online, PayStage marks the order as held, keeps funds in your configured flow until the buyer confirms receipt, and then completes the order so the vendor is paid.

PayStage works with:
- Dokan Multivendor (40,000+ active installs)
- WCFM Marketplace (10,000+ active installs)
- MultiVendorX / WC Marketplace (5,000+ active installs)
- WooCommerce Product Vendors (official WooCommerce extension)

The plugin is built for stores running Dokan (Lite or Pro), WCFM Marketplace, MultiVendorX, or WooCommerce Product Vendors on top of WooCommerce. Admins can see PayStage status on each order, configure how long the buyer has to inspect the purchase, and release payment manually if needed.

Typical flow: the customer places an order and pays online; PayStage records the hold; the buyer opens the order in My Account and confirms delivery when satisfied; the order can then complete and the vendor payment proceeds according to your marketplace rules. If something goes wrong, the buyer can open a dispute; admins use the PayStage Disputes screen to choose a resolution (full refund, full release to vendor, or split), with email notifications to the parties involved.

== Installation ==

1. Upload the `paystage` folder to `/wp-content/plugins/`, or upload the plugin ZIP via Plugins > Add New > Upload Plugin.
2. Activate PayStage through the Plugins menu in WordPress.
3. Ensure WooCommerce and a supported multi-vendor plugin (Dokan, WCFM Marketplace, MultiVendorX, or WooCommerce Product Vendors) are installed and active.
4. Go to WooCommerce > PayStage to set the inspection period and other options.
5. Place test orders as a buyer and vendor to confirm hold, confirm delivery, and dispute flows on your staging site before going live.

== Frequently Asked Questions ==

= Does PayStage work without Dokan? =

PayStage requires at least one supported marketplace plugin: Dokan Multivendor, WCFM Marketplace, MultiVendorX, or WooCommerce Product Vendors.

= Does PayStage work with WCFM Marketplace? =

Yes. PayStage supports both Dokan and WCFM Marketplace. Install PayStage alongside either plugin and it will automatically detect which marketplace platform you are using and integrate accordingly.

= Does PayStage work with MultiVendorX? =

Yes. PayStage detects MultiVendorX automatically and integrates with its vendor commission and withdrawal system to hold payments until buyers confirm delivery.

= Does PayStage work with WooCommerce Product Vendors? =

Yes. PayStage supports the official WooCommerce Product Vendors extension. It automatically detects the plugin and integrates with its vendor commission and payout system to hold payments until buyers confirm delivery.

= Which multi-vendor plugins does PayStage support? =

PayStage supports Dokan Multivendor, WCFM Marketplace, MultiVendorX (formerly WC Marketplace), and WooCommerce Product Vendors. These four plugins cover the majority of WooCommerce multi-vendor marketplaces. If you use a different platform, use the paystage_should_hold_order filter to integrate with it.

= Does it work with Cash on Delivery? =

No. PayStage buyer protection only applies to online payment methods. COD orders are excluded automatically.

= What happens if the buyer never confirms delivery? =

Payment is automatically released to the vendor after the inspection period (default 7 days, configurable in PayStage settings).

= Can the admin release payment manually? =

Yes. Admins can release payment from the order detail page at any time.

= Is this compatible with WooCommerce HPOS? =

Yes. PayStage is fully compatible with WooCommerce High-Performance Order Storage.

== External services ==

This plugin does not send order or customer data to PayStage servers or other third-party APIs. Notifications use WordPress `wp_mail()` (delivered according to your site’s email configuration).

A bundled Stripe PHP SDK exists under `vendor/` for possible future use; PayStage does not call Stripe or other payment APIs in this version.

== Hooks & Filters ==

= Actions =

**paystage_payment_held** - Fires when vendor payment is held.
Parameters: $order_id (int), $vendor_id (int), $order (WC_Order)

**paystage_payment_released** - Fires when payment is released.
Parameters: $order_id (int), $vendor_id (int), $release_type (string: buyer_confirmed|auto_released|admin_released), $order (WC_Order)

**paystage_dispute_opened** - Fires when buyer opens a dispute.
Parameters: $order_id (int), $reason (string), $details (string), $order (WC_Order)

**paystage_dispute_resolved** - Fires when admin resolves a dispute.
Parameters: $order_id (int), $resolution (string: refund|release|split), $refund_amount (float), $order (WC_Order)

= Filters =

**paystage_should_hold_order** - Return false to skip hold for a specific order.
Parameters: $should_hold (bool), $order (WC_Order)

**paystage_inspection_period_days** - Override inspection period for a specific order.
Parameters: $days (int), $order_id (int)

== Vendor Terms Template ==

PayStage requires marketplace operators to disclose payment hold
terms to their vendors. Copy and adapt the following template for
your vendor terms of service:

**Payment Hold Policy**

When a buyer places an order on our marketplace, your payment
for that order will be held for [X] days (the "Inspection Period")
to allow the buyer to confirm delivery. During this period you will
not be able to withdraw these earnings.

Payment will be released to you when:
- The buyer confirms delivery of the order, OR
- The Inspection Period expires with no buyer action

If the buyer opens a dispute during the Inspection Period, payment
will remain on hold until the dispute is resolved by our marketplace
administrators.

This policy exists to protect buyers and maintain trust on our
marketplace. By selling on our marketplace you agree to these
payment terms.

== Screenshots ==

1. PayStage Buyer Protection box on order confirmation page
2. Admin dispute dashboard
3. Resolve dispute modal
4. PayStage meta box on order detail page
5. PayStage settings page

== Changelog ==

= 1.1.2 =
* Fix: Made plugin name consistent across all files
* Fix: Added all contributors to readme.txt
* Fix: Removed unused Stripe SDK vendor folder
* Fix: Addressed WordPress.org review feedback

= 1.1.1 =
* Security/review: move inline admin and front-end scripts to enqueued assets; add shared vendor-notice stylesheet.
* Readme: contributors and External services disclosure.

= 1.1.0 =
* New: Dispute management system for buyers
* New: Admin dispute dashboard (PayStage > Disputes)
* New: Three resolution types: full refund, full release, split
* New: Email notifications for dispute opened and resolved
* New: Dispute meta box on individual order pages
* New: Auto-release cron paused when dispute is opened
* Fix: COD orders now correctly excluded from all PayStage protection
* Fix: Encoding issues in email subjects and order notes

= 1.0.0 =
* Initial release
* Hold vendor payments on order creation
* Buyer Confirm Delivery button on order details page
* AJAX confirm delivery releases payment
* Auto-release cron after configurable inspection period (default 7 days)
* Admin manual release from order meta box
* Email notification on payment held and released
* Settings page for inspection period
* Full WooCommerce HPOS compatibility

== Upgrade Notice ==

= 1.1.0 =
Adds dispute management. Upgrade recommended for all users.