> ## 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.

# The Refund object

> Money returned to a payer from a successful activity.

A **refund** returns all or part of a successful
[activity](https://docs.kwugwo.africa/ugwo/activity-object.md) to the payer. See
[Refunds](https://docs.kwugwo.africa/refunds/overview.md) for how they affect the payment.

## Attributes

**uid** `string`

Unique identifier, `rfd.XXXX.YYYYYYYYYYYYYYYYYYYYYYYY`. Every refund
webhook identifies itself with this.

**ugwo\_activity** `object`

The refunded [Activity object](https://docs.kwugwo.africa/ugwo/activity-object.md), already
updated. Its `charged_amount` and `refunded_amount` show how much is
left to refund.

**psp\_external\_ref** `string | null`

The PSP's own refund ID, for support tickets with them. `null` until
the PSP issues one.

**ref** `string | null`

Your reference, unique per workspace. `null` for refunds [created
outside the API](https://docs.kwugwo.africa/refunds/overview.md#refunds-created-outside-the-api).

**reason** `string | null`

Your reason; also sent to the PSP as the merchant note.

**amount** `integer`

Amount refunded, in the smallest currency unit.

**status** `enum`

`pending`, `processing`, `successful`, `failed` or `cancelled`. See
[Status](#status).

**error** `object | null`

Set when `status` is `failed`.

**properties**

**code** `enum`

`psp_error` (the PSP refused) or `system_error` (Kwugwo could not
complete the request with the PSP).

**message** `string | null`

Detail: the PSP's wording, or a message key such as
`nzube.psp.paystack.error.missing_destination`.

**created\_at** `string`

ISO-8601 timestamp.

**updated\_at** `string`

ISO-8601 timestamp.

**ugwo** `object`

The payment this refund belongs to: `{ "uid": "ugw.…", "currency": "NGN" }`.

**nzube\_psp** `string | null`

The PSP connection the refund went through, `psp.…`, **only when it
differs** from the one that took the payment (because you passed
`nzube_psp` on create). `null` in the usual case, where the refund goes
back through the original connection.

```json The Refund object theme={"system"}
{
  "uid": "rfd.VCvr.Hs7dQmXk2LpRvN9tYbCwZaEf",
  "ugwo_activity": {
    "uid": "act.VCvr.qnbBJaElzSTHOcaTzxbuDlIs",
    "activity_type": "charge",
    "psp": "paystack_ng",
    "psp_external_id": "5kfxw34ugz",
    "status": "partially_refunded",
    "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",
    "...": "see The Activity object"
  },
  "psp_external_ref": "3018284",
  "ref": "order_4719_refund_1",
  "reason": "Customer returned the notebook",
  "amount": 200000,
  "status": "processing",
  "error": null,
  "created_at": "2026-08-12T10:04:11+00:00",
  "updated_at": "2026-08-12T10:04:12+00:00",
  "ugwo": {
    "uid": "ugw.VCvr.7K2qPmRtV9xLnQ8sD1cYwHfE",
    "currency": "NGN"
  },
  "nzube_psp": null
}
```

> [!NOTE]
>
> `meta` and `destination` that you send on create are stored with the
> refund but not returned by the API.

## Status

| Status | Meaning | Terminal |
| - | - | - |
| `pending` | Recorded, not yet sent to the PSP. Rarely seen. | No |
| `processing` | Accepted by the PSP and in flight. Can take hours or days. | No |
| `successful` | The money has gone back to the payer. | Yes |
| `failed` | Rejected. `error` says why, and the activity's `refunded_amount` is released. | Yes |
| `cancelled` | Withdrawn before completion. Rare. | Yes |


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