@kwugwo/checkout is the official browser SDK for embedding the
Kwugwo checkout. It opens a hosted overlay on your page, listens for
the result via postMessage, and fires your callbacks. No React, no
framework, ~5 KB gzipped.
The merchant’s backend creates an ugwo and returns
its uid to the frontend. The SDK takes it from there: the customer’s
bank details and one-time codes never touch your site.
Why use the embed
- 5 lines of code. Init, open, done.
- No sensitive data on your page. Account numbers, PINs and OTPs are entered in Kwugwo’s overlay.
- All mediums, no extra work. New payment methods we add show up in your checkout automatically; you don’t have to ship anything.
- Mobile-friendly out of the box. Desktop modal, full-screen on mobile, backdrop + Escape to close, body-scroll lock while open.
- Tiny. ~5 KB gzipped, no framework, no peer deps.
Install
Framework SDKs are coming soon: first-party packages for
React, Vue, and Angular are on the roadmap. Until they
ship, use
@kwugwo/checkout directly from inside your
component: call KwugwoCheckout.init(...) once on mount and
instance.open(...) from your event handler. The vanilla SDK
works the same in every framework.Usage
API reference
KwugwoCheckout.init(options)
Returns a KwugwoCheckoutInstance.
string
required
Your public key (
pk.…), from the same environment as the secret key
that created the ugwo. It can only read that ugwo and start payments
on it, so it is safe in the browser.string
default:"https://checkout.kwugwo.africa"
Override the hosted-checkout origin. Useful for staging.
instance.open(options) → Promise<CheckoutResult>
string
required
Ugwo ID (
ugw.XXXX.YYYY...) returned from your backend after a
Create an ugwo call.string
If set, the parent window navigates here after a successful
payment. Promise still resolves first so
onSuccess can run any
cleanup.(result) => void | Promise<void>
Fires on successful payment. The promise is awaited before
redirecting to
returnUrl.() => void
Fires when the user dismisses the modal without completing payment.
(err) => void
Fires when the checkout cannot complete (invalid session, expired,
network, etc).
instance.close()
Programmatically dismiss the overlay (fires onClose).
Browser support
ES2020 targets: Chrome 80+, Edge 80+, Firefox 74+, Safari 13.1+. No polyfills needed for modern browsers; if you support older targets, bundle through your existing toolchain.End-to-end flow
1
Create the ugwo on your backend
Call
POST /v1/ugwo with your secret key. Return
the resulting uid to your frontend.2
Open the overlay
Pass that
uid to checkout.open({ ugwoUid }). The SDK
authenticates the iframe with your public key.3
Update the screen
onSuccess fires with the activityUid. Show “Payment received,
confirming your order…”. Don’t fulfil from the browser: callbacks
can be skipped or forged.4
Fulfil from your backend
On the
ugwo.successful webhook, re-fetch GET /v1/ugwo/{uid}
and check it against the order. See Validate and fulfil.