Reference

Testing your integration

Test mode end to end, local development, and testing without the internet.

There are three things worth testing, and they are separate: that you can reach Harbour, that a real payment works end to end in test mode, and that your webhook handler does the right thing when it is called. The first two need a provider; the third needs nothing but your own code.

What test mode does

  • A hb_sk_test_ key only ever reaches the business's test provider keys, so nothing you do can move real money.
  • Every list, the dashboard feed and the ledger are filtered by the key's mode: a test key sees test payments only, which is why a test key against a live business looks like an empty account.
  • Cards come from the provider, not from Harbour: use Paystack's test cards or Flutterwave's or OPay's.
  • Webhook endpoints have a mode of their own, so test deliveries can go to a different URL from live ones.

Checking the API by hand

Start here, before any code. It takes a minute and rules out the two things that break most first integrations: the wrong key and a proxy eating your header.

Terminal
# the ledger: proves the key, the header and that you are talking to the right environment
curl -s https://api.harbour.africa/v1/transactions?limit=1 \
  -H "Authorization: Bearer hb_sk_test_your_key"

# a charge
curl -s -X POST https://api.harbour.africa/v1/charges \
  -H "Authorization: Bearer hb_sk_test_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: smoke-$(date +%s)" \
  -d '{"amount_kobo":1200000,"email":"funke@example.ng","reference":"smoke-1","return_url":"https://example.ng/thanks"}'

# and back again
curl -s https://api.harbour.africa/v1/charges/HB-88413 \
  -H "Authorization: Bearer hb_sk_test_your_key"

What the answers mean:

You getIt means
200 with "data": []Everything works. There are simply no test payments yet.
401 unauthorizedThe key is wrong, revoked, or from the other environment. If the message is "Send an Authorization: Bearer header" and you did send one, something between you and Harbour is stripping it — a proxy, or an Apache that is not passing it to PHP.
422 no_providerThe key is fine. The business has no provider connected in this mode.
404 not_foundUsually a live reference being looked up with a test key, or the other way round.

Checking the SDK

A twenty-line script that proves the key, the ledger, a charge and the error mapping, all over real HTTP:

smoke test
// node tools/harbour-smoke.mjs
import { Harbour, HarbourError } from '@nordaxiz/harbour-connect';

const options = process.env.HARBOUR_API_BASE ? { apiBase: process.env.HARBOUR_API_BASE } : {};
const harbour = new Harbour(process.env.HARBOUR_SECRET_KEY, options);

console.log('mode', harbour.mode);                              // "test"

const page = await harbour.transactions.list({ limit: 3 });
console.log(`ledger: ${page.data.length} row(s) for ${page.tenantId}`);

try {
  const checkout = await harbour.charges.create({ amountKobo: 1_200_000, customer: 'funke@example.ng' });
  console.log('charge:', checkout.reference, checkout.checkout_url);
  console.log('verify:', (await harbour.charges.verify(checkout.reference)).status);
} catch (e) {
  if (!(e instanceof HarbourError)) throw e;
  console.log(`charge refused: ${e.code} (${e.status}) ${e.message}`);
}

Run it against test keys on every environment you deploy to, including production with a test key. It is the fastest way to tell a broken deploy from a broken integration.

Against a local Harbour

If you are running Harbour itself locally, point the SDK at it. Plain HTTP is allowed for localhost, *.localhost and 127.0.0.1; every other host must be HTTPS.

// plain HTTP is allowed for localhost, *.localhost and 127.0.0.1 only
new Harbour('hb_sk_test_…', { apiBase: 'http://localhost/harbour-api' });
// or, with the host-based local setup
new Harbour('hb_sk_test_…', { apiBase: 'http://api.harbour.localhost:8080' });
.env or from the environment
HARBOUR_SECRET_KEY=hb_sk_test_your_key
HARBOUR_WEBHOOK_SECRET=whsec_your_endpoint_secret
HARBOUR_API_BASE=http://localhost/harbour-api

A trailing /v1 on the base is accepted and ignored. Staging is https://api.staging.harbour.africa.

Testing your webhook endpoint

