Testing & Sandbox

Recurso is designed to be integrated against safely before a single real rupee or dollar moves. This page covers the three payment modes, how to confirm which one you’re in, how to simulate successes and failures, and how to test webhooks and dunning.

The three payment modes

Whether you’re moving real money is decided by your payment-gateway keys, not by your Recurso API key. Recurso surfaces the current mode as gateway_mode:

`gateway_mode`	When	What happens
`none`	No Stripe or Razorpay keys configured	The built-in mock gateway simulates every payment — nothing leaves your server
`test`	Stripe `sk_test…` or Razorpay `rzp_test…` keys	Real gateway test mode — use the provider’s test cards/UPI
`live`	Real gateway keys	Real money. Don’t point tests here

Your API key’s mode must match the server’s gateway_mode. A test key (rsk_test_…) is accepted on a none/test server and rejected on a live one (401 key_mode_mismatch); a live key (rsk_live_…) is the opposite. So a test key can never move real money — develop with one against a none/test instance. See Authentication.

Which mode am I in?

Ask the server. GET /version is unauthenticated and returns the mode:

curl https://api.recurso.dev/version

{ "version": "v0.4.0", "gateway_mode": "none" }

If you see none, you’re fully sandboxed on the mock gateway. If you see live, stop and point your tests at a non-production instance. The dashboard shows a Test mode chip driven by this same value.

Sandbox mode (mock gateway)

Run Recurso with no STRIPE_SECRET_KEY or RAZORPAY_KEY_ID set and every payment path is served by the mock gateway. This is the fastest way to wire up your integration — create plans, subscribe customers, generate invoices, and drive the full lifecycle without any provider account. What the mock gateway does:

Orders & checkout

CreateOrder returns a mock order_… id. Checkout verification succeeds.

Mandates (UPI)

CreateMandate returns a mock token and a mock authorization URL; mandate debits succeed.

Refunds

Refunds return status processed immediately.

Retries

Retry attempts succeed ~40% of the time with random decline codes — see Testing dunning.

Forcing a payment failure

To exercise your failure handling on the checkout verify path, pass the literal signature fail — the mock gateway will reject it:

curl -X POST https://api.recurso.dev/checkout/{invoice_id}/razorpay/verify \
  -H "Content-Type: application/json" \
  -d '{ "razorpay_order_id": "order_x", "razorpay_payment_id": "pay_x", "razorpay_signature": "fail" }'

Any other signature verifies successfully, so you can toggle between the happy and unhappy paths deterministically.

Gateway test mode

When you’re ready to test real gateway behavior (3-D Secure, actual UPI collect requests, provider webhooks), configure test keys and the mode flips to test:

export STRIPE_SECRET_KEY=sk_test_...      # Stripe test secret
export RAZORPAY_KEY_ID=rzp_test_...        # Razorpay test key id
export RAZORPAY_KEY_SECRET=...

Then pay with the providers’ documented test instruments:

Stripe (cards)
Razorpay (UPI & cards)

Scenario	Card
Success	`4242 4242 4242 4242`
Declined	`4000 0000 0000 0002`
Requires 3DS	`4000 0027 6000 3184`

Any future expiry and any CVC. Full list in Stripe’s testing docs.

Scenario	Instrument
UPI success	`success@razorpay`
UPI failure	`failure@razorpay`
Card success	`4111 1111 1111 1111`

Razorpay test mode never charges a real account.

Because routing is currency-based (INR → Razorpay, else → Stripe), test an INR invoice to hit Razorpay and a USD invoice to hit Stripe.

Testing webhooks

Two directions of webhooks are worth testing: Inbound (gateway → Recurso). Stripe and Razorpay call back to /webhooks/stripe and /webhooks/razorpay; Recurso verifies the signature on every event. To receive them on a local instance, use the Stripe CLI (stripe listen --forward-to localhost:8080/webhooks/stripe) or a tunnel such as ngrok for Razorpay, and set the matching webhook secret in your env. Outbound (Recurso → your app). Register an endpoint, then use the delivery log to inspect and replay:

# Register a webhook endpoint
curl -X POST https://api.recurso.dev/v1/webhooks \
  -H "Authorization: Bearer <your_api_key>" \
  -d '{ "url": "https://your-app.example.com/hooks", "events": ["invoice.paid"] }'

# Inspect deliveries, then redeliver a specific event to debug your handler
curl https://api.recurso.dev/v1/webhooks/{endpoint_id}/deliveries \
  -H "Authorization: Bearer <your_api_key>"

See Webhooks for signature verification code and the full event catalog.

Testing dunning and retries

On the mock gateway, retry attempts succeed ~40% of the time and otherwise return a random decline code (insufficient_funds, card_expired, card_declined, processing_error). That’s enough randomness to watch the smart retry engine schedule attempts, escalate a dunning campaign, and eventually mark an invoice recovered or exhausted. Create a subscription, let an invoice go past due, and observe the retry schedule and recovered-revenue attribution. See Smart Retry for how the bandit picks retry timing.

Idempotency in tests

Every mutating request accepts an Idempotency-Key header. Reusing the same key returns the original result instead of creating a duplicate — so a test that retries a flaky network call won’t double-charge or double-create:

curl -X POST https://api.recurso.dev/v1/subscriptions \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Idempotency-Key: test-sub-0001" \
  -d '{ "customer_id": "cust_123", "plan_id": "plan_pro" }'

Give each logical test operation a stable key. See Idempotency.

Loading and resetting test data

The demo dataset gives you a tenant with plans, customers, subscriptions, and invoices to poke at:

make demo   # builds & starts the full stack, then loads demo data
make seed   # reload demo data into an already-running stack

make seed wipes all data in the target database before loading — only run it against a development database.

After seeding, sign in to the dashboard and use the API with the demo key sk_test_12345. Emails the system “sends” land in Mailhog at http://localhost:8025 instead of real inboxes.

A pre-launch testing checklist

Sandbox the happy path

On gateway_mode: none, drive plan → customer → subscription → invoice → payment end-to-end.

Exercise failures

Force a verify failure (signature: fail), let a retry cycle run, and confirm your app handles declines and past-due states.

Switch to gateway test mode

Add sk_test/rzp_test keys and repeat with real test cards and UPI, in both INR and a non-INR currency.

Verify webhooks both ways

Confirm inbound gateway events are accepted and your outbound endpoint receives and can replay events.

Go live deliberately

Only then follow Going to Production to switch to live keys.

Get Started

Migrate to Recurso

Core Concepts

Usage & Monetization

Money & Books

Tax & Compliance

Recover & Retain

Customer Portal

Platform & Integrations

Deploy & Operate

Reference

The three payment modes

Which mode am I in?

Sandbox mode (mock gateway)

Orders & checkout

Mandates (UPI)

Refunds

Retries

Forcing a payment failure

Gateway test mode

Testing webhooks

Testing dunning and retries

Idempotency in tests

Loading and resetting test data

A pre-launch testing checklist

​The three payment modes

​Which mode am I in?

​Sandbox mode (mock gateway)

Orders & checkout

Mandates (UPI)

Refunds

Retries

​Forcing a payment failure

​Gateway test mode

​Testing webhooks

​Testing dunning and retries

​Idempotency in tests

​Loading and resetting test data

​A pre-launch testing checklist

The three payment modes

Which mode am I in?

Sandbox mode (mock gateway)

Forcing a payment failure

Gateway test mode

Testing webhooks

Testing dunning and retries

Idempotency in tests

Loading and resetting test data

A pre-launch testing checklist