step3/docs/STRIPE_DONATIONS.md

Stripe Donations

RanaZe: Step 3 Trainer accepts authenticated, one-time USD contributions through Stripe-hosted Checkout. The API enforces a minimum contribution of $5 and a maximum of $10,000. Payment card data never passes through or is stored by RanaZe.

Contributions are not tax-deductible.

Stripe test-mode setup

1. In the Stripe Dashboard, switch to test mode.

2. Create the UAT test-mode webhook endpoint at:

   https://us3q.ranaze.com/api/donations/stripe-webhook

3. Subscribe the endpoint to these events:

   • checkout.session.completed
   • checkout.session.async_payment_succeeded
   • checkout.session.async_payment_failed
   • checkout.session.expired

4. Copy the webhook signing secret (whsec_...).

5. Copy a test secret API key (sk_test_...).

6. Add both values as Gitea Actions secrets in the API repository:

   • UAT_STRIPE_SECRET_KEY
   • UAT_STRIPE_WEBHOOK_SECRET

The deployment workflow writes these values to the environment's step3-runtime-secrets Kubernetes secret. Never commit either value to the repository.

Stripe account settings

Configure RanaZe branding in Stripe Checkout and enable successful-payment email receipts in Stripe customer email settings. Stripe Checkout collects the contributor's email address.

Verification

After deployment:

1. Sign in to RanaZe and open Support RanaZe from the sidebar.
2. Confirm that amounts below $5 and above $10,000 are rejected.
3. Start a $5 test contribution.
4. Complete Checkout using Stripe's standard test card 4242 4242 4242 4242, any future expiration date, and any CVC.
5. Return to RanaZe and confirm the contribution changes from pending to confirmed.
6. In Stripe, confirm the Checkout Session and webhook delivery both succeeded.
7. In MongoDB, confirm the corresponding Donations document has Status: "paid" and a populated PaidUtc value.

The client-visible status endpoint returns only the donation ID, amount, currency, status, creation time, and paid time. Stripe payment identifiers and webhook metadata remain server-side.

Live-mode cutover

1. Create https://s3q.ranaze.com/api/donations/stripe-webhook in Stripe live mode.
2. Set PRD_STRIPE_SECRET_KEY to the live secret key (sk_live_...).
3. Set PRD_STRIPE_WEBHOOK_SECRET to that endpoint's signing secret.
4. Trigger a deployment and complete a small real contribution.
5. Confirm the payment, receipt, webhook delivery, and paid status before announcing availability.

Test and live webhook signing secrets are different. Both Stripe secrets must always belong to the same Stripe mode.