Initiate M-Pesa Business Payment (Paybill/Till)

POST

http://localhost:8080/api/v3/pay-bill

POST

/api/v3/pay-bill

curl -X POST http://localhost:8080/api/v3/pay-bill \
     -H "Authorization: Bearer {{accessToken}}" \
     -H "Idempotency-Key: idem-{{$guid}}" \
     -H "X-Device-Id: {{deviceId}}" \
     -H "X-Request-Id: {{requestId}}" \
     -H "X-Signature: {{signature}}" \
     -H "X-Timestamp: {{timestamp}}" \
     -H "Content-Type: application/json" \
     -d '{
  "walletId": "b1e7f6a0-9d2b-4a5b-9c3d-1a2b3c4d5e6f",
  "amount": 500,
  "category": "MPESA_PAYBILL",
  "shortCode": "888880",
  "referenceNumber": "ACC-12345",
  "description": "September rent"
}'

200Wallet_initiateMPesaBusinessPaymentPaybillTill_example

{
  "code": 200,
  "message": "Payment initiated.",
  "data": {
    "transactionId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5f",
    "walletId": "b1e7f6a0-9d2b-4a5b-9c3d-1a2b3c4d5e6f",
    "amount": 500,
    "fee": 0,
    "category": "MPESA_PAYBILL",
    "destination": "888880",
    "status": "INITIATED",
    "reference": "TX-2026-000126",
    "timestamp": "2026-09-17T10:00:00Z"
  }
}

category must be MPESA_PAYBILL (requires referenceNumber) or MPESA_TILL (referenceNumber optional). shortCode is the paybill/till number.

Headers

Request

This endpoint expects an object.

walletIdstringOptional

amountintegerOptional

categorystringOptional

shortCodestringOptionalformat: "color"

referenceNumberstringOptional

descriptionstringOptional

Response

200 OK

codeintegerOptional

messagestringOptional

dataobjectOptional