Sandbox · Compense Docs

This page is generated from the contract (data/gateway-v1.json): each operation shows its verb, path, parameters, body, responses, whether it carries an Idempotency-Key, and the equivalent method in all five SDKs. For the end-to-end flow with complete examples, see the implementation guide.

Operations in tag `sandbox` #

Contract description: Deterministic simulation surface for sandbox API keys (E6/E7): test clocks, time advance and wallet/credit simulations. Production keys are refused with 403.

Method	Path	Operation	Scope	Idem.
POST	`/v1/gateway/sandbox/credits/{app_id}/advance/`	Advance a credit lifecycle (sandbox only)	—	—
POST	`/v1/gateway/sandbox/test-clocks/`	Create a test clock (sandbox only)	—	—
GET	`/v1/gateway/sandbox/test-clocks/{clock_id}/`	Read a test clock (sandbox only)	—	—
POST	`/v1/gateway/sandbox/test-clocks/{clock_id}/advance/`	Advance a test clock (sandbox only)	—	—
POST	`/v1/gateway/sandbox/wallet/simulate/`	Simulate a wallet movement (sandbox only)	—	—

Advance a credit lifecycle (sandbox only) #

POST/v1/gateway/sandbox/credits/{app_id}/advance/

operationId advanceCreditDisbursement
Authentication X-API-Key · sandbox keys only
Idempotency-Key not applicable

Parameters

Name	In	Type	Description
`app_id` required	path	string	Credit application id. E.g.: `CRED-2026-000123`

Request body

Content type: application/json · required

Free-form object.

Responses

Code	Description	Body
200	Advanced lifecycle state.	object application/json

Possible errors (400, 401, 403, 404, 409, 422, 429, 500) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

client.sandbox.simulate.credit_disbursement()

client.sandbox.simulate.creditDisbursement()

$client->sandbox->simulate->creditDisbursement()

await client.Sandbox.Simulate.CreditDisbursementAsync()

client.Sandbox.Simulate.CreditDisbursement(ctx, …)

curl -X POST "https://sandbox.dev.compense.co/gw/v1/gateway/sandbox/credits/CRED-2026-000123/advance/" \
  -H "X-API-Key: $COMPENSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

Create a test clock (sandbox only) #

POST/v1/gateway/sandbox/test-clocks/

operationId createTestClock
Authentication X-API-Key · sandbox keys only
Idempotency-Key not applicable

Stateless: the clock state travels in the returned id (tcl-…, tamper-evident).

Request body

Content type: application/json

Free-form object.

Responses

Code	Description	Body
200	Test clock created; state encoded in `clock_id`.	object application/json

Possible errors (400, 401, 403, 404, 409, 422, 429, 500) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

client.sandbox.test_clocks.create()

client.sandbox.testClocks.create()

$client->sandbox->testClocks->create()

await client.Sandbox.TestClocks.CreateAsync()

client.Sandbox.TestClocks.Create(ctx, …)

curl -X POST "https://sandbox.dev.compense.co/gw/v1/gateway/sandbox/test-clocks/" \
  -H "X-API-Key: $COMPENSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

Read a test clock (sandbox only) #

GET/v1/gateway/sandbox/test-clocks/{clock_id}/

operationId getTestClock
Authentication X-API-Key · sandbox keys only
Idempotency-Key not applicable

Parameters

Name	In	Type	Description
`clock_id` required	path	string	Test clock id (state-carrying). E.g.: `tcl-eyJmcm96ZW4i-a1b2c3d4e5f6a7b8`

Responses

Code	Description	Body
200	Current clock state.	object application/json

Possible errors (400, 401, 403, 404, 409, 422, 429, 500) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

client.sandbox.test_clocks.get()

client.sandbox.testClocks.get()

$client->sandbox->testClocks->get()

await client.Sandbox.TestClocks.GetAsync()

client.Sandbox.TestClocks.Get(ctx, …)

curl "https://sandbox.dev.compense.co/gw/v1/gateway/sandbox/test-clocks/tcl-eyJmcm96ZW4i-a1b2c3d4e5f6a7b8/" \
  -H "X-API-Key: $COMPENSE_API_KEY"

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

Advance a test clock (sandbox only) #

POST/v1/gateway/sandbox/test-clocks/{clock_id}/advance/

operationId advanceTestClock
Authentication X-API-Key · sandbox keys only
Idempotency-Key not applicable

Forward-only and capped; returns the NEW clock id.

Parameters

Name	In	Type	Description
`clock_id` required	path	string	Test clock id (state-carrying). E.g.: `tcl-eyJmcm96ZW4i-a1b2c3d4e5f6a7b8`

Request body

Content type: application/json · required

Free-form object.

Responses

Code	Description	Body
200	Clock advanced; use the returned id from now on.	object application/json

Possible errors (400, 401, 403, 404, 409, 422, 429, 500) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

client.sandbox.test_clocks.advance()

client.sandbox.testClocks.advance()

$client->sandbox->testClocks->advance()

await client.Sandbox.TestClocks.AdvanceAsync()

client.Sandbox.TestClocks.Advance(ctx, …)

curl -X POST "https://sandbox.dev.compense.co/gw/v1/gateway/sandbox/test-clocks/tcl-eyJmcm96ZW4i-a1b2c3d4e5f6a7b8/advance/" \
  -H "X-API-Key: $COMPENSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

Simulate a wallet movement (sandbox only) #

POST/v1/gateway/sandbox/wallet/simulate/

operationId simulateWalletTransfer
Authentication X-API-Key · sandbox keys only
Idempotency-Key not applicable

Deterministic transform — no ledger behind it, no money moves.

Request body

Content type: application/json · required

Free-form object.

Responses

Code	Description	Body
200	Simulated result.	object application/json

Possible errors (400, 401, 403, 404, 409, 422, 429, 500) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

client.sandbox.simulate.wallet_transfer()

client.sandbox.simulate.walletTransfer()

$client->sandbox->simulate->walletTransfer()

await client.Sandbox.Simulate.WalletTransferAsync()

client.Sandbox.Simulate.WalletTransfer(ctx, …)

curl -X POST "https://sandbox.dev.compense.co/gw/v1/gateway/sandbox/wallet/simulate/" \
  -H "X-API-Key: $COMPENSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

Operations in tag sandbox #

Advance a credit lifecycle (sandbox only) #

Parameters

Request body

Responses

Example

Create a test clock (sandbox only) #

Request body

Responses

Example

Read a test clock (sandbox only) #

Parameters

Responses

Example

Advance a test clock (sandbox only) #

Parameters

Request body

Responses

Example

Simulate a wallet movement (sandbox only) #

Request body

Responses

Example

Operations in tag `sandbox` #