=== HandyPay for WooCommerce ===
Contributors: kylekonstnar
Tags: woocommerce, payments, stripe, checkout, caribbean
Requires at least: 6.2
Tested up to: 7.0
Requires PHP: 7.4
Requires Plugins: woocommerce, handypay-payments
Stable tag: 1.2.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Accept one-time and subscription payments at WooCommerce checkout with HandyPay and settle to a local bank account.

== Description ==

**HandyPay for WooCommerce** adds HandyPay as a payment method on your WooCommerce store. Customers check out as usual and you settle to a local bank account, built for the Caribbean: Jamaica, Trinidad & Tobago, St. Lucia, Antigua, Guyana, the Bahamas and major markets.

At checkout, customers are redirected to HandyPay's secure hosted page to pay, then returned to your store. Card data never touches your server (PCI SAQ-A). Works with both the classic shortcode checkout and the WooCommerce Cart/Checkout blocks.

Mark a simple or variable product as a HandyPay subscription and choose a daily, weekly, monthly, or yearly billing interval, an optional free trial, an optional sign-up fee, and whether shipping is charged once or every cycle. HandyPay's hosted checkout handles signup and recurring billing. Every renewal becomes its own WooCommerce order linked to the signup order, failed renewals and cancellations are noted on the order, and you manage every subscription from WooCommerce → Subscriptions.

Customers see their subscriptions under My Account → Subscriptions, where they can update their card on HandyPay's secure page, cancel, or keep a subscription they had cancelled.

Unlock content for subscribers: choose a role to grant while a subscription is active, then wrap members-only content in the [handypay_members] shortcode or the "Members only (HandyPay)" block. Access ends automatically when a subscription is cancelled, after a configurable grace period for failed payments. Themes can call handypay_wc_user_has_active_subscription().

Issue full or partial refunds right from the WooCommerce order screen - they are processed through HandyPay automatically. Disputes are managed from the HandyPay Payments plugin and the HandyPay merchant dashboard.

= Requires =

This add-on needs **WooCommerce** and **HandyPay Payments 1.2.0 or newer**, active and connected to your HandyPay account. Both dependencies are available from WordPress.org.

== Installation ==

1. Install and activate **WooCommerce** and **HandyPay Payments 1.2.0 or newer** from WordPress.org, then connect HandyPay.
2. Install and activate **HandyPay for WooCommerce**.
3. Go to **WooCommerce → Settings → Payments**, enable **HandyPay**, and save.

== External services ==

This plugin connects to the **HandyPay payments API** (`https://api.handypay.me`) to create checkout sessions and process card payments through HandyPay's payment processor (**Stripe**). This is required for the plugin to accept payments.

* **When:** when a customer places an order using HandyPay, and when the store owner views or manages payments.
* **Data sent:** order amount and currency, order/line item descriptions, the customer's email (if provided at checkout), and your HandyPay API key for authentication. Raw card details are collected by HandyPay/Stripe directly and are never sent to or stored on your site.
* **HandyPay:** Terms - https://handypay.me/terms · Privacy - https://handypay.me/privacy
* **Stripe (payment processor):** Terms - https://stripe.com/legal · Privacy - https://stripe.com/privacy

== Frequently Asked Questions ==

= Do I need the HandyPay Payments plugin? =
Yes. This gateway uses the connection and API key from HandyPay Payments 1.2.0 or newer. If it is missing, the gateway stays inactive and an admin notice links to the WordPress.org download.

= How do I create a subscription? =
Edit a simple or variable WooCommerce product, enable **HandyPay subscription** under Product data, choose the billing interval (and optionally a free trial, a sign-up fee, and shipping once or every cycle), and save. The product must be purchased by itself. Customers complete signup on HandyPay's hosted checkout page, and renewals run automatically.

= What happens on each renewal? =
HandyPay charges the card and sends a signed webhook. The plugin creates a new WooCommerce order for the renewal (linked to the signup order, marked paid, stock and reports updated) so your order history matches what was billed. If a renewal fails, the signup order is noted, the subscription shows as past due, and HandyPay retries the card; if the retries fail, the subscription is cancelled.

