Environments

An environment is a logical container that scopes wallets, API keys, and webhook endpoints. Every other Payments resource — wallets, transactions, webhooks — belongs to exactly one environment.

There are two types: SANDBOX (for development and tests) and LIVE (for production traffic).

Create a sandbox environment

Sandbox is the default starting point. Create one from the dashboard at rails.amboss.tech/pay, or programmatically with either:

• Dashboard JWT (Authorization: Bearer <token>) — works for both sandbox and live.
• Service API key with ENVIRONMENTS: WRITE — works for sandbox only. Live environment creation is gated to the master-account JWT (see Going live).

mutation CreateEnvironment {
  payment {
    environment {
      create(input: {
        name: "Sandbox - dev"
        type: SANDBOX
      }) {
        id
        name
        type
        created_at
      }
    }
  }
}

curl -X POST https://rails.amboss.tech/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AMBOSS_DASHBOARD_TOKEN" \
  -d '{
    "query": "mutation { payment { environment { create(input: { name: \"Sandbox - dev\", type: SANDBOX }) { id name type } } } }"
  }'

Save the returned id — every wallet, API key, and webhook you create later is scoped to it.

Sandbox behaviour

Sandbox transitions are deterministic. You drive them via the metadata.amb_sandbox_behavior field on create_receive / create_send:

This lets your integration tests assert on every branch without touching a real Lightning node. Example:

{
  "metadata": "{\"amb_sandbox_behavior\":\"complete\",\"order_id\":\"42\"}"
}

The amb_ prefix is reserved for control-plane state. Use your own keys for application metadata; they're round-tripped untouched.

Going live

When you're ready for production traffic, create a LIVE environment. This is gated by KYB — the dashboard "Go Live" button at rails.amboss.tech/pay redirects to Stripe to collect billing details. Only one live environment is allowed per team.

payment.environment.create with type: LIVE always requires the master-account dashboard JWT — API keys with ENVIRONMENTS: WRITE are explicitly rejected for live creation. The mutation also requires live.success_url and live.cancel_url (used by the Stripe checkout flow).

After the live environment exists:

1. Wallets you create won't be ready immediately. is_ready flips to true once liquidity has been provisioned for that wallet.
2. Generate new API keys scoped to the live environment — sandbox keys (amb_test_…) won't authenticate against live resources.
3. Re-register webhook endpoints under the live environment (event filters are per-endpoint).

See Wallets for provisioning details and API Keys for scoping.

Next steps