Sandbox
Sandbox
The gateway’s test environment: deterministic responses, no real money or data, decided by the key and not by the URL. What each module simulates, how it differs from production, test clocks, simulators and the CLI.
On this page
The sandbox is the gateway answering with a simulated engine: the same endpoints, the same request and response bodies, the same error codes, but without touching the real engine, without moving money and without real affiliate data. It’s where you build and test your complete integration before you request your production key.
Three properties you need to know #
1. The key decides, not the URL #
Every API key is issued for one environment: sandbox or prod. With a sandbox key, the gateway
answers with the simulated engine on any URL you call; with a production key, the request
reaches the real engine. There’s no way to “point at the wrong place”: the key sets the behavior.
| Environment | Base URL | Python / JS / PHP | .NET | Go |
|---|---|---|---|---|
| Production | https://api.compense.co | "production" (default) | CompenseEnvironment.Production | compense.Production |
| Sandbox | https://sandbox.dev.compense.co/gw | "sandbox" | CompenseEnvironment.Sandbox | compense.Sandbox |
| Dev | https://gateway.dev.compense.co | "dev" | CompenseEnvironment.Dev | compense.Dev |
In practice: use the sandbox URL with your sandbox key while you integrate, and when you go live change both things (key and URL) through configuration, without touching code. More in Environments.
2. It’s deterministic #
The same request produces the same response (except for the generated_at field). There’s no
randomness: the result depends on the test document you send, on a few magic amounts and on
the values you choose. That lets you write stable automated tests that assert, for example, that
CC 1000000002 is always rejected with NOT_ELIGIBLE. Every sandbox body includes
"environment": "sandbox".
3. It doesn’t store state #
The sandbox has no database: each object’s state travels in its id. A credit application submitted
with CC 1000000001 gets an id sbx-E-… (the E is the “eligible” profile), and any later lookup,
decision or disbursement with that id responds consistently. Consequences:
- Repeating a write with the same data returns the same id (natural idempotency).
- A write returns the new state, but doesn’t change what later reads return (for example,
answering a PQRS doesn’t leave it
resolvedon the nextGET; recording a loan payment doesn’t reduce the debt). - Webhooks aren’t sent: the sandbox doesn’t
POSTto your endpoints (see Testing your webhooks).
What each module simulates #
| Module | What you can test |
|---|---|
| Affiliates | Five documents with a fixed profile (eligible, ineligible, manual review, with debts, nonexistent). |
| Credits | Submit, decide, disburse and look up; rejection by profile or by an amount above 50,000,000. |
| Subsidies and monetary allowance | The same cycle as credits; monetary allowance generation by profile. |
| Wallet | Balance by profile, P2P, Bre-B, bill payments and top-ups with their documented errors; pockets, cards and FX. |
| Loan portfolio | One loan up to date, one past due and one written off; collection validation. |
| Health | Catalog, slots, appointments, health invoices and payer payments. |
| Administrative | Employees, payroll changes, payroll periods, journal entries, third parties and treasury. |
| PQRS | Submit, answer, change status and a fixed inbox of 5 PQRS. |
| Webhooks | Endpoints, secrets and three fixed deliveries; no real HTTP sending. |
| Sandbox only | Test clocks and lifecycle simulators. |
All test documents, amounts and ids are in Test data.
Differences from production #
| Aspect | Sandbox | Production |
|---|---|---|
| Engine | Simulated and deterministic | Real |
| Money | Doesn’t move | Moves |
| Affiliates | Test catalog (1000000001…1000000004, 9999999999) | Your affiliates |
| Unknown document | Treated as eligible (so any test flows through) | 404 if it doesn’t exist |
| State | Travels in the id; writes don’t change later reads | Persistent |
| Webhooks | Not sent; the catalog is a sample | Real signed deliveries |
| Idempotency | Natural (same request, same id) plus the gateway’s | The gateway’s |
sandbox/* routes (clocks, simulators) | Available | 403 with a production key |
| Authentication, scopes, rate limits | Same | Same |
What the sandbox can't test
Real provider latency and timeouts, receiving webhooks (for that, use a production key in the dev
environment, see Testing your webhooks)
and your affiliates’ data. Plan a round of testing in dev before production.
Sandbox-only tools #
Besides simulating the modules, the sandbox includes operations that only exist there (the API’s
sandbox tag, with no scope of its own: they’re authorized by the key being a sandbox key):
- Test clocks: a virtual time source you can move forward to test anything that depends on the passage of time.
- Lifecycle simulators: they advance a wallet transfer or a credit disbursement one state at a time, up to its terminal state, failures included.
compenseCLI: console commands for webhooks and the sandbox, bundled with the Python and JavaScript SDKs.