Skip to main content

​
Quickstart

This guide walks you through initiating your first M-Pesa STK Push using the PalPluss API.

​
Prerequisites

Before you start, you need:
  • A PalPluss account with an active API key
  • Your service wallet topped up with enough balance to cover the transaction fee
  • A publicly accessible HTTPS URL to receive payment callbacks
Don’t have an API key yet? Log in to the PalPluss dashboard and navigate to Settings → API Keys to generate one.

​
Step 1 — Set your API key

All requests use HTTP Basic Auth with your API key as the username and an empty password. 
export PALPLUSS_API_KEY="pk_live_xxxxxxxxxxxxxxxxxxxx"

​
Step 2 — Check your service wallet balance

Before initiating payments, verify you have sufficient balance to cover transaction fees. 
curl https://api.palpluss.com/v1/wallets/service/balance \
  -u "$PALPLUSS_API_KEY:"
Response: 
{
  "success": true,
  "data": {
    "currency": "KES",
    "availableBalance": 4250.00,
    "ledgerBalance": 4250.00
  }
}
If your balance is low, top up your service wallet before continuing.

​
Step 3 — Initiate an STK Push

Send a payment prompt to a customer’s phone: 
curl -X POST https://api.palpluss.com/v1/payments/stk \
  -u "$PALPLUSS_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100,
    "phone": "0712345678",
    "accountReference": "INV-001",
    "transactionDesc": "Payment",
    "callbackUrl": "https://yourserver.com/webhooks/mpesa"
  }'
Response: 
{
  "success": true,
  "data": {
    "transactionId": "fa98a577-95ea-4a8f-8467-1fbe74f5d6f4",
    "status": "PENDING",
    "amount": 100,
    "currency": "KES",
    "phone": "254712345678"
  }
}
Save the transactionId — you’ll use it to track this payment.

​
Step 4 — Handle the webhook callback

After the customer confirms (or cancels) payment on their phone, PalPluss sends a POST request to your callbackUrl: 
{
  "event": "transaction.updated",
  "event_type": "transaction.success",
  "transaction": {
    "id": "fa98a577-95ea-4a8f-8467-1fbe74f5d6f4",
    "status": "SUCCESS",
    "amount": 100,
    "currency": "KES",
    "phone_number": "254712345678",
    "result_code": "0",
    "result_desc": "The service request is processed successfully."
  }
}
Your endpoint must return a 2xx status code. PalPluss retries failed deliveries up to 5 times with exponential backoff.

​
Step 5 — Poll transaction status (optional)

If you prefer polling over webhooks, check transaction status at any time: 
curl https://api.palpluss.com/v1/transactions/fa98a577-95ea-4a8f-8467-1fbe74f5d6f4 \
  -u "$PALPLUSS_API_KEY:"
Use webhooks as the primary delivery mechanism and polling as a fallback. Polling on every request increases latency and counts toward your rate limit.

​
Next steps

STK Push reference

Full request/response reference for STK Push.

Webhooks guide

Understand callback delivery, retries, and verification.

B2C Payouts

Send money directly to customer M-Pesa numbers.

Error handling

Handle API errors correctly in your integration.