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.
| Environment | Base URL |
|---|---|
| Production | https://api.harbour.africa/v1 |
| Staging | https://api.staging.harbour.africa/v1 |
| Local | http://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 });
curl -s "https://api.harbour.africa/v1/transactions?limit=25" \
GET /v1/transactions?limit=25 HTTP/1.1
Host: api.harbour.africa
Authorization: Bearer hb_sk_live_your_key
Accept: application/json
| Credential | Format | Used by |
|---|---|---|
| Secret key | hb_sk_live_… / hb_sk_test_… | Your server. Never a browser or an app. |
| Public key | hb_pk_live_… / hb_pk_test_… | harbour.js, to create a checkout only. |
| User token | hat_… access, hrt_… refresh | The 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
POSTthat creates something acceptsIdempotency-Key(1 to 120 printable ASCII). The same key with the same body replays the first answer; with a different body it is409 idempotency_conflict. - Pagination. Lists take
limit(default 25, max 100) andcursor. - Errors. Always the same shape, with a plain-language
message. - Modes. A key only sees its own mode's data, end to end.
{
"data": [ { "object": "transaction", "id": "txn_…" } ],
"next_cursor": "eyJvIjoiMjAyNi0wOS0xM1QxNDozMjowN1oiLCJpIjoidHhuXzAxayJ9",
"tenant_id": "ten_01m2e48qxzwqrwz0axj3r20jpv"
}
{
"error": {
"code": "validation_failed",
"message": "Amount must be at least ₦100.",
"fields": { "amount_kobo": "Amount must be at least ₦100." }
}
}
Charges
| Endpoint | Body / query | Answers |
|---|---|---|
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',
});
curl -s -X POST https://api.harbour.africa/v1/charges \
POST /v1/charges
Authorization: Bearer hb_sk_live_…
Content-Type: application/json
Idempotency-Key: order-1043-attempt-1
{
"amount_kobo": 1200000,
"email": "funke@example.ng",
"name": "Funke Adeyemi",
"phone": "+2348031234567",
"reference": "order-1043",
"description": "Aso-ebi order, 12 yards",
"return_url": "https://shop.example.ng/thanks",
"provider": "auto",
"metadata": { "order_id": "1043" }
}
{
"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
| Endpoint | Body | Answers |
|---|---|---|
POST /v1/refunds | reference*, 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 }
curl -s -X POST https://api.harbour.africa/v1/refunds \
POST /v1/refunds
{
"reference": "HB-88402",
"amount_kobo": 250000,
"reason": "Two metres short on delivery"
}
→ 202 Accepted
{ "object": "refund", "id": "ref_…", "status": "requested", "amount_kobo": 250000 }
Refunds wait for an Owner to approve them; see Refunds.
Payment links
| Endpoint | Body | Answers |
|---|---|---|
POST /v1/payment-links | amount_kobo*, description*, customer, expires_in_days (1–90, default 7), provider | 201 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' }
curl -s -X POST https://api.harbour.africa/v1/payment-links \
POST /v1/payment-links
{
"amount_kobo": 1200000,
"description": "Aso-ebi order, 12 yards",
"customer": { "name": "Funke Adeyemi", "phone": "+2348031234567" },
"expires_in_days": 7,
"provider": "auto"
}
→ 201 Created
{ "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.
| Endpoint | Body | Answers |
|---|---|---|
POST /v1/invoices | customer* (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, send | 201 Invoice |
GET /v1/invoices | status (draft, open, overdue, paid, void…), cursor, limit | List of invoices |
GET /v1/invoices/{id} | — | Invoice |
POST /v1/invoices/{id}/issue | send (default true) | Invoice |
POST /v1/invoices/{id}/send | — | Invoice |
POST /v1/invoices/{id}/void | reason* | Invoice |
Products and orders
Needs Harbour StoreFront switched on to create products. Orders come from StoreFront and Tickets (?app=tickets).
| Endpoint | Body | Answers |
|---|---|---|
GET /v1/products | — | List of products |
POST /v1/products | name*, price_minor*, currency, stock, max_per_order, description, status | 201 Product |
GET /v1/products/{id} | — | Product |
GET /v1/orders | app, status, cursor, limit | List of orders |
GET /v1/orders/{id} | — | Order |
POST /v1/orders/{id}/fulfil | status (fulfilled or delivered), note | Order |
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.
| Endpoint | Body or query | Answers |
|---|---|---|
GET /v1/events | status (published, draft, cancelled), upcoming=1, slug | List 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}/orders | tickets* ([{type, quantity}]), customer* (name*, email*, phone), answers, consents, marketing_consent, return_url | 201 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}/registrations | status | Registrations with answers |
POST /v1/registrations/{id}/approve or /decline | reason (decline) | Registration |
POST /v1/events/{id}/check-in | code*, gate | result and ticket |
Connected apps and TaxMan
| Endpoint | Body or query | Answers |
|---|---|---|
GET /v1/apps/klaviyo/campaigns, POST same | name, list_id, template_id, subject, from_email, from_label | Klaviyo campaigns (connector) |
POST /v1/apps/klaviyo/campaigns/{id}/send | — | Sending |
POST /v1/apps/klaviyo/audiences | audience (paid_30d, abandoned_7d, invoice_overdue), list_id | Profiles added |
GET /v1/apps/zoho-books/invoices | status | Zoho Books invoices |
POST /v1/apps/whatsapp/messages | type (invoice, payment_link), id, to (optional) | Sent on WhatsApp (connector) |
GET /v1/tax/summary | year | Tax estimate (TaxMan) |
Transactions
| Endpoint | Query |
|---|---|
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
| Object | Fields worth knowing |
|---|---|
transaction | id, 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 |
checkout | reference, status, checkout_url, checkout_token, amount_kobo, expires_at, transaction |
refund | id, reference, transaction_id, amount_kobo, reason, status |
payment_link | id, url, amount_kobo, description, status, expires_at, transaction_id |
settlement | id, 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_limitedwithRetry-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.