Skip to content

heymegabyte/agent-skills / 06-build-and-slice-loop

build-and-slice-loop

Verified

Use when implementing features or streaming OnePrompt site builds. Complete vertical slices with real content, strict TypeScript and Zod. Parallel section/data work, deterministic assembly, granular patches and immediate valid previews.

FileKindSize
SKILL.mdskill md7.2 KB
admin-dashboard.mdmarkdown5.5 KB
ai-chat-widget.mdmarkdown6.0 KB
blog-and-content-engine.mdmarkdown6.2 KB
build-breaking-rules.mdmarkdown7.4 KB
chat-native-dashboard.mdmarkdown3.6 KB
contact-forms-and-endpoints.mdmarkdown6.7 KB
copilot-and-ai-features.mdmarkdown7.4 KB
custom-error-pages.mdmarkdown4.5 KB
data-tables.mdmarkdown7.7 KB
domain-provisioning.mdmarkdown4.6 KB
easter-eggs.mdmarkdown4.7 KB
empty-states-and-loading.mdmarkdown5.7 KB
file-uploads-and-storage.mdmarkdown6.7 KB
internationalization.mdmarkdown4.3 KB
keyboard-shortcuts-and-command-palette.mdmarkdown6.7 KB
microcopy-library.mdmarkdown8.0 KB
notification-center.mdmarkdown8.4 KB
onboarding-and-first-run.mdmarkdown5.0 KB
pre-digested-builds.mdmarkdown3.6 KB
pwa-kit.mdmarkdown6.8 KB
realtime-and-websockets.mdmarkdown7.2 KB
rich-text-editor.mdmarkdown7.4 KB
site-search.mdmarkdown4.0 KB
stripe-first-donations.mdmarkdown10.7 KB
web-manifest-system.mdmarkdown11.9 KB
webhook-system.mdmarkdown9.5 KB

stripe-first-donations.md

View on GitHub
---
name: "Stripe-First Donations"
version: "1.0.0"
updated: "2026-05-03"
description: "Every non-profit/donation-CTA site uses Stripe Connect Standard as the primary payment rail with GiveDirectly-style preset amounts, monthly-default frequency toggle, 2.9%+30¢ platform fee with cover-the-fees checkbox. PayPal/Donorbox/Network for Good are NEVER primary — they may appear as secondary fallbacks only. Build-breaking validator `validate-donation-stripe-first.mjs` fails any site whose primary donation widget is not Stripe Connect."
---

# Stripe-First Donations

## Why Stripe Connect Standard (***NON-NEGOTIABLE PRIMARY RAIL***)

GiveDirectly | GiveWell | charity:water | Watsi | Mercy Corps | Wikimedia all run Stripe Connect Standard. Reasons:

1. Lowest published rate 2.2% + 30¢ for verified non-profits via Stripe's non-profit pricing program (`https://stripe.com/nonprofits`)
2. Inline embedded checkout (no redirect)
3. ACH + SEPA + iDEAL + Apple Pay + Google Pay native
4. Recurring (`price.recurring.interval=month`) with one API call
5. Stripe Tax handles sales-tax/VAT/GST automatically
6. Stripe Radar fraud-blocks bad cards

- PayPal Smart Buttons require redirect, lose 1.7-3% of conversions, no native ACH
- Donorbox/Network for Good iframe widgets degrade brand recognition + add ~$50/mo fees on top of processing
- Stripe Connect Standard onboards the org's own bank account so funds settle T+2 to the org, NOT to a platform account

## The Component Contract (drop into `src/components/donation/StripeDonationForm.tsx`)

```tsx
import { useState } from 'react';
import { loadStripe } from '@stripe/stripe-js';
import { Elements, PaymentElement, useStripe, useElements } from '@stripe/react-stripe-js';

interface StripeDonationFormProps {
  orgConnectId: string;          // acct_xxx from Stripe Connect onboarding (server-side env)
  presets?: number[];            // default GiveDirectly: [10, 25, 50, 100, 250, 500]
  defaultMonthly?: boolean;      // default true — recurring is the bottom-line move
  defaultAmount?: number;        // default 50
  currency?: 'usd' | 'eur' | 'gbp' | 'cad' | 'aud';  // default 'usd'
  coverFees?: boolean;           // default true — checkbox shown checked
  brandColor: string;            // primary brand hex for button + selected preset border
  onSuccess?: (paymentIntentId: string) => void;
  onError?: (msg: string) => void;
}

export function StripeDonationForm(props: StripeDonationFormProps) {
  const presets = props.presets ?? [10, 25, 50, 100, 250, 500];
  const [amount, setAmount] = useState(props.defaultAmount ?? 50);
  const [frequency, setFrequency] = useState<'one-time' | 'monthly'>(props.defaultMonthly ? 'monthly' : 'one-time');
  const [coverFees, setCoverFees] = useState(props.coverFees ?? true);
  // Stripe + Elements wiring — see /api/donate/intent endpoint below
  // ...
}
```

