shadowdaoandClaude Sonnet 5.5 a41ad107a1
Test and Release / test (push) Successful in 2m1s
Test and Release / release (push) Successful in 14s
Donate form: fill container width, centre block, left-align text inside theme-centred modules
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0185ukXhhC8xipsBR7e3o76i
2026-11-16 06:48:30 -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.

Requires WordPress 7.x, PHP 8.1+, and a PayPal Business account to take live payments (see below).

Install

  1. Download streamgoals-donate.zip from the latest release.
  2. WordPress admin → Plugins → Add New → Upload Plugin → activate.
  3. Open StreamGoals in the admin menu. The setup wizard walks you through the rest.

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.

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.

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.

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.

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).
    • 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.
  • 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.
  • 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.
  • 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.
  • 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).
  • 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).

Not supported

  • 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.

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.

Updates

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.

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.

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).

S
Description
StreamGoals Donate: PayPal donations, goals and OBS stream overlays for WordPress
Readme GPL-2.0
927 KiB
0 Stars 1 Watchers 0 Forks
2026-11-16 16:39:55 +00:00
Languages
PHP 88%
JavaScript 8.7%
CSS 3.3%