M-Pesa STK Push Kenya : intégrer Daraja API en 2026

M-Pesa Safaricom domine paiements Kenya : 90 % transactions, 30M+ users. Pour vendre online Kenya, M-Pesa est non-négociable. STK Push (Sim Toolkit Push) permet checkout web/app : utilisateur entre numéro, popup paiement sur téléphone, valide PIN. Voici intégration complète Daraja API 2026.

TL;DR

- Daraja API : portail Safaricom pour intégrer M-Pesa.

- STK Push : push notification paiement sur téléphone client.

- C2B : Customer to Business (recevoir paiements clients).

- Frais : 1.5-2.5 % par transaction (négociable volumes).

Comprendre M-Pesa Kenya 2026

90 % adultes Kenya ont compte M-Pesa. Concurrent Airtel Money minoritaire.

Comptes M-Pesa Business

• Pay Bill Account
• Format : numéro Pay Bill 5-7 chiffres + Account Reference
• Usage : factures, abonnements, e-commerce

• Till Number (Buy Goods)
• Format : numéro Till 5-7 chiffres
• Usage : POS physique, restaurants, retail

• Stock Account
• Pour distribution / agents

Pour e-commerce / SaaS, Pay Bill Account = standard.

Inscription Daraja API

• Aller sur developer.safaricom.co.ke
• Créer compte développeur (gratuit)
• Créer une App :
• Sandbox d'abord (tests)
• Production après go-live + KYC
• Récupérer Consumer Key + Consumer Secret
• Demander activation produits :
• M-Pesa Express (STK Push)
• C2B
• B2C (payouts)
• Account Balance

Activation production : 5-15 jours ouvrables après demande KYC complete.

Intégration STK Push (Node.js)

Étape 1 — obtenir access token

`typescript

import axios from 'axios';

async function getMpesaToken() {

const auth = Buffer.from(

${process.env.MPESA_CONSUMER_KEY}:${process.env.MPESA_CONSUMER_SECRET}

).toString('base64');

const res = await axios.get(

'https://api.safaricom.co.ke/oauth/v1/generate?grant_type=client_credentials',

{ headers: { Authorization: Basic ${auth} } }

);

return res.data.access_token;

}

`

Étape 2 — initier STK Push

`typescript

async function initiateSTKPush({

phoneNumber, // Format : 254712345678

amount, // KES, integer

accountReference,

description,

}) {

const token = await getMpesaToken();

const timestamp = new Date()

.toISOString()

.replace(/[^0-9]/g, '')

.slice(0, 14);

const password = Buffer.from(

${process.env.MPESA_SHORTCODE}${process.env.MPESA_PASSKEY}${timestamp}

).toString('base64');

const res = await axios.post(

'https://api.safaricom.co.ke/mpesa/stkpush/v1/processrequest',

{

BusinessShortCode: process.env.MPESA_SHORTCODE,

Password: password,

Timestamp: timestamp,

TransactionType: 'CustomerPayBillOnline',

Amount: amount,

PartyA: phoneNumber,

PartyB: process.env.MPESA_SHORTCODE,

PhoneNumber: phoneNumber,

CallBackURL: ${process.env.APP_URL}/api/mpesa/callback,

AccountReference: accountReference,

TransactionDesc: description,

},

{ headers: { Authorization: Bearer ${token} } }

);

return res.data; // { CheckoutRequestID, MerchantRequestID, ... }

}

`

Étape 3 — gérer callback

`typescript

// app/api/mpesa/callback/route.ts (Next.js)

export async function POST(req: Request) {

const body = await req.json();

const callback = body.Body.stkCallback;

if (callback.ResultCode === 0) {

// Paiement réussi

const items = callback.CallbackMetadata.Item;

const amount = items.find((i) => i.Name === 'Amount').Value;

const mpesaReceipt = items.find((i) => i.Name === 'MpesaReceiptNumber').Value;

const phoneNumber = items.find((i) => i.Name === 'PhoneNumber').Value;

// Marquer transaction OK en DB

await markPaymentSuccess({

checkoutRequestId: callback.CheckoutRequestID,

mpesaReceipt,

phoneNumber,

amount,

});

} else {

// Paiement échoué (annulation, timeout, fonds insuffisants)

await markPaymentFailed({

checkoutRequestId: callback.CheckoutRequestID,

reason: callback.ResultDesc,

});

}

return Response.json({ ResultCode: 0, ResultDesc: 'Success' });

}

`

Étape 4 — vérifier statut (poll si besoin)

`typescript

async function queryTransaction(checkoutRequestId: string) {

const token = await getMpesaToken();

const timestamp = new Date()

.toISOString()

.replace(/[^0-9]/g, '')

.slice(0, 14);

const password = Buffer.from(

${SHORTCODE}${PASSKEY}${timestamp}

).toString('base64');

const res = await axios.post(

'https://api.safaricom.co.ke/mpesa/stkpushquery/v1/query',

{

BusinessShortCode: SHORTCODE,

Password: password,

Timestamp: timestamp,

CheckoutRequestID: checkoutRequestId,

},

{ headers: { Authorization: Bearer ${token} } }

);

return res.data;

}

`

UX best practices STK Push

• Format numéro : auto-prefix +254 si user tape 07XXXXXXXX
• Afficher loader pendant attente (max 60s timeout)
• Toast / sound success quand callback reçu
• Bouton "résend" si pas reçu après 30s
• Fallback Pay Bill manuel si STK Push échoue
• Stocker MpesaReceiptNumber pour réconciliation

Tarification 2026

Frais retrait business account : 50-150 KES selon montant.

Erreurs fréquentes

• Timestamp incorrect — formats hors UTC. Utiliser format YYYYMMDDHHMMSS strict.
• Callback URL non public — localhost OK sandbox. Production = HTTPS public obligatoire.
• Pas idempotence — callback peut arriver multiple fois. Vérifier MpesaReceiptNumber unique.
• Pas gérer timeout — STK Push expire 60s. Si pas de callback, query status.
• Tester direct production — sandbox d'abord obligatoire.

Daraja sandbox vs production

Sandbox :

• URL : sandbox.safaricom.co.ke
• Test phone : 254708374149
• Test PIN : 12345
• Test shortcode : 174379

Production :

• URL : api.safaricom.co.ke
• Vraie shortcode après KYC + activation
• Vraies transactions = vrai argent

Alternatives Kenya

• Airtel Money : minoritaire mais croissant
• Pesalink : transferts inter-banques rapides
• Card payments : Stripe (via Hong Kong) ou DPO Group
• Crypto : Yellow Card USDT (croissance forte 2024+)

FAQ

Q : KYC pour business Daraja ?

R : Oui. Documents société, certificat incorporation, ID directeurs, preuve adresse business.

Q : Multi-currency M-Pesa ?

R : Non. KES uniquement. Pour USD/EUR, conversion bank externe.

Q : Payouts vers M-Pesa users (B2C) ?

R : Oui via API B2C Daraja. Cas d'usage : remboursements, payroll gig workers, marketplace payouts.

Conclusion

M-Pesa STK Push Kenya 2026 = standard checkout. Daraja API mature mais setup 2-4 semaines (KYC + tests). 1.5-2.5 % frais. Toute startup vendant Kenya doit l'intégrer J1. Stack alternative : DPO Group si veut Pan-Africa unifié.