Skip to main content

​
Quickstart

You will have a payment running in minutes. Follow the steps below. Prerequisites:
  • An active PalPluss API key — get one at console.palpluss.com under Settings → API Keys
  • Service wallet with enough balance to cover the transaction fee
  • A publicly accessible HTTPS URL to receive callbacks

​
Step 1 — Set your API key

export PALPLUSS_API_KEY="pk_live_xxxxxxxxxxxxxxxxxxxx"

​
Step 2 — Check your balance

Verify you have sufficient balance before initiating payments. 
curl https://api.palpluss.com/v1/wallets/service/balance \
  -u "$PALPLUSS_API_KEY:"

{
  "success": true,
  "data": {
    "currency": "KES",
    "availableBalance": 4250.00,
    "ledgerBalance": 4250.00
  }
}
If balance is low, top up your service wallet first.

​
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"
  }'

{
  "success": true,
  "data": {
    "transactionId": "fa98a577-95ea-4a8f-8467-1fbe74f5d6f4",
    "status": "PENDING",
    "amount": 100,
    "currency": "KES",
    "phone": "254712345678"
  }
}
Save the transactionId — use it to track this payment.

​
Step 4 — Handle the webhook callback

When the customer confirms or cancels, PalPluss sends a POST 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."
  }
}
Return a 2xx status immediately. PalPluss retries failed deliveries up to 5 times.

​
Step 5 — Poll status (optional)

Use polling as a fallback when webhooks are unavailable. 
curl https://api.palpluss.com/v1/transactions/fa98a577-95ea-4a8f-8467-1fbe74f5d6f4 \
  -u "$PALPLUSS_API_KEY:"
Webhooks are faster and more reliable than polling. Use polling only as a backup.

​
Next steps

STK Push reference

Full request and response reference.

Webhooks guide

Callback delivery, retries, and idempotent handling.

B2C Payouts

Send money directly to customer M-Pesa numbers.

Error handling

Handle errors correctly in your integration.