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 API is organised around a handful of resources. Understanding how
they relate is the fastest way to model your integration.
Resources
Nzube — your workspace
A nzube is your merchant account. Every API key is scoped to a
single nzube. All other resources — customers, checkouts, payments —
belong to one nzube.
You create and manage nzubes from the dashboard. The merchant API
operates on the nzube that owns the secret key you authenticate with;
there is no nzube_id in any /v1/* URL.
Onye — a customer
An onye is one of your customers. You can store an email, a
human-readable reference, a name, a billing address, and arbitrary
string metadata. Onyes are optional on a payment — you can charge a
one-off ugwo without one — but creating them lets you keep a tidy
customer ledger and re-use the same payer across many payments.
Onye IDs look like ony.XXXX.YYYYYYYYYYYYYYYYYYYYYYYY.
Ugwo — a payment request
An ugwo is a single payment request. You set the amount and
currency when you create it. It then moves through statuses as
activities run against it:
| Status | Meaning |
|---|
requires_ugwo | Created but no activity has charged it yet. Only ugwos in this state can be cancelled. |
processing | An activity is in-flight at the PSP. |
ugwo_successful | Successfully paid. |
partially_refunded | Refunded in part. |
refunded | Fully refunded. |
cancelled | Cancelled before payment completed. Terminal. |
ugw.XXXX.YYYYYYYYYYYYYYYYYYYYYYYY.
Activity — how an ugwo gets charged
An activity is one attempt to act on an ugwo. The supported type
today is charge, which sends the ugwo to a PSP via a specific
medium (bank_transfer, mobile_money, or ussd).
A single ugwo can have many activities — for example, one bank
transfer attempt that the customer abandoned, followed by a
successful USSD charge. Activities have their own lifecycle:
| Status | Meaning |
|---|
pending | Just created. |
processing | Sent to the PSP. |
requires_action | Waiting on the customer (e.g. transfer to a virtual account, dial a USSD code). The next_action block tells the customer what to do. |
successful | Customer paid. |
failed | PSP rejected or the customer abandoned. |
act.XXXX.YYYYYYYYYYYYYYYYYYYYYYYY.
Checkout — a hosted payment surface
A checkout is a configuration you build in the dashboard that
describes which mediums to offer for which currency, and which PSPs
each medium should route to. When you create an ugwo, you can attach
it to a checkout to override the workspace’s default routing rules.
Checkout IDs look like chk.XXXX.YYYYYYYYYYYYYYYYYYYYYYYY.
PSP — a Payment Service Provider
A PSP is the underlying payment processor (e.g. Paystack) that
actually moves the money. You configure PSPs and the credentials
they need from the dashboard. The merchant API does not expose PSP
management — it only references PSPs indirectly through checkouts
and through the activities it routes to them.
Countries and currencies
Kwugwo currently supports Nigeria only. Ghana is coming
soon. Other African countries will follow.
Supported currencies
The API will reject any other ISO-4217 code with 422.
| Code | Currency | Min amount | Max amount |
|---|
NGN | Nigerian Naira | 20000 (₦200.00) | 5000000000 (₦50,000,000.00) |
config/services.yaml
under app.currencies_limits.
Available mediums by country
| Medium | NG (live) | GH (soon) |
|---|
bank_transfer | ✅ | — |
ussd | ✅ | ✅ |
mobile_money | — | ✅ |
Banks and mobile money providers
For mediums that need a provider (USSD bank, mobile-money wallet),
Kwugwo identifies each one with a short text code rather than a
numeric code. Pass these as provider (or bank) inside
medium_params when you create an activity.
USSD banks — Nigeria
| Code | Bank |
|---|
gtb | Guaranty Trust Bank |
More Nigerian banks are being onboarded — the codes above reflect
what’s live in the API today. If you need a bank that isn’t
listed, the activity will return a validation error.
Mobile money providers — Ghana (coming soon)
| Code | Provider |
|---|
mtn | MTN Mobile Money |
airtel_tigo | AirtelTigo Money |
telecel | Telecel Cash |
