=== KindLumen – Free Stripe Donation Forms ===
Contributors: kindlumen
Tags: donations, donate, stripe, fundraising, nonprofit
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.2.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Free Stripe donation forms for WordPress: a Donate button, embedded form, or campaign with a goal and progress bar. Gifts go to your own Stripe.

== Description ==

**KindLumen – Free Stripe Donation Forms** adds a free, Stripe-powered donation form to any WordPress page or post. Show it as a **Donate button** that opens the form in a popup, as a **donation form embedded** right in the page, or as a **donation campaign with a goal and a live progress bar**. Setup is three guided steps, and every donation settles directly in your organization's own Stripe account.

= Free donation forms on your own Stripe account =

KindLumen charges organizations no setup fee, monthly fee, or platform fee, and sets no limits on donation forms, campaigns, donations, or donors. You connect your own Stripe account — KindLumen never holds your money and never asks donors to tip. Stripe processing applies. Donors can optionally cover transaction costs; that added amount includes the estimated processing fee and a disclosed 1% contribution to KindLumen.

= Donation campaigns with goals and progress bars =

Raising for a building, a program, or a year-end push? Create a fundraising campaign in KindLumen with a goal, a story, and a picture, then put it on WordPress as a **campaign card** — amount raised, goal, progress bar, and a Donate button — or embed the **full campaign page**. The progress bar updates live as gifts arrive, and a campaign can start from what you have already raised offline.

= A floating Donate button on every page =

Want a Donate button that stays in view while visitors scroll? Switch on the **floating button** in KindLumen, choose which form or campaign it opens, and style it there. Connected WordPress sites show it on every page automatically within about a minute — nothing to paste — and it disappears the same way when you switch it off.

= One-time and monthly donations =

Every donation form supports one-time giving, suggested amounts and a custom amount, optional transaction-cost coverage, eligible card-backed wallets through Stripe, and branded email receipts. Recurring (monthly) giving is available on forms backed by a verified Stripe connection. The form appears on your WordPress page; a hosted payment fallback can be used when the inline Stripe interface is unavailable.

= Three guided steps =

1. **Connect with KindLumen** — sign in, or create a free account on the spot, and pick a donation form. Everything is filled in for you: no IDs to copy, no API keys.
2. **Connect Stripe** — done inside KindLumen. WordPress shows you whether donations are open yet.
3. **Put a Donate button on your site** — one click creates a Donate page with the form on it. Or use the embed builder to copy a shortcode or link: popup button, form on the page, campaign card, full campaign page, or a donate link for any button already in your theme.

= Highlights =

* **Free Stripe donation form** — branded, mobile-friendly, one-time and monthly, on your own Stripe account.
* **Donate button** — `[kindlumen_button]` opens the donation form in a polished popup.
* **Embedded donation form** — `[kindlumen_form]` puts the form right in the page, sized to fit.
* **Donation campaigns** — `[kindlumen_campaign]` shows a campaign card with goal and progress bar, or the whole campaign page.
* **Gutenberg block** — "KindLumen Donation Form": pick a form or campaign from a dropdown and choose button, form, card, or page.
* **Menu button and donate links** — a pre-styled Donate button in any menu; any link to `#kindlumen-donate` opens the popup.
* **Guided setup** — the settings screen walks you through it, shows Stripe status, and creates a Donate page in one click.
* **Light and safe** — a few kilobytes of CSS and JavaScript; no card or donor data ever touches WordPress.

= What it does NOT do =

* It does **not** process payments in WordPress.
* It does **not** store donor names, emails, amounts, card data, or Stripe IDs in WordPress.
* It does **not** create donations, donors, campaigns, or reports in WordPress — those live in your KindLumen dashboard.
* It does **not** ask for Stripe keys, API tokens, or webhook secrets.

= Requirements =

