The Ugwo object

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. Create one per order, store its uid, and fulfil the order when its status is ugwo_successful.

Attributes

string

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

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.

object | null

The customer this payment belongs to, as a Customer object.

integer

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

string

ISO-4217 currency code, e.g. NGN. See supported currencies.

enum

Where the payment is in its lifecycle. One of requires_ugwo, processing, ugwo_successful, partially_refunded, refunded, cancelled. See Status.

string | null

Text shown to the customer on the hosted checkout.

string

ISO-8601 timestamp.

string

ISO-8601 timestamp.

object | null

The checkout 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.

Show properties

string

Checkout ID, chk.….

string

ISO-4217 code.

object[]

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

object | null

The most recent activity on this ugwo. Returned by Get an ugwo and in webhooks; omitted from create, list and cancel responses. null if no activity has run.

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 does use the correct spelling).

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.

integer

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

object

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

The Ugwo object

{
  "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.
`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.
`partially_refunded`	Paid, then partly refunded.	n/a
`refunded`	Paid, then fully refunded.	n/a
`cancelled`	Cancelled before payment. Terminal.	n/a

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. The ugwo itself does not change; refund the extra activity.

Get started

Plugins

Guides

Concepts

API basics

Payments (Ugwo)

Activities

Next actions

Refunds

Customers (Onye)

Checkouts

Attributes

Status

​Attributes

​Status

Attributes

Status