Paystack in Kenya: Complete Developer Guide

Kenya runs on mobile money. M-Pesa processes billions of transactions annually, and for most Kenyans, their phone number is their primary financial account. This is not a niche payment method or an alternative channel. It is the default way people move money.

This reality shapes everything about building payment flows in Kenya:

• Mobile money is the highest-converting channel. If you only offer card payments to Kenyan customers, you are excluding the majority of your potential paying users. Most Kenyans do not have or regularly use debit cards for online purchases.
• The KES (Kenyan Shilling) is the local currency. All domestic transactions happen in KES. Amounts in the Paystack API are in cents (the smallest unit). One shilling equals 100 cents.
• Network conditions matter. Mobile data in Kenya is generally reliable in urban areas but can be inconsistent in rural regions. Your payment flow needs to handle timeouts gracefully, especially for mobile money transactions that depend on the customer responding to an STK push on their phone.
• M-Pesa has its own direct API (Daraja). Many Kenyan developers wonder whether to use Paystack or go direct with Daraja. Paystack gives you a unified API across multiple channels, while Daraja gives you deeper M-Pesa-specific features. Some teams use both.
• The regulatory environment includes the Central Bank of Kenya (CBK) and the Communications Authority. Payment service providers operating in Kenya must comply with local regulations around KYC, data protection, and transaction reporting.

Paystack entered Kenya as part of its expansion beyond West Africa, and the Kenyan market has different characteristics from Nigeria or Ghana. Understanding these differences is essential for building payment flows that actually convert.

Setting up Paystack for a Kenyan business follows the same general flow as other markets, but the verification documents are Kenya-specific.

Step 1: Create your Paystack account

Sign up at paystack.com and select Kenya as your country. You get immediate access to test mode with test API keys. Start building your integration before completing business verification.

Step 2: Complete business verification

To go live in Kenya, Paystack requires your KRA PIN certificate, certificate of incorporation (or business registration certificate for sole proprietors), a national ID or passport of the director, and your bank account details for settlement. The verification timeline varies but typically takes several business days.

Step 3: Get your live API keys

Once verified, your live secret key and public key become available in the dashboard. The secret key (starts with sk_live_) is for server-side operations. The public key (starts with pk_live_) is for client-side Paystack Popup or Inline JS.

Step 4: Initialize your first transaction

// Initialize a KES transaction
var response = await fetch('https://api.paystack.co/transaction/initialize', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.PAYSTACK_SECRET_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'customer@example.co.ke',
    amount: 200000, // 2,000 KES in cents
    currency: 'KES',
    reference: 'order_' + Date.now(),
    callback_url: 'https://yoursite.co.ke/payment/callback',
  }),
});

var data = await response.json();
// Redirect to data.data.authorization_url
// Or use data.data.access_code with Paystack Popup

Always pass currency: 'KES' explicitly. The amount 200000 means 2,000 KES (200,000 cents divided by 100). A common mistake is confusing KES and cents, which leads to charging customers 100 times the intended amount or 100 times less.

For the full document requirements and common rejection reasons, see Paystack onboarding and compliance requirements in Kenya.

Kenya has fewer payment channels on Paystack than Nigeria, but the ones available cover the vast majority of how Kenyans pay online.

Mobile Money (M-Pesa)

Mobile money is the dominant payment method. When a customer selects mobile money at the Paystack checkout, they receive an STK push notification on their phone asking them to enter their M-Pesa PIN to authorize the payment. The flow is familiar to virtually every Kenyan with a phone. This channel should be your default for consumer-facing products in Kenya.

Cards (Visa, Mastercard)

Card payments work for customers with Visa or Mastercard debit or credit cards. Card penetration in Kenya is lower than in Nigeria or South Africa, but cards are used by a segment of urban, tech-savvy customers and are important for B2B transactions and higher-value purchases.

Bank Transfer

Paystack supports bank transfers in Kenya, allowing customers to pay by transferring directly from their bank account. This channel is useful for B2B payments and customers who prefer bank-to-bank transfers over mobile money or cards.

When initializing a transaction, you can specify which channels to display:

// Show only mobile money and card channels
var response = await fetch('https://api.paystack.co/transaction/initialize', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.PAYSTACK_SECRET_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'customer@example.co.ke',
    amount: 150000, // 1,500 KES
    currency: 'KES',
    channels: ['mobile_money', 'card'],
    reference: 'order_' + Date.now(),
  }),
});

