SDKs and libraries

@borga/node

The official server-side client. Current version: 0.2.0. Requires Node.js 18 or newer and works in any TypeScript or JavaScript project.

npm install @borga/node

import { Borga } from "@borga/node";

const borga = new Borga({ apiKey: process.env.BORGA_SECRET_KEY! });

What it gives you over raw HTTP:

• Types for every request and response, generated from the same source the API validates against.
• Idempotency keys on every POST, so a retried call never creates a duplicate. Pass your own with { idempotencyKey } to make retries across processes safe too.
• Retries with exponential backoff for 429, 5xx and network errors (three by default; configurable with maxRetries), honouring Retry-After.
• Errors as BorgaError instances carrying type, code, status, param, requestId and the raw body.
• Webhook verification with verifyWebhookSignature.

Resources map one-to-one to the API: paymentSessions, payments, refunds, paymentMethods, customers, customerPortals, products, prices, subscriptions, subscriptionItems, invoices, invoiceItems, creditNotes, meters and usageEvents. Each exposes create, retrieve, list and update where the API does, plus the resource's actions such as subscriptions.cancel or paymentMethods.setDefault.

Options: baseUrl (for a local API), timeoutMs (default 60 seconds), fetch (custom implementation) and appInfo (appended to the User-Agent).

Every code sample on this site is compiled against the published package in CI, so if a sample is here, it typechecks against the current SDK.

borga.js

The browser script for embedded checkout, served from https://js.borga.is/v1/borga.js. It sets window.Borga:

const borga = new Borga("pk_test_…");
const handle = borga.checkout.open({ sessionId, clientSecret, onComplete, onCancel, onError });
handle.close();

It has no dependencies and no build step. Load it only in the browser.

@borga/react

A useBorgaCheckout hook that loads borga.js once and returns open and close, for React 18 and 19. It is built in the Borga monorepo next to the Node SDK and is not on npm yet; see Embedded checkout.

Other languages

There are no official Python, Ruby, PHP, Go or .NET clients. The API is plain REST over HTTPS with JSON bodies, bearer-token authentication and HMAC-SHA256 webhooks, so any HTTP client works. Two things to replicate from the Node SDK:

1. Send an Idempotency-Key header on every POST; see Idempotency.
2. Retry 429 and 5xx with backoff, honouring Retry-After.

The API reference shows curl for every endpoint. If you are generating a client, the OpenAPI document that describes request bodies is published in the Borga repository at apps/docs/openapi/borga-v1.json.