Skip to Content
Frequently Asked Questions

FAQ

Find answers to common integration challenges and learn how to resolve issues quickly.

Security & API Keys

1. Where can I get my Test and Production API keys?

You can obtain your API keys from the KisPay Merchant Dashboard.

Steps:

  1. Visit merchant.kispay.et 
  2. Click Create Account
  3. Sign up with your basic information

After successful registration, you will be redirected to the Merchant Dashboard, which provides a sandbox (Test) API key for development and testing.

Once testing is completed and your account is approved, Production API keys will be provided to enable live transactions.

2. Where should I store my Secret API Key?

Once you receive your Test and Production API keys, you must handle them with extreme care:

  • Never store your Secret Key on the client-side (Frontend, Mobile App, or Browser).
  • Always use Environment Variables: Store keys securely in a .env file on your backend server.

Exposing your API key in client-side code allows malicious actors to initiate transactions on your behalf.

Authentication & Headers

3. Which headers are required for API requests?

All API requests must include authentication headers:

  • API Key Authentication: x-api-key
  • Bearer Token Authentication (optional): Authorization: Bearer <token>
  • Content-Type: application/json

Missing or invalid headers will result in authentication errors.

Merchant Dashboard

4. Do merchants have a dashboard?

Yes. Every merchant is provided with a dedicated Merchant Dashboard to manage and monitor activity.

Through the dashboard, merchants can:

  • View real-time transaction status
  • Monitor payments and withdrawals
  • Check available and reserved balances
  • Track fees and net settlements
  • Access transaction history and reports
  • Manage API keys and webhook URLs

5. Can I download reports from the dashboard?

Yes. Merchants can download reports for:

  • Payments
  • Withdrawals
  • Settlements

Reports can be filtered by date range, status, and payment channel.

Withdrawals & Payouts

6. Why is my withdrawal stuck in PENDING status?

A withdrawal may remain in PENDING status due to:

  • Provider-side processing delays
  • Manual review requirements

Withdrawals are processed asynchronously and final updates are sent via webhooks.

Balances & Limits

7. How do I check my available balance?

You can check your available, reserved, and total balances directly from the Merchant Dashboard.

Monitoring your balance before initiating withdrawals helps avoid failed payout requests.

8. Is there a minimum or maximum withdrawal limit?

Yes. Withdrawal limits may apply based on:

  • Payment provider
  • Merchant account configuration
  • Compliance requirements

Limits are visible in the Merchant Dashboard.

Settlements

9. How long does it take to receive my funds?

Settlements are processed based on your request:

  • Timeline: Once we receive your request, settlements are typically processed within 1-2 business days.
  • Example: Funds from today’s transactions will be deposited into your linked Bank account by the next business day (excluding weekends and public holidays).

Webhooks & Status Updates

10. Payment or withdrawal completed but webhook not received?

If your system did not receive a webhook:

  1. Ensure your webhook URL is publicly accessible
  2. HTTPS is required for production
  3. Your server must return 200 OK immediately

You can manually verify any transaction status via the GET /api/checkout/withdrawal/verify/{withdrawal_requestID} endpoint if a webhook was missed.

Testing & Environment

11. Can I test everything before going live?

Yes. A sandbox environment is available that mirrors production behavior.

  • Test payments and withdrawals safely
  • Receive sandbox webhook events
  • Switch to production by updating your API keys

Common Technical Issues

12. Redirect works but status is not updated?

This happens when users close the browser before redirection completes.

  • Do not rely on redirects alone
  • Always use webhooks as your source of truth

Account & Compliance

13. Is KYC required to go live?

Yes. Merchants must complete KYC verification to activate live transactions.

Incomplete KYC may limit available payment channels.

14. Can I manage multiple payment channels?

Yes. You can select the channels you want and toggle them directly in the Merchant Dashboard.

Supported channels include TELEBIRR, CBE_BIRR, and AWASH, which can be enabled or disabled per merchant based on approval.

  • MPESA integration is coming soon.

Need Help?

Last updated on
Compliance