Reference
SDK reference: Node.js
Harbour Connect for Node.js and TypeScript: the client, the services, webhooks and errors.
Harbour Connect for Node.js has no dependencies: it uses the built-in fetch and node:crypto.
It ships as an ES module with TypeScript declarations, and require() works on Node.js 20.19 and newer. The
contract is the PHP SDK's: integer kobo, an idempotency key on every create, at most two safe retries, typed errors,
and the same webhook check, tested against the same shared vectors.
Install
npm install @nordaxiz/harbour-connect
git clone https://github.com/Nordaxiz-Technology-Limited/nordaxiz-harbour-connect.git
npm install ./nordaxiz-harbour-connect/node
Node.js 20.19 or newer. The source is in the node/ folder of the
Harbour Connect repository, MIT licensed.
The client
import { Harbour } from '@nordaxiz/harbour-connect'; // or: const { Harbour } = require(...)
const harbour = new Harbour(process.env.HARBOUR_SECRET_KEY, {
webhookSecret: process.env.HARBOUR_WEBHOOK_SECRET, // for harbour.webhooks
apiBase: 'https://api.harbour.africa', // HTTPS, except localhost
timeoutMs: 30_000, // 1000 to 300000
maxRetries: 2, // 0 to 2
webhookTolerance: 300, // seconds either side
});
harbour.mode; // "live" | "test", from the key
harbour.isTestMode;
harbour.maskedKey; // hb_sk_live_****abcd, for logs and support tickets
Create one client and share it. An unknown option throws InvalidArgumentError, so a typo never passes
silently. The key lives in a private field: console.log, util.inspect and
JSON.stringify only ever show the masked form. A public key (hb_pk_) is refused, with a pointer
to harbour.js.
Services
// charges
await harbour.charges.create({ amountKobo, customer, reference, description, returnUrl, provider, metadata, idempotencyKey });
await harbour.charges.verify('HB-88413');
await harbour.charges.findByMerchantReference('order-1043'); // or null
// refunds: each one waits for an Owner's approval
await harbour.refunds.create({ reference: 'HB-88413', amountKobo: 2_500_000, reason: 'Two metres short' });
await harbour.refunds.retrieve('rf_…');
// payment links
await harbour.paymentLinks.create({ amountKobo: 1_500_000, description: 'Aso-ebi, 12 yards', expiresInDays: 7 });
await harbour.paymentLinks.retrieve('pl_…');
// the ledger
const page = await harbour.transactions.list({ status: 'succeeded', from: '2026-09-01', limit: 50 });
page.data; page.nextCursor; page.hasMore; await page.nextPage();
for await (const txn of harbour.transactions.all({ provider: 'paystack' })) { /* every page, lazily */ }
await harbour.transactions.retrieve('HB-88413');
Options are camelCase; the objects that come back are the API's own, in snake_case (checkout.checkout_url,
txn.amount_kobo), exactly as in the API reference. Amounts must be whole numbers of kobo:
1200.5 or "1200" is refused before anything is sent. Money.toKobo("120,000.50")
converts a naira string.
Webhooks
Verify against the raw body. Parsing the JSON first changes the bytes and the signature fails.
constructEvent takes the body as a Buffer or string and either the header value or the whole headers object
(Express, Fetch Headers):
import express from 'express';
import { Event, SignatureVerificationError } from '@nordaxiz/harbour-connect';
// before app.use(express.json()): this route needs the raw bytes
app.post('/webhooks/harbour', express.raw({ type: 'application/json' }), (req, res) => {
let event;
try {
event = harbour.webhooks.constructEvent(req.body, req.headers);
} catch (e) {
if (e instanceof SignatureVerificationError) return res.sendStatus(400);
throw e;
}
if (event.type === Event.CHARGE_SUCCEEDED) fulfil(event.transaction()); // de-duplicate on event.id
res.sendStatus(200);
});
// app/api/webhooks/harbour/route.js
export const runtime = 'nodejs';
export async function POST(request) {
const raw = await request.text(); // never request.json() before verifying
const event = harbour.webhooks.constructEvent(raw, request.headers);
// …
return new Response(null, { status: 200 });
}
A NestJS controller is in the repository's node/examples. A failed check throws
SignatureVerificationError with kind set to malformed, mismatch or
tolerance; answer 400. See Webhooks for retries and de-duplication.
Errors and retries
import { HarbourError, ValidationError, RateLimitError, ApiConnectionError } from '@nordaxiz/harbour-connect';
try {
await harbour.charges.create({ amountKobo: 12_000_000, customer: 'funke@example.ng' });
} catch (e) {
if (e instanceof ValidationError) console.log(e.fields); // { amount_kobo: "…" }
else if (e instanceof RateLimitError) console.log(e.retryAfter); // seconds
else if (e instanceof ApiConnectionError) { /* no answer: safe to retry with the same idempotencyKey */ }
else if (e instanceof HarbourError) console.log(e.status, e.code, e.message);
}
Every error extends HarbourError with status and code:
AuthenticationError (401), PermissionError (403), NotFoundError (404),
IdempotencyConflictError (409), ValidationError (422), RateLimitError (429),
ApiConnectionError (no answer) and InvalidArgumentError (caught before sending). Network
errors, 429 and 5xx are retried at most twice with jittered backoff, only for GETs and creates that carry an
idempotency key, which every create does. See Idempotency.
Versioning
- The package is
@nordaxiz/harbour-connect, version 0.1.0. Below 1.0.0 a minor version may break things: pin with~0.1and read the changelog before moving. - The version travels as
User-Agent: harbour-connect-node/<version>. - Every call goes to the API's
/v1, whichever SDK version you run.