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

# List refunds

> Page through refunds on this workspace, filtered by payment, activity, or status.

Returns a [cursor-paginated](https://docs.kwugwo.africa/pagination.md) list of every refund on the
workspace that owns the secret key, **newest first**, including
refunds [created outside the API](https://docs.kwugwo.africa/refunds/overview.md#refunds-created-outside-the-api).

This is the endpoint to reach for when a create call timed out and
you're not sure whether the refund landed: filter by the activity and
look for your `ref`.

## Query parameters

**cursor** `string`

A `pagination.next_cursor` or `prev_cursor` from a previous page.

**limit** `integer` (default: 10)

Page size, between `1` and `100`.

**filters\[ugwo]** `string`

Only refunds against this ugwo, `ugw.XXXX.YYYY...`. Covers every
activity on the payment.

**filters\[ugwo\_activity]** `string`

Only refunds against this activity, `act.XXXX.YYYY...`.

**filters\[status]\[]** `string[]`

Repeat to match several. Accepts `pending`, `successful`, and
`failed`.

> [!WARNING]
>
> `processing` is **not** an accepted filter value even though
> refunds spend most of their life in it. Passing it returns
> `422` with `field: "filters[status]"`.
> To find in-flight refunds, fetch without a status filter
> and filter client-side.

> [!NOTE]
>
> Unknown keys inside `filters` are rejected rather than ignored, so a
> typo fails loudly with `422`.

## Response

**items** `Refund[]`

The page of refunds, each in the [Refund
object](https://docs.kwugwo.africa/refunds/object.md) shape.

**pagination** `object`

**pagination**

**next\_cursor** `string | null`

Pass back as `cursor` to fetch the next (older) page, or `null` on
the last page.

**prev\_cursor** `string | null`

Pass back as `cursor` to fetch the previous (newer) page, or
`null` on the first page.

```bash cURL theme={"system"}
curl -G https://api.kwugwo.africa/v1/refunds \
  -H "Authorization: Bearer $KWUGWO_SECRET_KEY" \
  --data-urlencode "limit=20" \
  --data-urlencode "filters[ugwo]=ugw.VCvr.7K2qPmRtV9xLnQ8sD1cYwHfE" \
  --data-urlencode "filters[status][]=successful" \
  --data-urlencode "filters[status][]=failed"
```

```js Node theme={"system"}
const params = new URLSearchParams({
  limit: "20",
  "filters[ugwo_activity]": activityUid,
});

const page = await fetch(`https://api.kwugwo.africa/v1/refunds?${params}`, {
  headers: { Authorization: `Bearer ${process.env.KWUGWO_SECRET_KEY}` },
}).then(r => r.json());

const alreadyRefunded = page.items.some(r => r.ref === `${orderId}_refund_1`);
```

```php PHP theme={"system"}
<?php
$query = http_build_query([
    'limit'   => 20,
    'filters' => ['ugwo_activity' => $activityUid],
]);

$ch = curl_init("https://api.kwugwo.africa/v1/refunds?{$query}");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('KWUGWO_SECRET_KEY')],
]);
$page = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```python Python theme={"system"}
import os, requests

page = requests.get(
    "https://api.kwugwo.africa/v1/refunds",
    headers={"Authorization": f"Bearer {os.environ['KWUGWO_SECRET_KEY']}"},
    params={
        "limit": 20,
        "filters[ugwo_activity]": activity_uid,
        "filters[status][]": ["successful", "failed"],
    },
).json()

for refund in page["items"]:
    print(refund["uid"], refund["status"], refund["amount"])
```

```go Go theme={"system"}
q := url.Values{}
q.Set("limit", "20")
q.Set("filters[ugwo_activity]", activityUid)

req, _ := http.NewRequest("GET", "https://api.kwugwo.africa/v1/refunds?"+q.Encode(), nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KWUGWO_SECRET_KEY"))

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
```

```json 200 OK theme={"system"}
{
  "items": [
    {
      "uid": "rfd.VCvr.Hs7dQmXk2LpRvN9tYbCwZaEf",
      "psp_external_ref": "3018284",
      "ref": "order_4719_refund_1",
      "reason": "Customer returned the notebook",
      "amount": 200000,
      "status": "successful",
      "error": null,
      "created_at": "2026-08-12T10:04:11+00:00",
      "updated_at": "2026-08-12T14:31:07+00:00",
      "ugwo": {
        "uid": "ugw.VCvr.7K2qPmRtV9xLnQ8sD1cYwHfE",
        "currency": "NGN"
      },
      "ugwo_activity": {
        "uid": "act.VCvr.qnbBJaElzSTHOcaTzxbuDlIs",
        "activity_type": "charge",
        "status": "partially_refunded",
        "psp": "paystack_ng",
        "psp_external_id": "5kfxw34ugz",
        "amount": 500000,
        "charged_amount": 500000,
        "refunded_amount": 200000,
        "error": null,
        "created_at": "2026-08-11T19:55:50+00:00",
        "updated_at": "2026-08-12T10:04:11+00:00"
      },
      "nzube_psp": null
    }
  ],
  "pagination": {
    "next_cursor": null,
    "prev_cursor": null
  }
}
```

```json 422 Validation Failed theme={"system"}
{
  "type": "validation.error",
  "title": "An error occurred",
  "status": 422,
  "detail": "One or more of the given values is invalid.",
  "message": "Validation failed",
  "errors": [
    { "field": "filters[status]", "message": "One or more of the given values is invalid." }
  ]
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.