Skip to main content
POST
/
v1
/
ugwo
curl https://api.kwugwo.africa/v1/ugwo \
  -H "Authorization: Bearer $KWUGWO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500000,
    "currency": "NGN",
    "ref": "order_4719",
    "description": "Order #4719",
    "onye": "ony.VCvr.7K2qPmRtV9xLnQ8sD1cYwHfE",
    "metadata": { "order_id": "4719", "channel": "web" }
  }'

{
  "uid": "ugw.VCvr.7K2qPmRtV9xLnQ8sD1cYwHfE",
  "amount": 500000,
  "currency": "NGN",
  "status": "requires_ugwo",
  "ref": "order_4719",
  "description": "Order #4719",
  "metadata": { "order_id": "4719", "channel": "web" },
  "onye": {
    "uid": "ony.VCvr.7K2qPmRtV9xLnQ8sD1cYwHfE",
    "email": "ada@example.com",
    "first_name": "Ada",
    "last_name": "Okeke"
  },
  "checkout": null,
  "created_at": "2026-05-15T09:14:22+00:00"
}

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.

Creates a payment request (an ugwo) on the workspace that owns your secret key. The ugwo starts in the requires_ugwo status — running a charge activity against it moves it through the rest of its lifecycle.

​
Body parameters

​
amount
integer
required
Amount to charge, in the smallest currency unit (kobo for NGN, pesewas for GHS, cents for USD).
​
currency
string
required
ISO-4217 currency code. Must be a supported currency and must be enabled on at least one of your PSPs.
​
onye
string
ID of an existing customer (ony.…). When set, the ugwo is attached to that customer and the merchant dashboard groups it under their record.
​
ref
string
Your own reference (max 150 chars) — typically an order number or invoice ID. Echoed back on the ugwo and on webhook deliveries.
​
description
string
Human-readable description (max 150 chars) shown to the customer on the hosted checkout.
​
checkout
string
ID of a checkout (chk.…). When set, the ugwo uses that checkout’s routing rules instead of the workspace defaults.
​
metadata
object
Free-form { string: string } map for your own tagging. Stored verbatim and surfaced on the dashboard. Not shown to the customer.

​
Response

​
uid
string
The new ugwo’s ID (ugw.…). Persist this on your order.
​
amount
integer
Amount in smallest currency unit.
​
currency
string
ISO-4217 code.
​
status
string
Always requires_ugwo for a freshly created ugwo.
​
ref
string | null
Your reference, if you sent one.
​
description
string | null
Description, if you sent one.
​
metadata
object
Echoed metadata.
​
onye
object | null
The attached customer, if any (null otherwise).
​
checkout
object | null
The attached checkout, if any.
​
created_at
string
ISO-8601 timestamp.
curl https://api.kwugwo.africa/v1/ugwo \
  -H "Authorization: Bearer $KWUGWO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500000,
    "currency": "NGN",
    "ref": "order_4719",
    "description": "Order #4719",
    "onye": "ony.VCvr.7K2qPmRtV9xLnQ8sD1cYwHfE",
    "metadata": { "order_id": "4719", "channel": "web" }
  }'

{
  "uid": "ugw.VCvr.7K2qPmRtV9xLnQ8sD1cYwHfE",
  "amount": 500000,
  "currency": "NGN",
  "status": "requires_ugwo",
  "ref": "order_4719",
  "description": "Order #4719",
  "metadata": { "order_id": "4719", "channel": "web" },
  "onye": {
    "uid": "ony.VCvr.7K2qPmRtV9xLnQ8sD1cYwHfE",
    "email": "ada@example.com",
    "first_name": "Ada",
    "last_name": "Okeke"
  },
  "checkout": null,
  "created_at": "2026-05-15T09:14:22+00:00"
}