The Easiest Ways to Integrate M-Pesa Automatic Payouts (B2C)

B2C (Business to Customer) is the M-Pesa product that moves money from a business to a person's phone: salaries, loan disbursements, refunds, rider and agent commissions, marketplace seller payouts, betting and gaming winnings. Doing it by hand from the M-Pesa portal works for ten payments a month. It breaks the moment payouts depend on events in your own product.

This guide compares the three realistic ways to automate M-Pesa payouts in Kenya, then walks through a production-ready integration with PalPluss — the option we built to make B2C a single API call.

Option 1: PalPluss B2C API (easiest)

PalPluss holds the Safaricom-side B2C configuration for you. You fund a B2C wallet, generate an API key in the console, and call POST /v1/b2c/payouts. There is no shortcode application, no initiator password and no certificate encryption on your side.

• One request per payout — amount, phone number, your own reference and an optional callback URL.
• Automatic reversals — if M-Pesa rejects a payout, the amount is credited back to your B2C wallet without manual action.
• Idempotency built in — send an Idempotency-Key header and retries never pay twice.
• Transparent fees — a tiered fee from KES 6 per payout, deducted from your service wallet. See pricing.
• Duplicate-payout protection — the API rejects a second payout to the same number within 60 seconds (429 B2C_PAYOUT_COOLDOWN), stopping double-clicks and runaway loops from emptying your float.

Option 2: Safaricom Daraja B2C directly

Daraja is Safaricom's own developer platform. Integrating B2C directly gives you full control and no platform fee, but expect real setup work before the first shilling moves:

1. Apply for a B2C-enabled shortcode and go-live approval for your organisation.
2. Create an initiator user on the M-Pesa organisation portal.
3. Encrypt the initiator password with Safaricom's public certificate to produce the SecurityCredential.
4. Implement OAuth token generation and refresh.
5. Call the B2C payment request endpoint, then correlate asynchronous results by ConversationID on a public ResultURL and QueueTimeOutURL.
6. Build your own retry, reversal and reconciliation logic.

Direct Daraja makes sense for large organisations with a dedicated payments team. For most startups the engineering and approval time costs more than a platform fee.

Option 3: Multi-country payment aggregators

Pan-African gateways also offer mobile-money payouts alongside cards. They are a good fit when you need many countries in one contract. The trade-off for a Kenya-first product is usually percentage-based pricing, longer onboarding, and M-Pesa treated as one channel among dozens rather than the core product.

Side-by-side comparison

Send your first automatic payout with PalPluss

1. Create an account and pass KYC

Register at console.palpluss.com. B2C payouts are unlocked once your KYC is approved — requests before approval return 403 KYC_NOT_VERIFIED.

2. Fund your wallets

Top up your B2C wallet (the float payouts are sent from) and your service wallet (which pays per-transaction fees). Both can be topped up by STK Push from the console or through the API.

3. Send the payout

curl -X POST https://api.palpluss.com/v1/b2c/payouts \
  -u "$PALPLUSS_API_KEY:" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payout-order-1042" \
  -d '{
    "amount": 1500,
    "phone": "0712345678",
    "reference": "ORDER-1042",
    "callbackUrl": "https://yourapp.com/webhooks/palpluss"
  }'

Prefer a typed client? The official Node.js SDK generates the idempotency key for you:

import { PalPluss } from "@palpluss/sdk";

const palpluss = new PalPluss({ apiKey: process.env.PALPLUSS_API_KEY });

const payout = await palpluss.b2cPayout(
  { amount: 1500, phone: "254712345678", reference: "ORDER-1042" },
  { idempotencyKey: "payout-order-1042" },
);

console.log(payout.status); // PROCESSING — final result arrives by webhook

4. Handle the webhook

Payouts settle asynchronously, usually within 30 seconds to 5 minutes. PalPluss sends a POST to your callbackUrl when the payout reaches SUCCESS or FAILED. Treat that callback as the source of truth, and make your handler idempotent because a callback can be delivered more than once.

app.post("/webhooks/palpluss", async (req, res) => {
  const { transaction } = req.body;

  // Ignore repeats — the same event may be delivered more than once.
  if (await alreadyProcessed(transaction.id)) return res.sendStatus(200);

  if (transaction.status === "SUCCESS") {
    await markPaid(transaction.external_reference, transaction.mpesa_receipt);
  } else if (transaction.status === "FAILED") {
    // The amount is already back in your B2C wallet.
    await markPayoutFailed(transaction.external_reference, transaction.result_desc);
  }

  res.sendStatus(200);
});

Best practices for automated payouts

• Use one idempotency key per business event (for example the withdrawal or order ID). A retried request then returns the original payout instead of paying twice.
• Never mark a payout complete from the API response alone — PROCESSING means accepted, not delivered. Wait for the webhook.
• Keep a float buffer in your B2C wallet sized to at least a day of payouts, and monitor it with the balance endpoint.
• Respect the per-number cooldown — if you genuinely need two payouts to one person, combine them or wait for details.retryAfterSeconds.
• Validate amounts server-side. The minimum payout is KES 10.