Sandbox

Base URL: $BUSINESS_API

The object

advanced_paymentsarray of object · required

Simulated payment sessions moved by this call; empty when none were pending.

Show child attributes
referencestring · required

Reference of the simulated payment session.

invoice_idstring · optional

Invoice the session pays, when it pays one.

statusstring · required

one of confirmed, failed, expired

transaction_idstring · optional

Simulated transaction reference, set when confirmed.

generated_readingsinteger · required

Meter readings generated; 0 unless readings was true.

The object
{
  "advanced_payments": [
    {
      "reference": "REF-2026-000142",
      "invoice_id": "inv_2jnourvAGxXMMd5IyFbwc1LqUX1",
      "status": "confirmed",
      "transaction_id": "tra_2uKL9uwRlmQRRWCNVk2NTMiTDU2"
    }
  ],
  "generated_readings": 1342
}

Advance sandbox

Logs

POST /sandbox/advance

Settle pending simulated payments and optionally generate readings

Available only in sandbox tenants. Moves pending simulated payment sessions of the caller's tenant to an outcome, as a real connector would report it: confirmed (the default) records the payment against its invoice and emits the same events as a live confirmation; failed and expired close the session. Without payment_id every pending simulated session of the tenant is advanced. With readings set to true the call also generates one new cycle of meter readings for the tenant's meters, recorded as the caller, so the caller also needs the meter and reading scopes the meter service checks (business:meters:read, business:readings:read and business:readings:create). Requires the payments:write scope, and business:readings:create as well when readings is true. A live tenant or a missing scope returns 403, an unknown outcome or malformed body returns 400.

Body application/json

payment_idstring · optional

Reference of one pending simulated payment session to advance; when omitted, all pending sessions of the tenant are advanced.

outcomestring · optional · default confirmed

Outcome to apply to the selected sessions.

one of confirmed, failed, expired

readingsboolean · optional · default false

Also generate one new cycle of meter readings.

Returns

200 Sessions advanced and readings generated

Show attributes
advanced_paymentsarray of object · required

Simulated payment sessions moved by this call; empty when none were pending.

Show child attributes
referencestring · required

Reference of the simulated payment session.

invoice_idstring · optional

Invoice the session pays, when it pays one.

statusstring · required

one of confirmed, failed, expired

transaction_idstring · optional

Simulated transaction reference, set when confirmed.

generated_readingsinteger · required

Meter readings generated; 0 unless readings was true.

Errors 400 · 401 · 403 · 404

Permissions payments:write · Roles: admin, billing_clerk, finance, owner

curl -X POST "$BUSINESS_API/sandbox/advance" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "payment_id": "pay_2eUBfC8BJA6JLIoHrQwtN0GL1mW",
  "outcome": "confirmed",
  "readings": false
}'
Response 200
{
  "advanced_payments": [
    {
      "reference": "REF-2026-000142",
      "invoice_id": "inv_2jnourvAGxXMMd5IyFbwc1LqUX1",
      "status": "confirmed",
      "transaction_id": "tra_2uKL9uwRlmQRRWCNVk2NTMiTDU2"
    }
  ],
  "generated_readings": 1342
}