Skip to main content
The SDK supports two built-in environments and an optional custom URL override. 
import { createOakClient } from '@oaknetwork/payments-sdk';

const client = createOakClient({
  environment: 'sandbox', // or 'production'
  clientId: process.env.CLIENT_ID!,
  clientSecret: process.env.CLIENT_SECRET!,
});

​
Environment URLs

EnvironmentTypeAPI Base URLTest operations
sandbox"sandbox"https://sandbox-payments.oaknetwork.orgAllowed
production"production"https://payments.oaknetwork.orgBlocked

​
Custom URL

Override the built-in URL by passing customUrl. This is useful for local development or self-hosted API instances: 
const client = createOakClient({
  environment: 'sandbox',
  clientId: process.env.CLIENT_ID!,
  clientSecret: process.env.CLIENT_SECRET!,
  customUrl: 'http://localhost:3000',
});
When customUrl is set, it takes priority over the environment’s default URL. The environment field is still required — it controls sandbox-only behavior regardless of the URL.

​
Environment utilities

The SDK exports helper functions for environment checks: 
import { getEnvironmentConfig, isTestEnvironment } from '@oaknetwork/payments-sdk';

const config = getEnvironmentConfig('sandbox');
console.log(config.apiUrl);              // "https://sandbox-payments.oaknetwork.org"
console.log(config.allowsTestOperations); // true

console.log(isTestEnvironment('sandbox'));    // true
console.log(isTestEnvironment('production')); // false

​
Sandbox-only restrictions

Some SDK operations are restricted to the sandbox environment using the @SandboxOnly decorator. If you call a sandbox-only method with environment: 'production', the SDK returns an EnvironmentViolationError in the Result without making a network request. 
import { EnvironmentViolationError } from '@oaknetwork/payments-sdk';

const result = await someService.sandboxOnlyMethod();

if (!result.ok && result.error instanceof EnvironmentViolationError) {
  console.error(result.error.message);
  // → 'Method "sandboxOnlyMethod" is only available in sandbox environment.
  //    Current environment: production.
  //    This method cannot be called in production to prevent accidental data corruption.'
}

​
How it works

The @SandboxOnly decorator (and its function equivalent sandboxOnlyFn) checks the environment field on the client config before executing the method:
  • If environment === 'sandbox' — the method runs normally
  • If environment === 'production' — an EnvironmentViolationError is returned (for async methods) or thrown (for sync methods)
This prevents test operations from accidentally running against production data.
For the full error type reference, see Error Handling.