=== TINSE Secure Pay on Delivery for WooCommerce ===
Contributors: tinseinc
Tags: cash on delivery, pay on delivery, cod, deposit, partial payment
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Pay on Delivery for serious buyers only. Prepaid shipping + return guarantee or a deposit, courier cash-handling fees, and per-product control.

== Description ==

Unpaid Pay on Delivery orders cost merchants twice: once to send the parcel, and again to bring it back when the buyer refuses it. Secure Pay on Delivery makes every POD buyer put something on the table first — through a real prepaid gateway — so only serious buyers get through.

**How it works**

* **Orders below your threshold:** the buyer prepays outbound shipping plus a *return-shipping guarantee*. When the parcel is accepted, the guarantee is deducted from the cash they hand the courier. If delivery fails or is refused, the guarantee covers bringing the parcel home.
* **Orders at or above your threshold:** the buyer prepays a part-payment (a percentage of the total or a fixed amount). No return fee is charged.
* **Courier cash-handling fee:** a percentage (plus optional fixed amount, minimum and maximum) calculated on the cash balance actually collected at the door.
* **Prepaid gateways only:** bank transfer (BACS), cheque and the core Cash on Delivery gateway are removed whenever Pay on Delivery is selected. Optionally restrict to an allow-list (e.g. Paystack, Flutterwave, Stripe).
* **Choose your POD products:** allow POD on selected products only, or on everything except the products you exclude.
* **Return rate sources:** mirror the outbound shipping cost (works with any shipping method or courier plugin), or a flat fee. Developers can plug in any carrier API with the `tspod_return_rate_providers` filter.
* **Delivery outcomes:** record "delivered, balance collected" or "delivery failed / refused" from the order screen. The amount to collect is shown on the order, the thank-you page and emails.
* Works with the classic checkout, page-builder checkouts that use the classic form, and the WooCommerce Checkout block. HPOS compatible.

**Example (threshold $1,000, 30% part-payment, 1.5% cash-handling fee, return fee = shipping × 1.1)**

* $250 order, $10 shipping, $11 return guarantee: pay $21.00 now, $242.64 cash on delivery.
* $3,500 order, $15 shipping: pay $1,065.69 now, $2,486.61 cash on delivery.

Works in any currency your store uses.

**No courier or shipping API required.** The return fee is calculated from whatever your existing shipping method charges, or a flat fee you set.

== Installation ==

1. Install and activate WooCommerce.
2. Install and activate this plugin.
3. Go to WooCommerce > Settings > Pay on Delivery and set your threshold, part-payment, return fee source and cash-handling fee.
4. Edit products and set "Pay on Delivery" under Product data > General (or switch to "All products except those I exclude").

== Frequently Asked Questions ==

= How is the order total recorded? =

The WooCommerce order total equals the amount paid online. The return guarantee and cash-handling fee are added as normal fee lines, and the order shows two extra rows above the total: the return guarantee credit and the balance payable on delivery. Tax (e.g. VAT) is still calculated on the full order value. The cash amount is also stored in the `_tspod_pay_on_delivery` order meta, and the order total stays at the amount paid even if you click "Recalculate".

= What if shipping is free? =

Shipping + return could then be zero. Set a "Minimum upfront commitment", or use a flat return fee. Pay on Delivery is hidden whenever nothing would be paid upfront.

= Does it work with my courier plugin? =

Yes. "Mirror outbound shipping" uses whatever your shipping method charged for the delivery leg, so it works with flat rate, table rate, local pickup-and-deliver plugins or any courier plugin. Developers can supply their own return rates with the `tspod_return_rate_providers` filter.

= Is any data sent to external services? =

No. The free plugin makes no external requests and collects no data.

= Which currencies are supported? =

Any currency your WooCommerce store uses. Amounts are rounded to your store's price decimals.

= What happens to Pay on Delivery when a buyer's cart contains a product that isn't eligible? =

The Pay on Delivery option is hidden and the buyer pays in full as normal.

= How do I record that the courier collected the cash? =

Open the order and choose "POD: delivered, balance collected" or "POD: delivery failed / refused" from the Order actions dropdown.

== Screenshots ==

1. The Pay on Delivery choice at checkout, showing what the buyer pays now and at the door.
2. Order summary with the return guarantee, cash-handling fee and balance lines.
3. Settings: threshold, part-payment and minimum commitment.
4. Settings: return shipping source and courier cash-handling fee.
5. Product setting to allow or block Pay on Delivery.
6. Order screen panel showing the amount to collect and delivery outcome actions.

== Privacy ==

This plugin does not send data to any external service, does not use cookies, and does not track users. It stores the Pay on Delivery breakdown for each order as order meta so the merchant knows how much to collect.

== Changelog ==

= 1.0.0 =
* Initial release.

== Upgrade Notice ==

= 1.0.0 =
Initial release.
