Take payments
M-Pesa payment prompts
Send an M-Pesa payment prompt to a payer's phone; the money lands in one of your wallets.
POST
/v1/collect/stkSigned · collect · Idempotency-KeySeeSigning requestsKeys and scopesWebhooks for the resultErrors
| Field | Required | Meaning |
|---|---|---|
wallet_id | Yes | Where the money lands: one of the account's wallets |
phone | Yes | The payer's phone, e.g. 0712345678 |
amount | Yes | KES, at least 1, at most 250,000, like "1500" or "1500.50" |
external_reference | Yes | Your reference: 1 to 64 of A-Z a-z 0-9 _ . : / -, unique for the app |
description | No | Shown on the statement (200 characters) |
include_bank_charges | No | true: the payer pays the deposit charge on top |
paypoint_id | No | One of your paypoints: the payment shows on its statement |
const payment = await tukupay.collect.mpesa({
wallet_id: 7, phone: "0712345678", amount: "1500", external_reference: "order-1042",
});
// payment.status is "pending": the payer now types their M-Pesa PIN on their phoneWhat happens next
- The answer is
201with the paymentpending. - The payer sees the prompt on their phone and confirms with their own M-Pesa PIN (or ignores it).
- You learn the outcome by checking every 30 seconds (
GET /transactions/external/order-1042), or from thepayment.completed/payment.failedwebhooks. - Hand over the goods only when the status is
completed.
Idempotency: no double charges
Send a new Idempotency-Key for each payment, and the same key when you retry the same payment (after a timeout, say). The same key with the same body within 24 hours answers the first result again (200, header Idempotent-Replayed: true) instead of prompting the payer twice; with a different body it is 409 idempotency_key_reused. An external_reference the app already used is 409 external_reference_taken. The libraries make the key from your external_reference for you.