# Refunds

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

Source: https://docs.borga.is/api/refunds

**The refund object**

- `id` (string): Prefixed `ref_`.
- `payment` (string): The refunded payment.
- `amount` (integer): - `currency` (string) <Param name="status" type="enum">`pending`, `succeeded` or `failed`.
- `reason` (string | null): Free text you supplied.
- `metadata` (object): - `created_at` (timestamp) - `updated_at` (timestamp) ## Create a refund `POST /v1/refunds` The payment must be `succeeded` or `processing`. The refundable balance is the amount minus previous and pending refunds. Send an `Idempotency-Key`. **Body** <Param name="payment" type="string" required>Payment to refund.
- `amount` (integer): Defaults to the full refundable balance.
- `reason` (string): Stored on the refund and shown in the dashboard.
- `metadata` (object):  ```ts Node.js // 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 ``` ```bash curl 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" }' ```  ```json title="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`](/errors/payment_not_refundable), [`amount_too_small`](/errors/amount_too_small), [`amount_too_large`](/errors/amount_too_large), [`card_payment_reverse_failed`](/errors/card_payment_reverse_failed), [`card_payment_reverse_uncertain`](/errors/card_payment_reverse_uncertain). ## Retrieve a refund `GET /v1/refunds/:id` ```bash curl https://api.borga.is/v1/refunds/ref_6Yz8Ab0Cd2Ef4Gh6Ij8Kl0Mn \ -H "Authorization: Bearer sk_test_…" ``` ## List refunds `GET /v1/refunds` Returns up to `limit` refunds, newest first, without a cursor. Filter by payment. **Query parameters** <Param name="payment" type="string">Only refunds of this payment.
- `limit` (integer, default 25): Up to 100.

```bash
curl "https://api.borga.is/v1/refunds?payment=pay_7Hs2Kq9LmW4xZc1Vb8Ny3Rt6" \
  -H "Authorization: Bearer sk_test_…"
```