After the payment

Refunds

Refunds are requests. Someone with authority approves them.

A refund in Harbour is a request, not an instruction. It waits in the business's approval queue until an Owner approves it in the dashboard or the app. That is deliberate: refunds move real money out of a real bank account, and an API key should not be able to do that on its own.

Request a refund

// partial: two metres short on a twelve-yard order
const refund = await harbour.refunds.create({
  reference: 'HB-88402',
  amountKobo: 2_500_000,
  reason: 'Two metres short on delivery',
});

// or the whole payment: leave out amountKobo
await harbour.refunds.create({ reference: 'HB-88402', reason: 'Customer cancelled before dispatch' });

refund.id;        // "ref_…"
refund.status;    // "requested"

A reason is required, and it is not paperwork: the Owner reads it in the queue before deciding. Write the sentence you would say out loud.

The approval queue

  • Finance users and API keys can request. Owners approve or decline.
  • An Owner requesting from the dashboard approves in the same step, so a one-person business is not stuck.
  • Staff cannot see refunds at all.
  • Every request, approval and decline is in the audit log with who and when.

Following the status

React to the events rather than polling:

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

switch (event.type) {
  case Event.REFUND_COMPLETED: await order.creditBack(event.refund().amount_kobo); break;
  case Event.REFUND_DECLINED:  await support.reopen(event.refund().id, 'Refund declined'); break;
  case Event.REFUND_FAILED:    await support.reopen(event.refund().id, 'Provider refused the refund'); break;
}

Or read the current state when you need it on a screen:

const refund = await harbour.refunds.retrieve('ref_…');

refund.status;    // requested | approved | processing | completed | failed | declined
refund.amount_kobo;
refund.reason;

Only completed means the money has left. approved and processing mean the provider has it in hand; a provider can still fail a refund afterwards.