Introduction
Authentication
How to authenticate your requests to the KPay API securely.
Sandbox mode. Use your kpay_test_... keys and the test numbers below. KPay routes your requests to its test environment — no real money is moved.
API Keys
KPay authenticates requests via a key pair generated from the <strong>Applications</strong> screen in your dashboard. Each authenticated request transmits two headers:
X-API-Key stringPublic key. Prefix <code>kpay_test_</code> (TEST) or <code>kpay_live_</code> (LIVE).
X-Secret-Key stringSecret key. Prefix <code>sk_test_</code> (TEST) or <code>sk_live_</code> (LIVE).
Required headers
X-API-Key: kpay_test_xxxxxxxxxxxxxxxx
X-Secret-Key: sk_test_xxxxxxxxxxxxxxxxSandbox by default, production after KYC
Your account is in <strong>sandbox</strong>: only <code>kpay_test_…</code> keys are available and never affect real data. To obtain <code>kpay_live_…</code> keys, complete <strong>identity verification (KYC)</strong> from your dashboard.
Request example
Example of an authenticated call, provided in Node.js, PHP, Python, Go and Dart.
Node.js
const res = await fetch("https://admin.kpay.site/api/v1/payments/init", {
method: "POST",
headers: {
"X-API-Key": process.env.KPAY_API_KEY,
"X-Secret-Key": process.env.KPAY_SECRET_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"amount": 5000,
"provider": "MTN_MOMO_CMR",
"phoneNumber": "237653456789",
"externalId": "ORDER-12345"
}),
});
const data = await res.json();Key security
- Keep your keys private. Never expose them in client code, a public repository or on social media. They travel only from server to server.
- Environment variables. Store keys in environment variables or a secrets vault, never hard-coded.
- Access controls. Limit key access to the only members who need it.
- Regular rotation. Regenerate keys periodically or if compromise is suspected — regeneration immediately invalidates the old key.
- Revocation. A compromised key can be revoked from the Applications screen.
- Test keys in development. Use <code>*_test_</code> while developing; switch to LIVE only for production.
Authentication error responses
Best practices
- Always HTTPS. Never send a request over an unencrypted connection.
- Robust error handling. Handle authentication errors cleanly; retry with exponential backoff for transient errors.
- Isolation. Use different keys per service/environment.
- Monitoring. Follow your API logs to detect any unusual access.
Next steps
Was this page helpful?