# 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.

```text title="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. |

```bash title="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"
  }'
```

```json title="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.

```text title="Endpoint"
POST https://paylod.dev/functions/v1/c2b-register
```

```bash title="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 '{}'
```

```json title="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.

```text title="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. |

```bash title="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"
  }'
```

```json title="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.

```text title="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. |

```bash title="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 '{}'
```

```json title="Response · 202 Accepted"
{
  "queryId": "9a8b7c6d-…",
  "conversationId": "AG_20260707_00005e6f7a8b"
}
```