Docs
API reference/Payments

Refunds

Return all or part of a card payment. Refunds create credit notes in your accounting system.

The refund object

idstring
Prefixed ref_.
paymentstring
The refunded payment.
amountinteger
currencystring
statusenum
pending, succeeded or failed.
reasonstring | null
Free text you supplied.
metadataobject
created_attimestamp
updated_attimestamp

Create a refund

POST/v1/refundsSecret key

The payment must be succeeded or processing. The refundable balance is the amount minus previous and pending refunds. Send an Idempotency-Key.

Body

paymentstringrequired
Payment to refund.
amountinteger
Defaults to the full refundable balance.
reasonstring
Stored on the refund and shown in the dashboard.
metadataobject
Node.jsts
// Partial refund. Omit `amount` to refund everything that is left.
const refund = await borga.refunds.create(
  {
    payment: "pay_7Hs2Kq9LmW4xZc1Vb8Ny3Rt6",
    amount: 990,
    reason: "Returned one item",
    metadata: { ticket: "support_1729" },
  },
  { idempotencyKey: "refund_support_1729" },
);

console.log(refund.status); // "pending" until payment.refunded arrives
Response
{
  "id": "ref_6Yz8Ab0Cd2Ef4Gh6Ij8Kl0Mn",
  "payment": "pay_7Hs2Kq9LmW4xZc1Vb8Ny3Rt6",
  "amount": 990,
  "currency": "ISK",
  "status": "pending",
  "reason": "Returned one item",
  "metadata": { "ticket": "support_1729" },
  "created_at": "2026-09-08T09:12:00.000Z",
  "updated_at": "2026-09-08T09:12:00.000Z"
}

Errors: payment_not_refundable, amount_too_small, amount_too_large, card_payment_reverse_failed, card_payment_reverse_uncertain.

Retrieve a refund

GET/v1/refunds/:idSecret key
curl https://api.borga.is/v1/refunds/ref_6Yz8Ab0Cd2Ef4Gh6Ij8Kl0Mn \
  -H "Authorization: Bearer sk_test_…"

List refunds

GET/v1/refundsSecret key

Returns up to limit refunds, newest first, without a cursor. Filter by payment.

Query parameters

paymentstring
Only refunds of this payment.
limitintegerdefault: 25
Up to 100.
curl "https://api.borga.is/v1/refunds?payment=pay_7Hs2Kq9LmW4xZc1Vb8Ny3Rt6" \
  -H "Authorization: Bearer sk_test_…"