SDKs.

Official SDKs are maintained by the OpenSettle team and ship the same day as the API itself. Every SDK exposes the same resource shape, the same error hierarchy, and the same retry/idempotency behavior — only the language idioms differ.

Install

npm install @opensettle/sdk

pip install opensettle

go get github.com/opensettle/opensettle-go

gem install opensettle

Versioning

SDKs follow strict semver. The major version tracks the API version pinned by default in the constructor — SDK v3.x sends OpenSettle-Version: 2026-04-01 unless you override it. Minor versions add features without breakage; patch versions are bug fixes only. Old SDK majors keep working — we run every dated API version for at least 36 months.

Test mode

Use a test-mode API key (sk_test_…) and the SDK will route to the sandbox automatically. There is no separate host. For unit tests, you can also set testMode: true explicitly to assert the right environment is in use.

const os = new OpenSettle({
  apiKey: process.env.OPENSETTLE_KEY,
  testMode: process.env.NODE_ENV !== "production",
  apiVersion: "2026-04-01",     // optional pin
  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.

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

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

Polling helpers

Webhooks are the right tool for production, but a polling helper is useful in scripts and CI. Each resource exposes .waitFor(state) with a sane default timeout and backoff.

const checkout = await os.checkouts.create({ /* … */ });
const payment = await os.checkouts.waitFor(checkout.id, "payment.confirmed", {
  timeoutMs: 120_000,
  intervalMs: 1_500,
});
console.log(payment.tx_hash);

Community SDKs

The community maintains SDKs for Elixir, Rust, PHP/Laravel, .NET, and Java. They are not covered by our SLA but track the API closely. Find the current list and maintainer contacts on GitHub at opensettle/community-sdks.