API reference

QR, C2B & queries

Generate an M-Pesa QR code, register offline C2B URLs, and query transaction status or account balance.

The rest of the Daraja surface, on the same hosted, credential-abstracted model: the same base URL, the same bearer key, no shortcode on the wire.

POST /qr-generate

Generate a dynamic Lipa na M-Pesa QR code for a specific amount. Synchronous — returns a base64-encoded PNG you render for the customer to scan. Stateless: no ledger row is created here. When the customer pays, the payment arrives later via your C2B confirmation URL (source c2b) and a signed webhook, exactly like any other offline payment.

Endpoint

POST https://paylod.dev/functions/v1/qr-generate

Body

Field	Type	Required	Description
`amount`	number	Required	Amount to encode in the QR. Must be greater than 0.
`refNo`	string	Optional	Reference shown to the customer. Up to 64 chars.
`merchantName`	string	Optional	Merchant / display name. Up to 64 chars.
`trxCode`	string	Optional	`BG` Buy Goods (till), `PB` Pay Bill, `WA` Withdraw at Agent, `SB` Send to Business, `SM` Send Money. Defaults to `BG`.
`cpi`	string	Optional	Credit Party Identifier (till / paybill). Defaults to the tenant shortcode.
`size`	string	Optional	Requested QR image size in pixels.

Request

curl -X POST https://paylod.dev/functions/v1/qr-generate \
  -H "Authorization: Bearer mp_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500,
    "refNo": "INV-2041",
    "merchantName": "Acme Ltd",
    "trxCode": "BG"
  }'

Response · 200 OK

{
  "qrBase64": "iVBORw0KGgoAAAANSUhEUgAAAP…"
}

POST /c2b-register

Register the offline C2B (Lipa na M-Pesa paybill / till) confirmation and validation URLs for your shortcode. Idempotent — safe to re-run. No body is required: the shortcode and callback URL are derived server-side from your API key.

After registering, offline customer payments to the till or paybill are delivered to paylod as C2B confirmations, recorded as payments (source c2b), and a signed webhook fires — the same envelope as STK payments.

Endpoint

POST https://paylod.dev/functions/v1/c2b-register

Request

curl -X POST https://paylod.dev/functions/v1/c2b-register \
  -H "Authorization: Bearer mp_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response · 200 OK

{
  "registered": true,
  "shortcode": "600123",
  "confirmationUrl": "https://paylod.dev/functions/v1/c2b-hook?app=…",
  "validationUrl": "https://paylod.dev/functions/v1/c2b-hook?app=…&validate=1",
  "responseCode": "0",
  "responseDescription": "Success"
}

responseCode and responseDescription echo Daraja's registration acknowledgement, and may be null if the shortcode was already registered.

POST /transaction-status

Query the status of any historical M-Pesa transaction by its receipt. Asynchronous — the HTTP call acknowledges with 202; the real answer arrives on a signed webhook of type admin.transaction_status. Requires the application's Initiator Name and Initiator Password.

Endpoint

POST https://paylod.dev/functions/v1/transaction-status

Body

Field	Type	Required	Description
`transactionId`	string	Required	The M-Pesa receipt / TransactionID to look up.
`identifierType`	string	Optional	`1` MSISDN, `2` till, `4` shortcode. Defaults to `4`.
`remarks`	string	Optional	Free-text remarks for the query.
`occasion`	string	Optional	Optional occasion label.

Request

curl -X POST https://paylod.dev/functions/v1/transaction-status \
  -H "Authorization: Bearer mp_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "UG1F3A1U7J",
    "identifierType": "4"
  }'

Response · 202 Accepted

{
  "queryId": "b1e2c3d4-…",
  "conversationId": "AG_20260707_00001a2b3c4d"
}

Correlate the webhook via queryId or conversationId.

POST /account-balance

Query your shortcode's M-Pesa float. Asynchronous — acknowledges with 202; the answer arrives on a signed webhook of type admin.account_balance. Requires the application's Initiator Name and Initiator Password.

Endpoint

POST https://paylod.dev/functions/v1/account-balance

Body

Field	Type	Required	Description
`identifierType`	string	Optional	`1` MSISDN, `2` till, `4` shortcode. Defaults to `4`.
`remarks`	string	Optional	Free-text remarks for the query.

Request

curl -X POST https://paylod.dev/functions/v1/account-balance \
  -H "Authorization: Bearer mp_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response · 202 Accepted

{
  "queryId": "9a8b7c6d-…",
  "conversationId": "AG_20260707_00005e6f7a8b"
}