> ## 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 Ugwo object

> A payment: the amount you want to collect for one order.

An **ugwo** is a request to collect a fixed amount from a customer. It
does not move money by itself; each attempt to collect it is an
[activity](https://docs.kwugwo.africa/ugwo/activity-object.md). Create one per order, store its
`uid`, and fulfil the order when its `status` is `ugwo_successful`.

## Attributes

**uid** `string`

Unique identifier, `ugw.XXXX.YYYYYYYYYYYYYYYYYYYYYYYY`. Store it on
your order.

**ref** `string | null`

Your own reference, e.g. an order number. **Unique per workspace** and
case-sensitive. Use it to match webhooks to orders and as an
[idempotency key](https://docs.kwugwo.africa/errors.md#retries-and-idempotency).

**onye\_nzube** `object | null`

The customer this payment belongs to, as a [Customer
object](https://docs.kwugwo.africa/customers/object.md).

**amount** `integer`

Amount to collect, in the smallest currency unit (kobo for `NGN`):
`500000` is ₦5,000.00.

**currency** `string`

ISO-4217 currency code, e.g. `NGN`. See [supported
currencies](https://docs.kwugwo.africa/concepts.md#supported-currencies).

**status** `enum`

Where the payment is in its lifecycle. One of `requires_ugwo`,
`processing`, `ugwo_successful`, `partially_refunded`, `refunded`,
`cancelled`. See [Status](#status).

**description** `string | null`

Text shown to the customer on the hosted checkout.

**created\_at** `string`

ISO-8601 timestamp.

**updated\_at** `string`

ISO-8601 timestamp.

**checkout** `object | null`

The [checkout](https://docs.kwugwo.africa/checkouts/object.md) this payment is routed through:
either the one you passed on create, or the one your workspace's
routing rules picked. `null` if none could be resolved, in which case
the ugwo cannot be charged.

**properties**

**uid** `string`

Checkout ID, `chk.…`.

**currency** `string`

ISO-4217 code.

**mediums** `object[]`

Mediums enabled on the checkout, in display order. Each item is
`{ "medium": "bank_transfer" }`.

**lastest\_ugwo\_activity** `object | null`

The most recent [activity](https://docs.kwugwo.africa/ugwo/activity-object.md) on this ugwo.
Returned by [Get an ugwo](https://docs.kwugwo.africa/ugwo/get.md) and in webhooks; omitted from
create, list and cancel responses. `null` if no activity has run.

> [!WARNING]
>
> **The field name is spelled `lastest_ugwo_activity`** (with an
> extra `t`). This is a known quirk of the API. Read exactly this
> key; `latest_ugwo_activity` does not exist on an ugwo (the
> [customer object](https://docs.kwugwo.africa/customers/object.md) does use the correct
> spelling).

**total\_amount\_paid** `integer`

Total collected so far across successful activities, in the smallest
currency unit. Equals `amount` once fully paid. Useful for spotting
underpayment while `status` is still `requires_ugwo`.

**fee** `integer`

Kwugwo fee on this payment, in the smallest currency unit. Currently
always `0`.

**meta** `object`

The `{ "key": "value" }` metadata you set on create. Never shown to
the customer. `{}` when there is none.

```json The Ugwo object theme={"system"}
{
  "uid": "ugw.VCvr.7K2qPmRtV9xLnQ8sD1cYwHfE",
  "ref": "order_4719",
  "onye_nzube": {
    "uid": "ony.VCvr.Qm3kTn8XcBd5RyWkJhZsAuLp",
    "email": "ada@example.com",
    "first_name": "Ada",
    "last_name": "Okeke",
    "nzube_ref": "user_8821",
    "billing_address": null,
    "created_at": "2026-05-10T08:00:00+00:00",
    "updated_at": "2026-05-10T08:00:00+00:00",
    "meta": {},
    "total_successful_activities": 3,
    "total_failed_activities": 0,
    "latest_ugwo_activity": "act.VCvr.X9yLp2KmRtV7nQ8sD4cYwHfE"
  },
  "amount": 500000,
  "currency": "NGN",
  "status": "ugwo_successful",
  "description": "Order #4719",
  "created_at": "2026-05-15T09:14:22+00:00",
  "updated_at": "2026-05-15T09:21:40+00:00",
  "checkout": {
    "uid": "chk.VCvr.vBtGwathtd99FpQGIGwIAATX",
    "currency": "NGN",
    "mediums": [
      { "medium": "bank_transfer" },
      { "medium": "ussd" },
      { "medium": "pay_with_bank" }
    ]
  },
  "lastest_ugwo_activity": {
    "uid": "act.VCvr.qnbBJaElzSTHOcaTzxbuDlIs",
    "activity_type": "charge",
    "status": "successful",
    "amount": 500000,
    "charged_amount": 500000,
    "refunded_amount": 0,
    "...": "see The Activity object"
  },
  "total_amount_paid": 500000,
  "fee": 0,
  "meta": { "order_id": "4719", "channel": "web" }
}
```

## Status

| Status | Meaning | What you do |
| - | - | - |
| `requires_ugwo` | Not paid yet: no attempt has started, or the latest one is still being sent to the PSP, failed, expired, or was underpaid. | Start an activity, or let the customer retry in the checkout. Can be [cancelled](https://docs.kwugwo.africa/ugwo/cancel.md). |
| `processing` | The latest attempt is waiting on the customer (`requires_action`). | Wait for the webhook. You can still start another attempt, e.g. if the customer switches medium. |
| `ugwo_successful` | Paid in full. | [Validate and fulfil](https://docs.kwugwo.africa/guides/validate-and-fulfil.md). |
| `partially_refunded` | Paid, then partly [refunded](https://docs.kwugwo.africa/refunds/overview.md). | n/a |
| `refunded` | Paid, then fully refunded. | n/a |
| `cancelled` | Cancelled before payment. Terminal. | n/a |

> [!NOTE]
>
> Several attempts can be open at once, and a customer can still pay
> into an old bank-transfer account after the ugwo is already
> `ugwo_successful`. Only the first successful attempt pays the ugwo. Kwugwo records that as a separate
> activity with `is_double_charge: true` and sends
> [`ugwo.activity.double_charge_detected`](https://docs.kwugwo.africa/webhook-events#double-charge-detected).
> The ugwo itself does not change; refund the extra activity.


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