Going to Production

Before You Accept Real Payments

This checklist covers everything you need to do before accepting real payments. Work through each section in order — skipping a step may cause issues with live transactions.

Prefer managed infrastructure? Recurso Cloud handles hosting, scaling, backups, and SSL so you can skip most of this checklist. Compare plans

1. Switch to Live API Keys

During development you use test-mode keys (prefixed rzp_test_ / sk_test_). For production, generate and configure live keys.

.env

# Replace test keys with live keys
RAZORPAY_KEY_ID=rzp_live_xxxxxxxxxxxx
RAZORPAY_KEY_SECRET=your_live_secret

STRIPE_SECRET_KEY=sk_live_xxxxxxxxxxxx
STRIPE_WEBHOOK_SECRET=whsec_xxxxxxxxxxxx

Generate a production Recurso API key from Settings > API Keys and store it securely (e.g., in a secrets manager, not in source code).

Never commit live API keys to version control. Use environment variables or a secrets manager like AWS Secrets Manager, HashiCorp Vault, or Doppler.

2. Configure Payment Gateways

Razorpay (India)

Log in to Razorpay Dashboard and switch to Live Mode
Complete KYC verification (required for live payouts)
Copy the live Key ID and Key Secret to your environment
Enable auto-capture in Razorpay settings so payments are captured immediately

Stripe (Global)

Activate your Stripe account (requires business verification)
Copy the live secret key and webhook signing secret
Create a webhook endpoint in Stripe pointing to your Recurso instance: https://your-domain.com/webhooks/stripe

See the Payment Gateways guide for detailed configuration.

3. Set Up Webhook Endpoints

Configure production webhook URLs in Recurso to receive billing events.

The examples below use https://api.recurso.dev as a placeholder for your Recurso instance. Substitute the domain where your deployment is hosted.

curl -X POST https://api.recurso.dev/v1/webhooks \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-domain.com/webhooks/recurso",
    "events": [
      "subscription.created",
      "subscription.canceled",
      "payment.succeeded",
      "payment.failed",
      "invoice.paid",
      "invoice.payment_failed"
    ],
    "secret": "whsec_your_webhook_secret"
  }'

Verify your endpoint:

Returns 200 status within 5 seconds
Validates the X-Recurso-Signature header (see Webhooks guide)
Handles duplicate deliveries idempotently

4. Enable E-Invoicing (India)

If you are registered under India’s GST e-invoicing mandate (turnover above the threshold), configure your IRP credentials.

curl -X POST https://api.recurso.dev/v1/settings/irp \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "gstin": "29ABCDE1234F1Z5",
    "irp_username": "your_irp_user",
    "irp_password": "your_irp_password",
    "auto_generate": true
  }'

Test the connection before going live:

curl -X POST https://api.recurso.dev/v1/settings/irp/test \
  -H "Authorization: Bearer $API_KEY"

See the E-Invoicing guide for details.

5. Configure DNS and HTTPS

Ensure your Recurso instance is accessible over HTTPS with a valid TLS certificate.

Requirement	Details
Domain	Point your DNS (e.g., `billing.yourapp.com`) to your server
TLS certificate	Use Let’s Encrypt, AWS ACM, or Cloudflare for automatic certificates
HTTPS only	Redirect all HTTP traffic to HTTPS
Firewall	Allow inbound traffic on ports 443 (HTTPS) and block direct access to port 8080

Reverse Proxy Example (nginx)

