Skip to main content
OpenSettle
Start building
Developer›SDKs

SDKs.

Node, Python, Go, and Rust are all out — typed end-to-end, signed-webhook verifier included, idempotent writes by default. For anything else, the REST API is stable and works from any HTTP client.

Languages

bash
npm install @opensettle/sdk
bash
pip install opensettle
bash
go get github.com/OpenSettle/opensettle-sdk-go
bash
cargo add opensettle

Versioning

The HTTP API is on v1. SDKs follow strict semver: the major version tracks the API major version, minor versions add features without breakage, and patch versions are bug fixes only.

Test mode

Test-mode API keys are prefixed sk_test_… and operate against the same hostname as live keys — there is no separate host. The Node client surface looks like this:

client.ts
const os = new OpenSettle({
  apiKey: process.env.OPENSETTLE_KEY!,
  workspaceId: process.env.OPENSETTLE_WORKSPACE!,
  testMode: process.env.NODE_ENV !== "production",
  timeoutMs: 30_000,
  maxNetworkRetries: 3,         // exponential backoff on 5xx + 429
});

Error classes

Errors raised by the SDK extend a base OpenSettleError. Catch the specific subclass for typed handling.

errors.ts
import {
  InvalidRequestError,
  AuthenticationError,
  SettlementError,
  RateLimitError,
  APIError,
} from "@opensettle/sdk";

try {
  await os.checkouts.create({ /* … */ });
} catch (err) {
  if (err instanceof RateLimitError) {
    await sleep((err.retryAfter ?? 1) * 1000);
    return retry();
  }
  if (err instanceof SettlementError && err.code === "insufficient_confirmations") {
    return tryAgainInAFewBlocks();
  }
  throw err;
}

Polling helpers

Webhooks are the right tool for production, but a polling helper is useful in scripts and CI. The SDK ships a generic waitFor() that polls any resource's retrieve() on a fixed interval and resolves when your predicate is satisfied — or throws WaitTimeoutError once the deadline elapses.

poll.ts
import { waitFor, WaitTimeoutError } from "@opensettle/sdk";

const checkout = await os.checkouts.create({ /* … */ });

try {
  const done = await waitFor(
    (id) => os.checkouts.retrieve(id),
    checkout.id,
    (c) => c.status === "succeeded" || c.status === "failed",
    { timeoutMs: 120_000, intervalMs: 1_500 },
  );
  console.log(done.status);
} catch (err) {
  if (err instanceof WaitTimeoutError) {
    // err.last is the last-observed checkout
  }
  throw err;
}

Pagination

List endpoints return a cursor-paged envelope ({ data, nextCursor, hasMore }). The paginate() helper threads the cursor for you and yields every item across every page as an AsyncGenerator.

paginate.ts
import { paginate } from "@opensettle/sdk";

for await (const customer of paginate(
  os.customers.list.bind(os.customers),
)) {
  console.log(customer.id, customer.email);
}
API referenceWebhooks