Reference

SDKs

@orven/node is the official server-side TypeScript SDK. It is publish-ready but not published to npm yet. It is deliberately thin: typed wrappers over the REST API plus timing-safe webhook verification, with zero runtime dependencies — just the built-in fetch and node:crypto.

Installation

Not on npm yet

The package metadata and tarball are prepared for publication, but @orven/node is not available from the public npm registry yet. Until the first publish, design partners should use the REST API directly or install from the workspace/repository in a controlled test environment.

# After the first npm publish:
npm install @orven/node

Requires Node 18 or newer and is ESM-only. Everything ships with TypeScript declarations — no @types package needed. The SDK is server-side only: it holds your secret key and never belongs in browser code.

Creating a client

TypeScript

import { Orven } from "@orven/node";

const orven = new Orven(process.env.ORVEN_SECRET_KEY!, {
  baseUrl: "https://pay.example.com", // or set ORVEN_BASE_URL
});

orven.livemode; // false for orven_sk_test_ keys, true for orven_sk_live_

apiKeystringrequired

Your secret key (orven_sk_test_… or orven_sk_live_…). The constructor throws on anything else.

options.baseUrlstring

Where your Subsie instance runs. Falls back to the ORVEN_BASE_URL environment variable, then http://localhost:3000 for development.

options.timeoutMsnumber

Per-request timeout in milliseconds. Default 30000.

Resources

Resource	Methods
`orven.checkoutSessions`	`create(params, options?)` · `retrieve(id)` · `list(params?)`
`orven.payments`	`retrieve(id)` · `list(params?)`
`orven.refunds`	`create(params, options?)` · `retrieve(id)` · `list(params?)`
`orven.subscriptions`	`retrieve(id)` · `list(params?)`
`orven.paymentAttempts`	`list(params?)`
`orven.wallets`	`create(params, options?)` · `verify(id, { signature })` · `retrieve(id)` · `list(params?)` · `revoke(id)`
`orven.webhookEndpoints`	`create(params, options?)` · `list(params?)` · `del(id)` · `sendTest(id, params?)`
`orven.webhookEvents`	`list(params?)` · `resend(id)`
`Orven.webhooks`	`constructEvent(params)` · `verifySignature(params)`

Method parameters mirror the REST API exactly — the request and response shapes in the API reference are the SDK types. List methods return OrvenList<T>: { object: "list", data: T[], has_more: boolean }.

Examples

// Create a session, safe to retry
const session = await orven.checkoutSessions.create(
  { mode: "payment", title: "Pro plan", amount: "25" },
  { idempotencyKey: "order_42" },
);

// Page through a customer's sessions
const sessions = await orven.checkoutSessions.list({
  customer_reference: "user_8231",
  limit: 50,
});

// Inspect a payment's fee split
const payment = await orven.payments.retrieve("pay_...");
payment.amount;          // "25"     gross paid by the buyer
payment.fee_amount;      // "0.5"    Subsie fee
payment.merchant_amount; // "24.5"   settled to your wallet

Idempotency

Every create method takes an optional second argument with an idempotencyKey, sent as the Idempotency-Key header. The SDK never retries automatically — you stay in control — but with a key, your own retries are safe: the same key and body within 24 hours replays the original result.

Error handling

Class	Thrown when	Useful fields
`OrvenApiError`	The API returned a non-2xx response.	`status`, `code`, `details`, `retryAfterSeconds`
`OrvenConnectionError`	The API was unreachable, timed out, or returned non-JSON.	`cause`
`OrvenWebhookVerificationError`	A webhook signature failed verification.	—

TypeScript

import { OrvenApiError } from "@orven/node";

try {
  await orven.checkoutSessions.create({ mode: "payment", title: "X", amount: "5" });
} catch (error) {
  if (error instanceof OrvenApiError) {
    if (error.code === "rate_limit_error") {
      // back off for error.retryAfterSeconds
    }
    if (error.code === "invalid_request_error") {
      console.error(error.details); // [{ field, message }]
    }
  }
  throw error;
}

All three extend OrvenError, so one instanceof check catches anything the SDK throws.

Webhook verification

Orven.webhooks.constructEvent verifies the Orven-Signature header (timing-safe HMAC comparison plus timestamp tolerance, 300 seconds by default) and returns the parsed, typed event — or throws OrvenWebhookVerificationError. Pass the raw request body, never re-serialized JSON. A full handler example is in the webhooks guide.

Other languages

The API is plain REST with Bearer auth, so any HTTP client works — every endpoint in the API reference includes a curl-ready shape, and webhook verification is a standard HMAC-SHA256 you can implement in a few lines in any language (the exact scheme is documented in the webhooks guide). More official SDKs are planned.

By design, the SDK does not

Touch the chain (no RPC, no keys, no transactions — buyers pay on the hosted page), run in browsers, or retry automatically. It is a typed HTTP client you can read in one sitting.