server {
    listen 443 ssl;
    server_name billing.yourapp.com;

    ssl_certificate /etc/letsencrypt/live/billing.yourapp.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/billing.yourapp.com/privkey.pem;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

6. Environment Variables for Production

Review all environment variables before launch.

.env

# Core
DATABASE_URL=postgres://user:pass@prod-db:5432/recurso
PORT=8080

# Payment Gateways (LIVE keys)
RAZORPAY_KEY_ID=rzp_live_xxxxxxxxxxxx
RAZORPAY_KEY_SECRET=<live-secret>
STRIPE_SECRET_KEY=sk_live_xxxxxxxxxxxx
STRIPE_WEBHOOK_SECRET=whsec_xxxxxxxxxxxx

# Email (production SMTP)
SMTP_HOST=smtp.your-email-provider.com
SMTP_PORT=587
SMTP_USER=billing@yourapp.com
SMTP_PASSWORD=<smtp-password>

# Webhook
WEBHOOK_SECRET=whsec_your_webhook_secret

# US sales tax (US sellers): live jurisdiction rates via TaxJar.
# Unset = US invoices ship at 0% marked sales_tax_stub.
# See /compliance/us-sales-tax for the full behavior matrix.
COMPANY_COUNTRY=US
COMPANY_STATE=CA
TAXJAR_API_KEY=<taxjar-api-token>
# TAXJAR_API_URL=https://api.sandbox.taxjar.com   # sandbox only; default is production

# Analytics: reporting currency for FX-normalized MRR (default USD).
# A tenant's BaseCurrency, when set, wins over this value.
REPORTING_CURRENCY=USD

# Operational alerting (see section 7)
ALERT_WEBHOOK_URL=https://hooks.slack.com/services/T000/B000/XXXX
ALERT_WEBHOOK_FORMAT=slack   # json (default) | slack

# API rate limit per key (default 500/min)
RATE_LIMIT_PER_MINUTE=500

7. Monitoring and Alerting Checklist

Set up monitoring to catch issues before your customers do.

Built-in Health Alerting

The API ships with a health watcher: every 60 seconds it evaluates the same component checks as GET /health (PostgreSQL, Redis if configured, TigerBeetle) and POSTs an alert to ALERT_WEBHOOK_URL on state transitions only — one alert when a component goes down (PostgreSQL = critical, Redis/TigerBeetle = warning), one when it recovers. No repeats while the state is steady, and no alerts at all if the variable is unset.

.env

# Any HTTP endpoint, or a Slack incoming webhook with format=slack
ALERT_WEBHOOK_URL=https://hooks.slack.com/services/T000/B000/XXXX
ALERT_WEBHOOK_FORMAT=slack   # json (default) | slack

Payload formats:

json → {"severity", "title", "body", "source": "recurso", "timestamp"}
slack → {"text": "[SEVERITY] title — body"} (Slack incoming webhooks)

The alert fires from inside the API process — if the process or host dies, nothing fires. Pair it with an external uptime monitor on /health for coverage the process cannot provide about itself.

External Monitoring

Health check endpoint

Monitor GET /health on your Recurso instance. Alert if it returns non-200 for more than 2 minutes.

Webhook delivery failures

Track webhook response codes. Alert on repeated 4xx/5xx responses — failed webhooks mean your app is not processing billing events.

Payment failure rate

Monitor the ratio of payment.failed to payment.succeeded webhooks. A sudden spike may indicate a gateway issue or expired credentials.

Database backups

Verify that automated database backups are running. Billing data is critical — test restoring from a backup at least once.

Log aggregation

Ship Recurso logs to a centralized service (Datadog, Grafana, CloudWatch) for debugging production issues.

Incident Response

Before going live, read the SEV1 incident runbook (the canonical copy lives in the main repository). In short:

Severities — SEV1: money moved wrongly or ledger integrity is broken; SEV2: payments degraded (money that should move, isn’t); SEV3: non-money functionality broken. When unsure, treat it as one level higher until the reconciliation report says the ledger is clean.
SEV1, in order — stop the bleeding (there is no partial kill-switch for individual workers; stopping outbound charges means stopping the API process), snapshot Postgres and logs before touching anything, verify ledger integrity with GET /v1/finance/reconciliation, then check the gateway dashboards — Stripe/Razorpay are the source of truth for money that actually moved.
Recovery — restore from pg_dump, replay missed gateway webhooks from the gateway dashboards (handlers are idempotent on payment state), and re-run reconciliation before re-enabling traffic.

The runbook also includes a symptom → first-command triage table and an honest list of current gaps (single alert channel, no status page, no per-worker kill switch).

8. Migrate Existing Subscribers (optional)

Moving from Stripe Billing, Chargebee, or spreadsheets? The cmd/import tool in the main repository loads plans, customers, and subscriptions directly into the database — without generating invoices or calling payment gateways, so migrated customers are never double-billed mid-cycle. Each imported subscription keeps its original billing period; Recurso issues the next invoice at its current_period_end.

# Dry-run first: validates the file, writes nothing
DATABASE_URL=postgres://... go run ./cmd/import \
  -tenant <your-tenant-uuid> -input data.json -dry-run

# Then import for real
DATABASE_URL=postgres://... go run ./cmd/import \
  -tenant <your-tenant-uuid> -input data.json

The import is idempotent — plans match by code, customers by email, subscriptions by external_id (the ID from your old system). Re-running skips anything that already exists, so partial failures are safe to retry.

Input is JSON (see cmd/import/example.json in the repo) or CSVs via -plans-csv, -customers-csv, and -subscriptions-csv.

Pre-Launch Checklist

Use this checklist to verify everything is ready:

Item	Status
Live payment gateway keys configured
Webhook endpoint reachable over HTTPS
Webhook signature verification working
E-invoicing IRP configured (if India)
TaxJar configured (if US seller — else US invoices are 0%/`sales_tax_stub`)
DNS pointing to production server
TLS certificate valid and auto-renewing
Environment variables set (no test keys)
Database backups enabled
Health check monitoring active
At least one test transaction completed end-to-end

Run at least one complete end-to-end transaction (plan > customer > subscription > payment) with live keys before opening to real customers. Use a small amount (e.g., 1 INR plan) and refund after testing.

Next Steps

Developer Settings

Configure API keys, rate limits, and tenant settings

Idempotency

Ensure your integration handles retries safely

Recurso Cloud

Skip infrastructure management with managed hosting

Get Started

Migrate to Recurso

Core Concepts

Usage & Monetization

Money & Books

Tax & Compliance

Recover & Retain

Customer Portal

Platform & Integrations

Deploy & Operate

Reference

Before You Accept Real Payments

1. Switch to Live API Keys

2. Configure Payment Gateways

Razorpay (India)

Stripe (Global)

3. Set Up Webhook Endpoints

4. Enable E-Invoicing (India)

5. Configure DNS and HTTPS

Reverse Proxy Example (nginx)

6. Environment Variables for Production

7. Monitoring and Alerting Checklist

Built-in Health Alerting

External Monitoring

Incident Response

8. Migrate Existing Subscribers (optional)

Pre-Launch Checklist

Next Steps

Developer Settings

Idempotency

Recurso Cloud

​Before You Accept Real Payments

​1. Switch to Live API Keys

​2. Configure Payment Gateways

​Razorpay (India)

​Stripe (Global)

​3. Set Up Webhook Endpoints

​4. Enable E-Invoicing (India)

​5. Configure DNS and HTTPS

​Reverse Proxy Example (nginx)

​6. Environment Variables for Production

​7. Monitoring and Alerting Checklist

​Built-in Health Alerting

​External Monitoring

​Incident Response

​8. Migrate Existing Subscribers (optional)

​Pre-Launch Checklist

​Next Steps

Developer Settings

Idempotency

Recurso Cloud

Before You Accept Real Payments

1. Switch to Live API Keys

2. Configure Payment Gateways

Razorpay (India)

Stripe (Global)

3. Set Up Webhook Endpoints

4. Enable E-Invoicing (India)

5. Configure DNS and HTTPS

Reverse Proxy Example (nginx)

6. Environment Variables for Production

7. Monitoring and Alerting Checklist

Built-in Health Alerting

External Monitoring

Incident Response

8. Migrate Existing Subscribers (optional)

Pre-Launch Checklist

Next Steps