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-000002and 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.
curl -sS -X POST "$BUSINESS_API/sandbox/advance" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"readings":true}'
{
"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.