Start here
Quickstart
From nothing to a paid test payment, in six steps.
This is the whole integration, in the order it is done. It ends with a real (test) payment landing in the dashboard feed. Budget twenty minutes, most of it waiting for a provider dashboard to load.
-
1
Connect a provider in test mode
In the dashboard open Providers → Add a provider, choose Paystack, Flutterwave or OPay, pick Test keys, and paste the test public and secret keys from that provider's own dashboard (Paystack: Settings → API Keys & Webhooks. Flutterwave: Settings → API Keys. OPay: API Keys & Webhooks, where OPay also shows the merchant ID Harbour asks for). Harbour validates them with the provider before it stores anything.
Harbour then shows a webhook URL to paste back into the provider's dashboard, and for Flutterwave a secret hash shown once. Do that now: it is how Harbour hears that a payment succeeded.
-
2
Create your test keys
Open Settings → Developers and create a key pair in test mode. You get:
hb_sk_test_…— the secret key, shown once. Server only.hb_pk_test_…— the public key, safe in a browser.
On the same screen, add a webhook endpoint pointing at your server and copy its
whsec_…signing secret, also shown once. -
3
Install Harbour Connect
npm install @nordaxiz/harbour-connect git clone https://github.com/Nordaxiz-Technology-Limited/nordaxiz-harbour-connect.git npm install ./nordaxiz-harbour-connect/nodeexport HARBOUR_SECRET_KEY=hb_sk_test_your_key curl -s "https://api.harbour.africa/v1/transactions?limit=1" \composer require nordaxiz/harbour-connect:^0.1Node.js 20.19 or newer, or PHP 8.1 or newer; neither SDK has dependencies. Any other language calls the HTTP API directly, as the cURL tab does. The SDKs are below 1.0.0, so pin them to patches while the API settles (why). Put the keys in your environment, never in code:
.env HARBOUR_SECRET_KEY=hb_sk_test_your_key HARBOUR_WEBHOOK_SECRET=whsec_your_endpoint_secret -
4
Send the customer to checkout
Create the charge on your server, store the Harbour reference against the order, then redirect.
checkout import { Harbour } from '@nordaxiz/harbour-connect'; const harbour = new Harbour(process.env.HARBOUR_SECRET_KEY); app.post('/checkout', async (req, res) => { const order = await Order.find(req.body.orderId); const checkout = await harbour.charges.create({ amountKobo: 1_200_000, // ₦12,000.00 customer: 'funke@example.ng', reference: order.reference, // your own order reference, "order-1043" description: 'Aso-ebi order, 12 yards', returnUrl: 'https://shop.example.ng/thanks', }); // store checkout.reference ("HB-88413") against the order before you redirect await order.update({ harbourReference: checkout.reference }); res.redirect(303, checkout.checkout_url); });curl -s -X POST https://api.harbour.africa/v1/charges \<?php use Nordaxiz\HarbourConnect\Harbour; Harbour::configure((string) getenv('HARBOUR_SECRET_KEY')); $checkout = Harbour::charge(12_000_00, 'funke@example.ng', [ 'reference' => 'order-1043', // your own order reference 'description' => 'Aso-ebi order, 12 yards', 'return_url' => 'https://shop.example.ng/thanks', ]); // store $checkout->reference ("HB-88413") against the order before you redirect $order->harbour_reference = $checkout->reference; $order->save(); header('Location: ' . $checkout->checkoutUrl, true, 303);Amounts are integer kobo:
1200000is ₦12,000. Floats are refused. -
5
Confirm the payment
The customer comes back to your
return_urlwith?reference=HB-88413&status=succeeded. Ignore thatstatusand ask Harbour:thanks app.get('/thanks', async (req, res) => { const checkout = await harbour.charges.verify(req.query.reference); // GET /v1/charges/HB-88413 const order = await Order.findByReference(checkout.merchant_reference); if (checkout.status === 'succeeded' && order && checkout.amount_kobo === order.totalKobo) { await order.markPaid(); // idempotent: the webhook may get here first } res.render('thanks', { order }); });curl -s https://api.harbour.africa/v1/charges/HB-88413 \<?php use Nordaxiz\HarbourConnect\Harbour; $checkout = Harbour::verify($_GET['reference'] ?? ''); // GET /v1/charges/HB-88413 if ($checkout->isPaid() && $checkout->merchantReference === $order->reference && $checkout->amountKobo === $order->total_kobo) { $order->markPaid(); // idempotent: the webhook may get here first }Check the amount and your own reference before you fulfil anything.
-
6
Add the webhook
A customer who closes the tab never reaches your return URL, but the webhook still arrives. This, not the redirect, is what makes fulfilment reliable.
webhook import express from 'express'; import { Harbour, Event, SignatureVerificationError } from '@nordaxiz/harbour-connect'; const harbour = new Harbour(process.env.HARBOUR_SECRET_KEY, { webhookSecret: process.env.HARBOUR_WEBHOOK_SECRET, }); // before app.use(express.json()): the signature is checked against the raw bytes app.post('/webhooks/harbour', express.raw({ type: 'application/json' }), async (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) { const txn = event.transaction(); const order = await Order.findByReference(txn.merchant_reference); if (order && order.totalKobo === txn.amount_kobo) { await order.markPaid(event.id); // de-duplicate on the event id } } res.sendStatus(200); });<?php use Nordaxiz\HarbourConnect\Exception\SignatureVerificationException; use Nordaxiz\HarbourConnect\Harbour; use Nordaxiz\HarbourConnect\Webhook\Event; try { Harbour::webhooks((string) getenv('HARBOUR_WEBHOOK_SECRET'))->handle(null, function (Event $event): void { if ($event->type !== Event::CHARGE_SUCCEEDED) { return; } $transaction = $event->transaction(); $order = Order::findByReference($transaction->merchantReference); if ($order && $order->total_kobo === $transaction->amountKobo) { $order->markPaid($event->id); // de-duplicate on the event id } }); http_response_code(200); } catch (SignatureVerificationException $e) { http_response_code(400); }Answer 2xx within ten seconds and do slow work in a queue. Harbour retries a failed delivery for 24 hours. The full rules are on Webhooks.
What you have now
Pay for a test order with the provider's test card. Within a second or two:
- your webhook fires and the order is marked paid;
- the payment appears in the dashboard feed with its provider, channel and fee;
harbour.charges.verify()andGET /v1/transactionsboth show it.
Nothing about this changes when you go live except the keys. Read Testing for the checks worth automating, then Going live for the switch.