= How do customers cancel or update their card? =
From **My Account → Subscriptions**. "Update card" opens HandyPay's secure manage page; "Cancel" stops the subscription at the end of the paid period. You can also cancel, resume, or open the manage page for any subscription from **WooCommerce → Subscriptions**.

= How do I unlock content for subscribers? =
On the subscription product, choose a role under **Grant role while active**. Then wrap content in `[handypay_members product="123"]...[/handypay_members]` or use the **Members only (HandyPay)** block. Access is removed when the subscription ends, after the grace period you set in the gateway settings for failed payments.

= Is card data PCI compliant? =
Yes. Customers pay on HandyPay's hosted page, so raw card data never touches your server (PCI SAQ-A).

= How do refunds work? =
Open the order in **WooCommerce → Orders**, click **Refund**, and issue a full or partial refund - it is processed through HandyPay automatically. You can also refund from the HandyPay Payments plugin or the HandyPay dashboard.

= Which currency is sent to HandyPay? =
The gateway uses the currency saved on each WooCommerce order. Amounts, checkout sessions, order notes, and refunds therefore stay in the order currency instead of assuming US or Jamaican dollars.

== Changelog ==

= 1.2.0 =
* Subscriptions, complete: renewals become linked WooCommerce orders, failed renewals mark the subscription past due with the retry date, and cancellations from HandyPay or the customer sync to the order.
* New WooCommerce → Subscriptions screen and an order-screen box: status, next renewal, cancel at period end, cancel now, resume, sync, and the customer's manage page.
* New My Account → Subscriptions tab: customers update their card on HandyPay's secure page, cancel, or keep a cancelled subscription.
* Unlock content: grant a role while a subscription is active, gate content with the [handypay_members] shortcode or the Members only (HandyPay) block, and a past-due grace period setting.
* Subscription products gain a free trial, a sign-up fee, "charge shipping once", and support for variable products. The recurring amount, one-time items, and the WooCommerce order total always agree to the cent.
* Fixed: test-mode webhooks could act on live orders (the mode is now checked on every event). Expired checkouts cancel the order; failed payments mark it failed with the processor's reason.
* Refunds from the WooCommerce order screen now work on renewal orders too, and dashboard refunds of renewals sync back.
* Requires HandyPay Payments 1.2.0 or newer for subscription management (checkout works on 1.1.0).

= 1.1.1 =
* Added HandyPay subscriptions for simple WooCommerce products with daily, weekly, monthly, or yearly billing through hosted Stripe Checkout.
* Subscription checkout uses the WooCommerce order currency, including GYD for Guyana merchants, and keeps recurring billing on HandyPay's managed payment rails.
* Added a clear update prompt when HandyPay Payments is older than the required 1.1.0 release.
* Orders record whether they were paid in live or test mode, and test webhook events can never change live orders.
* Refund fixes: a failed HandyPay refund no longer marks the order refunded (previously WooCommerce would restock and adjust reports anyway), pending refunds are noted as processing, and the refund id is stored so the webhook cannot double-record it.
* Restored the delayed-payment guard on the thank-you page: complete-but-unpaid sessions (bank debits and similar) stay pending until the payment actually settles.
* Quick links to HandyPay system status, product updates, and support from the gateway settings.

= 1.0.2 =
* Fixed partial-refund sync so every refund amount is recorded correctly in WooCommerce.
* Added reliable handling for delayed payment methods and failed asynchronous payments.
* Refreshed settings links and HandyPay branding.

= 1.0.1 =
* Removed handypay-payments from the Requires Plugins header. That plugin is distributed from handypay.me rather than the WordPress.org directory, so the header cannot resolve it. The dependency is handled by a runtime check whose admin notice links to the download.

= 1.0.0 =
* First public release: HandyPay payment gateway for WooCommerce (hosted checkout), block checkout support, native full/partial refunds from the WooCommerce order screen, and Caribbean local-bank settlement.
