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; card and bank-transfer data never touch your origin, so you stay out of PCI scope.

Why use the embed

  • 5 lines of code. Init, open, done.
  • PCI scope stays at zero. Sensitive data never enters your page.
  • 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
Merchant public key (the one prefixed pk.). The matching secret key stays on your backend; the public key only lets the SDK fetch the ugwo from /checkout/v1.
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

Listen for the result

onSuccess fires with the activityUid. Trust your webhook (not the browser callback) as the source of truth for fulfilment. See Webhook deliveries for details.
4

Reconcile on your backend

Either poll GET /v1/ugwo/{uid} or wait for the ugwo.activity.updated webhook. Mark the order paid once the ugwo is ugwo_successful.