Two ways, and you want both.

A real delivery from Harbour

Settings → Developers → Webhook endpoints → Test sends a genuine signed delivery to your URL and shows you the status code that came back. That proves DNS, TLS, your firewall and your route in one click. It needs a URL Harbour can reach; a tunnel (ngrok, Cloudflare Tunnel) is fine for development.

A signed delivery you make yourself

No tunnel, no internet, and it can live in your test suite. Signature::header() signs a body exactly as Harbour does:

import { randomBytes } from 'node:crypto';
import { Signature } from '@nordaxiz/harbour-connect';

const body = JSON.stringify({
  id: `evt_test_${randomBytes(6).toString('hex')}`,
  type: 'charge.succeeded',
  created_at: new Date().toISOString().replace(/\.\d{3}Z$/, 'Z'),
  mode: 'test',
  tenant_id: 'ten_test',
  data: {
    object: 'transaction',
    id: 'txn_test',
    reference: 'HB-88413',
    merchant_reference: 'order-1043',   // an order that exists in your database
    status: 'succeeded',
    amount_kobo: 1_200_000,             // exactly what that order costs
    currency: 'NGN',
    channel: 'card',
    provider: 'paystack',
    mode: 'test',
  },
});

const header = Signature.header(body, process.env.HARBOUR_WEBHOOK_SECRET);

Then POST that body with Harbour-Signature: {$header} at your own endpoint. The webhooks page has a full payload to copy.

In your own test suite

Three cases cover almost everything that goes wrong in production:

Your webhook tests
import { test } from 'node:test';
import assert from 'node:assert/strict';
import request from 'supertest';
import { app } from '../app.js';

test('a signed delivery marks the order paid', async () => {
  const order = await Order.create({ reference: 'order-1043', totalKobo: 1_200_000 });
  const { body, header } = harbourEvent('charge.succeeded', order);

  await request(app).post('/webhooks/harbour')
    .set('Content-Type', 'application/json').set('Harbour-Signature', header)
    .send(body).expect(200);

  assert.ok((await Order.find(order.id)).isPaid());
});

test('the same delivery twice ships once', async () => {
  // …post the identical body and header again; the second must not fulfil a second time
});

test('a tampered body is refused', async () => {
  const order = await Order.create({ reference: 'order-1044', totalKobo: 1_200_000 });
  const { body, header } = harbourEvent('charge.succeeded', order);

  await request(app).post('/webhooks/harbour')
    .set('Content-Type', 'application/json').set('Harbour-Signature', header)
    .send(body + ' ').expect(400);
});

For the outgoing side, give the client a fake fetch (Node.js) or transport (PHP) instead of letting tests talk to the network:

import { Harbour } from '@nordaxiz/harbour-connect';

// the client takes any fetch: record what it sends and answer from a list
const requests = [];
const answers = [
  Response.json({ reference: 'HB-88413', checkout_url: 'https://pay.harbour.africa/c/ct_x', status: 'open' }, { status: 201 }),
];
const fakeFetch = async (url, init) => {
  requests.push({ url: String(url), init });
  return answers.shift() ?? Response.json({ error: { code: 'server_error' } }, { status: 500 });
};

const harbour = new Harbour('hb_sk_test_x', { fetch: fakeFetch, maxRetries: 0 });

const checkout = await harbour.charges.create({ amountKobo: 1_200_000, customer: 'funke@example.ng' });
// then assert on requests: the path, the body, the Idempotency-Key header

The SDKs' own suites work this way, so they run offline: npm test in node/, or composer test for PHP.

Before you call it done

  • A test payment succeeds and your order is marked paid by the webhook, with the return URL disabled.
  • The same delivery twice fulfils once.
  • A tampered body is refused with 400.
  • A failed payment does not mark anything paid, and the failure message reaches your logs.
  • An amount mismatch raises an alert instead of shipping.
  • A refund request appears in the dashboard queue, and refund.completed credits the order back.
  • Your endpoint answers in well under ten seconds with everything slow queued.
  • Secret keys are absent from the repository, the browser bundle and the logs.

Then Going live.