Environments and keys · Compense Docs

The gateway has a single contract (the same paths, bodies and errors) across all its deployments. What changes between “testing” and “operating” is the key you call with.

Base URL per environment #

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`

Every path starts with /v1/gateway/..., so the base URL never includes /v1. The sandbox URL keeps the /gw prefix of the sandbox console: the full path is https://sandbox.dev.compense.co/gw/v1/gateway/health/.
Production is the URL declared in the contract. There’s no public production deployment yet: the final URL is confirmed during onboarding. If it differs, pass it as a custom base URL (base_url, baseUrl, BaseUrl, WithBaseURL), which always takes precedence over the environment.
Dev is Compense’s development gateway, useful for end-to-end testing with real webhooks (with a production key issued for dev).

The key decides, not the URL #

Every key is issued with an environment:

Key	Who responds	Money	Webhooks	`sandbox.*` simulators
`sandbox`	The simulated, deterministic engine: same request, same response.	None	Simulated (`"simulated": true`)	Allowed
`prod`	Your entity’s real engine.	Real	Real signed HTTP deliveries	`403`

A sandbox key gets simulated responses at any URL you call, and a production key reaches the real engine. That’s why a configuration mistake (pointing at the sandbox URL with a production key) does not protect you: keep keys separate per environment in your secrets manager and in your CI.

flowchart TD
  R[Your request<br/>X-API-Key: cmp_...] --> G{Key<br/>environment}
  G -- sandbox --> S[Simulated engine<br/>deterministic, no money]
  G -- prod --> M[Tenant's real engine]
  S --> E[Same contract:<br/>paths, envelope and errors]
  M --> E

What the sandbox doesn't simulate

Looking up, matching and loading affiliates read and write the tenant’s real records with any key. Review the test data table before designing your automated tests.

Choosing the environment in code #

from compense_gateway import CompenseClient

sandbox = CompenseClient(api_key=SANDBOX_KEY, environment="sandbox")
dev = CompenseClient(api_key=DEV_KEY, environment="dev")
prod = CompenseClient(api_key=PROD_KEY)  # "production" is the default
otro = CompenseClient(api_key=PROD_KEY, base_url="https://gateway.horizonte.example")

import { CompenseClient } from "@compense/sdk";

const sandbox = new CompenseClient({ apiKey: SANDBOX_KEY, environment: "sandbox" });
const dev = new CompenseClient({ apiKey: DEV_KEY, environment: "dev" });
const prod = new CompenseClient({ apiKey: PROD_KEY }); // "production" by default
const otro = new CompenseClient({ apiKey: PROD_KEY, baseUrl: "https://gateway.horizonte.example" });

use Compense\Sdk\CompenseClient;

$sandbox = new CompenseClient(apiKey: $sandboxKey, environment: 'sandbox');
$dev = new CompenseClient(apiKey: $devKey, environment: 'dev');
$prod = new CompenseClient(apiKey: $prodKey); // 'production' by default
$otro = new CompenseClient(apiKey: $prodKey, baseUrl: 'https://gateway.horizonte.example');

var sandbox = new CompenseClient(sandboxKey, CompenseEnvironment.Sandbox);
var dev = new CompenseClient(devKey, CompenseEnvironment.Dev);
var prod = new CompenseClient(prodKey, CompenseEnvironment.Production);
var otro = new CompenseClient(new CompenseClientOptions
{
    ApiKey = prodKey,
    BaseUrl = "https://gateway.horizonte.example",
});

sandbox, _ := compense.NewClient(sandboxKey, compense.WithEnvironment(compense.Sandbox))
dev, _ := compense.NewClient(devKey, compense.WithEnvironment(compense.Dev))
prod, _ := compense.NewClient(prodKey) // Production by default
otro, _ := compense.NewClient(prodKey, compense.WithBaseURL("https://gateway.horizonte.example"))

curl https://sandbox.dev.compense.co/gw/v1/gateway/health/ -H "X-API-Key: $SANDBOX_KEY"
curl https://gateway.dev.compense.co/v1/gateway/health/ -H "X-API-Key: $DEV_KEY"
curl https://api.compense.co/v1/gateway/health/ -H "X-API-Key: $PROD_KEY"

From sandbox to production #

Integrate and automate your tests against the sandbox (credits, wallet, loans, simulated webhooks, clocks and simulators).
Test end to end in dev with real webhooks to a public HTTPS URL in your test environment.
Request the production key and the final URL during onboarding; create your production webhook endpoints (the secret is different) and deploy.
Monitor with client.system.health() and alert on 401/403, 429 and 5xx.