CLI

The paylod CLI sends a real M-Pesa STK Push from your terminal, decodes Daraja result codes offline, and forwards live webhooks to localhost without ngrok. It talks to the same API documented in the API reference.

npm install -g @paylod/cli

The package is @paylod/cli; the command it installs is paylod.

Or run it without installing:

npx @paylod/cli errors 1032

Node 20 or newer.

Set up

paylod init

init signs you in (it opens your browser), lets you pick an application, and mints an API key for this machine. Credentials go into your OS keychain, or a 0600 file under ~/.config/paylod if there is no keychain available.

If you only want to sign in:

paylod login
paylod whoami       # who am I, and where is the token stored?

For CI, skip the login entirely and set PAYLOD_API_KEY in the environment. Every data-plane command (collect, status, listen) will use it.

Take a payment

paylod collect --phone 254712345678 --amount 100

The customer's phone rings. The CLI polls until the payment settles and prints the outcome — an M-Pesa receipt on success, or a decoded reason on failure.

Look a payment up later, or watch it settle:

paylod status e69e5c00-8a01-44ed-b003-48e2e86a7c9e
paylod status e69e5c00-8a01-44ed-b003-48e2e86a7c9e --watch

status decodes the failure reason for you — you never have to look 2001 up in a PDF.

Decode a result code

Offline. No login, no network, no API key.

paylod errors 1032          # why did that payment fail?
paylod errors --list        # the whole catalogue
paylod errors 2001 --json   # machine-readable, for your error handler

This is the fastest way to answer "what does 2001 mean" mid-incident. The same catalogue is browsable in the error reference.

Webhooks on localhost, without ngrok

paylod listen --forward http://localhost:3000/webhook

listen streams your application's live webhook events and re-POSTs each one to your local server, with the signature intact — so the code you are writing verifies a real signature against a real payload. No tunnel, no public URL, no ngrok.

Roll (or fetch) the signing secret with:

paylod webhooks secret

Test without spending money

paylod simulate --outcome user_cancelled
paylod simulate --interactive

simulate creates a payment in the paylod sandbox and forces an outcome — no Daraja call, no handset, no money. It is how you exercise your failure paths in CI.

Manage the integration

These commands do everything the dashboard does.

Scripting

Every command takes a global --json flag and prints machine-readable output.

paylod collect -p 254712345678 -a 100 --json | jq -r '.mpesaReceipt'

paylod collect exits 5 if the payment is still pending when the timeout expires — which is not a failure, just an unanswered prompt. A non-zero exit on a settled failure carries the decoded reason in the JSON.

Environment variables

Next

• Building an app rather than a script? Use the Node SDK.
• Wiring an AI agent? The MCP server exposes the same capabilities as tools.
• The HTTP endpoints underneath: API reference.