Files
karaoke-gen/docs/STRIPE-SETUP.md
T
Andrew Beveridge ☄️andClaude Opus 5.5 542ad66b65 feat: opt-in 'tip the creator' add-on at gen checkout (v0.270.0) (#1155)
## 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>
2026-10-14 23:39:06 -04:00

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

  1. Log in to your Stripe Dashboard: https://dashboard.stripe.com
  2. Go to Developers > API keys
  3. You'll need two keys:
    • Publishable key (starts with pk_live_ or pk_test_)
    • Secret key (starts with sk_live_ or sk_test_)

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 (not gcloud secrets create).

3. Set Up Webhook Endpoint

Webhooks notify your backend when payments complete.

In Stripe Dashboard:

  1. Go to Developers > Webhooks
  2. Click Add endpoint
  3. Enter your endpoint URL: https://api.nomadkaraoke.com/api/users/webhooks/stripe
  4. Select events to listen to:
    • checkout.session.completed (required - adds credits)
    • checkout.session.expired (optional - logging)
    • payment_intent.payment_failed (optional - logging)
  5. Click Add endpoint
  6. Copy the Signing secret (starts with whsec_)
  7. 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:

  1. Go to Stripe Dashboard > Settings > Payment methods
  2. Create or select a configuration (e.g., "Default")
  3. Enable the payment methods you want (Google Pay, Apple Pay, Link, etc.)
  4. Copy the configuration ID (starts with pmc_)
  5. 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:

  1. Sign up for Postmark: https://postmarkapp.com
  2. Verify a sender signature or domain for nomadkaraoke.com
  3. Create a server and copy its Server API Token
  4. 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=-
  1. The environment variables are configured in the Cloud Run deployment. Defaults:
    • EMAIL_FROM=gen@nomadkaraoke.com
    • EMAIL_FROM_NAME=Nomad Karaoke

6. Test the Integration

Test Mode

Use test keys (starting with pk_test_ and sk_test_) for testing:

  1. Use Stripe's test card: 4242 4242 4242 4242
  2. Any future expiration date
  3. Any 3-digit CVC

Verify Webhook Delivery

  1. In Stripe Dashboard, go to Developers > Webhooks
  2. Click on your endpoint
  3. View recent webhook attempts and their status
  4. 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...
}

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_total and users.total_spent. stripe_payments.tip_cents records it separately. Referral earnings are calculated on amount_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

  1. Verify the endpoint URL is correct and publicly accessible
  2. Check the webhook signing secret matches
  3. Ensure your server returns 2xx status codes
  4. Check Cloud Run logs for errors

Credits Not Adding

  1. Verify checkout.session.completed event is being received
  2. Check that metadata contains user_email and credits
  3. Review backend logs for errors in stripe_webhook handler

Email Not Sending

  1. Verify Postmark server token is valid
  2. Check sender email/domain is verified in Postmark
  3. Review Postmark activity logs (Messages → Outbound) for suppressions or hard bounces

Security Considerations

  1. Never expose secret keys - Use environment variables or Secret Manager
  2. Always verify webhook signatures - The code does this automatically
  3. Use HTTPS - All Stripe communication must be over HTTPS
  4. Monitor webhook logs - Watch for failed deliveries or suspicious activity
  5. 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