Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.kulmipay.com/llms.txt

Use this file to discover all available pages before exploring further.

Requests to KulmiPay are authenticated with API keys. KulmiPay provides two key types:
  • Public / publishable key: prefixed with ISPubKey_
  • Secret key: prefixed with ISSecretKey_
Keys are tied to an environment. Test keys include test and must be used with sandbox endpoints. Live keys include live and must be used with live endpoints.
EnvironmentBase URLPublic key prefixSecret key prefix
Sandboxhttps://sandbox.kulmipay.comISPubKey_test_ISSecretKey_test_
Livehttps://app.kulmipay.comISPubKey_live_ISSecretKey_live_
Never expose your secret key in frontend code, mobile apps, public repositories, logs, or browser requests. Use it only from your backend.

​
How to get API keys

Create or view your API keys in the KulmiPay dashboard under API Applications. Your public key is used for browser-safe checkout and collection flows. Your secret key is used for protected server-to-server operations such as wallets, disbursements, payment sessions, webhooks management, and other account-level API calls. Only generate and use a secret key when your integration needs backend access.

​
Public key authentication

Use your public key for checkout flows and public collection requests. You can pass it in the request body: 
{
  "public_key": "ISPubKey_test_xxxxxxxxxxxxxxxx",
  "amount": 1000,
  "currency": "KES"
}
Or pass it as a request header: 
X-KULMI-PUBLIC-API-KEY: ISPubKey_test_xxxxxxxxxxxxxxxx
Example checkout request: 
curl -X POST https://sandbox.kulmipay.com/api/v1/checkout/ \
  -H "Content-Type: application/json" \
  -d '{
    "public_key": "ISPubKey_test_xxxxxxxxxxxxxxxx",
    "amount": 1000,
    "currency": "KES",
    "email": "customer@example.com",
    "api_ref": "ORDER-1001"
  }'
The kulmipay browser SDK handles public key authentication for you: 
new KulmiPay({
  publicAPIKey: "ISPubKey_test_xxxxxxxxxxxxxxxx",
  redirectURL: "https://merchant.example/thank-you",
  live: false
});

​
Secret key authentication

Use your secret key for protected REST API requests. Send it in the Authorization header with the Bearer prefix. 
Authorization: Bearer ISSecretKey_test_xxxxxxxxxxxxxxxx
Example: 
curl --request GET \
  --url https://sandbox.kulmipay.com/api/v1/wallets/ \
  --header 'Authorization: Bearer ISSecretKey_test_xxxxxxxxxxxxxxxx'
In production, switch to the live base URL and a live secret key: 
curl --request GET \
  --url https://app.kulmipay.com/api/v1/wallets/ \
  --header 'Authorization: Bearer ISSecretKey_live_xxxxxxxxxxxxxxxx'
Secret keys do not require an OAuth token exchange. Use the key directly as the Bearer token.
The PHP SDK attaches the correct headers from the credentials you pass to init(): 
use KulmiPay\KulmiPayPHP\Wallet;

$wallet = new Wallet();
$wallet->init([
    "token" => "ISSecretKey_test_xxxxxxxxxxxxxxxx",
    "publishable_key" => "ISPubKey_test_xxxxxxxxxxxxxxxx",
    "sandbox" => true,
]);

​
Choosing the right key

Use caseKey to useWhere to use it
Hosted checkout with kulmipay SDKPublic keyBrowser
Create a checkout session directlyPublic keyBrowser or backend
Check or list account resourcesSecret keyBackend only
Send money or approve payoutsSecret keyBackend only
Manage webhooksSecret keyBackend only
Wallet operationsSecret keyBackend only

​
Common authentication errors

StatusErrorWhat to check
401 UnauthorizedInvalid api tokenThe secret key is wrong, revoked, or not attached to an active account.
401 UnauthorizedInvalid token for live environmentYou used a sandbox key on the live API, or a live key on sandbox.
401 UnauthorizedNo credentials providedThe Authorization header is missing or incomplete.
401 UnauthorizedBearer string should not contain spacesThe Bearer token contains spaces or the header has too many parts.
403 ForbiddenAccount cannot transactYour business account is not enabled for the requested operation.

​
Keeping credentials secure

  • Store secret keys in environment variables or a secrets manager.
  • Do not commit .env files or hard-code credentials.
  • Rotate keys immediately if they are exposed.
  • Use HTTPS for all requests between your backend, frontend, and KulmiPay.
  • Use sandbox keys while testing and live keys only after you are ready to process real payments.

​
Next steps

Client Libraries

Install and configure the browser checkout SDK or PHP SDK.

Sandbox

Test your integration with sandbox keys before going live.