For a deep dive into each channel with conversion tips, read payment methods available on Paystack in Kenya.

Every amount in the Paystack API is in the smallest currency unit. For Kenya, that means cents. One Kenyan Shilling equals 100 cents.

// Converting KES to cents for the API
function kesToCents(kes) {
  return Math.round(kes * 100);
}

// Converting cents back to KES for display
function centsToKes(cents) {
  return cents / 100;
}

// Examples
kesToCents(2000);    // 200000 cents = 2,000 KES
kesToCents(50);      // 5000 cents = 50 KES
kesToCents(1499.50); // 149950 cents = 1,499.50 KES

Common mistakes with KES amounts:

• Passing KES instead of cents. If your product costs 2,000 KES and you pass amount: 2000, Paystack charges 20 KES. If you pass amount: 200000, Paystack charges 2,000 KES. Always multiply by 100.
• Mixing up M-Pesa amounts and Paystack amounts. When customers see M-Pesa confirmations, they see the amount in KES. Make sure the amount in your Paystack API call matches what the customer expects to pay. A mismatch causes confusion and abandoned transactions.
• Floating point rounding. Use Math.round() when converting to cents to avoid JavaScript floating point quirks that produce values like 149999.99999.

When you verify a transaction, always confirm the amount and currency match your expectations:

var verifyResponse = await fetch(
  'https://api.paystack.co/transaction/verify/' + reference,
  {
    headers: {
      Authorization: 'Bearer ' + process.env.PAYSTACK_SECRET_KEY,
    },
  }
);

var verifyData = await verifyResponse.json();

if (verifyData.data.status === 'success') {
  var expectedAmount = 200000; // 2,000 KES in cents
  if (verifyData.data.amount !== expectedAmount || verifyData.data.currency !== 'KES') {
    console.error('Amount or currency mismatch');
    return;
  }
  // Amount verified. Grant value to the customer.
}

Mobile money transactions behave differently from card payments. The customer does not enter payment details in a browser. Instead, they receive a push notification on their phone and authorize the payment there. This changes how you handle the payment flow.

The STK push flow:

1. Your server initializes the transaction via the Paystack API
2. The customer is shown the Paystack checkout (or your custom UI) and selects mobile money
3. The customer enters their phone number
4. An STK push notification appears on their phone
5. The customer enters their M-Pesa PIN
6. Payment is authorized and Paystack sends a webhook to your server

The gap between step 4 and step 6 can be seconds or minutes. The customer might be on a different screen, have their phone locked, or be in an area with poor signal. Your application needs to handle this waiting period gracefully.

// Frontend: poll for payment status after STK push
function pollPaymentStatus(reference, maxAttempts) {
  var attempts = 0;

  function check() {
    attempts = attempts + 1;

    fetch('/api/payment/status/' + reference)
      .then(function(res) { return res.json(); })
      .then(function(data) {
        if (data.status === 'success') {
          // Payment confirmed. Show success to customer.
          showSuccess();
        } else if (data.status === 'failed') {
          // Payment failed. Show retry option.
          showRetry();
        } else if (attempts < maxAttempts) {
          // Still pending. Check again in 5 seconds.
          setTimeout(check, 5000);
        } else {
          // Timed out. Tell customer to check their phone.
          showTimeout();
        }
      });
  }

  check();
}

Key engineering considerations for mobile money in Kenya:

• Timeouts are normal. M-Pesa STK pushes can take 30 seconds or longer. Do not treat a slow response as a failure. Wait for the webhook.
• The webhook is your source of truth. Do not grant value based on the frontend polling alone. Use webhooks for the definitive payment confirmation.
• Phone number format matters. Kenyan phone numbers can be entered in multiple formats (07XX, +2547XX, 2547XX). Normalize the format before sending to Paystack.
• STK push can fail silently. The customer might not receive the push due to network issues. Provide a way for them to retry or use an alternative payment method.

Webhook handling in Kenya follows the same pattern as other Paystack markets, but mobile money transactions make webhooks even more critical because the payment authorization happens on the customer's phone, not in the browser.

var crypto = require('crypto');

