docs: correct Sponsorship & Donation System in the beta README
Evidence: spikersoft-backend@master SpikerSoft.Data/Mongos/Donation.cs:11 an organization gift is 100% operations, not an even split. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
1 parent
e2bccfacde
commit
e0aae206a7
1 file changed
+11
-8
@@ -1854,7 +1854,7 @@ Staff and admin users can manage locations and open positions via `/admin/locati
|
|||||||
|
|
||||||
## Sponsorship & Donation System
|
## Sponsorship & Donation System
|
||||||
|
|
||||||
SpikerSoft is a nonprofit organization. The sponsorship system enables donors to fund travel experiences for approved **individuals, children, and families** — under the "Sponsor a Journey" banner. The public landing page was rebranded family-first ("Family Exploration & Learning" / "Explore the World, Together"; the stat row leads with the *Families* count) and `/sponsor` now offers three view modes — Families, Families by destination, Individuals by destination — plus a "Location funds" section. The individual flow below came first; families and funds are documented in [Families, Family Funds & Location Funds](#families-family-funds--location-funds).
|
SpikerSoft is a nonprofit organization. The sponsorship system enables donors to fund travel experiences for approved **individuals, children, and families** — under the "Sponsor a Journey" banner. `/sponsor` is one page: a destination explorer (`?destination=`) and the people waiting for a sponsor. The old `families-by-destination` and `individuals-by-destination` views open that explorer. Location funds live at `/sponsor/fund/:code`. The individual flow below came first; families and funds are documented in [Families, Family Funds & Location Funds](#families-family-funds--location-funds).
|
||||||
|
|
||||||
**How It Works:**
|
**How It Works:**
|
||||||
|
|
||||||
@@ -1863,7 +1863,7 @@ SpikerSoft is a nonprofit organization. The sponsorship system enables donors to
|
|||||||
3. **Trip Cost Assignment** — Staff sets estimated travel costs per wishlisted destination for each approved profile.
|
3. **Trip Cost Assignment** — Staff sets estimated travel costs per wishlisted destination for each approved profile.
|
||||||
4. **Public Donation Page** — A public `/sponsor` page (no login required) displays approved profiles with their bio, interests, destinations, and funding progress.
|
4. **Public Donation Page** — A public `/sponsor` page (no login required) displays approved profiles with their bio, interests, destinations, and funding progress.
|
||||||
5. **Stripe Checkout** — Donors can donate to an individual or to the SpikerSoft organization. Payments are processed via Stripe Checkout with automatic nonprofit receipts.
|
5. **Stripe Checkout** — Donors can donate to an individual or to the SpikerSoft organization. Payments are processed via Stripe Checkout with automatic nonprofit receipts.
|
||||||
6. **Organization Donations** — Organization-wide donations are distributed evenly among all eligible (approved, not fully funded) profiles at the time of donation. New applicants do not retroactively receive prior donations.
|
6. **Organization Donations** — A gift to SpikerSoft (`/sponsor/donate-org`) is 100% operations. It is not split across travelers. A distributed gift (`/sponsor/donate-distributed`) is split evenly among approved profiles plus one organization share. New applicants do not receive prior donations.
|
||||||
7. **Overfunding** — When an individual is fully funded (total raised >= total trip cost), additional donations automatically redirect to the organization pool.
|
7. **Overfunding** — When an individual is fully funded (total raised >= total trip cost), additional donations automatically redirect to the organization pool.
|
||||||
8. **QR Code & Sharing** — Each sponsor profile page has a "Generate QR Code" button for creating business-card-ready QR codes linking to the donation page.
|
8. **QR Code & Sharing** — Each sponsor profile page has a "Generate QR Code" button for creating business-card-ready QR codes linking to the donation page.
|
||||||
|
|
||||||
@@ -1878,7 +1878,7 @@ SpikerSoft is a nonprofit organization. The sponsorship system enables donors to
|
|||||||
|
|
||||||
- Display name mode: First name + last initial, handle/alias only, or full name
|
- Display name mode: First name + last initial, handle/alias only, or full name
|
||||||
- Photo mode: Original, Cartoon (recommended for minors), or Hidden
|
- Photo mode: Original, Cartoon (recommended for minors), or Hidden
|
||||||
- **Cartoon mode** uses SixLabors.ImageSharp to generate a stylized cartoon version of the avatar (Gaussian blur + color quantization + edge detection composite), stored as a separate GridFS file
|
- **Cartoon mode** shows a cartoon avatar the parent picks from Art Studio, stored separately from the photo. It is not generated by an ImageSharp filter.
|
||||||
- This protects the child's identity while still showing a personalized image on the public donation page
|
- This protects the child's identity while still showing a personalized image on the public donation page
|
||||||
- Toggles for showing: bio, interests, destinations
|
- Toggles for showing: bio, interests, destinations
|
||||||
|
|
||||||
@@ -1911,7 +1911,7 @@ Stripe webhooks notify the backend when a payment is completed. Without a proper
|
|||||||
3. Set the **Endpoint URL** to your publicly accessible backend URL:
|
3. Set the **Endpoint URL** to your publicly accessible backend URL:
|
||||||
- Production: `https://your-domain.com/api/sponsor/webhook`
|
- Production: `https://your-domain.com/api/sponsor/webhook`
|
||||||
- Local development: Use [Stripe CLI](https://stripe.com/docs/stripe-cli) to forward events (see below).
|
- Local development: Use [Stripe CLI](https://stripe.com/docs/stripe-cli) to forward events (see below).
|
||||||
4. Under **Events to send**, select: `checkout.session.completed`.
|
4. Under **Events to send**, select `checkout.session.completed`, `checkout.session.expired`, `charge.refunded`, `charge.refund.updated`, `charge.dispute.created`, and `charge.dispute.closed`.
|
||||||
5. Click **Add endpoint**.
|
5. Click **Add endpoint**.
|
||||||
6. Copy the **Signing secret** (`whsec_...`) from the endpoint details page and set it as `Stripe:WebhookSecret` in `appsettings.json` (or your environment config).
|
6. Copy the **Signing secret** (`whsec_...`) from the endpoint details page and set it as `Stripe:WebhookSecret` in `appsettings.json` (or your environment config).
|
||||||
|
|
||||||
@@ -1929,7 +1929,7 @@ stripe listen --forward-to https://localhost:5001/api/sponsor/webhook
|
|||||||
# The CLI prints a webhook signing secret (whsec_...) — copy it into appsettings.Development.json
|
# The CLI prints a webhook signing secret (whsec_...) — copy it into appsettings.Development.json
|
||||||
```
|
```
|
||||||
|
|
||||||
The backend gracefully handles a missing `WebhookSecret` — if the value is empty, webhook payloads are parsed without signature verification and a warning is logged. This is acceptable during development but **must** be configured in production.
|
The backend accepts a donation webhook with a missing `WebhookSecret` and logs a warning. Refunds and other product fulfillments refuse an unverified event. Production **must** set the secret.
|
||||||
|
|
||||||
**Webhook Event Flow:**
|
**Webhook Event Flow:**
|
||||||
|
|
||||||
@@ -1939,7 +1939,8 @@ Donor completes Stripe Checkout
|
|||||||
→ POST /api/sponsor/webhook receives the event
|
→ POST /api/sponsor/webhook receives the event
|
||||||
→ Signature verified against WebhookSecret (if configured)
|
→ Signature verified against WebhookSecret (if configured)
|
||||||
→ Matching Donation record updated: Status → Completed, PaymentIntentId saved
|
→ Matching Donation record updated: Status → Completed, PaymentIntentId saved
|
||||||
→ For Organization donations: amount distributed evenly among eligible profiles
|
→ For an organization gift: the credited amount stays with operations
|
||||||
|
→ For a distributed gift: the amount is split evenly among approved profiles plus one organization share
|
||||||
→ Duplicate webhooks are safely ignored (idempotent)
|
→ Duplicate webhooks are safely ignored (idempotent)
|
||||||
```
|
```
|
||||||
|
|
||||||
@@ -1949,7 +1950,9 @@ Donor completes Stripe Checkout
|
|||||||
|--------|---------|
|
|--------|---------|
|
||||||
| `Pending` | Checkout session created, awaiting payment |
|
| `Pending` | Checkout session created, awaiting payment |
|
||||||
| `Completed` | Webhook confirmed successful payment |
|
| `Completed` | Webhook confirmed successful payment |
|
||||||
| `Failed` | Payment failed or was cancelled |
|
| `Failed` | Payment failed |
|
||||||
|
| `Refunded` | A completed gift was refunded or charged back |
|
||||||
|
| `Abandoned` | The donor opened Checkout and the session expired without a charge |
|
||||||
|
|
||||||
**Test vs. Production Keys:**
|
**Test vs. Production Keys:**
|
||||||
|
|
||||||
@@ -1970,7 +1973,7 @@ Public (no auth):
|
|||||||
Authenticated:
|
Authenticated:
|
||||||
- `GET /api/sponsor/settings` — Own sponsorship settings
|
- `GET /api/sponsor/settings` — Own sponsorship settings
|
||||||
|
|
||||||
Staff only:
|
Staff (finance can read donations):
|
||||||
- `GET /api/sponsor/profiles/pending` — Pending profiles
|
- `GET /api/sponsor/profiles/pending` — Pending profiles
|
||||||
- `POST /api/sponsor/profiles/{id}/approve` — Approve profile
|
- `POST /api/sponsor/profiles/{id}/approve` — Approve profile
|
||||||
- `DELETE /api/sponsor/profiles/{id}/approve` — Revoke approval
|
- `DELETE /api/sponsor/profiles/{id}/approve` — Revoke approval
|
||||||
|
|||||||
Reference in new issue
Block a user