TukuPay Docs

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-Key

SeeSigning requestsKeys and scopesWebhooks for the resultErrors

FieldRequiredMeaning
wallet_idYesWhere the money lands: one of the account's wallets
phoneYesThe payer's phone, e.g. 0712345678
amountYesKES, at least 1, at most 250,000, like "1500" or "1500.50"
external_referenceYesYour reference: 1 to 64 of A-Z a-z 0-9 _ . : / -, unique for the app
descriptionNoShown on the statement (200 characters)
include_bank_chargesNotrue: the payer pays the deposit charge on top
paypoint_idNoOne 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 phone

What happens next

  1. The answer is 201 with the payment pending.
  2. The payer sees the prompt on their phone and confirms with their own M-Pesa PIN (or ignores it).
  3. You learn the outcome by checking every 30 seconds (GET /transactions/external/order-1042), or from the payment.completed / payment.failed webhooks.
  4. 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.