## Summary - Add support for `STRIPE_PAYMENT_METHOD_CONFIG` environment variable to enable wallet payment methods (Google Pay, Apple Pay, Link) in Stripe Checkout sessions - Update `docs/STRIPE-SETUP.md` with configuration instructions - Add diagnostic scripts for testing Stripe payment method setup ## Context Investigation revealed that Google Pay and Link require the `payment_method_configuration` parameter to be passed to Stripe Checkout session creation. Without this, Stripe uses defaults which may not include all enabled wallet methods. Additional findings: - Link visibility is subject to Stripe A/B testing (confirmed by Stripe support) - Google Pay requires Chrome/Chromium browser (Firefox not supported) ## Test plan - [x] Tested checkout session creation with payment method config on Android Chrome - [x] Verified Google Pay and Link appear in checkout - [x] Verified made-for-you checkout flow shows all payment methods @coderabbitai ignore 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
6.6 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 (SendGrid)
For sending magic link and purchase confirmation emails:
- Sign up for SendGrid: https://sendgrid.com
- Create an API key with "Mail Send" permissions
- Store it in Secret Manager (secret container created by Pulumi):
echo -n "SG.your_sendgrid_api_key" | gcloud secrets versions add sendgrid-api-key --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...
}
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 SendGrid API key is valid
- Check sender email is verified in SendGrid
- Review SendGrid activity logs
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