A free [KindLumen](https://www.kindlumen.com) account and a Stripe account (free to create). You can create the KindLumen account from the plugin's Connect button, and Stripe is connected inside KindLumen. The plugin embeds your KindLumen donation form — it doesn't replace it.

= How donations are handled =

When a visitor donates, the form is served by KindLumen and the payment is processed by Stripe on KindLumen's domain, then paid out by Stripe to your bank account. WordPress only displays the embedded form. See the External services and Privacy sections below.

== Installation ==

1. Install the plugin from the WordPress plugin directory, or upload the `kindlumen-donation-forms` folder to `/wp-content/plugins/`.
2. Activate it. You land on **Settings → KindLumen**, which walks you through the rest.
3. Click **Connect with KindLumen**. Sign in — or create a free account — and choose the form you want. You're sent straight back with everything filled in. (Prefer to do it by hand? Paste your form link instead.)
4. Connect Stripe in KindLumen. The setup screen shows whether donations are open yet and where to go.
5. Click **Create a Donate page**, or add the form yourself:
   * **Donate button:** add `[kindlumen_button]` to any page or post.
   * **Inline form:** add `[kindlumen_form]`.
   * **Block:** add the **KindLumen Donation Form** block and choose Button or Inline.
   * **Menu:** Appearance → Menus → tick **Donate button** in the KindLumen box.

== Frequently Asked Questions ==

= Is this donation plugin really free? =

Yes. The plugin is free, and KindLumen charges organizations no setup fee, monthly fee, or platform fee, with no limits on donation forms, campaigns, donations, or donors. Stripe processing applies. Donors can optionally cover transaction costs; that added amount includes the estimated processing fee and a disclosed 1% contribution to KindLumen.

= Do I need a Stripe account? =

Yes — a free Stripe account, which you connect inside KindLumen (the plugin's setup screen shows you where). Donations are processed by Stripe and paid out by Stripe directly to your bank account. KindLumen never holds funds.

= Can I run a fundraising campaign with a goal and a progress bar? =

Yes. Create a campaign in KindLumen with a goal, a story, a picture, and optionally what you've already raised, publish it, and show it on WordPress as a campaign card or a full campaign page — with `[kindlumen_campaign id="your-campaign"]` or the block. The progress bar updates live as donations come in.

= Does it support recurring or monthly donations? =

Yes, on forms backed by a verified Stripe connection. Turn on monthly giving for the form in KindLumen; donors choose one-time or monthly at checkout, and Stripe handles the subscription. Forms backed by Square or PayPal currently accept one-time gifts only.

= Can someone change which organization receives the donations? =

Not through content. Shortcodes and the block always use the organization you connected on the setup screen — an `organization` attribute is ignored unless it matches (or a developer allows extra organizations with the `kindlumen_donation_forms_allowed_organizations` filter). The plugin only ever loads forms from kindlumen.com, the connection can only be changed by an administrator through the one-click Connect flow, and no card or donor data exists in WordPress to steal.

= Do I need a KindLumen account? =

Yes. This plugin embeds a form you create in KindLumen. If you don't have an account yet, click **Connect with KindLumen** on the setup screen — you can create a free account right there and you'll be brought straight back.

= What's the difference between the button and the inline form? =

`[kindlumen_button]` shows a Donate button; clicking it opens the donation form in a popup over your page. `[kindlumen_form]` places the form directly in the page content. Use the button on busy pages or in menus/hero sections; use the inline form on a dedicated "Donate" page.

= How do I connect without copying IDs? =

On **Settings → KindLumen**, click **Connect with KindLumen**. You'll sign in to KindLumen (if you aren't already), pick a form, and you'll be sent back to WordPress with everything filled in.

= Are payments processed in WordPress? =

No. Payments are processed entirely by KindLumen and its payment provider on KindLumen's domain. WordPress only displays the embedded form.

= Is any donor or payment data stored in WordPress? =

No. The plugin stores only your display settings (organization slug, form ID, button label, height, and similar). No donor, payment, or card data ever touches WordPress.

= Can I customize how it looks? =

Yes. The button's label, color, size, and alignment are configurable in settings or per shortcode. The inline form's height and theme are configurable too. The form's own colors, content, and suggested amounts are set in KindLumen and apply everywhere the form appears.

= Can I use it with the Classic Editor or a page builder? =

Yes. The shortcodes work in the Classic Editor, the block editor, and most page builders that render shortcodes.

= Can I show different forms on different pages? =

Yes. In **Settings → KindLumen**, step 3 has an embed builder: choose the form or campaign and how to show it, then copy the shortcode. Under the hood that's `[kindlumen_button form_id="abc123"]`, `[kindlumen_form form_id="abc123"]`, and so on. The block has the same dropdown.

= How do I show a campaign (goal and progress bar)? =

Publish the campaign in KindLumen, then in the embed builder choose the campaign and pick **Campaign card** (goal, progress bar, Donate button — good for a homepage or sidebar) or **Full campaign page** (story, goal, and form — good on its own page). The shortcodes are `[kindlumen_campaign id="spring-2026"]` and `[kindlumen_campaign id="spring-2026" display="page"]`. The card's Donate button opens the donation popup right on your page.

= I already have a button in my theme or page builder. Can it open the donation popup? =

Yes. Set the button's link to `#kindlumen-donate` (the embed builder gives you the exact link, e.g. `https://example.org/#kindlumen-donate`). Clicking it opens the popup for your connected form. To open a specific form or campaign, use `#kindlumen-donate:form:abc123` or `#kindlumen-donate:campaign:spring-2026`. Opening such an address directly (from an email, say) opens the popup as the page loads.

= How do I add a Donate button to my navigation menu? =

The easy way (classic menus):

1. Connect a default form in **Settings → KindLumen**.
2. Go to **Appearance → Menus**. In the **KindLumen donation** box on the left, tick **Donate button** and click **Add to Menu**.
3. Click **Save Menu**. Done — the menu item opens the donation popup and is styled as a button automatically.

If you don't see the KindLumen box, open **Screen Options** (top right) and enable it.

Block themes / manual: edit the **Navigation** block, select the link, and add `kindlumen-donate-trigger` under **Advanced → Additional CSS class(es)**. The same class works on any link or button.

Either way, the menu item is **automatically styled as a pill button** matching your button color — no extra CSS needed. Restyle it with your own CSS if you prefer.

= Donations say "open soon". Why? =

Stripe isn't verified in KindLumen yet. Open **Settings → KindLumen** — step 2 shows the current status and a button to connect Stripe. Once KindLumen reports it as verified, the form takes donations.

= How do I add a floating Donate button that stays on every page? =

Open **Floating button** in the KindLumen sidebar, pick what it opens, style it, and switch it on. Because this site is connected to KindLumen, the button appears on every page automatically within about a minute (the plugin loads KindLumen's embed script only while the button is on). Switch it off in KindLumen to remove it. Step 3 of **Settings → KindLumen** shows whether it is currently on.

= The form doesn't appear. What should I check? =

Open **Settings → KindLumen**. Step 1 shows which organization and form the site is connected to (and warns if the form can't be found or is still a draft in KindLumen). Logged-in administrators see a short setup message in place of the form when the connection is missing; visitors simply see nothing.

== Shortcodes ==

**Donate button** — opens the form in a popup:

`[kindlumen_button]`

Attributes (all optional; fall back to your settings):

* `form_id` — the KindLumen form to open.
* `campaign_id` — open a campaign instead of a single form.
* `organization` — your organization slug (must match the connected organization; see the FAQ).
* `label` — button text (e.g. "Donate", "Give now").
* `color` — button color as a hex value (e.g. `#5C60FF`).
* `size` — `small`, `medium`, or `large`.
* `align` — `left`, `center`, or `right`.
* `amount` — preselect a donation amount (in your currency's main unit).
* `frequency` — `one-time` or `monthly`.
* `source` — attribution label recorded on the donation.
* `class` — extra CSS class on the wrapper.
* `title` — accessible label for the popup.

**Inline form** — embeds the form in the page:

`[kindlumen_form]`

Attributes: `form_id`, `campaign_id`, `organization`, `height`, `min_height`, `theme` (`inherited`/`light`/`minimal`), `amount`, `frequency`, `source`, `class`, `title`.

**Campaign** — a campaign's card (default), full page, popup button, or form:

`[kindlumen_campaign id="spring-2026"]`

Attributes: `id` (the campaign), `display` (`card`, `page`, `button`, or `inline`), plus the button/inline attributes above.

**Donate link** — no shortcode needed: link anything to `#kindlumen-donate` (or `#kindlumen-donate:form:abc123` / `#kindlumen-donate:campaign:spring-2026`) and clicking it opens the donation popup.

Examples:

`[kindlumen_button label="Give now" color="#0a7f5b" size="large"]`
`[kindlumen_button form_id="abc123" amount="50" frequency="monthly"]`
`[kindlumen_form]`
`[kindlumen_form campaign_id="spring-2026" height="760"]`
`[kindlumen_campaign id="spring-2026"]`
`[kindlumen_campaign id="spring-2026" display="page"]`

== External services ==

This plugin relies on KindLumen to display and process your donation form.

**KindLumen** (https://www.kindlumen.com)

* **What it is:** Your KindLumen-hosted donation form is embedded in an iframe on your WordPress page (as a button popup or inline). All payment processing, donor records, and receipts happen inside KindLumen.
* **When data is sent:** A request is made to KindLumen each time a page containing the form is viewed (to load the form), when a visitor opens the popup, and when a visitor submits a donation. The one-click connect also sends you to KindLumen and back. Additionally, when an administrator opens **Settings → KindLumen** or the block editor, WordPress asks KindLumen for the connection status (`/api/wordpress/status`) so it can show which form is connected, whether donations are open, and the list of your live forms and campaigns to pick from; the answer is cached for about a minute. When you have switched on the floating Donate button in KindLumen, every front-end page also loads KindLumen's embed script (`/embed/widget.js`), which asks KindLumen for the button's design and, if you have enabled them, your recent-donation notifications (`/public/site-widget`, cached in the visitor's browser for about a minute). The plugin learns whether the button is on from the same cached status check, so the script loads only while the button is on.
* **What is sent:** The form/organization identifiers you configure; a source label (default "WordPress"); and, only if you turn the matching options on, your site's public domain and the page address. The status check sends only the organization slug and form id (plus your site address in the request's user agent). The embed script sends only the organization slug. When a visitor donates, the details they enter are sent directly to KindLumen — never to or through WordPress.
* **Terms & privacy:** https://www.kindlumen.com/terms and https://www.kindlumen.com/privacy

By default the form is loaded from `https://www.kindlumen.com`. You can point the plugin at a different KindLumen environment in **Settings → KindLumen → Advanced**.

== Privacy ==

This plugin does not collect, process, or store any personal data in WordPress.

The donation form is loaded from KindLumen inside an iframe. When a visitor interacts with the form, their information is handled by KindLumen and its payment provider under KindLumen's privacy policy — not by your WordPress site.

For attribution, the plugin can include the following non-personal information in the embedded form's URL: a source label you choose (e.g. "WordPress"); optionally your site's public domain (off by default); and optionally the address of the page showing the form (off by default). No visitor or donor data is added to these.

== Screenshots ==

1. The setup screen — connect KindLumen, connect Stripe, add a Donate button.
2. A Donate button on a WordPress page, with the donation popup open.
3. A donation form embedded inline on a page.
4. The KindLumen Donation Form block — pick what to show and how in its settings.
5. A campaign card (goal, progress bar, Donate) and a Donate button on a page.

== Changelog ==

= 1.2.4 =
* Update open donation forms when the website language changes, without clearing entered donation details.
* Keep fallback wording and links synchronized with the form, including Arabic direction.
* Protect KindLumen fallback wording from automatic page translators.

= 1.2.3 =
* Donation forms automatically follow the current WordPress page language when English, French, Spanish, Arabic, or German is available. Supports WordPress locale, WPML, and Polylang, with a browser-side check of the page language.
* Forms, popups, and fallback links use the organization’s custom wording for that language. Other languages use the organization’s default; saved settings are never changed.

= 1.2.2 =
* The inline form fallback link now follows the organization’s language and custom wording in KindLumen, including Arabic text direction.

= 1.2.1 =
* The connection status (which also decides whether the floating Donate button loads) is re-checked about once a minute instead of every five, so switching the button on or off in KindLumen reaches the site faster.

= 1.2.0 =
* Floating Donate button: switch it on in KindLumen (Floating button in the sidebar), pick what it opens, and style it there — connected sites show it on every page automatically within a few minutes, with nothing to paste. The plugin loads KindLumen's embed script only while the button is on; use the `kindlumen_donation_forms_site_widget` filter to opt out.
* The setup screen's step 3 shows whether the floating button is on.

= 1.1.3 =
* Fixed the setup status so verified Stripe, Square, and PayPal connections are identified correctly, with neutral guidance when a provider is not yet known.

= 1.1.2 =
* Security hardening: shortcodes and the block are pinned to the connected organization (an `organization` attribute that doesn't match is ignored), the KindLumen site URL setting only accepts kindlumen.com or localhost addresses, and the front-end only opens donation popups from the configured KindLumen site — never from a URL found in page content.
* New automated tests for the connect handshake, URL allow-listing, organization pinning, and the front-end popup rules.

= 1.1.1 =
* Renamed to "KindLumen – Free Stripe Donation Forms" and rewrote the listing around what the plugin does: free Stripe donation forms, Donate buttons, and donation campaigns with goals and progress bars.
* Block: added Stripe, fundraising, and campaign keywords so it's easier to find in the inserter.

= 1.1.0 =
* Guided setup: the settings screen is now three steps — connect KindLumen, connect Stripe, add a Donate button — and shows what's done.
* Create a free KindLumen account from the connect flow; you're brought straight back to pick a form.
* Stripe status from KindLumen shown in WordPress, with a link to connect it.
* "Create a Donate page" adds a draft page with the form already on it.
* Activating the plugin opens the setup screen; a reminder appears on the Dashboard and Plugins screens until you're connected.
* Campaigns: `[kindlumen_campaign]` shows a campaign card (goal, progress bar, Donate button) or the full campaign page; the card's Donate button opens the popup on your page.
* Embed builder on the setup screen: pick what to show (your form, another form, or a campaign) and how; copy the shortcode or link.
* Block: "What to show" dropdown of your live forms and campaigns, with card and full-page options for campaigns.
* Donate links: any link to `#kindlumen-donate` (optionally `:form:{id}` / `:campaign:{id}`) opens the donation popup.
* Fixed: the block ignored the connected form when its own fields were left blank.
* Organization slug / Form ID fields moved under Advanced (still filled in automatically).

= 1.0.0 =
* Initial release.
* One-click connect with KindLumen (pick a form, no copy-paste).
* `[kindlumen_button]` popup button and `[kindlumen_form]` inline embed.
* KindLumen Donation Form block with Button/Inline display.
* Customizable button label, color, size, and alignment; inline height, theme, and auto-resize.
* Loading state, no-JS fallback, and source attribution recorded on donations in KindLumen.

== Upgrade Notice ==

= 1.1.3 =
The setup screen now reports the payment provider connected to your KindLumen form accurately.

= 1.1.2 =
Security hardening release; no changes to how your forms look or work.

= 1.1.1 =
New name — KindLumen – Free Stripe Donation Forms — same plugin. Nothing changes on your site.

= 1.1.0 =
Guided three-step setup with Stripe status and one-click Donate page. Your existing connection and settings are kept.

= 1.0.0 =
Initial release of KindLumen Donation Forms.
