## Summary This is BACKLOG Frog #2 ("plug the gen revenue leaks"), tip track. Tips were **27% of old order-form revenue** ($950 on 178 of 231 orders), and gen had nothing like them. - Both gen checkouts (credit packs and Made For You) now offer an **opt-in** Stripe Checkout `optional_items` tip: "Add to your order → Tip the creator (optional) $5 [+ Add]". - It's never pre-added. The old order form put a $5 tip line in the cart at quantity 1 (opt-out), which is banned for UK/EU consumers. - **Price:** $1/unit, found or created by `lookup_key=gen_checkout_tip_usd_1`. It defaults to 5 units and is adjustable from 1 to 100. - Live product `prod_VRY9FhfNhiS0NN` already exists, with a description explaining "each unit is $1". - Any Stripe error means no tip is offered, so checkout is never blocked. Kill switch: `CHECKOUT_TIP_ENABLED=false`. - **Accounting:** credits are untouched. `stripe_payments.tip_cents` records the tip separately. - Referral earnings exclude tips. If the tip can't be read from Stripe, the base is capped at the package list price (CodeRabbit finding). - Docs: STRIPE-SETUP.md has a new "Checkout Tip" section. ## Testing - Verified against **live Stripe**: created a real session (since expired, nothing charged), and the hosted page shows the tip as an opt-in "Add" item with the total unchanged. - `make test`: backend 5977, emulator 150, frontend Jest 1676, package 2044. All green. - New `backend/tests/test_checkout_tip.py`: price lookup and creation, kill switch, optional item on both checkouts, opt-in only, tip_cents, referral base. - Local CodeRabbit: 1 finding fixed. @coderabbitai ignore 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_019KuzHAU4rxkv8JfD8NmHTN Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
9.2 KiB
Stripe Setup Guide
This guide walks you through setting up Stripe for the Nomad Karaoke payment system.
Prerequisites
- A Stripe account (sign up at https://stripe.com)
- Access to Google Cloud Secret Manager (for secure credential storage)
- The Nomad Karaoke backend deployed and running
1. Get Your Stripe API Keys
- Log in to your Stripe Dashboard: https://dashboard.stripe.com
- Go to Developers > API keys
- You'll need two keys:
- Publishable key (starts with
pk_live_orpk_test_) - Secret key (starts with
sk_live_orsk_test_)
- Publishable key (starts with
Important
: Never commit your secret key to version control. Always use environment variables or Secret Manager.
2. Store Keys in Google Cloud Secret Manager
The secret containers are already created via Pulumi (in infrastructure/__main__.py). You just need to add the secret values:
# Store the Stripe secret key
echo -n "sk_live_your_key_here" | gcloud secrets versions add stripe-secret-key --data-file=-
# Store the webhook secret (after step 3)
echo -n "whsec_your_webhook_secret" | gcloud secrets versions add stripe-webhook-secret --data-file=-
Note
: If running for the first time after Pulumi creates the secrets, use
gcloud secrets versions add(notgcloud secrets create).
3. Set Up Webhook Endpoint
Webhooks notify your backend when payments complete.
In Stripe Dashboard:
- Go to Developers > Webhooks
- Click Add endpoint
- Enter your endpoint URL:
https://api.nomadkaraoke.com/api/users/webhooks/stripe - Select events to listen to:
checkout.session.completed(required - adds credits)checkout.session.expired(optional - logging)payment_intent.payment_failed(optional - logging)
- Click Add endpoint
- Copy the Signing secret (starts with
whsec_) - Store it in Secret Manager (see step 2)
4. Configure Environment Variables
Set these environment variables for your backend:
# Required
STRIPE_SECRET_KEY=sk_live_your_key_here
STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret
# Optional (defaults shown)
FRONTEND_URL=https://gen.nomadkaraoke.com
# BUY_URL defaults to FRONTEND_URL after site consolidation
# Payment Method Configuration (enables Google Pay, Apple Pay, Link)
# Get this from: Dashboard > Settings > Payment methods > [Your Config] > Copy ID
STRIPE_PAYMENT_METHOD_CONFIG=pmc_your_config_id_here
Payment Method Configuration
To enable Google Pay, Apple Pay, Link, and other wallet payment methods in your checkout:
- Go to Stripe Dashboard > Settings > Payment methods
- Create or select a configuration (e.g., "Default")
- Enable the payment methods you want (Google Pay, Apple Pay, Link, etc.)
- Copy the configuration ID (starts with
pmc_) - Set it as
STRIPE_PAYMENT_METHOD_CONFIG
Without this setting, checkout sessions will only show basic payment methods (cards, some regional methods). With it, customers will see Google Pay, Apple Pay, and Link options when available on their device.
For Cloud Run deployment:
The CI workflow (.github/workflows/ci.yml) automatically injects these secrets during deployment. No manual gcloud commands needed - just add the secret values to Secret Manager (step 2) and the next backend deployment will pick them up.
5. Configure Email Service (Postmark)
For sending magic link and purchase confirmation emails:
- Sign up for Postmark: https://postmarkapp.com
- Verify a sender signature or domain for
nomadkaraoke.com - Create a server and copy its Server API Token
- Store it in Secret Manager (secret container created by Pulumi):
echo -n "your_postmark_server_token" | gcloud secrets versions add postmark-server-token --data-file=-
- The environment variables are configured in the Cloud Run deployment. Defaults:
EMAIL_FROM=gen@nomadkaraoke.comEMAIL_FROM_NAME=Nomad Karaoke
6. Test the Integration
Test Mode
Use test keys (starting with pk_test_ and sk_test_) for testing:
- Use Stripe's test card:
4242 4242 4242 4242 - Any future expiration date
- Any 3-digit CVC
Verify Webhook Delivery
- In Stripe Dashboard, go to Developers > Webhooks
- Click on your endpoint
- View recent webhook attempts and their status
- Use the "Send test webhook" feature to verify connectivity
Credit Packages
The system comes with these default packages:
| Package | Credits | Price | Per Credit |
|---|---|---|---|
| 1 Credit | 1 | $5.00 | $5.00 |
| 3 Credits | 3 | $12.00 | $4.00 (20% off) |
| 5 Credits | 5 | $17.50 | $3.50 (30% off) |
| 10 Credits | 10 | $30.00 | $3.00 (40% off) |
To modify packages, edit backend/services/stripe_service.py:
CREDIT_PACKAGES = {
"1_credit": {
"credits": 1,
"price_cents": 500,
"name": "1 Karaoke Credit",
"description": "Create 1 professional karaoke video",
},
# Add more packages...
}
Legacy Payment Links (pre-gen)
Two Stripe Payment Links predate gen. Neither is in code; they were shared by hand. Dashboard/API changes are recorded here because they leave no trace in code.
| Link | Product | Status |
|---|---|---|
https://buy.stripe.com/dR67sx4wZcdt2DC9AA (plink_1PSsYyJqOK5vtxo4A1gBQUUO) |
"Custom Karaoke Video" $10 + optional $5 tip: the old nomadkaraoke.com "Buy Video" order form | Deactivated 2026-10-14. It now shows an inactive_message pointing to gen.nomadkaraoke.com (self-serve or Made For You). |
https://buy.stripe.com/00geUZgfHdhx6TS001 (plink_1R08pkJqOK5vtxo4qf1Sqq6v) |
"Custom Karaoke Service", customer-entered amount | Active. Used for tips: nomadkaraoke.com/tip, pay.nomadkaraoke.com (Cloudflare redirect), and the kjbox singer UI "Card / Apple Pay" tip button. |
Why dR67sx was deactivated: the last sale on it was 2025-12-23. From 2025-12-31 to 2026-10-08 it opened about 30 checkout sessions, and none completed. Andrew had emailed the link to regulars as "my order form", so returning customers kept landing on a $10 manual order that is no longer fulfilled. To undo: POST /v1/payment_links/plink_1PSsYyJqOK5vtxo4A1gBQUUO active=true.
Checkout Tip (optional add-on)
Both gen checkouts (credit packs and Made For You) offer an opt-in tip as a Stripe Checkout optional_items entry. It appears under "Add to your order"; the customer taps Add and can change the quantity. The tip is never pre-added to the cart: pre-ticked paid extras are banned for UK/EU consumers. The old order form did pre-add a $5 tip, and 77% of buyers kept it.
- Price: $1/unit, found by
lookup_key=gen_checkout_tip_usd_1(created automatically if missing). Default quantity is 5 ($5), adjustable from 1 to 100. Live product:prod_VRY9FhfNhiS0NN"Tip the creator (optional)". Its description ("each unit is $1...") was set via the API on 2026-10-14; an auto-created replacement would have no description. - Accounting: the tip is included in
amount_totalandusers.total_spent.stripe_payments.tip_centsrecords it separately. Referral earnings are calculated onamount_total - tip. - Credits are unaffected: they come from session metadata.
- Kill switch:
CHECKOUT_TIP_ENABLED=false. If Stripe errors, no tip is offered and checkout still works. - Caveat: a referral coupon (e.g. 50%) also discounts an added tip, because coupons apply to every line item.
Admin Features
Issue Free Credits
Admins can issue free credits via the API:
curl -X POST https://api.nomadkaraoke.com/api/users/admin/credits \
-H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"amount": 5,
"reason": "Beta tester reward"
}'
View Users
curl https://api.nomadkaraoke.com/api/users/admin/users \
-H "Authorization: Bearer YOUR_ADMIN_TOKEN"
Troubleshooting
Webhook Not Receiving Events
- Verify the endpoint URL is correct and publicly accessible
- Check the webhook signing secret matches
- Ensure your server returns 2xx status codes
- Check Cloud Run logs for errors
Credits Not Adding
- Verify
checkout.session.completedevent is being received - Check that
metadatacontainsuser_emailandcredits - Review backend logs for errors in
stripe_webhookhandler
Email Not Sending
- Verify Postmark server token is valid
- Check sender email/domain is verified in Postmark
- Review Postmark activity logs (Messages → Outbound) for suppressions or hard bounces
Security Considerations
- Never expose secret keys - Use environment variables or Secret Manager
- Always verify webhook signatures - The code does this automatically
- Use HTTPS - All Stripe communication must be over HTTPS
- Monitor webhook logs - Watch for failed deliveries or suspicious activity
- Set up alerts - Configure Stripe to alert on unusual activity
Going Live Checklist
- Switch from test to live API keys
- Update webhook endpoint to use live signing secret
- Verify email sending works with real addresses
- Test a real purchase with a small amount
- Set up Stripe Radar for fraud protection
- Configure Stripe tax settings if applicable
- Review and enable appropriate Stripe email receipts