API reference

M-Pesa API overview: base URL, auth, conventions

The base URL, the auth header, the request/response conventions, and an index of every paylod endpoint.

Base URL

https://paylod.dev/functions/v1

Authentication

Every endpoint needs a bearer API key. The API key identifies the application and the environment. No request carries a shortcode or a Daraja credential.

Header

Authorization: Bearer mp_live_YOUR_API_KEY

See Authentication for API keys, environments, idempotency and rate limits.

Endpoints

Method	Path	What it does
`POST`	`/collect`	Send an STK Push to a customer's handset
`GET`	`/status/:id`	Read a payment's current state
`POST`	`/payout`	Send money out to a customer (B2C)
`POST`	`/reversal`	Reverse or refund a completed transaction
`POST`	`/qr-generate`	Generate a dynamic Lipa na M-Pesa QR code
`POST`	`/c2b-register`	Register the offline C2B confirmation URL and validation URL
`POST`	`/transaction-status`	Read a past transaction by its receipt
`POST`	`/account-balance`	Read your shortcode's M-Pesa float

Synchronous and asynchronous endpoints

M-Pesa is an asynchronous network. The paylod API keeps that behaviour visible.

`200 OK` — the answer is in the response body. Only GET /status/:id, POST /qr-generate and POST /c2b-register work this way.
`202 Accepted` — paylod accepted the request and sent it to M-Pesa. The final outcome comes later on your webhook. For /collect you can also poll GET /status/:id. The response body carries an id for correlation.

Four endpoints move money or read the ledger: /payout, /reversal, /transaction-status and /account-balance. For these four endpoints you must also set the application's Initiator Name and Initiator Password. See Go live.

Errors

Status	Meaning
`400`	The JSON is malformed, or you did not set Daraja credentials for this application and environment
`401`	The API key is missing or invalid
`404`	The resource does not exist, or it belongs to another application
`409`	You reused the idempotency key with a different body. Or the first request is still in flight. Or an interrupted provider call spent the key
`422`	The body failed validation
`429`	You reached the rate limit
`502`	Daraja rejected the request. paylod passes the upstream error through

The error reference decodes M-Pesa's own result codes, such as 1032, 1037 and 2001.