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",
    "channelId": "your-payment-channel-id",
    "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.

Get Started

Guides

SDKs

STK Push

Transactions

B2C Payouts

Service Wallet

Payment Channels

Quickstart

Quickstart

Step 1 — Set your API key

Step 2 — Check your balance

Step 3 — Initiate an STK Push

Step 4 — Handle the webhook callback

Step 5 — Poll status (optional)

Next steps

STK Push reference

Webhooks guide

B2C Payouts

Error handling

​Quickstart

​Step 1 — Set your API key

​Step 2 — Check your balance

​Step 3 — Initiate an STK Push

​Step 4 — Handle the webhook callback

​Step 5 — Poll status (optional)

​Next steps

STK Push reference

Webhooks guide

B2C Payouts

Error handling

Quickstart

Step 1 — Set your API key

Step 2 — Check your balance

Step 3 — Initiate an STK Push

Step 4 — Handle the webhook callback

Step 5 — Poll status (optional)

Next steps