TEST ONLY · No real payments or eSIMs · Never enter a real card

Sīrū sandbox API documentation

# Sīrū public developer sandbox

## When to use this
Test a synthetic eSIM order with Stripe-hosted test-card checkout. No signup,
real customer, real money or real eSIM is involved. Production OAuth grants and
tokens are not accepted here. This sandbox tests customer-confirmed checkout;
automatic saved-card payments and production OAuth consent are not simulated.

## Quick start
1. GET /api/v1/sandbox/products lists the synthetic test plan (EUR 1.00).
2. POST /api/v1/sandbox/sessions with Content-Type: application/json and body {}
   returns a temporary Bearer token. Keep it private. No email or card is needed.
3. POST /api/v1/sandbox/checkouts with Authorization: Bearer YOUR_SANDBOX_TOKEN,
   Idempotency-Key: example-order-0001, Content-Type: application/json, and
   body {"productId":"sandbox-jp-1gb"} returns a Stripe test checkout URL.
4. The customer opens the checkout URL and enters a Stripe test card.
5. GET /api/v1/sandbox/orders with the same Bearer token returns your test orders.
   A signed Stripe webhook confirms paid status. A browser success redirect alone
   does not prove payment. Paid orders are synthetic and never provision an eSIM.

## Test cards
Use 4242 4242 4242 4242 for success, 4000 0000 0000 0002 for a generic decline,
and 4000 0000 0000 3220 for bank authentication. Use a future expiry and any
three-digit CVC. Never use a real card. Use a synthetic email such as
developer@example.com if Stripe asks. See https://docs.stripe.com/testing.

## Limits and resets
Sessions last two hours and expire on service restart. Synthetic orders are held
in bounded memory and also reset on restart; do not use this as durable storage.
Stripe test checkout links expire after one hour.
One instance permits 10 new sessions/minute, 300 API requests/minute, and
100 new test checkouts/hour. Each session permits 30 authenticated requests/minute
and 10 orders. Retry-After accompanies throttling. Reuse the same idempotency key
after a timeout; do not create another order to resolve an unknown payment result.

## Isolation
This service accepts only its own temporary sandbox credentials. It has its own
Stripe account, signing secret and deployment. It has no production database,
supplier, provisioning, saved cards, refund or email delivery integrations.
Do not submit personal information. Tokens, URLs and cards from production are
not supported. The complete machine-readable contract is /openapi.json.

## Official CLI
The production catalog CLI is available as @siru-world/cli on npm:
npx @siru-world/cli@0.1.0 products --country JP --limit 10
It is read-only. Use the sandbox API above for test checkout.

## Guided self-serve onboarding
Open this sandbox's homepage to create temporary credentials, create one Stripe
test checkout and refresh your synthetic orders. No signup or real card is needed.
The browser keeps credentials only in memory; reload forgets them. Retries within
the same tab keep the same idempotency key. The HTTP quick start above works
without JavaScript. Never use production credentials in this sandbox.

## Resources
- [OpenAPI specification](/openapi.json)
- [Agent instructions](/llms.txt)
- [Production documentation](https://www.siru.world/docs)
- [Official CLI](https://www.npmjs.com/package/@siru-world/cli)