Lumeo Developer Docs

Simulate payment scenarios safely before going live, with test recipients, forced failures, and webhook triggers.

Sandbox is fully isolated from production. No real money moves, and sandbox API keys (sk_sandbox_...) are rejected by the production base URL. Every endpoint and webhook event available in production is available in sandbox.

Sandbox base URL

https://api-sandbox.lumeo.co.in/api/v1

Test recipient addresses

Use these pre-seeded destination addresses to simulate specific settlement outcomes:

Address	Simulates
`GTEST_SUCCESS_ADDR_XXXXXXXXXXXXXXXXXX`	Immediate settlement — payment reaches `CONFIRMED` within 5 seconds
`GTEST_DELAY_ADDR_XXXXXXXXXXXXXXXXXX`	30-second settlement delay — useful for testing timeout handling
`GTEST_FAIL_ADDR_XXXXXXXXXXXXXXXXXX`	Payment fails with `failedReason: recipient_invalid`
`GTEST_COMPLIANCE_ADDR_XXXXXXXXXXXXXXX`	Triggers `MANUAL_REVIEW` status — simulates a compliance hold
`GTEST_TIMEOUT_ADDR_XXXXXXXXXXXXXXXX`	Settlement times out — triggers `failedReason: settlement_timeout`

Use these in the destinationAddress field of POST /payments/initiate.

Simulate a full flow

# 1. Initiate
curl -X POST https://api-sandbox.lumeo.co.in/api/v1/payments/initiate \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 250.00,
    "currency": "USD",
    "destinationAddress": "GTEST_SUCCESS_ADDR_XXXXXXXXXXXXXXXXXX",
    "purposeCode": "P0801",
    "invoiceRef": "test-invoice-001"
  }'

# 2. Confirm (use the id from step 1)
curl -X POST https://api-sandbox.lumeo.co.in/api/v1/payments/confirm \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Content-Type: application/json" \
  -d '{
    "id": "<payment-id>",
    "destinationAddress": "GTEST_SUCCESS_ADDR_XXXXXXXXXXXXXXXXXX",
    "amount": "250.00",
    "currency": "USD",
    "vaultId": "<your-vault-id>"
  }'

# Payment settles within ~5 seconds. payout.settled and fira.generated webhooks fire.

Manually trigger webhook events

You can fire any webhook event manually in sandbox without waiting for a real settlement cycle. This is useful for testing your handler before you've built the full payment flow:

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 '{
    "webhookEndpointId": "wh_01j4abc",
    "event": "payout.settled",
    "paymentId": "clx1a2b3c4d5e6f7g8h9"
  }'

Supported values for event: any entry from the webhook event catalogue.

Test FIRA generation

After a GTEST_SUCCESS_ADDR payment settles, a FIRA is auto-generated exactly as it would be in production. Fetch it to verify your integration handles the fira.generated event and stores the document:

# Get the firaId from the webhook payload, then:
curl https://api-sandbox.lumeo.co.in/api/v1/compliance/fira/<firaId> \
  -H "Authorization: Bearer sk_sandbox_..."

Test reconciliation edge cases

To test the PENDING_RECONCILIATION flow, initiate a payment without an invoiceRef:

curl -X POST https://api-sandbox.lumeo.co.in/api/v1/payments/initiate \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "currency": "USD",
    "destinationAddress": "GTEST_SUCCESS_ADDR_XXXXXXXXXXXXXXXXXX"
  }'

After settling, the payment enters PENDING_RECONCILIATION. Then test the manual resolution:

curl -X POST https://api-sandbox.lumeo.co.in/api/v1/ledger/reconciliation/<paymentId>/resolve \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Content-Type: application/json" \
  -d '{ "invoiceRef": "test-invoice-002" }'

Common pitfalls

Using a production API key against the sandbox base URL, or vice versa. Sandbox keys (sk_sandbox_...) are rejected by the production API, and production keys are rejected by api-sandbox.lumeo.co.in. The error is a plain 401, not a message telling you the key/environment don't match.

Forgetting sandbox data doesn't carry over to production. Test payments, webhook endpoints, and vaults created in sandbox are entirely separate records from production. You need to register your webhook endpoint again once you switch to a live key.

Checklist before going to production

Signature verification is in place and tested with a forced non-matching signature.
Your handler responds within 10 seconds and queues heavy work asynchronously.
You handle payout.failed and alert appropriately, not just payout.settled.
You handle payout.manual_review. Do not assume every payment settles automatically.
Idempotency keys are generated fresh per payment, and your handler deduplicates on event id.
invoiceRef is supplied on every initiate call using your internal invoice ID.
purposeCode is set correctly for your service category.

Test in sandbox