Stripe (Payments)
Set up Stripe to accept payments through hosted Checkout sessions.
Prerequisites
- A Stripe account (test mode for development, live mode for production)
- Your deployment URL for webhook configuration
How it works
tripplan.ing uses Stripe hosted Checkout — attendees are redirected to a Stripe-hosted page to enter payment details. No card fields are rendered on your site. After payment, Stripe sends a webhook to confirm the transaction and the payment record is updated automatically.
Create a Stripe account
Sign up at stripe.com. New accounts start in test mode, which lets you simulate payments without real charges.
Get your API keys
- In the Stripe dashboard, navigate to Developers → API Keys
- Copy the Secret key — this is the value for
STRIPE_SECRET_KEY
TIP
Start with test keys (sk_test_...) during development. Switch to live keys (sk_live_...) only when deploying to production.
The publishable key is not needed — tripplan.ing uses server-side Checkout sessions exclusively.
Create a webhook endpoint
- In the Stripe dashboard, navigate to Developers → Webhooks
- Click Add endpoint
- Set the endpoint URL to
https://<your-domain>/api/stripe/webhook - Subscribe to the event:
checkout.session.completed - Click Add endpoint
- Copy the Signing secret — this is the value for
STRIPE_WEBHOOK_SECRET
Only checkout.session.completed is required. tripplan.ing does not listen for other Stripe events.
WARNING
Each deployment environment (development, production) needs its own webhook endpoint pointing to its own URL. Create separate endpoints for each.
Configure tripplan.ing
Map your Stripe credentials to environment variables:
| Stripe value | Environment variable | Example |
|---|---|---|
| Secret key | STRIPE_SECRET_KEY | sk_test_abc123... |
| Webhook signing secret | STRIPE_WEBHOOK_SECRET | whsec_abc123... |
For local development, add these to .dev.vars:
STRIPE_SECRET_KEY=sk_test_abc123...
STRIPE_WEBHOOK_SECRET=whsec_abc123...For production, set these as GitHub Environment secrets (see Environment & Secrets).
Per-event overrides
Events can use different Stripe accounts by setting per-event credentials in /admin/settings:
| Event setting | Overrides | Purpose |
|---|---|---|
stripeSecretKey | STRIPE_SECRET_KEY | Use a separate Stripe account for this event |
stripeWebhookSecret | STRIPE_WEBHOOK_SECRET | Webhook secret for the per-event Stripe account |
The fallback chain is: per-event setting → global environment variable. If an event has no override, it uses the global credentials.
When using a per-event Stripe account, create a separate webhook endpoint in that Stripe account pointing to the same https://<domain>/api/stripe/webhook URL.
Test mode vs live mode
| Test mode | Live mode | |
|---|---|---|
| Key prefix | sk_test_... | sk_live_... |
| Real charges | No | Yes |
| Test cards | 4242 4242 4242 4242 | Real card numbers |
| Webhook events | Simulated | Real |
| Use for | Development, staging | Production |
Use test keys in your development environment and live keys in production. Never mix test and live keys in the same environment.
Verify it works
- Start the dev server with
make dev - Create an event with at least one add-on in
/admin/add-ons - Visit
/payon the event subdomain - Select an item and click "Pay"
- On the Stripe checkout page, use test card
4242 4242 4242 4242with any future expiry and any CVC - After redirect, check
/admin/payments— the payment should show ascompleted
If the payment shows as completed in Stripe but pending in the admin, the webhook was not delivered — see troubleshooting below.
Troubleshooting
| Symptom | Fix |
|---|---|
| Checkout page doesn't open | Verify STRIPE_SECRET_KEY is set and valid; check server logs for API errors |
Checkout works but payment stays pending | Webhook not delivered — verify endpoint URL and signing secret in Stripe dashboard |
| "No signatures found matching the expected signature" | STRIPE_WEBHOOK_SECRET doesn't match the endpoint; regenerate and update |
| "Invalid API Key provided" | Key is expired or from wrong mode (test vs live); copy a fresh key from Stripe |
| Webhook endpoint shows errors in Stripe | Check the error details in Developers → Webhooks → Endpoint → Attempts |
| Per-event override not working | Confirm the override values are saved in /admin/settings; the event falls back to global if empty |
Related pages
- Payments — organizer guide for managing payments
- Environment & Secrets — full environment variable inventory
- PayPal (Payments) — alternative payment method setup