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