After the payment

The ledger

Read your payments back: filters, cursors and settlement.

The ledger is every payment, refund and dispute across every provider the business has connected, in one shape. It is the thing most integrations read from after the first week: reconciliation, exports, a payments screen inside your own product.

List transactions

const page = await harbour.transactions.list({
  status: 'succeeded',            // succeeded | pending | failed | refunded | disputed
  provider: 'paystack',
  channel: 'card',                // card | bank_transfer | ussd | qr | mobile_money
  from: '2026-09-01',
  to: '2026-09-13',
  customer: 'tunde@example.ng',
  limit: 100,                     // 1 to 100, default 25
});

for (const txn of page.data) {    // this page only
  console.log(txn.reference, txn.amount_kobo);
}

Dates are the business's local days (Africa/Lagos), so "from 1 September" means from midnight in Lagos, not UTC. Every filter is optional; with none you get the newest payments, newest first.

Paging through everything

Lists are cursor paginated, never offset: a payment landing while you page will not shift rows under you.

// every page, fetched lazily as you walk
for await (const txn of page) {
  await exportRow(txn);
}

// the same, from the start, in one call
for await (const txn of harbour.transactions.all({ status: 'settled' })) {
  await exportRow(txn);
}

// or drive it yourself
page.nextCursor;                  // "eyJvIjoi…" or null
page.hasMore;                     // boolean
const next = await page.nextPage();

One transaction

const txn = await harbour.transactions.retrieve('HB-88413');   // or 'txn_…'

txn.reference;           // "HB-88413"
txn.merchant_reference;  // "order-1043"
txn.amount_kobo;         // 1200000
txn.fee_kobo;            // 18000  (the provider's fee; Harbour adds nothing)
txn.net_kobo;            // 1182000
txn.status;              // "succeeded"
txn.provider;            // "paystack"
txn.channel;             // "card"
txn.customer.email;      // "funke@example.ng"
txn.occurred_at;         // "2026-09-13T14:32:07Z"
txn.settlement_id;       // "stl_…" once it is in a payout, else null

Node.js hands back the API's own objects, in snake_case. In PHP every model also exposes the raw API fields, so a field added tomorrow is readable today: $transaction['net_kobo'], $transaction->net_kobo and $transaction->toArray() all work.

Settlement

A payment is succeeded when the customer paid, and settled once it is part of a payout that reached the bank. settlement_id ties the two together, and the dashboard's settlement calendar shows what is forecast, what landed and what landed short. Harbour never moves that money: the provider pays the business's own bank account on the provider's own schedule.

If you reconcile against bank statements, match on the settlement, not on individual payments: providers pay in batches, net of their fees.