CASPER-TECH-KE / DARAJA PLAYBOOK

Production Till STK, mapped clearly.

This guide documents the exact product, identifiers, API calls, callbacks, and status outcomes used by XCASPER SPACE STK TILL PUSH.

Choose the right Daraja product

This app uses M-Pesa Express / Lipa na M-Pesa Online for a customer-facing STK prompt. It is not the Business Buy Goods B2B API. In your production Daraja app, add the M-Pesa Express/Lipa na M-Pesa Online product and use its production passkey.

Important: Business Buy Goods is a separate business-to-business use case. It does not replace the STK Push product.

Map the Till identifiers

For a Buy Goods Till STK request, use the H.O./Store number as BusinessShortCode and the actual Till number as PartyB.

BusinessShortCode: H.O. or Store number
PartyB: Actual customer-facing Till number
TransactionType: CustomerBuyGoodsOnline

Correct API calls

POST https://api.safaricom.co.ke/oauth/v1/generate?grant_type=client_credentials
Authorization: Basic base64(CONSUMER_KEY:CONSUMER_SECRET)

POST https://api.safaricom.co.ke/mpesa/stkpush/v1/processrequest
Authorization: Bearer ACCESS_TOKEN

Sandbox swaps api.safaricom.co.ke for sandbox.safaricom.co.ke.

Request body essentials

{
  "BusinessShortCode": "HO_OR_STORE_NUMBER",
  "TransactionType": "CustomerBuyGoodsOnline",
  "Amount": 10,
  "PartyA": "2547XXXXXXXX",
  "PartyB": "TILL_NUMBER",
  "PhoneNumber": "2547XXXXXXXX",
  "CallBackURL": "https://your-domain.example/api/callback"
}

Production callback checklist

Use a public, internet-accessible URL.
Use HTTPS in production; HTTP is only allowed for sandbox simulation.
Register the exact confirmation/callback URL in Daraja before testing.
Do not use public URL testers or blocked keywords in the URL.
Return {"ResultCode":0,"ResultDesc":"Accepted"} quickly, then process the result.

In this app: the callback is /api/callback; the UI polls the server and shows successful, cancelled, insufficient-balance, timeout, or failed states.

What each result means

Successful — Safaricom returned ResultCode 0.

Cancelled — the customer cancelled the prompt.

Insufficient balance — the customer balance could not cover the amount.

No response — the prompt expired or the customer did not act.

Protected runtime settings

MPESA_ENV: production
HO_NUMBER: Production H.O./Store number
TILL_NUMBER: Production Buy Goods Till
CALLBACK_URL: Public HTTPS callback URL
CONSUMER_KEY / SECRET: Never expose in browser code

Official references

Safaricom Daraja FAQs Daraja Getting Started Safaricom Till identifier discussion Safaricom Business Till guide