Sandbox - Kulmi Pay

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.

Resource	URL
Sandbox dashboard	`https://sandbox.kulmipay.com`
API base URL	`https://sandbox.kulmipay.com/api/`
API v1 base URL	`https://sandbox.kulmipay.com/api/v1/`
Checkout API	`https://sandbox.kulmipay.com/api/v1/checkout/`
Checkout page	`https://checkout-sandbox.kulmipay.com`

Sandbox API keys use test prefixes:

Key	Prefix
Public key	`ISPubKey_test_`
Secret key	`ISSecretKey_test_`

Create sandbox keys from API Applications in the sandbox dashboard.

Live environment

Use live only when you are ready to process real payments.

Resource	URL
Live dashboard	`https://app.kulmipay.com`
Sign up	`https://app.kulmipay.com/account/signup/`
API base URL	`https://app.kulmipay.com/api/`
API v1 base URL	`https://app.kulmipay.com/api/v1/`
Checkout API	`https://app.kulmipay.com/api/v1/checkout/`
Checkout page	`https://checkout.kulmipay.com`

Live API keys use live prefixes:

Key	Prefix
Public key	`ISPubKey_live_`
Secret key	`ISSecretKey_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 number	Simulated behavior
`254723890353`	Payment succeeds
`254700000000`	Payment fails
`254711111111`	Payment 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:

Replace https://sandbox.kulmipay.com with https://app.kulmipay.com.
Replace sandbox keys with live keys.
Use https://checkout.kulmipay.com for live hosted checkout.
Point webhooks to your production HTTPS endpoint.
Complete live business verification before processing real payments.

If you are using the kulmipay browser SDK, set live: true when switching to production.

​Integration testing environment

​Resources for KulmiPay integration and API testing

​Sandbox / development environment

​Live environment

​Testing details for sandbox environment

​Create a checkout session

​Authenticate protected sandbox requests

​Test M-Pesa phone numbers

​Test amounts

​Switching from sandbox to live

Integration testing environment

Resources for KulmiPay integration and API testing

Sandbox / development environment

Live environment

Testing details for sandbox environment

Create a checkout session

Authenticate protected sandbox requests

Test M-Pesa phone numbers

Test amounts

Switching from sandbox to live