> ## Documentation Index
> Fetch the complete documentation index at: https://docs.borga.is/llms.txt
> Use this file to discover all available pages before exploring further.

# Refunds API — full and partial payment refunds

> Issue full or partial refunds against a payment with POST /v1/refunds, then list or retrieve refunds to track their status and amounts.

A refund returns funds to the customer for a completed payment. Omit `amount` to refund the full payment amount, or pass a specific value to issue a partial refund. Multiple partial refunds can be issued against the same payment until the fully refunded amount equals the original charge.

**Status values**

| Value       | Description                                                    |
| ----------- | -------------------------------------------------------------- |
| `pending`   | Refund has been submitted and is being processed.              |
| `succeeded` | Funds have been returned to the customer.                      |
| `failed`    | Refund could not be processed. Contact support if this occurs. |

***

## Create a refund

`POST /v1/refunds`

Issues a refund against an existing payment. The payment must have a status of `succeeded` or `partially_refunded`.

### Request parameters

<ParamField body="payment" type="string" required>
  ID of the payment to refund (e.g. `pay_xxx`).
</ParamField>

<ParamField body="amount" type="number">
  Amount to refund in whole ISK kronur. Minimum value is `1`. Omit to refund the full remaining amount of the payment.
</ParamField>

<ParamField body="reason" type="string">
  Reason for the refund. Stored on the refund object and visible in the dashboard.
</ParamField>

<ParamField body="metadata" type="object">
  Set of key-value pairs to attach to the refund. Values must be strings.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.borga.is/v1/refunds \
    --header "Authorization: Bearer sk_live_..." \
    --header "X-Merchant-Id: mer_xxx" \
    --header "Content-Type: application/json" \
    --data '{
      "payment": "pay_01hx9z3k2mfq7nbvd4cw8ej5rt",
      "amount": 1990,
      "reason": "Customer request",
      "metadata": {
        "support_ticket": "tkt_8821"
      }
    }'
  ```
</RequestExample>

### Response fields

<ResponseField name="id" type="string" required>
  Unique identifier for the refund (e.g. `ref_xxx`).
</ResponseField>

<ResponseField name="payment" type="string" required>
  ID of the payment that was refunded.
</ResponseField>

<ResponseField name="amount" type="number" required>
  Amount refunded in whole ISK kronur.
</ResponseField>

<ResponseField name="currency" type="string" required>
  Three-letter ISO 4217 currency code, inherited from the payment.
</ResponseField>

<ResponseField name="status" type="string" required>
  Current refund status. One of `pending`, `succeeded`, `failed`.
</ResponseField>

<ResponseField name="reason" type="string">
  Reason provided at creation.
</ResponseField>

<ResponseField name="metadata" type="object">
  Key-value pairs attached to the refund.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  ISO 8601 timestamp of when the refund was created.
</ResponseField>

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": "ref_01hxa4p7qwrs3nt5vjb8ck2mde",
    "payment": "pay_01hx9z3k2mfq7nbvd4cw8ej5rt",
    "amount": 1990,
    "currency": "ISK",
    "status": "pending",
    "reason": "Customer request",
    "metadata": {
      "support_ticket": "tkt_8821"
    },
    "created_at": "2026-04-29T12:00:00Z"
  }
  ```
</ResponseExample>

***

## List refunds

`GET /v1/refunds`

Returns a paginated list of refunds, ordered by creation date descending.

### Query parameters

<ParamField query="payment" type="string">
  Filter refunds by payment ID. Use this to retrieve all refunds for a specific payment.
</ParamField>

<ParamField query="limit" type="number">
  Maximum number of refunds to return per page.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url "https://api.borga.is/v1/refunds?payment=pay_01hx9z3k2mfq7nbvd4cw8ej5rt&limit=10" \
    --header "Authorization: Bearer sk_live_..." \
    --header "X-Merchant-Id: mer_xxx"
  ```
</RequestExample>

### Response fields

<ResponseField name="data" type="object[]" required>
  Array of refund objects.

  <Expandable title="refund fields">
    <ResponseField name="id" type="string" required>
      Unique refund identifier.
    </ResponseField>

    <ResponseField name="payment" type="string" required>
      ID of the refunded payment.
    </ResponseField>

    <ResponseField name="amount" type="number" required>
      Refunded amount in whole ISK kronur.
    </ResponseField>

    <ResponseField name="currency" type="string" required>
      Three-letter ISO 4217 currency code.
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Refund status: `pending`, `succeeded`, or `failed`.
    </ResponseField>

    <ResponseField name="reason" type="string">
      Reason for the refund.
    </ResponseField>

    <ResponseField name="metadata" type="object">
      Key-value pairs attached to the refund.
    </ResponseField>

    <ResponseField name="created_at" type="string" required>
      ISO 8601 creation timestamp.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="has_more" type="boolean" required>
  Whether more refunds exist beyond this page.
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "id": "ref_01hxa4p7qwrs3nt5vjb8ck2mde",
        "payment": "pay_01hx9z3k2mfq7nbvd4cw8ej5rt",
        "amount": 1990,
        "currency": "ISK",
        "status": "succeeded",
        "reason": "Customer request",
        "metadata": {},
        "created_at": "2026-04-29T12:00:00Z"
      }
    ],
    "has_more": false
  }
  ```
</ResponseExample>

***

## Retrieve a refund

`GET /v1/refunds/{id}`

Retrieves the details of an existing refund.

### Path parameters

<ParamField path="id" type="string" required>
  The ID of the refund to retrieve.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.borga.is/v1/refunds/ref_01hxa4p7qwrs3nt5vjb8ck2mde \
    --header "Authorization: Bearer sk_live_..." \
    --header "X-Merchant-Id: mer_xxx"
  ```
</RequestExample>

### Response fields

<ResponseField name="id" type="string" required>
  Unique refund identifier.
</ResponseField>

<ResponseField name="payment" type="string" required>
  ID of the refunded payment.
</ResponseField>

<ResponseField name="amount" type="number" required>
  Refunded amount in whole ISK kronur.
</ResponseField>

<ResponseField name="currency" type="string" required>
  Three-letter ISO 4217 currency code.
</ResponseField>

<ResponseField name="status" type="string" required>
  Current refund status. One of `pending`, `succeeded`, `failed`.
</ResponseField>

<ResponseField name="reason" type="string">
  Reason for the refund.
</ResponseField>

<ResponseField name="metadata" type="object">
  Key-value pairs attached to the refund.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  ISO 8601 timestamp of when the refund was created.
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "ref_01hxa4p7qwrs3nt5vjb8ck2mde",
    "payment": "pay_01hx9z3k2mfq7nbvd4cw8ej5rt",
    "amount": 1990,
    "currency": "ISK",
    "status": "succeeded",
    "reason": "Customer request",
    "metadata": {
      "support_ticket": "tkt_8821"
    },
    "created_at": "2026-04-29T12:00:00Z"
  }
  ```
</ResponseExample>