app.post('/webhooks/paystack', function(req, res) {
  res.sendStatus(200);

  var hash = crypto
    .createHmac('sha512', process.env.PAYSTACK_SECRET_KEY)
    .update(JSON.stringify(req.body))
    .digest('hex');

  if (hash !== req.headers['x-paystack-signature']) {
    console.error('Invalid webhook signature');
    return;
  }

  var event = req.body;

  if (event.event === 'charge.success') {
    var reference = event.data.reference;
    var channel = event.data.channel;

    // Log the channel for analytics
    // 'mobile_money' for M-Pesa, 'card' for cards
    console.log('Payment via ' + channel + ': ' + reference);

    // Process the payment
    processPayment(reference, event.data);
  }
});

Settlement in Kenya:

Settlement timelines in Kenya are generally longer than in Nigeria. The exact timeline depends on your account tier, transaction volume, and the payment channel used. Check your Paystack dashboard under Settings for your specific settlement schedule.

Things to plan for:

• Settlement is to your registered Kenyan bank account. Ensure your bank details are correct during onboarding. Settlement failures due to wrong account details delay your payouts.
• Fees are deducted before settlement. The amount you receive is the transaction amount minus Paystack's processing fee.
• Weekend and holiday delays. Settlements may not process on weekends and Kenyan public holidays.

For detailed settlement timelines and reconciliation strategies, see settlement and payouts on Paystack in Kenya.

This is the question every Kenyan developer faces. M-Pesa has its own API (Daraja) that gives you direct access to STK push, C2B, B2C payouts, and more. Paystack wraps M-Pesa alongside other payment channels behind a unified API. So which do you use?

Use Paystack when:

• You want one API for mobile money, cards, and bank transfers
• You are building a product that will expand to other African countries (Nigeria, Ghana, South Africa)
• You want a managed checkout experience without building your own payment UI
• Your team does not have experience with Daraja API integration
• You want settlement, reconciliation, and dispute handling through a single dashboard

Use direct Daraja when:

• You need B2C payouts (sending money to customer M-Pesa wallets)
• You need Lipa Na M-Pesa Till or Paybill integration for physical stores
• You need maximum control over the STK push flow (custom timeout handling, specific shortcode configuration)
• Your product is Kenya-only and M-Pesa-only with no plans to add other payment methods
• You want to avoid the gateway fee on top of M-Pesa's own charges

Use both when:

• You accept payments through Paystack (for the multi-channel checkout) but need direct Daraja for B2C payouts or till number integration
• You want Paystack as your primary gateway with Daraja as a fallback for M-Pesa-specific flows

Many production Kenyan systems use both. Paystack handles the checkout, and Daraja handles the disbursement. This is a valid architecture. The key is to keep your payment records normalized so you can reconcile across both providers.

Testing Paystack in Kenya uses the same test mode as other markets, but there are Kenya-specific things to watch for.

Testing mobile money: In test mode, mobile money transactions are simulated. You will not receive an actual STK push on your phone. The test dashboard lets you simulate successful and failed mobile money payments. Test the full flow including webhook handling.

Common pitfalls for Kenyan integrations:

• Not making mobile money the default. If your checkout shows cards first and mobile money second, you are losing conversions. In Kenya, mobile money should be the first option customers see.
• Ignoring phone number validation. Kenyan phone numbers need to be in the right format for M-Pesa. Validate and normalize phone numbers on your end before they reach Paystack.
• No fallback for failed STK push. If the STK push fails (network issues, wrong phone number, customer declined), your UI should offer a clear retry path or an alternative payment method. Do not leave the customer stuck on a loading screen.
• Assuming Nigerian settlement timelines. Kenya has different settlement schedules. Do not promise your vendors or suppliers instant payouts based on what you know about Nigerian Paystack settlement.
• Not handling currency correctly. If your Paystack account is set to Kenya but you forget to pass currency: 'KES', the API behavior may not match your expectations. Always be explicit about currency.
• Ignoring the Daraja option for specific use cases. If you need B2C payouts or till number integration, Paystack alone will not cover it. Plan your architecture early to accommodate both providers if needed.

Paystack in Kenya gives you a unified gateway for a market where mobile money dominates. The challenge is not the API integration itself. It is understanding the Kenyan payment landscape well enough to build flows that convert.

If you are building products that accept payments in Kenya and want hands-on experience with both Paystack and Daraja, the McTaba bootcamp covers payment integration as a core module. Graduates ship code that handles real KES transactions across multiple channels.

Create a free McTaba account