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.

Use the KulmiPay sandbox to build and test your integration without moving real money. Sandbox and live are separate environments with separate accounts, credentials, API URLs, and checkout URLs.
Never mix sandbox and live credentials. Sandbox keys only work on sandbox.kulmipay.com, and live keys only work on app.kulmipay.com.

​
Integration testing environment

KulmiPay provides two environments:
  • Sandbox / development for testing integrations.
  • Live / production for real transactions.
All API requests should be made over HTTPS. Webhook callback URLs should also use HTTPS and be publicly reachable.

​
Resources for KulmiPay integration and API testing

​
Sandbox / development environment

Use sandbox while building and testing your application.
ResourceURL
Sandbox dashboardhttps://sandbox.kulmipay.com
API base URLhttps://sandbox.kulmipay.com/api/
API v1 base URLhttps://sandbox.kulmipay.com/api/v1/
Checkout APIhttps://sandbox.kulmipay.com/api/v1/checkout/
Checkout pagehttps://checkout-sandbox.kulmipay.com
Sandbox API keys use test prefixes:
KeyPrefix
Public keyISPubKey_test_
Secret keyISSecretKey_test_
Create sandbox keys from API Applications in the sandbox dashboard.

​
Live environment

Use live only when you are ready to process real payments.
ResourceURL
Live dashboardhttps://app.kulmipay.com
Sign uphttps://app.kulmipay.com/account/signup/
API base URLhttps://app.kulmipay.com/api/
API v1 base URLhttps://app.kulmipay.com/api/v1/
Checkout APIhttps://app.kulmipay.com/api/v1/checkout/
Checkout pagehttps://checkout.kulmipay.com
Live API keys use live prefixes:
KeyPrefix
Public keyISPubKey_live_
Secret keyISSecretKey_live_

​
Testing details for sandbox environment

​
Create a checkout session

Use your sandbox public key to create a test checkout. 
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",
    "phone_number": "254723890353",
    "api_ref": "ORDER-1001",
    "redirect_url": "https://merchant.example/thank-you"
  }'

​
Authenticate protected sandbox requests

For backend-only API calls, pass your sandbox secret key as a Bearer token. 
curl --request GET \
  --url https://sandbox.kulmipay.com/api/v1/wallets/ \
  --header 'Authorization: Bearer ISSecretKey_test_xxxxxxxxxxxxxxxx'

​
Test M-Pesa phone numbers

Phone numberSimulated behavior
254723890353Payment succeeds
254700000000Payment fails
254711111111Payment times out

​
Test amounts

Use small amounts such as 1, 5, or 10 to keep test records easy to review.

​
Switching from sandbox to live

When you are ready to go live:
  1. Replace https://sandbox.kulmipay.com with https://app.kulmipay.com.
  2. Replace sandbox keys with live keys.
  3. Use https://checkout.kulmipay.com for live hosted checkout.
  4. Point webhooks to your production HTTPS endpoint.
  5. Complete live business verification before processing real payments.
If you are using the kulmipay browser SDK, set live: true when switching to production.