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. 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. 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. 3

    Install Harbour Connect

    npm install @nordaxiz/harbour-connect
    
    # until the package is on the npm registry
    git clone https://github.com/Nordaxiz-Technology-Limited/nordaxiz-harbour-connect.git
    npm install ./nordaxiz-harbour-connect/node

    Node.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. 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);
    });

    Amounts are integer kobo: 1200000 is ₦12,000. Floats are refused.

  5. 5

    Confirm the payment

    The customer comes back to your return_url with ?reference=HB-88413&status=succeeded. Ignore that status and 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 });
    });

    Check the amount and your own reference before you fulfil anything.

  6. 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);
    });

    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() and GET /v1/transactions both 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.