Skip to main content
The merchant API uses bearer token authentication. Send your secret key in the Authorization header on every request: 
Authorization: Bearer sk.VCvr.1MsEBjzxlrfJdomgQlVgSlbZzFMjyQXCjnxayf6JnP6EsQEUcRgFPimPbtsP9nokwwpWmOeoweezF0Ja

export KWUGWO_SECRET_KEY=sk.VCvr.1MsEBjzxlrfJdomgQlVgSlbZzFMjyQXCjnxayf6JnP6EsQEUcRgFPimPbtsP9nokwwpWmOeoweezF0Ja

curl https://api.kwugwo.africa/v1/ugwo \
  -H "Authorization: Bearer $KWUGWO_SECRET_KEY"

​
Where to get your key

Sign in to the dashboard, open the workspace you want to integrate, and generate a key from the API Keys screen. Each workspace has one active secret key at a time; regenerating rotates the value and invalidates the previous one immediately.

​
Environments

Keys are scoped to a single environment. The same physical workspace exists separately in sandbox and live, each with its own keys:
EnvironmentBase URLKey prefix
Sandboxhttps://sandbox-api.kwugwo.africaIssued from the sandbox dashboard; use against the sandbox base URL only.
Livehttps://api.kwugwo.africaIssued from the live dashboard; use against the live base URL only.
A sandbox key sent to api.kwugwo.africa (or a live key sent to sandbox-api.kwugwo.africa) returns 401 Unauthorized. There is no shared key tier.

​
Two key types

Each workspace exposes two keys with different scopes:
KeyPrefixUsed byScope
Secret keysk.…Your backendFull read/write on /v1/*. Never expose this to a browser.
Public keypk.…Your customer’s browser (e.g. the checkout embed)Read an ugwo and post charges to it from a hosted checkout.
Sample values look like: 
sk.VCvr.1MsEBjzxlrfJdomgQlVgSlbZzFMjyQXCjnxayf6JnP6EsQEUcRgFPimPbtsP9nokwwpWmOeoweezF0Ja
pk.VCvr.iemkSYEKZlpPqUEoeHLqEmvbHPln4JnyNBehFnATM3GzpcMILEUjNPJSpyMuYc13JiByfYohiCPPlwnu
The 4-character segment after the prefix matches the workspace segment in your resource IDs. This reference covers the secret-key API at /v1/*. The public key is used by the Kwugwo hosted checkout and embedded widget; you do not need to call those endpoints yourself.

​
Errors

StatusMeaning
401 UnauthorizedMissing or malformed Authorization header, or the key is not active.
403 ForbiddenThe key is valid but does not have access to the resource.
404 Not FoundThe resource does not exist on the workspace that owns this key.
If you regenerate a key, requests with the old value start failing with 401 immediately; there is no grace period.

​
Keep secrets secret

  • Store the key in an environment variable or secrets manager, never in source control.
  • Use the sandbox key while you build; only swap in the live key when you’re ready to take real money.
  • Rotate at the first sign of compromise. Regeneration takes effect instantly.