Glossary

Terms Kenyan merchants meet on DukaBot.

15 plain-English definitions of the M-Pesa, Safaricom Daraja, and WhatsApp Business Platform concepts that show up when you run a shop on DukaBot.

STK Push: STK Push (SIM Toolkit Push) is the M-Pesa payment prompt that Safaricom's Daraja API sends directly to a customer's phone. The customer sees a request with the merchant's Till or Paybill, the amount in KES, and an order reference, and enters their M-Pesa PIN to authorise the payment. DukaBot triggers STK Push for every WhatsApp checkout so the customer never leaves the WhatsApp Business Platform conversation. Safaricom returns a callback to the merchant's webhook when the prompt is confirmed, expired, or cancelled.
Daraja: Daraja is Safaricom's official HTTP API for M-Pesa. It exposes endpoints for STK Push, C2B (Customer-to-Business), B2C (Business-to-Customer), transaction status queries, and reversal requests. DukaBot uses Daraja directly to charge customers on either a Till or Paybill, and to look up the final status of a payment if the callback is delayed or lost. Every Daraja call is authenticated with an OAuth token derived from the merchant's consumer key and consumer secret, and runs against either the Daraja sandbox or production environment.
M-Pesa: M-Pesa is Safaricom's mobile money service, the dominant way Kenyan customers pay in KES. On DukaBot it is the default checkout: a customer adds items to a WhatsApp cart, the bot triggers an M-Pesa STK Push via Daraja, and once the customer enters their PIN the funds settle into the merchant's M-Pesa Till or Paybill. M-Pesa balances, receipts, and reversal IDs all flow through DukaBot's reconciliation pipeline so the merchant has one view of each order across WhatsApp and M-Pesa.
Till Number (Buy Goods): A Till number is the Buy Goods short code that Safaricom issues to a merchant for M-Pesa payments. Customers pay by selecting Lipa na M-Pesa > Buy Goods and entering the Till and amount in KES. DukaBot can drive a Till via Daraja STK Push so the customer never has to type the Till manually — the prompt is pushed directly to their phone from the WhatsApp Business Platform conversation. Tills are usually the simpler choice for a single shop without account-number-style references; Paybill is used when sub-accounts matter.
Paybill: A Paybill is a Safaricom short code that lets M-Pesa customers pay with an extra account number, useful when a merchant needs to route funds to sub-accounts, invoices, or branches. On DukaBot, Paybill checkout still runs through Daraja STK Push so the customer does not need to type the Paybill or account number manually. The bot generates the account reference (often the order ID or shop code) and Safaricom returns it on the M-Pesa callback, which DukaBot then matches against the originating WhatsApp Business Platform order.
WhatsApp Business Platform (Cloud API): The WhatsApp Business Platform (formerly WhatsApp Business API), specifically the Cloud API hosted by Meta, is the API surface DukaBot uses to send and receive WhatsApp messages on behalf of a merchant. Unlike the consumer WhatsApp app, the Cloud API supports automated replies, message templates, catalogs, and webhooks. DukaBot reads inbound customer messages, sends catalog buttons, and triggers M-Pesa STK Push via Daraja inside that same conversation, all through the WhatsApp Business Platform endpoints. To onboard a number a merchant needs a verified Meta Business Manager, a phone number that is not in use on the consumer WhatsApp app, and an access token scoped to the Cloud API.
Opt-in / Opt-out: Opt-in is the customer's explicit consent to receive WhatsApp messages from a merchant. The WhatsApp Business Platform requires merchants to log a clear opt-in source (a checkout box, a USSD acknowledgement, a written reply) before sending any non-template message outside the 24-hour customer service window. Opt-out is the customer asking to stop receiving messages, which DukaBot honors by suppressing further marketing sends. Failing to track opt-in correctly is one of the fastest ways to get a WhatsApp Business Platform number flagged by Meta.
24-hour customer service window: When a customer sends a message on WhatsApp, the merchant has 24 hours to reply freely with any text. After that window closes, the WhatsApp Business Platform only allows messages built from pre-approved message templates. DukaBot's WhatsApp router tracks every inbound message timestamp so automated replies, order confirmations, and M-Pesa STK Push prompts go out inside the free window, and only template-based reminders go out after. Mishandling this window is the most common cause of failed sends on a freshly onboarded Cloud API number.
Message templates: Message templates (sometimes called HSMs, Highly Structured Messages) are pre-approved WhatsApp message bodies that a merchant can send outside the 24-hour customer service window. Meta reviews each template for category — utility, marketing, authentication — before it can be used on the WhatsApp Business Platform. DukaBot ships default order-status and payment-reminder templates that variable-substitute the customer name, order ID, and M-Pesa receipt so a merchant does not need to author them from scratch. Templates with promotional language usually require longer review than utility ones.
Webhook callback: A webhook is an HTTP endpoint that an external service POSTs to when an event happens. DukaBot exposes one webhook for the WhatsApp Business Platform (inbound messages, status updates) and another for Daraja (STK Push confirmation, reversal results). Each webhook is authenticated — the WhatsApp webhook by a verify token, the Daraja webhook by IP allowlist and a shared secret — and idempotency is enforced so a duplicate retry from Safaricom or Meta does not double-charge the customer or double-post the order in DukaBot's database.
Shop code: A shop code is the short identifier DukaBot assigns to every merchant business — for example, the slug visible at /s/<shopCode>. It is passed as the M-Pesa account reference on Paybill STK Push so the Daraja callback can be matched back to the originating shop, even when many merchants share the same WhatsApp Business Platform number. Shop codes are also embedded in the WhatsApp catalog link and the shareable storefront URL, which is how customers discover and bookmark a merchant's DukaBot page.
WhatsApp catalog: A WhatsApp catalog is a structured product list that lives inside a merchant's WhatsApp Business Platform account and can be browsed by customers inside the chat. DukaBot syncs the merchant's products into the WhatsApp catalog so customers can tap a product, add it to a cart, and check out without ever leaving WhatsApp. The catalog product IDs are persisted in DukaBot's PostgreSQL store and reconciled against M-Pesa receipts at checkout, so the merchant has a single audit trail per order from browse to paid.
Reconciliation: Reconciliation is the process of matching every M-Pesa receipt to the WhatsApp order it paid for. DukaBot reconciles on three signals: the STK Push CheckoutRequestID returned by Daraja, the M-Pesa receipt code in the callback, and the account reference (shop code or order ID) carried through the Paybill flow. When all three line up the order is marked paid in DukaBot's dashboard; mismatches stay in a review queue so the merchant can act on them rather than silently lose KES revenue.
Daraja sandbox vs production: Safaricom runs two Daraja environments: sandbox for testing and production for live M-Pesa traffic. Sandbox accepts STK Push requests against test phone numbers but never moves real KES; production touches the real M-Pesa rails and a real Till or Paybill. DukaBot keeps the two environments behind a per-business configuration flag so a merchant can dry-run a checkout end-to-end before flipping their WhatsApp Business Platform shop to production. The consumer key, consumer secret, and webhook URLs are separate between the two — never share sandbox credentials with production.
M-Pesa reversal / refund: An M-Pesa reversal is Safaricom's mechanism for returning a paid amount to a customer, either initiated by the customer's Safaricom support call or by the merchant via the Daraja Reversal API. DukaBot surfaces the M-Pesa receipt ID and the Daraja TransactionID on every order so a merchant has the exact references Safaricom needs to process the reversal. Once Safaricom confirms the reversal through a webhook callback, DukaBot updates the order status and adjusts the merchant's reconciled KES revenue so the dashboard stays accurate.