# Sandbox

A test workspace kept apart from the live account, with sample data, test-only keys, payments that never leave for a provider and fresh readings on demand with sandbox advance.


## What a sandbox is

A sandbox is a separate utility account tied to your live one. It inherits the live account's country, locale, currency and time zone, but copies none of its records and none of its connector configuration. Its name is the account's name followed by "Sandbox".

If the account's plan has test environments, the sandbox is born at sign-up, and the person signing up becomes its owner. In the dashboard, enter it from the account menu with **Switch to sandbox** and leave with **Exit sandbox**; while you are inside, a band at the top reminds you that the data is test data.

## Sample data

The sandbox created at sign-up comes filled in, so you can call the API from the first minute:

- service areas, tariffs and the network (assets and topology);
- six customers, each with an account, a property and a connection;
- one meter per connection, with serial numbers `SBX-000001`, `SBX-000002` and onwards;
- reading routes, one reading cycle with its consumption worked out, and one billing run;
- open invoices, at most half of them already paid, so you have both history and invoices ready to pay.

## Keys in the sandbox

A sandbox issues test keys only: `sk_test_` (secret) and `sk_rtest_` (restricted). Asking for a live key in a sandbox returns `400`, and the dashboard shows "Only test keys can be created in the sandbox.". The other way round, asking for a test key in a live account returns `400` with "Test keys are created in the sandbox.".

At request time, a test key used on a live account, or a live key used on a sandbox, gets `401`. Money-moving scopes such as `payments:write` reach a test key only when the installation's operator has turned on test payments.

## Test payments

With test payments turned on, a payment started in the sandbox never reaches a real provider. The session stays `pending` and gets a reference that starts with `sbx_`. It becomes confirmed when the customer confirms it from the customer area, with `POST $CONSUMER_API/payment-sessions/{id}/sandbox/confirm`, or when the automatic confirmation delay runs out, if the operator set one. Confirming records the payment, the receipt and the allocation to the invoice. Without test payments, that call returns `404`.

## Advance the sandbox

`POST $BUSINESS_API/sandbox/advance` takes an optional body with three fields:

| Field | What it does |
| :--- | :--- |
| `outcome` | Outcome for the simulated payment connector's pending sessions: `confirmed` (default), `failed` or `expired`. Any other value returns `400`. |
| `payment_id` | Limits the change to the session with that reference; without it, every pending session moves. |
| `readings` | With `true`, records a new reading on every sandbox meter, 12.5 m³ above the latest one. |

The response lists in `advanced_payments` the sessions whose state changed (empty when none were pending) and states in `generated_readings` how many readings were accepted.

```bash
curl -sS -X POST "$BUSINESS_API/sandbox/advance" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"readings":true}'
```

```json
{
  "advanced_payments": [],
  "generated_readings": 6
}
```

On a live account, the same request returns `403` with the title `Sandbox Only`.

## From the CLI

`gotactl sandbox advance` sends the same request and refuses to run outside a sandbox context. Flags:

| Flag | Description |
| :--- | :--- |
| `--outcome` | Outcome to apply: `confirmed` (default), `failed` or `expired`. |
| `--payment` | Reference of one pending session to advance; without it, all of them move. |
| `--readings` | Also records a new reading on every meter. |

`gotactl events trigger` causes real events in the active sandbox (`gotactl events trigger --list` shows the supported types), and `gotactl webhooks listen` accepts a live context only with `--live` and `--confirm-live`.

## Next steps

- [Testing guide](/docs/testing)
- [Test webhooks with the CLI and the dashboard](/docs/webhooks/testing)
- [What changes when you go live](/docs/go-live)

