2026-11-15 10:26:23 -08:00
|
|
|
|
# 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.
|
|
|
|
|
|
|
2026-11-15 10:30:59 -08:00
|
|
|
|
Requires WordPress 7.x, PHP 8.1+, and a **PayPal Business** account to take live payments (see below).
|
2026-11-15 10:26:23 -08:00
|
|
|
|
|
|
|
|
|
|
## 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.
|
|
|
|
|
|
|
2026-11-15 10:30:59 -08:00
|
|
|
|
## Which PayPal account?
|
|
|
|
|
|
- **Testing:** nothing special. PayPal's Sandbox gives every developer account a sandbox business account
|
|
|
|
|
|
(the seller) and a sandbox personal account (the buyer).
|
|
|
|
|
|
- **Live payments:** PayPal's developer policy requires a **Business** account to go live. Upgrading a
|
|
|
|
|
|
Personal account is free, and a personal name is fine (no company needed).
|
|
|
|
|
|
- PayPal's User Agreement also expects accounts used mainly for business or donation-taking to be Business accounts;
|
|
|
|
|
|
a Personal account used that way risks limits or closure. Read PayPal's current terms before going live.
|
|
|
|
|
|
|
2026-11-15 10:26:23 -08:00
|
|
|
|
## 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.
|
|
|
|
|
|
|
2026-11-15 21:44:47 -08:00
|
|
|
|
### Going live
|
|
|
|
|
|
1. In the PayPal developer dashboard (Apps & Credentials), switch to **Live** and create a Live app (type Merchant).
|
|
|
|
|
|
2. In StreamGoals > Settings, paste the Live **Client ID** and **Secret**.
|
|
|
|
|
|
3. Switch the mode to **Live**, then **Save and test connection**.
|
|
|
|
|
|
4. Webhook: the plugin registers it for you when the test succeeds (changing mode or credentials clears the old one, so
|
|
|
|
|
|
the Live webhook is created fresh). It points to `https://YOUR-SITE/wp-json/streamgoals/v1/webhook` and listens for
|
|
|
|
|
|
`PAYMENT.CAPTURE.COMPLETED`. If the message says it could not register it (needs a public https site, or a webhook
|
|
|
|
|
|
for that address already exists), add it by hand in your Live app in the PayPal dashboard with that URL and that event.
|
|
|
|
|
|
5. Make a small real donation and check it appears under Donations and on your goal, then refund yourself in PayPal if you like.
|
|
|
|
|
|
6. Set the visitor IP header if needed (Settings > Advanced; Cloudflare is detected automatically).
|
|
|
|
|
|
7. Add the overlays in OBS as Browser Sources (StreamGoals > Overlays).
|
|
|
|
|
|
8. Turn on two-factor authentication for both your PayPal and WordPress accounts.
|
|
|
|
|
|
|
|
|
|
|
|
### Chargebacks and refunds
|
|
|
|
|
|
Chargebacks and refunds are handled manually in PayPal. The plugin does not track them, so totals, timers, counters
|
|
|
|
|
|
and tiers are not reduced. If you need to compensate, adjust the goal or its rules yourself by editing them.
|
|
|
|
|
|
|
2026-11-15 13:28:57 -08:00
|
|
|
|
### Behind Cloudflare?
|
|
|
|
|
|
Nothing to do: the plugin recognises Cloudflare automatically (by its published addresses) so each visitor is rate
|
|
|
|
|
|
limited separately. For another proxy, choose it in StreamGoals > Settings > Advanced; the panel there shows what your
|
|
|
|
|
|
server sees.
|
|
|
|
|
|
|
2026-11-15 10:26:23 -08:00
|
|
|
|
### 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).
|
2026-11-15 17:48:37 -08:00
|
|
|
|
- `show_progress="no"` hides the progress bar above the form (default `yes`; also accepts `true/false/1/0`).
|
|
|
|
|
|
- `[streamgoals_progress]` (or `[streamgoals_progress goal="ID"]`) shows just the progress bar, e.g. in a sidebar or a stream page.
|
|
|
|
|
|
The bar shows raised / target, the percentage and, for tiered goals, the current tier and its target, using the same
|
|
|
|
|
|
numbers as the overlay (base amounts, or including fees only if the goal counts fees). It refreshes after a donation and
|
|
|
|
|
|
about every 30 seconds while the tab is visible, from the public `GET /wp-json/streamgoals/v1/progress?goal=ID` (totals only).
|
|
|
|
|
|
The first render is server-side HTML, so page caches and Cloudflare are fine.
|
2026-11-15 10:26:23 -08:00
|
|
|
|
- **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.
|
2026-11-15 12:45:45 -08:00
|
|
|
|
- **Rewards (actions for set amounts):** StreamGoals > Rewards. Add things you do on stream for a set amount, for example
|
|
|
|
|
|
"$5: eat an every-flavor bean" or "$25: 25 pushups". Each reward is either *exactly this amount* or *every time the
|
|
|
|
|
|
donation adds up to this amount* (a $10 donation triggers a $5 reward twice). Rewards appear as buttons on the donation
|
|
|
|
|
|
form, as a **Rewards menu** overlay for OBS, and as a highlighted line in the donation alert. Triggered rewards land in a
|
|
|
|
|
|
**queue** on the Rewards screen so you can tick them off as you do them. Rewards count the donation amount, not the
|
|
|
|
|
|
optional fee cover, and must be at least your minimum donation.
|
2026-11-15 13:28:57 -08:00
|
|
|
|
- **Alerts with pictures, GIFs, videos and sounds:** StreamGoals > Alerts. Pick files from your WordPress Media Library
|
|
|
|
|
|
(PNG, JPEG, GIF, WebP, MP4, WebM for the picture/video; MP3, OGG, WAV for sound). Tie an alert to **a donation size**
|
|
|
|
|
|
("any donation of at least $5": the highest matching amount wins) or to **a reward** (a reward alert beats an amount
|
|
|
|
|
|
alert). Set the volume, how long a picture stays, and a message using `{name}`, `{amount}` and `{reward}`. In OBS media
|
|
|
|
|
|
plays automatically; in an ordinary browser tab click the page once before sound is allowed. Keep files small (videos
|
|
|
|
|
|
under about 25 MB). If a file is deleted the alert still shows, just without it.
|
|
|
|
|
|
- **Tiers (milestones):** on the Goals screen use **Tiers** to turn one goal into a ladder, for example $100 "Giveaway",
|
|
|
|
|
|
$250 "New microphone", $500 "24-hour stream". The goal bar shows the current tier and fills within it; unlocking a tier
|
|
|
|
|
|
shows a **TIER UNLOCKED** line in the alert and the bar moves on to the next one. The goal's final target is your highest
|
|
|
|
|
|
tier. The donation form shows "Next unlock: ... to go".
|
|
|
|
|
|
- **End at target:** tick "Close this goal to donations when the target is reached" on a goal. When the total reaches or
|
|
|
|
|
|
passes the target (for a tiered goal, the final tier) the goal closes and the donation page says so. Donations already
|
|
|
|
|
|
in checkout still go through. Use **Reopen** after raising the target.
|
2026-11-15 10:26:23 -08:00
|
|
|
|
- **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).
|
2026-11-15 17:07:32 -08:00
|
|
|
|
- The filter masks bad words in messages and in donor names (anonymous donors have no stored name). If a **donor name**
|
|
|
|
|
|
trips the filter, the donation still completes and counts towards the goal, timer, counters, rewards and tiers, but it
|
|
|
|
|
|
is **held on the Moderation screen** (flagged "Name", "Message" or "Name and message") even when message moderation is
|
|
|
|
|
|
off. A held donation shows no alert (name or message) and no public donor-feed entry until you approve it; approving
|
|
|
|
|
|
shows the already-masked name. Rejecting it means it is never shown.
|
|
|
|
|
|
- If the server dies right after a payment is recorded, a five-minute background job re-applies any timer, counter,
|
|
|
|
|
|
reward and tier effects that were missed (never twice).
|
2026-11-15 10:26:23 -08:00
|
|
|
|
|
|
|
|
|
|
## Not supported
|
2026-11-15 14:07:44 -08:00
|
|
|
|
- **Refunds and chargebacks are not tracked.** Refunds and chargebacks done in PayPal are NOT reflected in goal
|
|
|
|
|
|
totals, timers, counters or tiers. The donation keeps counting as if it had been paid.
|
2026-11-15 10:26:23 -08:00
|
|
|
|
|
2026-11-15 13:41:18 -08:00
|
|
|
|
## Transparent alerts
|
|
|
|
|
|
In StreamGoals > Alerts, tick **Frameless** on an alert to drop the dark box, border and glow so only your picture or
|
|
|
|
|
|
video shows. Transparency works with PNG, GIF and WebP pictures that have an alpha channel and with WebM (VP8/VP9)
|
|
|
|
|
|
videos made with alpha; MP4 (H.264) can never be transparent. To make a WebM with alpha:
|
|
|
|
|
|
`ffmpeg -i input.mov -c:v libvpx-vp9 -pix_fmt yuva420p -b:v 0 -crf 30 output.webm`. The name and bonus lines still
|
|
|
|
|
|
show under the media, outlined so they stay readable. The alert preview has a checkerboard/sample-scene backdrop.
|
|
|
|
|
|
|
|
|
|
|
|
## Overlays update themselves
|
|
|
|
|
|
An open OBS Browser Source never reloads on its own. Every overlay response now carries a build id (plugin version
|
|
|
|
|
|
plus a counter); when it differs from the one the page was loaded with, the overlay reloads itself once. Updating the
|
|
|
|
|
|
plugin does this automatically, and StreamGoals > Overlays > "Refresh all overlays now" does it on demand. Alert media
|
|
|
|
|
|
URLs also carry `?v=<file modified time>`, so replacing a file with the same name is picked up.
|
|
|
|
|
|
|
2026-11-15 11:53:42 -08:00
|
|
|
|
## Updates
|
2026-11-15 11:59:53 -08:00
|
|
|
|
New versions appear in WordPress automatically (Dashboard > Updates and the Plugins screen), checked against
|
|
|
|
|
|
this repository's releases. The repository is public, so no token is needed. (If you run a private fork, paste an
|
|
|
|
|
|
access token with read access to releases in StreamGoals > Settings > Advanced > Plugin updates.) You can switch
|
|
|
|
|
|
automatic updates on or off for this plugin on the Plugins screen, and use "Check for updates now" in
|
|
|
|
|
|
StreamGoals > Settings > Advanced to look straight away.
|
2026-11-15 11:53:42 -08:00
|
|
|
|
|
2026-11-15 10:26:23 -08:00
|
|
|
|
## 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.
|
2026-11-15 14:00:04 -08:00
|
|
|
|
|
|
|
|
|
|
## License
|
|
|
|
|
|
StreamGoals Donate is free software, released under the GNU General Public License, version 2 or (at your option)
|
|
|
|
|
|
any later version (GPL-2.0-or-later). See the `LICENSE` file for the full text.
|
|
|
|
|
|
|
|
|
|
|
|
## Uninstalling
|
|
|
|
|
|
Deleting the plugin from the Plugins screen always removes its scheduled task and cached data. Your donations, goals,
|
|
|
|
|
|
rules, rewards, alerts, tiers and settings are kept unless you first tick "Delete all data when the plugin is deleted"
|
|
|
|
|
|
in StreamGoals > Settings > Advanced (off by default; deleting cannot be undone).
|