How Kwugwo works

The payment flow

What to take from it:

Your secret key never leaves your server. The browser only ever holds the ugwo uid and, for the embed, your public key.
The browser is not the source of truth. A customer can close the tab after paying, or tamper with a callback. Fulfil from the webhook plus a server-side GET. See Validate and fulfil.
Payment is asynchronous. Bank transfers and USSD complete when the customer acts, which may be minutes later.

Object	What it is	You create it with
Ugwo	The amount you want to collect for one order.	`POST /v1/ugwo`
Activity	One attempt to collect the ugwo through one medium. Retry with a new activity if one fails.	`POST /v1/ugwo/{uid}/activities`, or the embed
Next action	What the customer must do to complete an activity.	Kwugwo, automatically
Refund	Money returned from a successful activity.	`POST /v1/refunds`
Onye	A customer record. Optional.	`POST /v1/onye`, or implicitly via `onye_email`
Checkout	Which mediums to offer and how to route them to PSPs.	Dashboard

Several attempts can be open at once. A customer who starts a bank transfer can switch to USSD; just create another activity. The first one to succeed pays the ugwo. If a later one also succeeds, it is flagged as a double charge and the ugwo is not changed. Once the ugwo is paid or cancelled, new activities are rejected with 409.
A failed attempt doesn’t close the ugwo. It returns to requires_ugwo and you can try again, with any medium.
Underpayment keeps it open. If a PSP reports collecting less than the ugwo’s amount, the ugwo goes back to requires_ugwo and total_amount_paid records what was received so far.

Full status tables live on each object page: Ugwo, Activity, Next action, Refund.