Getting started
Environments
Sandbox vs production, covering base URLs, test data, and switching guidance.
Lumeo has two fully isolated environments. All endpoints, event types, and webhook behaviors are identical between them, only the base URL and key prefix differ.
| Environment | Base URL | Key prefix |
|---|---|---|
| Sandbox | https://api-sandbox.lumeo.co.in/api/v1 | sk_sandbox_ |
| Production | https://api.lumeo.co.in/api/v1 | sk_live_ |
Isolation guarantees
- Separate databases, separate ledger accounts, separate webhook delivery queues.
- Nothing created in sandbox is visible in production or counted toward billing or compliance records.
- Sandbox settlement uses Stellar testnet contracts and OnMeta/Crossmint test credentials. No real money moves.
Switching environments
API keys are environment-scoped: a sandbox key is rejected by the production base URL and vice versa. There is no environment flag in the request body. To switch: swap the base URL and the key.
// Sandbox
const lumeo = new LumeoClient({
apiKey: process.env.LUMEO_SANDBOX_KEY!,
baseUrl: "https://api-sandbox.lumeo.co.in/api/v1",
});
// Production
const lumeo = new LumeoClient({
apiKey: process.env.LUMEO_LIVE_KEY!,
// baseUrl defaults to production
});Test recipients in sandbox
Use these pre-seeded addresses in sandbox to simulate specific outcomes:
| Recipient address | Simulates |
|---|---|
GTEST_SUCCESS_ADDR_XXXXXXXXXXXXXXXXXX | Immediate settlement — CONFIRMED within 5 s |
GTEST_DELAY_ADDR_XXXXXXXXXXXXXXXXXX | 30-second settlement delay — useful for testing webhook retry handling |
GTEST_FAIL_ADDR_XXXXXXXXXXXXXXXXXX | Payment fails with FAILED status and failedReason: recipient_invalid |
GTEST_COMPLIANCE_ADDR_XXXXXXXXXXXXXXX | Triggers MANUAL_REVIEW — simulates a compliance hold |
Webhook events fire in sandbox exactly as they do in production, including retries on non-2xx handler responses. See Handle webhook retries for the delivery SLA and retry schedule.
Simulating webhook events
In sandbox, you can manually trigger a webhook delivery without waiting for a real settlement cycle:
curl -X POST https://api-sandbox.lumeo.co.in/api/v1/sandbox/trigger-event \
-H "Authorization: Bearer sk_sandbox_..." \
-H "Content-Type: application/json" \
-d '{
"event": "payout.settled",
"paymentId": "clx1a2b3c4d5e6f7g8h9"
}'This is only available in sandbox. Attempting it against the production base URL returns 404.