Initiate STK Push

curl --request POST \
  --url https://api.palpluss.com/v1/payments/stk \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 1000,
  "phone": "0712345678",
  "accountReference": "INV-2024-001",
  "transactionDesc": "Payment for invoice #2024-001",
  "callbackUrl": "https://yourserver.com/webhooks/mpesa"
}
'

{
  "success": true,
  "data": {
    "transactionId": "fa98a577-95ea-4a8f-8467-1fbe74f5d6f4",
    "tenantId": "b6fbe75f-ce87-4d44-b318-6cfdb8b7de4d",
    "channelId": null,
    "type": "STK",
    "status": "PENDING",
    "amount": 1000,
    "currency": "KES",
    "phone": "254712345678",
    "accountReference": "INV-2024-001",
    "transactionDesc": "Payment for invoice #2024-001",
    "providerRequestId": "29115-34620561-1",
    "providerCheckoutId": "ws_CO_191220191020363925",
    "transactionFee": 2.5,
    "resultCode": "0",
    "resultDescription": "Success. Request accepted for processing",
    "createdAt": "2026-03-01T08:00:00.000Z",
    "updatedAt": "2026-03-01T08:00:00.000Z"
  },
  "requestId": "c1b2a3d4-0000-0000-0000-000000000000"
}

POST

payments

stk

curl --request POST \
  --url https://api.palpluss.com/v1/payments/stk \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 1000,
  "phone": "0712345678",
  "accountReference": "INV-2024-001",
  "transactionDesc": "Payment for invoice #2024-001",
  "callbackUrl": "https://yourserver.com/webhooks/mpesa"
}
'

{
  "success": true,
  "data": {
    "transactionId": "fa98a577-95ea-4a8f-8467-1fbe74f5d6f4",
    "tenantId": "b6fbe75f-ce87-4d44-b318-6cfdb8b7de4d",
    "channelId": null,
    "type": "STK",
    "status": "PENDING",
    "amount": 1000,
    "currency": "KES",
    "phone": "254712345678",
    "accountReference": "INV-2024-001",
    "transactionDesc": "Payment for invoice #2024-001",
    "providerRequestId": "29115-34620561-1",
    "providerCheckoutId": "ws_CO_191220191020363925",
    "transactionFee": 2.5,
    "resultCode": "0",
    "resultDescription": "Success. Request accepted for processing",
    "createdAt": "2026-03-01T08:00:00.000Z",
    "updatedAt": "2026-03-01T08:00:00.000Z"
  },
  "requestId": "c1b2a3d4-0000-0000-0000-000000000000"
}

Trigger a payment. The customer receives a PIN prompt on their phone within seconds.

A transaction fee is deducted from your service wallet when the request is accepted. Verify your balance before calling this endpoint.

Key notes

Phone numbers are accepted in 07XXXXXXXX, 01XXXXXXXX, +254XXXXXXXXX, or 254XXXXXXXXX format and normalised internally.
accountReference must be 12 characters or fewer — it appears on the customer’s M-Pesa statement.
transactionDesc must be 13 characters or fewer — it appears on the customer’s PIN prompt.
Save the returned transactionId — use it to poll status or match incoming webhooks.
PENDING means the STK prompt was sent. The final result arrives via your callbackUrl.
transactionFee in the response shows the service wallet amount deducted for this request. It is 0 when no pricing rule is configured.

Using a credential profile (`credential_id`)

The optional credential_id field lets you route the STK Push through your own M-Pesa Daraja credentials (BYOC — Bring Your Own Credentials) instead of the platform default. When credential_id is provided:

Daraja OAuth and the STK Push initiation use that profile’s consumerKey, consumerSecret, passkey, and shortcode.
With a channel (channelId) — the channel type determines the transaction type (PAYBILL → CustomerPayBillOnline, TILL → CustomerBuyGoodsOnline). The channel’s shortcode is used as PartyB.
Without a channel — the credential profile’s transactionType (set when creating the profile) determines the transaction type. The profile’s shortcode is used as PartyB. Falls back to the platform DARAJA_TRANSACTION_TYPE setting if the profile has no transactionType set.

Credential profiles are managed from the merchant dashboard under Settings → Credential Profiles. Create a MERCHANT_BYOC profile and copy its UUID to use here.

Response fields

Field	Type	Description
`transactionId`	string	UUID of the created transaction
`type`	string	Always `"STK"`
`status`	string	Always `"PENDING"` on initiation
`amount`	number	Payment amount in KES
`currency`	string	Always `"KES"`
`phone`	string	Normalised phone number (`254XXXXXXXXX`)
`accountReference`	string	Reference shown on customer’s M-Pesa statement
`transactionDesc`	string	Description shown on customer’s PIN prompt
`transactionFee`	number	Service wallet fee charged for this request. `0` if no fee applies.
`providerRequestId`	string \| null	Safaricom MerchantRequestID
`providerCheckoutId`	string \| null	Safaricom CheckoutRequestID
`resultCode`	string \| null	Provider result code (`"0"` = accepted)
`resultDescription`	string \| null	Provider result message
`createdAt`	string	ISO 8601 timestamp
`updatedAt`	string	ISO 8601 timestamp

STK abuse protection

If your API key initiates too many STK Pushes with a low success rate in a short window, further requests return 429 STK_TEMP_BANNED. The ban lasts 1 hour. Check details.retryAfterSeconds for the exact wait time.

Authorizations

Authorization

string

header

required

Use your API key as the username. Leave the password field empty.

Authorization: Basic <base64(apikey:)>

You can also pass the raw API key:

Authorization: Basic <apikey>

Body

application/json

amount

number<decimal>

required

Amount to charge in KES.

Required range: x >= 1

Example:

1000

phone

string

required

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

Example:

"0712345678"

accountReference

string

required

Your reference — invoice number, order ID, etc.

Maximum string length: 12

Example:

"INV-2024-001"

transactionDesc

string

required

Short description shown on the customer's PIN prompt.

Maximum string length: 13

Example:

"Payment"

callbackUrl

string<uri>

required

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

Example:

"https://yourserver.com/webhooks/mpesa"

channelId

string<uuid> | null

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

credential_id

string<uuid> | null

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.

Response

STK Push accepted. Transaction is in PENDING state.

success

boolean

required

Example:

true

data

object

required

Response payload. Shape varies by endpoint.

Show child attributes

requestId

string<uuid>

required

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

Example:

"c1b2a3d4-e5f6-7890-abcd-ef1234567890"

PHP SDK List Transactions

Documentation Index

​Key notes

​Using a credential profile (credential_id)

​Response fields

​STK abuse protection

Authorizations

Body

Response

Key notes

Using a credential profile (`credential_id`)

Response fields

STK abuse protection