Environments and Sandbox Testing: live, sandbox, and demo

The Aplauso API supports three isolated data environments. Every business logic endpoint accepts an environment parameter to control which environment is used for reads and writes.

Environments

Passing the Environment Parameter

As a query parameter:

GET /v2/analytics?type=employee&employeeId=abc123&environment=sandbox

Or in the request body:

{
  "employeeId": "abc123",
  "amount": 10.00,
  "environment": "sandbox"
}

If omitted, the API defaults to live.

Data Isolation

Each environment stores data completely separately:

• A tip created in sandbox never appears in live tip queries.
• Wallet balances are maintained per environment (wallet.live, wallet.sandbox).
• Stripe account IDs are separate per environment (one Express account per user per environment).
• Analytics are computed separately per environment.

Testing in Sandbox

To run a full end-to-end test in sandbox:

1. Create a tip with environment: "sandbox".
2. Use the sandbox Stripe keys to create a Payment Intent (the API handles this automatically when environment is sandbox).
3. Use a Stripe test card number to simulate payment:

Any future expiry date, any 3-digit CVC, any billing ZIP.

4. The sandbox Stripe webhook delivers a payment_intent.succeeded event.
5. The tip status updates to 20 (Paid) and dividends are created.
6. Query /v2/tips?environment=sandbox and /v2/dividends?environment=sandbox to verify.

Environment in the Kiosk

The kiosk app (k.aplauso.io) displays a colored environment banner when running in a non-live environment:

The environment is controlled server-side per recipient (employee/outlet/department). If a recipient's record is set to sandbox, the kiosk automatically operates in sandbox mode when that recipient's URL is opened.

Local Development

When running the Firebase emulators locally, the API automatically uses test Stripe keys regardless of the environment parameter. This ensures no real charges occur during local development.

cd api
npm run serve
# Firebase emulators start on localhost:5001

Point your frontend apps at the local emulator base URL for testing:

http://localhost:5001/aplauso-f0501/us-central1/api/v2/