Sign in

v1

latestOpenAPI 3.1.02026-07-2691531.2 KB
STK Push

Initiate STK Push

Sends an M-Pesa STK Push prompt to the customer's phone. The customer enters their M-Pesa PIN to authorise payment.

Payment results are delivered asynchronously to the callbackUrl you supply. Poll GET /transactions/{id} if you need to check status programmatically.

Fees: A transaction fee is deducted from your service wallet balance at the time the request is accepted. If your balance is insufficient the request returns 402.

post/payments/stk

Request body

amountnumber required

Amount to charge in KES.

phonestring required

Customer phone number. Accepted formats: 0712345678, 254712345678, +254712345678. Normalised to 254XXXXXXXXX internally.

accountReferencestring required

Your reference — invoice number, order ID, etc.

transactionDescstring required

Short description shown on the customer's PIN prompt.

callbackUrlstring uri required

HTTPS URL where PalPluss will POST the transaction result after the customer confirms or cancels payment.

channelIdstring uuid nullable

Optional. Route the STK Push through a specific payment channel (shortcode). If omitted, the default channel is used.

credential_idstring uuid nullable

Optional. Use a specific MERCHANT_BYOC credential profile for this request. When provided, Daraja OAuth and STK initiation use that profile's credentials (consumerKey, consumerSecret, passkey, shortcode).

Transaction type (commandId) resolution when credential_id is set:

  • Channel present → channel type drives it (PAYBILL = CustomerPayBillOnline, TILL = CustomerBuyGoodsOnline)
  • No channel → profile's transactionType is used when set; falls back to platform default

PartyB resolution when no channel is configured: the credential profile's shortcode is used instead of the platform default shortcode.

Example request

{
  "amount": 1000,
  "phone": "0712345678",
  "accountReference": "INV-2024-001",
  "transactionDesc": "Payment",
  "callbackUrl": "https://yourserver.com/webhooks/mpesa"
}

Response

STK Push accepted. Transaction is in PENDING state.

successboolean required
requestIdstring uuid required

Unique identifier for this API request. Include in support tickets.

Example response

{
  "success": true,
  "data": {
    "type": "STK",
    "status": "PENDING",
    "amount": 1000,
    "currency": "KES",
    "phone": "254712345678",
    "accountReference": "INV-2024-001",
    "transactionDesc": "Payment",
    "transactionFee": 2.5
  },
  "requestId": "c1b2a3d4-e5f6-7890-abcd-ef1234567890"
}