API ReferenceTransactions
Create STK Push Transaction
Create an STK Push transaction to collect money from a phone number. Current-account deposits require the account owner's phone number; credit-account repayments may use any payer phone number.
Header Parameters
Idempotency-Key?string
Unique key that de-duplicates retries of this request: the first call executes and its response is stored, identical retries replay it, and reusing a key with a different request body is rejected with 409 Conflict.
Length
length <= 255Request Body
application/json
Request to initiate STK Push payment collection
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/transactions/mpesa/stk-push" \ -H "Content-Type: application/json" \ -d '{ "account_id": "550e8400-e29b-41d4-a716-446655440000", "amount": { "value": 150000, "currency": "KES" }, "mobile_number": "+254712345678" }'{ "id": "550e8400-e29b-41d4-a716-446655440000", "resource_id": "trx_2n1t201rmv87aae5j4csam8000", "mpesa_transaction_id": "ABCDE12345", "amount": { "value": 100000, "currency": "KES" }, "fee_amount": { "value": 5000, "currency": "KES" }, "status": "POSTED", "failure_reason": null, "transacted_at": "2025-10-20T10:30:00Z", "confirmed_at": "2025-10-20T10:30:05Z", "posted_at": "2025-10-20T10:30:10Z", "failed_at": null, "details": { "type": "BUY_GOODS", "till_number": "12345" }}{ "code": "BAD_REQUEST", "description": "Bad Request"}{ "code": "UNAUTHORISED", "description": "Unauthorised"}{ "code": "WAITING_LIST", "description": "User is in the waiting list"}{ "code": "TOO_MANY_REQUESTS", "description": "Too Many Requests"}{ "code": "INTERNAL_SERVER_ERROR", "description": "Internal Server Error"}