Reference

API reference

Every endpoint, object and convention of the Harbour API v1.

JSON in, JSON out, UTF-8. Money is always integer kobo; times are ISO 8601 in UTC. In Node.js, PHP and Python, Harbour Connect (Node.js, PHP, Python) wraps all of this.

EnvironmentBase URL
Productionhttps://api.harbour.africa/v1
Staginghttps://api.staging.harbour.africa/v1
Localhttp://api.harbour.localhost:8080/v1 or http://localhost/harbour-api/v1

The whole integration API is also described in an OpenAPI 3.1 spec: generate a client for Go, Java, .NET, Ruby or any other language. For quick manual calls, import the Postman collection, which carries ids from one request to the next so it runs top to bottom. For webhooks, generated code cannot verify signatures for you; follow Webhooks or use an SDK.

Authentication

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

const harbour = new Harbour(process.env.HARBOUR_SECRET_KEY);   // sends Authorization: Bearer on every call
const page = await harbour.transactions.list({ limit: 25 });
CredentialFormatUsed by
Secret keyhb_sk_live_… / hb_sk_test_…Your server. Never a browser or an app.
Public keyhb_pk_live_… / hb_pk_test_…harbour.js, to create a checkout only.
User tokenhat_… access, hrt_… refreshThe Harbour mobile app and first-party clients.

Every response carries X-Harbour-Tenant: ten_…, and every list body repeats it as tenant_id. Keys are made in the dashboard under Settings → Developers; see Keys and modes.

Conventions

  • Idempotency. Every POST that creates something accepts Idempotency-Key (1 to 120 printable ASCII). The same key with the same body replays the first answer; with a different body it is 409 idempotency_conflict.
  • Pagination. Lists take limit (default 25, max 100) and cursor.
  • Errors. Always the same shape, with a plain-language message.
  • Modes. A key only sees its own mode's data, end to end.
JSON A list response
{
  "data": [ { "object": "transaction", "id": "txn_…" } ],
  "next_cursor": "eyJvIjoiMjAyNi0wOS0xM1QxNDozMjowN1oiLCJpIjoidHhuXzAxayJ9",
  "tenant_id": "ten_01m2e48qxzwqrwz0axj3r20jpv"
}
JSON An error response
{
  "error": {
    "code": "validation_failed",
    "message": "Amount must be at least ₦100.",
    "fields": { "amount_kobo": "Amount must be at least ₦100." }
  }
}

Charges

EndpointBody / queryAnswers
POST /v1/charges amount_kobo*, email*, name, phone, reference, description, return_url, provider (auto|paystack|flutterwave|opay), metadata 201 Checkout
GET /v1/charges/{reference} The Harbour HB-… reference Checkout, with transaction set once paid. Asks the provider when not yet final.
GET /v1/charges merchant_reference=order-1043 The charge for your own reference, or 404.
const checkout = await harbour.charges.create({
  amountKobo: 1_200_000,
  customer: { email: 'funke@example.ng', name: 'Funke Adeyemi', phone: '+2348031234567' },
  reference: 'order-1043',
  description: 'Aso-ebi order, 12 yards',
  returnUrl: 'https://shop.example.ng/thanks',
  provider: 'auto',
  metadata: { order_id: '1043' },
  idempotencyKey: 'order-1043-attempt-1',
});
JSON Checkout
{
  "object": "checkout",
  "id": "ct_01k5m0r3w9a2c8n7xq4v6t1b0d",
  "reference": "HB-88413",
  "merchant_reference": "order-1043",
  "status": "open",
  "amount_kobo": 1200000,
  "currency": "NGN",
  "checkout_url": "https://pay.harbour.africa/c/ct_01k5m0r3w9a2c8n7xq4v6t1b0d",
  "checkout_token": "ct_01k5m0r3w9a2c8n7xq4v6t1b0d",
  "provider": "paystack",
  "expires_at": "2026-09-13T15:32:07Z",
  "mode": "live",
  "transaction": null
}

Refunds

EndpointBodyAnswers
POST /v1/refundsreference*, amount_kobo (default: all of it), reason*202 Refund, status requested
GET /v1/refunds/{id}—Refund
const refund = await harbour.refunds.create({
  reference: 'HB-88402',
  amountKobo: 250_000,
  reason: 'Two metres short on delivery',
});
// { object: 'refund', id: 'ref_…', status: 'requested', amount_kobo: 250000 }

Refunds wait for an Owner to approve them; see Refunds.