## Preset Amounts (GiveDirectly Pattern)

- Universal preset ladder — `[10, 25, 50, 100, 250, 500]`
- 6-tile grid (3×2) is the highest-converting layout (Donorbox 2024 benchmark — 6 presets vs 4 presets = +18% completion)
- $50 is highlighted as default
- Custom-amount input shows beneath the grid with `min={1} max={50000} step={1}`
- Currency symbol prefix matches `currency` prop
- **Never** use round even ladders like `[5, 10, 20, 50, 100, 200]` — the GiveDirectly spread tests significantly better

## Frequency Toggle (Monthly = Default)

- Two-tab segmented control above the amount grid — `[Monthly] [One-time]`
- Monthly is selected by default and visually emphasized (brand-color background, white text)
- Below the toggle — small italic copy `"Monthly donations help us plan and budget — change or cancel anytime"`
- **Why monthly default** — GiveDirectly + charity:water both default monthly. LTV per donor is 4-7× higher than one-time when monthly is the default vs opt-in (Bloomerang, 2023).
- **Build-breaking** — any donation widget where one-time is the default OR monthly is hidden behind a click = fail

## Cover-The-Fees Checkbox

- **Label** — `"Cover the 2.9% + $0.30 fee so 100% of my gift reaches the mission"`
- Checkbox checked by default
- **Math** — `displayedTotal = amount + (amount * 0.029 + 0.30)` rounded to nearest cent
- Show the bumped total under the checkbox — `"You'll be charged $51.78 — $50.00 to {OrgName} + $1.78 fee coverage"`
- When unchecked — `"You'll be charged $50.00 — {OrgName} receives $48.25 after Stripe fees"`
- ~75% of donors leave the box checked when default-on (Classy 2024 study)
- For non-profit Stripe pricing rate (2.2% + 30¢), substitute — `amount * 0.022 + 0.30`
- Fee-cover math MUST live server-side — client value is display-only

## Backend Endpoint (`POST /api/donate/intent`)

```ts
import { Hono } from 'hono';
import { zValidator } from '@hono/zod-validator';
import { z } from 'zod';
import Stripe from 'stripe';

const donateBody = z.object({
  amount: z.number().int().min(100).max(5_000_000),  // cents
  frequency: z.enum(['one-time', 'monthly']),
  coverFees: z.boolean(),
  email: z.string().email(),
  name: z.string().min(1).max(120),
  currency: z.enum(['usd', 'eur', 'gbp', 'cad', 'aud']).default('usd'),
});

app.post('/api/donate/intent', zValidator('json', donateBody), async (c) => {
  const stripe = new Stripe(c.env.STRIPE_SECRET_KEY, { apiVersion: '2024-11-20.acacia' });
  const { amount, frequency, coverFees, email, name, currency } = c.req.valid('json');

  const totalCents = coverFees
    ? Math.round((amount / 100 + (amount / 100) * 0.029 + 0.30) * 100)
    : amount;

  if (frequency === 'monthly') {
    const customer = await stripe.customers.create(
      { email, name, metadata: { source: 'donation_widget' } },
      { stripeAccount: c.env.ORG_CONNECT_ID }
    );
    const price = await stripe.prices.create(
      { unit_amount: totalCents, currency, recurring: { interval: 'month' }, product_data: { name: `Monthly donation to ${c.env.ORG_NAME}` } },
      { stripeAccount: c.env.ORG_CONNECT_ID }
    );
    const subscription = await stripe.subscriptions.create(
      { customer: customer.id, items: [{ price: price.id }], payment_behavior: 'default_incomplete', payment_settings: { save_default_payment_method: 'on_subscription' }, expand: ['latest_invoice.payment_intent'] },
      { stripeAccount: c.env.ORG_CONNECT_ID }
    );
    const pi = (subscription.latest_invoice as Stripe.Invoice).payment_intent as Stripe.PaymentIntent;
    return c.json({ clientSecret: pi.client_secret, type: 'subscription', subscriptionId: subscription.id });
  }

  const paymentIntent = await stripe.paymentIntents.create(
    { amount: totalCents, currency, automatic_payment_methods: { enabled: true }, receipt_email: email, metadata: { donor_name: name, original_amount_cents: String(amount), cover_fees: String(coverFees) } },
    { stripeAccount: c.env.ORG_CONNECT_ID }
  );
  return c.json({ clientSecret: paymentIntent.client_secret, type: 'one-time' });
});
```

