Donations

Viewers donate on the marathon's own page. Donations can go toward incentives (a goal to reach, a bid war between options), moderators approve them before they show, and the total reaches the overlay on its own.

Payment is by Pix, through LivePix or Tipa, or by PayPal. The accounts are registered once per organization under Integrations, and each marathon picks the ones its donations can be paid into. With more than one (say PayPal and LivePix) the donor chooses how to pay on the donation page.

Integrations

Open Integrations on the organization page. Only the organizer and the beneficiary (whoever receives the money) can see it. Give the person who receives the money the beneficiary role, and they connect their own account without access to anything else.

An account can be used by other organizations too, but that is decided inside each of them: someone who is organizer or beneficiary of both opens the other organization's Integrations page and links the account under Linked to this organization. The account's own card only lists which organizations use it. Unlinking is done in the same place.

Then open a marathon's Donations page and pick the accounts in the Payment accounts card. You can pick several, and the same account can serve any number of marathons. Click an account again to take it off. Until an account is picked (and while it is paused or deleted) the donation page says donations aren't open.

Connecting LivePix

Click Connect LivePix and authorize the account on LivePix. If the authorization lapses, use Reconnect on its card.

To use your own LivePix app instead, create one in your LivePix account settings, then under LivePix with your own app enter a name, the app's Client ID and its Client secret. The connection is direct, with no authorization screen. The webhook is registered on your account for you, and its URL is shown on the page and on the card in case you prefer to register it by hand. Use Replace app credentials on the card after rotating the secret.

Tipa

Enter a name and the username of the page (tipa.ai/<username>) and register it.

The donation page shows the Pix QR code and the copy-and-paste code, and the donation reaches the moderation queue once the Pix is paid, within seconds. Nothing needs to be set up on Tipa, but you can paste the integration's webhook URL into your Tipa panel under Apps > Webhooks to confirm donations right away.

On Tipa's side the donation shows up under the marathon's name, without the donor's name or message, which stay in Speedthon for moderation. Tips paid directly on the Tipa page are not counted.

PayPal

The money goes straight to the PayPal account whose app credentials you give Speedthon, in reais. Whoever receives it does this once:

Sign in to the PayPal Business account that should receive the money. Personal accounts can't create the app Speedthon needs; a Business account is free to open.
Open developer.paypal.com, sign in with that same account and go to Apps & Credentials.
At the top choose Live for real payments, or Sandbox to test with fake accounts. Remember which one: the two have separate credentials.
Click Create App, name it (for example "Speedthon") and keep the type Merchant. In the app's features leave only Accept payments on and turn the rest off.
Copy the Client ID, then click Show under Secret key 1 and copy the secret.
In Speedthon open Integrations, find PayPal account, enter a name, the same environment as in step 3, the Client ID and the Secret, and register. Speedthon checks them with PayPal first; if it refuses them, recheck for typos and that the environment matches the app.
On the marathon's Donations page pick the account in the Payment accounts card.

To test, switch to Sandbox, create two accounts under Testing Tools > Sandbox Accounts (a Business one to receive, a Personal one to pay), create the app while signed in to the Business one, and register it here with the Sandbox environment. Pay with the Personal sandbox account on the donation page. Sandbox accounts are marked with a Sandbox badge; replace them with Live credentials before the event.

Keeping the credentials safe. The Client ID and Secret let whoever has them create and capture payments on that account.

Only the organizer and the beneficiary can enter them. They are checked with PayPal, stored encrypted, and never shown again: not on the page, not in the audit log, not to other staff. The audit log only records that they were registered or replaced.
Use an app made just for Speedthon, with only Accept payments on, and never one shared with another site or tool.
Type or paste the secret straight into Speedthon. Don't send it by chat or email; if it ended up somewhere it shouldn't, treat it as leaked.
If it leaks, or the person who knew it leaves the team, open the app on PayPal and generate a new secret (or delete the app) so the old one stops working, then open the account's card in Speedthon and use Replace the credentials.
Deleting the account in Speedthon doesn't delete the app on PayPal. Delete it there too if it won't be used again.
If the server's BETTER_AUTH_SECRET is ever changed, stored credentials can no longer be read and each account needs Replace the credentials.

The donor is sent to PayPal to pay in reais with their balance or card and comes back to the donation page. The donation reaches the moderation queue once the payment is captured, within seconds; if the donor never comes back, it is captured in the background within about half a minute. Nothing needs to be set up as a webhook.

On PayPal's side the payment shows under the marathon's name; the donor's name and message stay in Speedthon for moderation. The PayPal account must be able to receive BRL.

Incentives

Editors create incentives on the Donations page:

Goal: an amount to reach, such as "R$ 500 and the runner plays blindfolded".
Bid war: options that compete for donations, such as naming the character. A bid war can let donors suggest their own option, which a moderator approves.

An incentive can be tied to a run, and closes:

when its run starts (goals and choices), so donations after that go to the general total;
or by hand (bid wars), so it can stay open into the run.

Marathon goals are a separate thing, also on the Donations page: a title, a total to reach and an optional deadline ("R$ 7,000 raised by Saturday 20:00 unlocks a bonus run"). They count the marathon's whole approved total. Before the deadline a goal is reached as soon as the total gets there; after it, the verdict is final and judged by the total at the deadline.

Incentives proposed on run signups can be imported with one click. Deleting an incentive or option sends its money back to the general total.

Donation page

/<organization>/m/<marathon>/donate, open to everyone once the marathon is published.

At the top: the total raised so far, the donor's amount, and the total with that donation, so donors can see what rounding up does. Below, the amount, name, email and message sit side by side.

Marathon goals are on the right, always visible. They follow the total on their own and need no choice from the donor; the page shows which ones the donation would unlock and offers to donate the exact amount that reaches the next one.

Incentives come below, soonest to close first, with the ones closing within 3 hours flagged. Donors may point part of the donation at any open incentive: a slider sets a share of the donation, or they type an amount. An incentive can take at most what the others left; if a typed amount goes over the donation, the page offers to raise the donation. What is not assigned goes to the general total.

Paying shows the Pix QR code and copy-and-paste code in a dialog, so the donor never leaves the page.

Signing in is optional. It fills in the name and email and links the donation to the account. Anyone can donate as anonymous: public pages and the overlay show "Anonymous", while moderators still see the name.

Tracker. /<organization>/m/<marathon>/tracker shows the incentives with their progress and bid war standings, the approved total, the number of donations and the largest one, and every donation, newest first.

Moderation

Donations arrive pending. Moderators and staff approve or reject them in the queue on the live dashboard or on the full review page, /<organization>/m/<marathon>/donations/review, with tabs for pending, approved, rejected and all, and search.

Approving can also point a donation at an incentive or option, for donations that arrived without one (such as those made on LivePix's own page). Either decision can be undone.

Only approved donations count toward totals and show on stream. The donation total module updates as soon as one is approved.