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"
curl -s -X POST https://api.harbour.africa/v1/refunds \
<?php
use Nordaxiz\HarbourConnect\Harbour;
// partial: two metres short on a twelve-yard order
$refund = Harbour::refund('HB-88402', 25_000_00, 'Two metres short on delivery');
// or the whole payment
$refund = Harbour::refund('HB-88402', null, '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;
}
<?php
use Nordaxiz\HarbourConnect\Webhook\Event;
match ($event->type) {
Event::REFUND_COMPLETED => $order->creditBack($event->refund()->amountKobo),
Event::REFUND_DECLINED => $support->reopen($event->refund()->id, 'Refund declined'),
Event::REFUND_FAILED => $support->reopen($event->refund()->id, 'Provider refused the refund'),
default => null,
};
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;
curl -s https://api.harbour.africa/v1/refunds/ref_01k5m0r3w9 \
<?php
$refund = Harbour::refunds()->retrieve('ref_…');
$refund->status; // requested | approved | processing | completed | failed | declined
$refund->amountKobo;
$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.