From 19d399e8c7e3d8248890316c9184191f01048de5 Mon Sep 17 00:00:00 2001 From: Josh Knapp Date: Sun, 15 Nov 2026 10:26:23 -0800 Subject: [PATCH] Add README with install and PayPal setup guide Co-Authored-By: Claude Sonnet 5.5 --- README.md | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..8d88a6a --- /dev/null +++ b/README.md @@ -0,0 +1,56 @@ +# StreamGoals Donate + +PayPal donations for WordPress, built for streamers: multiple donation goals, optional "cover the fees", +and OBS overlays (goal bar, subathon timer, counter, donation alerts) that update live. + +Requires WordPress 7.x, PHP 8.1+, and a **PayPal Business** account. + +## Install +1. Download `streamgoals-donate.zip` from the latest [release](../../releases). +2. WordPress admin → Plugins → Add New → Upload Plugin → activate. +3. Open **StreamGoals** in the admin menu. The setup wizard walks you through the rest. + +## Connect PayPal (about 5 minutes) +You need two values from PayPal: a **Client ID** and a **Secret**. + +1. Go to and log in with your PayPal Business account. +2. Open **Apps & Credentials**. Use the **Sandbox** toggle for testing, **Live** for real money. +3. Click **Create App**, name it anything (e.g. "My Donations"), type **Merchant**. +4. Copy the **Client ID** and **Secret** into the StreamGoals wizard (Step 1). +5. Click **Test connection**. On success the plugin registers its webhook with PayPal automatically. + +Start in **Sandbox**, make a test donation using a PayPal sandbox buyer account, then repeat the steps +with the Live credentials and switch the mode to Live in Settings. + +### Notes on fees and currency +- "Cover the processing fees" adds an estimate based on the rates in Settings (default: US domestic, + 3.49% + $0.49). Your actual PayPal rate depends on your account, country and payment method. +- Cross-border and currency-conversion fees are **not** included in the estimate, so a covered donation + from another country can net slightly less than intended. +- One currency per site. PayPal converts for donors paying from another currency. +- Donations are not tax-deductible. Don't present them as such. + +## Using it +- **Donation page:** add the shortcode `[streamgoals_donate]` to a page (or `[streamgoals_donate goal="ID"]` to pin one goal). +- **Goals:** StreamGoals → Goals. Create as many as you like; each can have its own rules. +- **Rules (time and counters):** per goal, e.g. "+60 seconds per $1" (subathon timer), "+1 per $10" (counter), + or a bonus event above a minimum amount. Amounts can be measured on the base donation or including fee cover. +- **Overlays:** StreamGoals → Overlays. Copy a widget URL into OBS as a **Browser Source** (suggested 800×200 + for the goal bar; transparent background is built in). Keep the URL private; "Regenerate token" invalidates it. +- **Test:** "Send test donation" on the Overlays screen shows an alert without touching real totals. + +## Privacy and moderation +- Donors choose a name or "Anonymous". For anonymous donors the **name is never stored**. +- Optional message approval queue and a streamer-controlled profanity filter (whole-word, your own word list). + +## Not supported +- **Refunds and chargebacks are not tracked.** If you refund someone in PayPal, goal totals, timers and + counters are not adjusted. + +## Development +``` +composer install +vendor/bin/phpunit +``` +Architecture notes are in `docs/ARCHITECTURE.md`. Every push to `main` runs the tests and, if they pass, +publishes a versioned zip release via Gitea Actions.