Skip to main content
This is the recommended way to integrate Kwugwo. Unless you have a strong reason to build your own checkout UI, embed ours; you’ll ship faster, stay out of PCI scope, and pick up every new payment medium we add the day it goes live, with no client-side changes.
@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).
The returned promise always resolves (never rejects) with one of:

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.