SDKs and libraries

@borga/node

The official server-side client. This documentation is written for version 0.6.1. 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), appInfo (appended to the User-Agent) and defaultHeaders (sent on every request; Authorization is refused there and in per-request headers).

An app acting for a merchant through an OAuth connection passes new Borga({ accessToken }) instead of apiKey. Those clients also get the dashboard resources webhookEndpoints, webhookDeliveries, merchant, accountingLink, auditLog and apiKeys, plus invoices.pdf, invoices.retrySync, invoices.retryPayment and subscriptions.mrr. These answer to OAuth access tokens, within the scopes the connection was granted, and to the dashboard's own sessions, but refuse secret keys.

Every code sample on this site is compiled in CI against @borga/node 0.6.1, so if a sample is here it typechecks against that version. Releases are staged from the same commit and approved by a maintainer, so npm can briefly lag the docs. If a sample does not compile for you, compare npm ls @borga/node with the version above and upgrade.

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. Install it with npm install @borga/react; 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 3.0 document at docs.borga.is/openapi.json describes every merchant-facing route with its request body, query parameters, typed responses and the shared error envelope. Dashboard and checkout-internal routes are not in it. Response schemas are generated from the @borga/node types, so a generated client and the Node SDK agree on every object. The document is exported from the API build and the reference pages are checked against it.