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 nonzube_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 likeony.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:
Ugwo IDs look like
ugw.XXXX.YYYYYYYYYYYYYYYYYYYYYYYY. Full reference:
The Ugwo object.
Activity: how an ugwo gets charged
An activity is one attempt to act on an ugwo. The supported type today ischarge, which sends the ugwo to a PSP via a specific
medium (bank_transfer, ussd, pay_with_bank, or mobile_money).
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:
Two amount fields on the activity matter once refunds are in play:
charged_amount (what the PSP reports it actually collected, which
can differ from the requested amount) and refunded_amount (how much
of it is committed to refunds).
Activity IDs look like act.XXXX.YYYYYYYYYYYYYYYYYYYYYYYY. Full
reference: The Activity object.
Next action: what the customer must do
When an activity lands inrequires_action, Kwugwo attaches a
next action. It is its own addressable object rather than a blob on the
activity. It has an ID (uac.XXXX.YYYY...), a status of its own, and
an optional expiry:
actionis the instruction itself.typeisuser_action(show these details to the customer),open_url(send the customer to this URL), or one ofinput_otp,input_pin,input_bvn,input_birthday(collect a value and submit it).statusispendingwhile the customer still has to act,fulfilledonce the activity succeeds,expiredonce it can no longer be completed.
Refund: money going back
A refund returns money to the payer. It hangs off the activity that collected the money, not off the ugwo. Only the attempt that actually succeeded holds funds to return.
Refunds can be partial, and an activity can have several of them
until the collected amount is exhausted. Creating one immediately
raises the activity’s
refunded_amount (and rolls it back if the
refund fails), which is what moves the ugwo to partially_refunded
or refunded.
Refund IDs look like rfd.XXXX.YYYYYYYYYYYYYYYYYYYYYYYY. See
Refunds for the full picture.
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 likechk.XXXX.YYYYYYYYYYYYYYYYYYYYYYYY.
PSP: a Payment Service Provider
A PSP is the underlying payment processor 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 with422.
Amounts are always in the smallest currency unit (kobo for NGN).
Available mediums by country
Whether a medium is actually charge-able for a given ugwo also
depends on which PSPs you have configured and on the routing rules of
the checkout (if any).
Pay with Bank
pay_with_bank charges a customer’s bank or wallet account directly.
Instead of a transfer or a USSD string, the customer is sent to their
provider to approve the debit, so the activity’s next_action is an
open_url rather than a
set of instructions.
It needs three things when you create the
activity: the provider (bank code), the
customer’s 10-digit account_number, and an
account_name_fragment, part of the account holder’s name (all inside
data.medium_params). Kwugwo resolves the account and, when the
fragment fairly matches the bank’s name for it, shows the customer the
full name so they can confirm it’s their account. A mismatch doesn’t
stop the charge; the name just isn’t shown.
Banks and mobile money providers
For mediums that need a provider (USSD bank, pay-with-bank account, mobile-money wallet), Kwugwo identifies each one with a short text code rather than a numeric code. Pass it asprovider inside the
activity’s data when you create an
activity.
The banks available to you are subject to the ones supported by the
PSPs linked to your account:
Check your PSP’s own documentation for the banks it supports per
medium, or call Get medium providers
for the live list on a checkout.
Bank codes: Nigeria
The same codes are used forussd and pay_with_bank.
Coverage differs by medium and by provider, and changes as
providers are onboarded. Resolve the live list per checkout with
Get medium providers rather than
hard-coding one.