paylod CLI: M-Pesa from your terminal

The paylod CLI sends a real M-Pesa STK Push from your terminal. The CLI also decodes Daraja result codes offline. The CLI also forwards live webhooks to localhost without ngrok. The CLI uses the same API as the API reference.

npm install -g @paylod/cli

The package is @paylod/cli. The package installs the command paylod. Source: github.com/mosesmrima/paylod-cli.

You can also run the CLI without installation:

npx @paylod/cli errors 1032

The CLI needs Node 20 or newer.

Set up

paylod init

init opens your browser and signs you in. Then init lets you pick an application. Then init mints an API key for this machine. The CLI puts the credentials in your OS keychain. If your machine has no keychain, the CLI uses a 0600 file under ~/.config/paylod.

To only sign in, use these commands:

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

In CI, do not sign in. Set PAYLOD_API_KEY in the environment. Every data-plane command (collect, status, listen) uses that environment variable.

Take a payment

paylod collect --phone 254712345678 --amount 100

The customer receives the STK Push prompt on the handset. The CLI polls until the payment settles. Then the CLI prints the outcome. On success, the outcome is an M-Pesa receipt. On failure, the outcome is a decoded reason.

To read a payment later, or to watch a payment settle, use these commands:

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

status decodes the failure reason for you. You do not have to read 2001 in a PDF.

Decode a result code

This command works offline. It needs no login, no network and 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

Use this command to find the meaning of a code such as 2001 quickly during an incident. The error reference shows the same catalogue.

Webhooks on localhost, without ngrok

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

listen streams the live webhook events of your application. listen then sends each event again to your local server. The signature stays intact. Therefore your code verifies a real signature against a real payload. You need no tunnel, no public URL and no ngrok.

To get a new signing secret, or to read the current signing secret, use this command:

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. simulate makes no Daraja call, uses no handset and moves no money. Use simulate to test 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. Exit code 5 is not a failure. It means that the customer did not answer the prompt yet. On a settled failure, the CLI exits with a non-zero code. The JSON output then contains the decoded reason.

Environment variables

Next

• To build an application and not a script, use the Node SDK.
• To set up an AI agent, use the MCP server. The MCP server shows the same capabilities as tools.
• To read about the HTTP endpoints below the CLI, see the API reference.