Concepts

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: Ugwo IDs look like 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: Activity IDs look like 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

​

Supported currencies

The API will reject any other ISO-4217 code with 422. 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).

​

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. The banks and mobile money providers available to you are subject to the ones supported by the PSPs linked to your account:

• Paystack — see Payment channels.
• Flutterwave — see USSD.

​

USSD banks: Nigeria

​

Mobile money providers: Ghana (coming soon)