Add README with install and PayPal setup guide
Test and Release / test (push) Successful in 1m15s
Test and Release / release (push) Successful in 8s

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
shadowdaoandClaude Sonnet 5.5 committed 2026-11-15 10:26:23 -08:00
1 parent 4efdef72f6
commit 19d399e8c7
1 file changed
+56
+56
View File
@@ -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 <https://developer.paypal.com> 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.