EndpointBodyAnswers
POST /v1/payment-linksamount_kobo*, description*, customer, expires_in_days (1–90, default 7), provider201 Payment link
GET /v1/payment-links/{id}—Payment link
const link = await harbour.paymentLinks.create({
  amountKobo: 1_200_000,
  description: 'Aso-ebi order, 12 yards',
  customer: { name: 'Funke Adeyemi', phone: '+2348031234567' },
  expiresInDays: 7,
  provider: 'auto',
});
// { object: 'payment_link', id: 'lnk_…', url: 'https://pay.harbour.africa/okafor-textiles/k2m9x', status: 'active' }

Invoices

Needs Harbour Invoice switched on for the key's mode (403 otherwise). Amounts are minor units. See the page for the object and the life of an invoice.

EndpointBodyAnswers
POST /v1/invoicescustomer* (id of a saved customer, or name*, email*, phone), lines* (description*, quantity, unit, item_id, unit_amount_minor*), currency, discount_minor, tax (label, rate_percent), reference, terms_days, due_date, notes, allow_part_payment, reminders, issue, send201 Invoice
GET /v1/invoicesstatus (draft, open, overdue, paid, void…), cursor, limitList of invoices
GET /v1/invoices/{id}—Invoice
POST /v1/invoices/{id}/issuesend (default true)Invoice
POST /v1/invoices/{id}/send—Invoice
POST /v1/invoices/{id}/voidreason*Invoice

Products and orders

Needs Harbour StoreFront switched on to create products. Orders come from StoreFront and Tickets (?app=tickets).

EndpointBodyAnswers
GET /v1/products—List of products
POST /v1/productsname*, price_minor*, currency, stock, max_per_order, description, status201 Product
GET /v1/products/{id}—Product
GET /v1/ordersapp, status, cursor, limitList of orders
GET /v1/orders/{id}—Order
POST /v1/orders/{id}/fulfilstatus (fulfilled or delivered), noteOrder

Events and tickets

Needs Harbour Tickets switched on for the key's mode. To sell from your own website, see Selling from your own pages.

EndpointBody or queryAnswers
GET /v1/eventsstatus (published, draft, cancelled), upcoming=1, slugList of events, each with pictures, ticket types (class, session, price, price_now_minor, early_bird, seats left) and the attendee form
GET /v1/events/{id}—Event
POST /v1/events/{id}/orderstickets* ([{type, quantity}]), customer* (name*, email*, phone), answers, consents, marketing_consent, return_url201 Ticket order with checkout_url and its invoice; 202 Registration when the ticket needs approval
GET /v1/orders/{id}—Order with its lines (an early-bird line has "price_tier": "early"); a ticket order adds event, invoice and tickets (each with code, qr and url)
GET /v1/events/{id}/registrationsstatusRegistrations with answers
POST /v1/registrations/{id}/approve or /declinereason (decline)Registration
POST /v1/events/{id}/check-incode*, gateresult and ticket

Connected apps and TaxMan

EndpointBody or queryAnswers
GET /v1/apps/klaviyo/campaigns, POST samename, list_id, template_id, subject, from_email, from_labelKlaviyo campaigns (connector)
POST /v1/apps/klaviyo/campaigns/{id}/send—Sending
POST /v1/apps/klaviyo/audiencesaudience (paid_30d, abandoned_7d, invoice_overdue), list_idProfiles added
GET /v1/apps/zoho-books/invoicesstatusZoho Books invoices
POST /v1/apps/whatsapp/messagestype (invoice, payment_link), id, to (optional)Sent on WhatsApp (connector)
GET /v1/tax/summaryyearTax estimate (TaxMan)

Transactions

EndpointQuery
GET /v1/transactions status, provider, channel, from, to (ISO dates, local days), customer (email), limit, cursor
GET /v1/transactions/{id} A txn_… id or an HB-… reference

Objects

ObjectFields worth knowing
transactionid, reference, merchant_reference, type, status, provider, provider_reference, amount_kobo, fee_kobo, net_kobo, refunded_kobo, currency, channel, customer, failure_message, occurred_at, settled_at, settlement_id, recovered, metadata, mode
checkoutreference, status, checkout_url, checkout_token, amount_kobo, expires_at, transaction
refundid, reference, transaction_id, amount_kobo, reason, status
payment_linkid, url, amount_kobo, description, status, expires_at, transaction_id
settlementid, provider, status, expected_date, expected_amount_kobo, landed_amount_kobo, shortfall_kobo, fee_kobo, transaction_count, bank, landed_at

Statuses: a charge is initiated → pending → succeeded → settled, or failed; later it may become refunded or disputed. Channels are card, bank_transfer, ussd, qr, mobile_money and other.

Rate limits

  • 300 requests a minute per secret key.
  • 600 a minute per user token.
  • Over the limit is 429 rate_limited with Retry-After. The SDK waits and retries twice.

Webhook deliveries to your server are not rate limited by you; they retry at 1m, 5m, 30m, 2h, 6h and 12h for up to 24 hours. See Webhooks.