paylod
Introduction

Get started

paylod: M-Pesa payments without a backend

.md

paylod is M-Pesa (Safaricom Daraja) without the backend: one HTTP call sends the STK Push, we host the callback, sign your webhooks and decode every result code.

What paylod is

paylod is a hosted layer over Safaricom's Daraja API. You keep your own till or paybill, and your own Daraja credentials. M-Pesa settles the money straight to you. paylod never holds the money and never takes a part of it.

paylod does the difficult work for you. You do not host a public HTTPS callback. You do not refresh access tokens. You do not retry failed STK pushes. You do not decode resultCode: 1037. You do not build a webhook signature scheme.

import { Paylod } from "@paylod/node";

const paylod = new Paylod(process.env.PAYLOD_API_KEY!);

const outcome = await paylod.collectAndWait({
  amount: 100,
  phone: "0712345678",
  idempotencyKey: attempt.id,   // one key per payment attempt
});

if (outcome.paid) console.log("Paid:", outcome.receipt);
else console.log(outcome.message);   // already decoded, safe to show a customer

That is the full integration. Install @paylod/node and use one API key. paylod does the other work. If you do not use Node, make the same call over plain HTTP. See the API reference.

How it works

  1. Create an application for a till or a paybill. Then put your Daraja consumer key, consumer secret, shortcode and passkey into the application. paylod encrypts these four values at rest, and the values never leave the server.
  2. paylod gives you a hosted callback URL. Copy the callback URL into the Safaricom Daraja portal one time. That is the only Safaricom procedure that you do.
  3. Your backend calls collect() with an amount and a phone number, and with a paylod API key. The customer's handset shows an M-Pesa PIN prompt.
  4. M-Pesa sends the result to paylod's callback. paylod puts the result into a standard format, decodes the result code, and records the payment. Then paylod sends you a signed webhook, or you poll for the result. You select the method.

Your integration must never let the client set the amount. Your server owns the amount. See Secure integration.

Where to start

If you want to…Go to
Send your first STK push nowQuickstart
Use the Node/TypeScript clientNode SDK
Send a payment from your terminalCLI
Understand keys, environments and idempotencyAuthentication
Charge a customer correctly, in productionAccept a payment
Know when the money is in your accountHandle the result
Find the parameters of an endpointAPI reference
Find what 1032 meansError codes
Let an AI agent do all of the aboveMCP server

What you can build

  • Checkout — collect a payment for an order. Fulfil the order when the webhook confirms the settled amount.
  • Payouts — send money to customers, riders or staff (B2C). Reverse a transaction when you must refund a customer.
  • Offline payments — register C2B, and counter payments to your till then reach your systems. Or give the customer a dynamic QR code.
  • Operations — read a past transaction by receipt, or read the float of your shortcode.

Each item above is one SDK call, or one HTTP request. Each item uses one API key. You host no callback.