Partner API

Ask a payer to send you KES over M-PESA

Sends an STK Push prompt to the number you name. The payer approves it on their own handset with their PIN — there is no OTP for you to handle and no way for you to complete it on their behalf. The deposit lands in your own KES account, which is resolved from your verified business and is not something you can specify. This returns as soon as the prompt is out, so treat the response as pending: the completion signal is the credit.received webhook, and a prompt the payer declines or ignores produces no event at all. There is no idempotency key. A repeated call is a second prompt, and if the payer approves both then both deposits land and each raises its own credit.received.

post/v1/funding/mpesa-push

Request

Base URL
https://sandbox.onlink.africa
Auth
API key in header X-OnLink-Key

Request body

phonestring required

The payer mobile number to prompt, in any recognised Kenyan format — +254712345678, 254712345678, 0712345678 or 0112345678. Normalised server-side to the form the bank requires, so you can send the number as you hold it.

amountstring required

Amount in WHOLE KES, as a decimal string, at most 150,000 — the M-PESA per-transaction limit. M-PESA does not process decimals on an inbound customer-to-business push, so "100.50" is refused rather than rounded, and a leading zero is refused rather than normalised.

Example request

{
  "phone": "254700000000",
  "amount": "1000"
}

Response

The prompt was sent. Nothing has moved yet.

pushIdstring required

An opaque handle for this push. Quote it to support if a prompt never arrived or a deposit never landed. There is no route that reads it, and it is NOT the transactionId on the credit.received event — that id belongs to a record created later, when the money actually clears.

status'pending' required

Always pending. The payer has been prompted on their handset and nothing has moved. The completion signal is the credit.received webhook; a prompt the payer declines or ignores produces no event at all.

Example response

{
  "pushId": "SBXTX0000001",
  "status": "pending"
}

Changes

No recorded changes to this operation across all 1 revision of this API.