Refunds

Refund all or part of a payment, and let Borga issue the matching credit note in your accounting system.

A refund returns money to the payer's card. Refunds are their own object (ref_…) so a payment can have several partial refunds over time. Bank-invoice payments cannot be refunded through Borga; issue a credit note in your accounting system and pay the customer back directly.

Create a refund

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

curlbash

curl https://api.borga.is/v1/refunds \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: refund_support_1729" \
  -d '{
    "payment": "pay_7Hs2Kq9LmW4xZc1Vb8Ny3Rt6",
    "amount": 990,
    "reason": "Returned one item"
  }'

Omit amount to refund the full remaining balance. The refundable balance is the payment's amount minus refunded_amount minus any refunds still pending, so two concurrent partial refunds cannot exceed the payment. Only payments in status succeeded or processing can be refunded. While a payment is still processing only a refund of the whole amount is possible; partial refunds wait until it is succeeded.

Always send an Idempotency-Key with refunds. A retried request with the same key returns the original refund instead of creating a second one; see Idempotency.

Statuses

Status	Meaning
`pending`	Accepted by the processor, awaiting confirmation. `refund.created` fired.
`succeeded`	Confirmed. The payment's `refunded_amount` has increased and `payment.refunded` fired. When fully refunded, the payment's status becomes `refunded`.
`failed`	The processor rejected the refund. Nothing was returned.

Confirmation usually arrives within seconds. The money reaches the payer's card in a few business days depending on their bank.

A refund requested moments after the charge can be refused with card_payment_reverse_failed because the processor does not have the payment on record yet. Wait a few minutes and create the refund again.

Credit notes

If the original payment was booked as an invoice in PayDay or DK+, a succeeded refund creates a credit note there for the refunded amount and Borga records it as a CreditNote object (cn_…) with credit_note.created. Your books therefore show the sale and the reversal without manual work. PayDay can only credit a whole invoice, which it does by cancelling it, so for a partial refund the credit note is recorded as failed with a message and you issue it in PayDay yourself. See Invoicing.

Errors

Code	Meaning
`payment_not_refundable`	The payment is not `succeeded` or `processing`, or it is `processing` and the refund is for less than the whole amount.
`amount_too_large`	More than the refundable balance.
`card_payment_reverse_failed`	The processor refused. The refund is recorded as `failed`.
`card_payment_reverse_uncertain`	The processor did not answer. The refund stays `pending`; check its status before retrying.

Fees

The fee on the original payment is not returned. There is no fee on the refund itself.