Home Documentation
Documentation

Setup & Documentation

A complete, beginner-friendly guide — from registering your M-Pesa Paybill all the way to live, automated STK Push. New to Daraja? Start at the top and follow along.

1 Before You Begin

AlkaPay connects your WooCommerce store to M-Pesa in two ways. It helps to know which path you're on before you start:

  • Free (Manual payments): customers pay your Paybill or Till from their phone and type in the M-Pesa code. You verify it. No API credentials needed.
  • Pro (Automated STK Push): the M-Pesa PIN prompt pops up on the customer's phone automatically, and paid orders complete themselves. This requires Safaricom Daraja API credentials.

What you'll need before you start: a working WordPress site (5.0+) with WooCommerce installed and active (6.0+), on PHP 7.4 or newer — AlkaPay is a WooCommerce payment gateway, so WooCommerce must be set up first. We also recommend configuring your site's email delivery (an SMTP plugin or your host's mail service) so WooCommerce order and payment notifications actually reach you and your customers. If your server has no working mail, you can switch off the specific WooCommerce emails you don't need under WooCommerce → Settings → Emails.

Here's the big picture of what a full Pro setup involves — each step has its own section below:

  1. Register a Paybill or Buy Goods Till with Safaricom

    Your M-Pesa "shortcode" — the number customers pay to. Section 2.

  2. Install & configure AlkaPay

    Add the plugin and switch on manual payments right away. Section 3 & 4.

  3. Get your API keys from the Daraja portal

    Consumer Key, Consumer Secret, and Passkey for STK Push. Section 6.

  4. Register your callback URL with Safaricom

    So Safaricom can tell your site when a payment lands — this is what powers auto-verification. Section 7.

  5. Activate Pro and switch to Production

    Go live and let orders complete automatically. Section 8.

You don't need everything on day one. You can launch with free manual payments in minutes (Sections 3–4) and add automation later when your Paybill and API access are ready.

Safaricom's requirements and portals change from time to time. Treat the Safaricom-specific steps below as a friendly guide, and always confirm the latest details through the official channels in Safaricom Resources.

2 Get a Paybill or Buy Goods Till

Your shortcode is the M-Pesa number customers pay to. Safaricom offers two types, and the one you pick affects how orders are matched:

  • Paybill — has a Business Number and an Account Number field. The account field is great for stores because customers can enter their order number, making payments easy to reconcile. Funds usually settle to a bank account.
  • Buy Goods (Till) — a single Till Number with no account field. Simpler for the customer, but there's no reference field, so matching relies on the transaction code and amount.

Which should you choose? For an online store, Paybill is often the better fit because the Account Number lets customers tag payments with their order. Both work perfectly with AlkaPay.

What you'll typically need to register

Requirements vary by business type, but Safaricom generally asks for:

  • A registered business — Certificate of Incorporation (limited company) or Business Name / Registration certificate, or a single business permit for sole proprietors.
  • KRA PIN certificate for the business (and sometimes the owner).
  • Valid national ID or passport for the owner and any signatories.
  • Business bank account details — usually a bank letter or cancelled cheque — for settlement (required for Paybill and Business Tills).
  • A Safaricom line registered to the business or owner, used to manage the account and receive notifications.
  • Passport-size photos of signatories and completed Lipa na M-Pesa / KYC forms (in some cases).

How to apply

  1. Apply online or in person

    Start your application on Safaricom's M-Pesa for Business portal at m-pesaforbusiness.co.ke, through the M-PESA Business app, or by visiting any Safaricom shop.

  2. Choose your product

    Select Paybill or Buy Goods (Till), and whether settlement goes to a bank account or, for some individual tills, to an M-Pesa account.

  3. Submit your documents

    Upload or present the documents above. Safaricom runs KYC checks before approving.

  4. Receive your shortcode

    Simple tills can be issued quickly; business Paybills with bank settlement may take a few business days to review and activate.

Not sure about your case? Requirements differ for companies, sole proprietors, NGOs, and schools. Confirm the exact list and fees with Safaricom Business support or your nearest Safaricom shop — see Safaricom Resources.

3 How to Install AlkaPay

AlkaPay installs like any standard WordPress plugin. You'll need a working WordPress site with WooCommerce already active, on PHP 7.4 or newer.

  1. Download the plugin

    Get the free plugin ZIP from the pricing section (or WordPress.org). Pro customers receive a premium ZIP by email after purchase.

  2. Upload it to WordPress

    In your dashboard, go to Plugins → Add New → Upload Plugin, then choose the ZIP file you downloaded.

  3. Install & Activate

    Click Install Now, then Activate. A new AlkaPay menu appears in your WordPress admin sidebar.

Requirements: WordPress 5.0+, WooCommerce 6.0+, and PHP 7.4 or higher. AlkaPay is tested up to WordPress 6.8 and WooCommerce 9.9.

4 Setting Up the Free Version

The free version lets you accept manual M-Pesa payments straight away — no API credentials required. Customers pay to your Paybill or Till and enter their transaction code at checkout.

  1. Open the settings

    Go to AlkaPay → Settings in your WordPress admin.

  2. Choose your payment type

    Select Paybill or Buy Goods (Till) to match the shortcode you registered in Section 2.

  3. Enter your Safaricom number

    Type in your Paybill or Till number. This is the number customers will see and pay to at checkout.

  4. Save changes

    Click Save. Your checkout is now ready to receive manual M-Pesa payments.

How verification works: Manual orders are placed On Hold. After the customer enters their M-Pesa code, check it against your statement in WooCommerce → Orders, then mark the order complete. Pro automates this matching for you (see Sections 7–8).

5 Access the M-Pesa Business (Org) Portal

Once your Paybill/Till is live, Safaricom gives you access to the M-Pesa Business web portal at org.ke.m-pesa.com. This is the organization's control room — separate from the Daraja developer portal.

You use it to:

  • View transactions, download statements, and reconcile payments;
  • Manage operators — including API operators (Initiators) used for advanced production calls such as reversals or B2C payouts;
  • Generate the production security credential when an API requires an Initiator.

Do you need this for STK Push? For basic AlkaPay use (STK Push + manual payment verification), the items you really need are your shortcode, passkey, and Consumer Key/Secret from Daraja (Section 6). The org portal becomes important for the production callback URL registration (Section 7) and any advanced payout features.

Access to the org portal — and historically installing an M-Pesa certificate on a Windows machine — is arranged by Safaricom when your business shortcode is approved. If you can't log in or create an API operator, contact Safaricom Business support; they manage these permissions.

6 Getting Your Daraja API Credentials

For automated (Pro) STK Push, AlkaPay talks to Safaricom's Daraja API. You'll collect three things: a Consumer Key, a Consumer Secret, and a Passkey.

  1. Log in to the Daraja portal

    Go to the Safaricom Daraja Developer Portal and sign in, or create a free account.

  2. Create a new app

    Click My Apps → Add a new App. Give it a name (e.g. "My Store Payments") and tick Lipa na M-Pesa Sandbox for testing, or Lipa na M-Pesa for live.

  3. Copy your Consumer Key & Secret

    Open the app to reveal the Consumer Key and Consumer Secret. Paste both into AlkaPay → Settings.

  4. Test in Sandbox first

    Daraja provides test credentials so you can trial the full STK Push flow (with Pro) before going live. The default sandbox shortcode is 174379, with a test passkey shown on the portal's Simulator / Test Credentials page.

  5. Go Live to get your Production Passkey

    Click Go Live on the Daraja portal, link your real shortcode, and complete Safaricom's verification. Once approved, Safaricom emails your Production Passkey. Enter it in AlkaPay and switch the environment to Production.

Some businesses are asked to email m-pesabusiness@safaricom.co.ke with their company name, registration number, shortcode, the APIs they want enabled, confirmation of sandbox testing, and their callback URLs. Approval typically takes a few business days.

Keep credentials private. Your Consumer Secret and Passkey are sensitive. AlkaPay stores them encrypted, but never share them publicly or commit them to a public repository.

7 Register Your Callback URL

A callback URL (also called a webhook) is the address on your website where Safaricom sends payment notifications. Without it, your site never hears back that a payment succeeded — so this step is what makes auto-verification possible.

The two kinds of callback in AlkaPay

  • STK Push callback — used when the customer pays via the automated PIN prompt. AlkaPay sends this URL inside every STK request automatically, so there's nothing to register manually. It just needs your site to be publicly reachable over HTTPS.
  • C2B confirmation/validation URL — used when a customer pays your Paybill/Till directly (the manual flow). Safaricom only sends these notifications to a URL you have registered with them. Registering it lets AlkaPay match and complete manual orders automatically.

Find your AlkaPay callback URLs

AlkaPay generates secure callback URLs for you (each includes a secret key so only Safaricom's notifications are trusted). Copy them exactly from AlkaPay → Settings. They look like:

STK Push: https://your-store.co.ke/wc-api/alkapay_gateway/?wh_key=••••• C2B (manual): https://your-store.co.ke/wc-api/alkapay_gateway_c2b/?wh_key=•••••

Always copy the full URL including the wh_key from your AlkaPay settings — don't retype it. The key lets AlkaPay reject spoofed callbacks. Your site must use a valid HTTPS/SSL certificate; http:// and localhost URLs are rejected by Safaricom.

How to register the C2B URL with Safaricom

Most accounts now do this in the Daraja Portal under Self Service → URL Management. There's also an API route and an email route — use whichever Safaricom enables for your account:

  1. Recommended: Daraja Portal → Self Service → URL Management

    Log in to the Daraja Portal, open Self Service → URL Management, and click Register New URLs. Your Production App Name and Short Code are already filled in. Then set:

    • Response Type — choose Completed. Safaricom then completes the payment even if your site is briefly unreachable (AlkaPay still reconciles it afterwards). Cancelled would reverse the payment whenever your URL is down — avoid it.
    • Confirmation URL — paste your AlkaPay C2B callback URL (the …/wc-api/alkapay_gateway_c2b/… one, copied exactly from AlkaPay → Settings). This is the URL that matters — it's how AlkaPay hears that a payment succeeded and completes the order.
    • Validation URL — the form requires it, so paste the same AlkaPay callback URL here too. Safaricom only calls the Validation URL if you've asked them to switch on External Validation (off by default, and AlkaPay doesn't need it), so re-using the same URL is safe.

    Click Register URLs. Once saved, they appear in the URL Management table as Confirmation and Validation, with source Daraja.

  2. Alternative: the Daraja "Register URL" API

    Daraja also exposes a C2B Register URL endpoint (/mpesa/c2b/v1/registerurl) that takes the same ConfirmationURL, ValidationURL, and a ResponseType of Completed. Handy for sandbox and scripted setups.

  3. Or ask Safaricom to register it

    For some production shortcodes, registration is handled by Safaricom directly. Email m-pesabusiness@safaricom.co.ke with your shortcode and your AlkaPay Confirmation (and Validation) URLs and ask them to register them.

Same URL in both fields? Yes — AlkaPay gives you a single C2B callback URL; use it for both Confirmation and Validation. Only the Confirmation URL is actually used unless you turn on External Validation, which AlkaPay doesn't require.

Safaricom's portal and rules change from time to time — menu names, field labels, and endpoints may differ from what's shown here. Always confirm the current C2B registration steps in Safaricom's official Daraja documentation, or contact Safaricom Business support if a step looks different — see Safaricom Resources.

No callback yet? You're still fine. If the C2B URL isn't registered, AlkaPay simply keeps manual orders On Hold for you (or a Pro user) to verify. Registering the callback is what upgrades that to hands-off automatic verification.

8 Activate Pro & Go Live

Pro unlocks live STK Push, automatic order completion, analytics, and detailed logging. Once you've purchased a license, activating it takes seconds.

  1. Purchase a license

    Buy a Pro or Lifetime license from the pricing page. You'll receive a license key by email.

  2. Activate your key

    In WordPress, go to AlkaPay → Account, paste your License Key, and click Activate. Pro features unlock instantly.

  3. Enter your production credentials

    In AlkaPay → Settings, add your live Consumer Key, Consumer Secret, shortcode, and Production Passkey from Section 6.

  4. Switch to Production & test

    Flip the environment from Sandbox to Production, save, and place a small real order (e.g. KES 5) to confirm the STK prompt arrives and the order auto-completes.

If a Pro license ever expires, AlkaPay keeps working in Free mode — your store keeps accepting manual payments, you just lose the automated extras until you renew.

9 Go-Live Checklist

Before you flip the switch to Production, run through this quick list:

  • Your Paybill/Till is active and you can see it in the M-Pesa Business portal.
  • Your site is served over HTTPS with a valid SSL certificate.
  • Daraja app created; Consumer Key, Secret, and Production Passkey entered in AlkaPay.
  • Environment set to Production and the shortcode matches your real number.
  • For auto-verifying manual payments: your C2B Confirmation URL is registered with Safaricom (Section 7).
  • You placed a small live test order and watched it complete end-to-end.
  • Order emails and receipts are sending correctly.

All ticked? You're ready to accept real M-Pesa payments. Start with low-value test orders and monitor your first few live transactions in WooCommerce → Orders.

Troubleshooting

The STK prompt never reaches the customer's phone

Check that you're in the right environment (Sandbox vs Production), the shortcode and passkey match, and the phone number is a valid Safaricom format (e.g. 2547XXXXXXXX). In sandbox, use Safaricom's test numbers.

Paid orders stay "On Hold" and don't auto-complete

This almost always means the callback isn't reaching your site. Confirm your site is on HTTPS, that the C2B Confirmation URL is registered with Safaricom (Section 7), and that no firewall or security plugin is blocking the /wc-api/ endpoint.

"Invalid Access Token" or authentication errors

Your Consumer Key/Secret are likely wrong for the selected environment, or you're using sandbox keys in production (or vice-versa). Re-copy them from Daraja and save.

"Wrong credentials" when going live

The Production Passkey is different from the sandbox one and is emailed by Safaricom after Go Live approval. Make sure you've switched to Production and entered the production passkey.

Pro tip: Pro includes detailed logging under AlkaPay → Logs. The logs show each API request/response and incoming callback, which makes pinpointing the issue much faster. If it's an account or shortcode issue, contact Safaricom; if it's the plugin, contact AlkaPay support.

Official Safaricom Resources & Contacts

When in doubt, go to the source. These are the official Safaricom channels for registration, credentials, and API details:

  • Daraja Developer Portal & API docs — create apps, get keys, read the API reference, and start the Go Live process: developer.safaricom.co.ke
  • M-Pesa for Business (apply for Paybill/Till) — register a shortcode and manage KYC: m-pesaforbusiness.co.ke
  • M-Pesa Business / Organization portal — manage your shortcode, statements, and API operators: org.ke.m-pesa.com
  • Go-live & business API requests — email m-pesabusiness@safaricom.co.ke
  • Safaricom Business support — call Safaricom customer care or visit any Safaricom shop for account, KYC, and shortcode questions.

AlkaPay is an independent WooCommerce plugin and is not affiliated with or endorsed by Safaricom PLC. Registration requirements, fees, portals, and API details are set by Safaricom and may change — always verify the current process through the official links above.

No matching sections

Try a different keyword, or contact support and we'll point you to the right place.

Still stuck? Check the FAQ on the home page, or contact support and we'll help you get running.