The Refund object

A refund returns all or part of a successful activity to the payer. See Refunds for how they affect the payment.

Attributes

string

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

object

The refunded Activity object, already updated. Its charged_amount and refunded_amount show how much is left to refund.

string | null

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

string | null

Your reference, unique per workspace. null for refunds created outside the API.

string | null

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

integer

Amount refunded, in the smallest currency unit.

enum

pending, processing, successful, failed or cancelled. See Status.

object | null

Set when status is failed.

Show properties

enum

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

string | null

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

string

ISO-8601 timestamp.

string

ISO-8601 timestamp.

object

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

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.

The Refund object

{
  "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
}

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

Get started

Plugins

Guides

Concepts

API basics

Payments (Ugwo)

Activities

Next actions

Refunds

Customers (Onye)

Checkouts

Attributes

Status

​Attributes

​Status

Attributes

Status