- Note `stripeAccount: ORG_CONNECT_ID` on every call — funds route to the org's connected account, NOT the platform
- Webhook handler at `/webhooks/stripe` MUST verify `event.account === ORG_CONNECT_ID` for donation events

## Connect Onboarding Flow (one-time per org)

1. Org owner signs into admin dashboard → "Set up donations" → POST `/api/connect/onboard`
2. Server creates Account Link via `stripe.accountLinks.create({ account, refresh_url, return_url, type: 'account_onboarding' })`
3. Owner completes Stripe-hosted onboarding (bank account, EIN/501c3 verification, identity)
4. Webhook `account.updated` with `charges_enabled=true` and `details_submitted=true` flips `orgs.stripe_connect_status='live'` in D1
5. Donation widget hides until `stripe_connect_status='live'`. Until then, show `"Donations open soon — sign up for alerts"` + email capture.

## Receipt Email (Resend)

- Triggered by webhook `payment_intent.succeeded` (one-time) or `invoice.payment_succeeded` (recurring)
- Template includes — org name + 501(c)(3) EIN + donation amount + date + payment method last4 + tax-deductible language + monthly cancel link (recurring only)
- Send via Resend with `from: "donations@{org-domain}"` (verified)
- Subject — `"Your $50 donation to {OrgName} — receipt"`

## Secondary Rails (NEVER PRIMARY)

- PayPal Smart Buttons | Donorbox | Network for Good | Givebutter | GoFundMe Charity may appear as a "More ways to give" expand below the Stripe form for donors who insist
- Acceptable secondary widget shape — `<details><summary>More ways to give</summary>...</details>` collapsed by default
- **Never** an iframe widget that competes with the Stripe form for above-the-fold attention
- **Build-breaking** — any site with a Donorbox/PayPal/Givebutter widget rendered ABOVE the Stripe form OR with no Stripe form at all = fail

## Validator (`scripts/validators/validate-donation-stripe-first.mjs`)

```js
// Pseudo: load every page HTML, find donation sections (heuristic: contains 'donate'|'give'|'support our mission'),
// assert: Stripe Elements present (script src=js.stripe.com OR @stripe/stripe-js bundle string),
// assert: NOT preceded above-the-fold by donorbox.org iframe OR paypal.com/sdk/js.
fail when: donation page exists AND js.stripe.com NOT in HTML.
fail when: donorbox.org iframe present AND js.stripe.com missing.
fail when: paypal.com/sdk/js present AND js.stripe.com missing.
fail when: monthly toggle missing on donation form (assert ['monthly','one-time'] both as text content of toggle buttons).
fail when: presets missing — assert at least 5 of [10, 25, 50, 100, 250, 500] visible as button labels with $ prefix.
fail when: cover-fees checkbox missing — assert any input[type=checkbox] sibling text contains 'cover'+'fee'.
```

Runs in `report` mode initially → flips to `strict` after njsk.org + lonemountainglobal.com benchmarks pass clean.

## Reference Incidents (canonical fixes)

- **njsk.org (2026-05-02)** — Original site uses PayPal Smart Buttons exclusively → rebuild MUST replace with Stripe Connect form using GiveDirectly presets. Connect onboarding deferred to admin dashboard; widget shows "Donations launching soon" until org completes onboarding.
- **lonemountainglobal.com (2026-05-02)** — Source uses Donorbox iframe widget. Rebuild replaces with native Stripe form. Donorbox kept ONLY in the `<details>` "More ways to give" expand for donor familiarity.

## Cross-Refs

- Validator registered in `~/.agentskills/15-site-generation/quality-gates.md` row 67 (`validate-donation-stripe-first.mjs`)
- Component lives in `~/.agentskills/15-site-generation/template-system.md` `<StripeDonationForm>` entry
- Fee-cover banned-words exemption — "100% of my gift reaches the mission" stays — it's a quantitative, sourced claim (the math actually delivers 100% to the org when fees covered)
- Pricing program — `https://stripe.com/nonprofits` — orgs MUST apply once verified 501(c)(3) for the 2.2% + 30¢ rate
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall