=== Donor Merchant ===
Contributors: mattmcwilliam
Tags: donations, donate, fundraising, recurring donations, nonprofit
Requires at least: 6.0
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 2.3.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Free donation plugin for WordPress — one-time and recurring donations via Stripe and PayPal, with donor tracking, receipts, and reports.

== Description ==

**Donor Merchant** is a lightweight donation plugin for nonprofits, churches, schools, and community groups. Drop the donation form on any page with a block or shortcode, connect Stripe or PayPal, and start accepting gifts in minutes.

Unlike most donation plugins, **recurring giving is included in the free plugin** — monthly, quarterly, and yearly gifts powered by Stripe subscriptions, at no extra cost and with no transaction fees added by us.

= Features =

* **One-time and recurring donations** — monthly, quarterly, and yearly giving built in, free.
* **Campaigns with goal thermometers** — run multiple donation forms, each with its own goal, suggested amounts, and description, and show a live progress bar.
* **Donor portal** — a passwordless, magic-link dashboard where donors view their giving history, download receipts, and manage recurring gifts (update card or cancel) via Stripe's secure billing portal.
* **Printable receipts & annual tax statements** — every gift gets a save-as-PDF receipt, and donors can download a year-end giving statement. No PDF library bloat.
* **Offline donations** — record checks, cash, and gifts taken elsewhere so donor totals stay complete.
* **Stripe** — cards, Apple Pay, Google Pay, and **bank debit (ACH)** via Stripe's secure Payment Element. Card details never touch your server.
* **PayPal** — one-time gifts through Smart Buttons, plus **recurring PayPal subscriptions**.
* **Designations / funds** — let donors choose which fund their gift supports.
* **Integrations** — outgoing webhooks (Zapier, Make, or anything) and Mailchimp audience sync.
* **Custom fields** — add your own questions to the donation form.
* **Fee recovery** — let donors add a little extra so 100% of the gift reaches you.
* **Tributes and memorials** — donors can dedicate a gift in honor or in memory of someone.
* **Donor management** — every donor and gift tracked automatically, with lifetime totals and CSV export.
* **Email receipts** — customizable thank-you receipts and new-donation notifications.
* **Reports dashboard** — total raised, monthly totals, average gift, recurring count at a glance.
* **Test mode** — try everything end to end with Stripe test keys and the PayPal sandbox before going live.
* **International** — 20 currencies supported.
* **Block and shortcodes** — the Donation Form block, plus `[donor_merchant]`, `[donor_merchant campaign="N"]`, `[donor_merchant_progress campaign="N"]`, and `[donor_merchant_portal]`.

= How it stays secure =

Payment details are collected by Stripe and PayPal directly in the donor's browser. No card number, expiration date, or CVC is ever transmitted to or stored on your server. Donation totals are always recomputed server-side, payment status is confirmed server-to-gateway, and webhook signatures are verified.

= External services =

To process donations this plugin connects to third-party payment and (optionally) marketing services. Nothing is sent until you enable and configure a given service.

* **Stripe** (only when Stripe is enabled). The Stripe.js library is loaded from `https://js.stripe.com` on pages that display the donation form, so payment details can be collected securely in the donor's browser. Your server also calls the Stripe API at `https://api.stripe.com` to create payment intents, customers, and subscriptions, and to verify payments. Data sent: donation amount and currency, the donor's name and email, and the payment details the donor enters (handled by Stripe — they do not touch your server). Stripe terms: https://stripe.com/legal — privacy: https://stripe.com/privacy
* **PayPal** (only when PayPal is enabled). The PayPal JS SDK is loaded from `https://www.paypal.com` on pages with the donation form. Your server calls the PayPal API (`https://api-m.paypal.com`, or `https://api-m.sandbox.paypal.com` in sandbox mode) to create and capture orders and subscriptions. Data sent: donation amount, currency, and an internal reference. PayPal terms: https://www.paypal.com/legalhub — privacy: https://www.paypal.com/privacy
* **Mailchimp** (optional — only when you enable it and the donor opts in). Your server calls the Mailchimp API (`https://<dc>.api.mailchimp.com`) to add the donor to the audience you choose. Data sent: donor email and name. Mailchimp terms: https://mailchimp.com/legal/terms/ — privacy: https://mailchimp.com/legal/privacy/
* **Outgoing webhooks** (optional). If you enter one or more webhook URLs, completed-donation data is POSTed to those URLs — which you control and choose (e.g. your Zapier or Make endpoint). No third party receives data unless you configure it.

= Getting started =

1. Install and activate the plugin.
2. Go to **Donor Merchant → Settings → Payments** and paste your Stripe and/or PayPal API keys.
3. Add the **Donation Form** block (or `[donor_merchant]`) to any page.
4. Test with Stripe test mode, then switch to live.

== Frequently Asked Questions ==

= Is recurring giving really free? =

Yes. Monthly, quarterly, and yearly donations via Stripe are part of the free plugin. You pay only the payment processor's own fees.

= Do I need an SSL certificate? =

Yes. Stripe and PayPal require your site to be served over HTTPS.

= Where do I find my Stripe API keys? =

In your Stripe dashboard under **Developers → API keys**. Use the test keys with Test mode to try things out safely.

= Does the plugin store card numbers? =

No, never. Card details are entered into fields hosted by Stripe (or on PayPal's site) and never reach your server.

= Can donors cover the processing fees? =

Yes — enable fee recovery in settings and donors can opt in to add the estimated processing fee to their gift.

= Are webhooks required? =

Recommended, but not required for one-time gifts. Recurring renewal payments are recorded via the Stripe webhook, so set it up if you accept recurring gifts. The settings page shows the exact URL and events to use.

= Does it work with my theme? =

The form ships with clean, self-contained styling that adapts to any well-built theme, and everything is namespaced to avoid conflicts.

== Screenshots ==

1. The donation form with recurring options, suggested amounts, and fee recovery.
2. Dashboard with fundraising totals at a glance.
3. Donations list with status filters, search, and CSV export.
4. Donor list with lifetime giving totals.
5. Settings — payments tab.

== Changelog ==

= 2.3.0 =
* New: Monthly fundraising summary email — totals, new donors, recurring count, and top campaign, sent on the first of each month (with a "send a sample now" button).
* Docs: documented the developer hooks (actions, filters) and the signed outgoing-webhook payload.

= 2.2.0 =
* New: Bank debit (ACH) payments through Stripe — lower fees than cards.
* New: Recurring PayPal donations via PayPal Subscriptions, with a webhook for renewals.
* New: Designations / funds — donors choose which fund their gift supports.
* New: Integrations — outgoing webhooks (Zapier/Make) signed with HMAC, and Mailchimp audience sync with an opt-in checkbox.
* New: Custom form fields (text, paragraph, dropdown, checkbox), saved with each donation and included in exports.
* Improved: Donations CSV now includes designation and custom-field columns; admin notifications list them too.
* Developer: webhook payload includes campaign, designation, and custom fields.

= 2.1.0 =
* New: Campaigns — multiple donation forms, each with its own goal, suggested amounts, and description, plus a live goal thermometer (`[donor_merchant campaign="N"]` and `[donor_merchant_progress campaign="N"]`).
* New: Donor self-service portal — passwordless magic-link dashboard for giving history, receipts, and managing recurring gifts through Stripe's billing portal (`[donor_merchant_portal]`).
* New: Printable receipts (save as PDF) for every donation, plus year-end annual tax statements, served securely over signed links.
* New: Offline / manual donation entry from the admin (checks, cash, bank, other).
* New: Tax-receipt settings (Tax ID/EIN, organization address, tax-deductible language) and a donor-portal page setting.
* Improved: Donations CSV export now includes the campaign column.
* Developer: `donor_merchant_suppress_receipt` and `donor_merchant_suppress_admin_notification` filters.

= 2.0.0 =
* Complete rewrite for production.
* Stripe Payment Element with one-time and recurring (monthly/quarterly/yearly) donations.
* PayPal Smart Buttons for one-time donations.
* Fee recovery, tributes/memorials, and donor notes.
* Donor and donation management with search, filters, and CSV export.
* Customizable email receipts and admin notifications.
* Stripe webhooks with signature verification (renewals, refunds, failures).
* Reports dashboard.
* Donation Form block for the editor; legacy [donation_form] shortcode still supported.
* Internationalization-ready; 20 currencies.

= 1.0 =
* Initial prototype.

== Upgrade Notice ==

= 2.3.0 =
Adds an automatic monthly fundraising summary email and documents the developer hooks. No database changes.

= 2.2.0 =
Adds ACH bank payments, recurring PayPal, designations/funds, Zapier & Mailchimp integrations, and custom form fields. Database updates automatically; existing data is preserved.

= 2.1.0 =
Adds campaigns with goal thermometers, a donor self-service portal, printable/annual tax receipts, and offline donation entry. Database updates automatically; existing donations and settings are preserved.

= 2.0.0 =
Complete production rewrite. Settings carry over; the [donation_form] shortcode keeps working. Raw card fields are gone — payments now run through Stripe's hosted Payment Element and PayPal.
