Sozuri Payments lets a Paybill or Till holder collect M-Pesa payments by STK Push, using their own Daraja credentials. Plug the credentials in once, and Sozuri:

• Sends an M-Pesa payment prompt to your customer’s phone — from your own system through the API, or from a hosted payment link (with a QR code) that anyone can open.
• For every confirmed payment, sends an SMS from your Sender ID to the customer who paid and to every number in Staff to Notify. Each SMS ends with a shared five-digit Zuka OTP — the cashier can ask the customer for it to confirm they really paid, which stops fake-screenshot fraud. These are ordinary SMS sent from your project.
• Forwards every confirmed payment to your webhook URL.

• Setup — Bring Your Own Shortcode
• Initiate STK Push
• Payment webhook callback
• Check payment status
• Payment link

Setup — Bring Your Own Shortcode

Register your M-Pesa credentials in your project’s Payments settings. You’ll need a Daraja API application from developer.safaricom.co.ke and an M-Pesa admin account at org.ke.m-pesa.com. To set these up, follow the steps below:

1. Apply for a Till/Paybill number by visiting a Safaricom shop or via m-pesaforbusiness.co.ke. (For assistance, the M-PESA Business Team contacts are: 0722 002 222, e-mail: [email protected].)
2. Once approved, you’ll receive:
   • Your Till/Paybill number.
   • Access to the M-PESA Business admin portal (org.ke.m-pesa.com) — if this is missing, contact the team above.
3. Create an assistant role user in the Business admin portal for Daraja verification.
4. Create a developer account at the Daraja portal: developer.safaricom.co.ke.
5. Create a sandbox app and select the “Lipa Na M-Pesa Sandbox and Paybill Sandbox” API.
6. Get your Consumer Key and Consumer Secret.
7. Click “Go Live” and select verification by shortcode.
8. Enter the assistant username (created above) and select your desired API products.
9. You’ll receive production credentials and a passkey on the Daraja portal or via email.

Now you have your Paybill/Till No., Consumer Key, Consumer Secret, and Passkey. Open your project’s Payments menu, click Configure in the top right, and fill in these fields:

Once saved, the dialog also shows a Confirmation URL. Register it with M-Pesa as your paybill’s confirmation URL if you want payments that customers make straight to your paybill (not through a prompt) to produce the same SMS and webhook. You do not need to register the STK callback URL: Sozuri sends it with every prompt.

1. Initiate STK Push

This sends an M-Pesa payment prompt to your customer’s phone. When they enter their M-Pesa PIN and the payment succeeds, Sozuri records the transaction, sends the payment SMS and posts the confirmation to your webhook. A successful response here only means the prompt was sent — the outcome arrives later, through the webhook or the status check.

Authenticate with your project’s API key as a Bearer token (or an apiKey body field — an apiKey header is not read) and send your project’s exact name in project. See Authentication.

Request parameters

Sample request

POST /api/v1/zuka/push HTTP/1.1
Host: sozuri.net
Authorization: Bearer YOUR_PROJECT_API_KEY
Content-Type: application/json
Accept: application/json

{
    "project": "Your_Project_Name",
    "phone": "0700000000",
    "amount": 500,
    "account_reference": "INV-001"
}

<?php

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL            => 'https://sozuri.net/api/v1/zuka/push',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode([
        'project'           => 'Your_Project_Name',
        'phone'             => '0700000000',
        'amount'            => 500,
        'account_reference' => 'INV-001',
    ]),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_PROJECT_API_KEY',
        'Content-Type: application/json',
        'Accept: application/json',
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

$result = json_decode($response, true);
echo $result['checkout_request_id'];

const response = await fetch('https://sozuri.net/api/v1/zuka/push', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_PROJECT_API_KEY',
        'Content-Type': 'application/json',
        'Accept': 'application/json',
    },
    body: JSON.stringify({
        project: 'Your_Project_Name',
        phone: '0700000000',
        amount: 500,
        account_reference: 'INV-001',
    }),
});

const data = await response.json();
console.log(data.checkout_request_id);

import requests

response = requests.post(
    "https://sozuri.net/api/v1/zuka/push",
    headers={
        "Authorization": "Bearer YOUR_PROJECT_API_KEY",
        "Content-Type": "application/json",
        "Accept": "application/json",
    },
    json={
        "project": "Your_Project_Name",
        "phone": "0700000000",
        "amount": 500,
        "account_reference": "INV-001",
    },
)
print(response.json())

curl --request POST 'https://sozuri.net/api/v1/zuka/push' \
    --header 'Authorization: Bearer YOUR_PROJECT_API_KEY' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --data '{
        "project": "Your_Project_Name",
        "phone": "0700000000",
        "amount": 500,
        "account_reference": "INV-001"
    }'

Success response (200)

{
    "message": "STK push sent. Prompt your customer to check their phone.",
    "checkout_request_id": "ws_CO_08112026101530123456789",
    "merchant_request_id": "12345-67890123-1"
}

Keep checkout_request_id: it is what you pass to the status check. The webhook does not carry it — match the webhook to your payment by BillRefNumber.

Errors

{
    "error_code": "AUTHENTICATION_FAILED",
    "message": "Authentication failed. Check your API key or bearer token.",
    "retryable": false
}

{
    "error_code": "VALIDATION_FAILED",
    "message": "The submitted data failed validation.",
    "retryable": false,
    "errors": {
        "phone": ["The phone must be a string."],
        "amount": ["The amount must be at least 1."]
    }
}

{
    "error": "No active paybill with STK credentials found for this project."
}

{
    "error": "Could not authenticate with M-Pesa. Check paybill credentials."
}

{
    "error": "Network error initiating payment."
}

{
    "error": "<M-Pesa's error message>"
}

Payment webhook callback

For every confirmed payment, Sozuri POSTs a JSON body to each URL in your Webhook URL setting. That covers prompts sent through the API or your payment link, and — if you registered the Confirmation URL with M-Pesa — payments made straight to your paybill. A payment produces one webhook per URL, even when M-Pesa reports it to Sozuri twice.

• Only successful payments are sent. A prompt the customer cancels, ignores, or cannot pay sends nothing — use the status check to see a failure.
• One attempt, no retries. Your response is not read, so any status code is fine, but a URL that is down when the payment arrives misses it. If a URL cannot be connected to at all (unknown host, connection refused), the URLs listed after it miss that payment too, so list your most important URL first.
• Not signed. The request carries no signature or key. Before releasing high-value goods, confirm the TransID and amount in your M-Pesa statement.

Request headers

POST {your webhook URL}
Content-Type: application/json
Accept: application/json

Webhook body — payment from a prompt

{
    "TransactionType": "Pay Bill",
    "TransID": "TKA0000000",
    "TransTime": "20261108101530",
    "TransAmount": "500",
    "BusinessShortCode": "123456",
    "BillRefNumber": "INV-001",
    "InvoiceNumber": "",
    "OrgAccountBalance": "",
    "ThirdPartyTransID": "",
    "MSISDN": "254700000000",
    "FirstName": "",
    "MiddleName": "",
    "LastName": ""
}

Webhook body — payment straight to your paybill

For a payment M-Pesa reports to your Confirmation URL, Sozuri forwards M-Pesa’s own confirmation unchanged. It has the same fields as above, filled with M-Pesa’s values: TransactionType as M-Pesa names it, TransAmount with decimals (for example "500.00"), BillRefNumber as the account number the customer entered, and the payer’s number and names as M-Pesa supplies them. If a prompt payment is also reported this way, you receive whichever of the two reports reaches Sozuri first.

Check payment status

After sending a prompt, you can ask for its outcome with the checkout_request_id from the push response. This is the check your payment link page runs; it needs no API key.

Request

{code} is your payment-link code — the last part of your payment link.

curl https://sozuri.net/zuka/pay/YOUR_PAYMENT_LINK_CODE/status/ws_CO_08112026101530123456789

Responses (always HTTP 200)

// Pending
{ "status": "pending", "trans_id": "", "amount": "500" }

// Confirmed
{ "status": "confirmed", "trans_id": "TKA0000000", "amount": "500" }

// Failed
{ "status": "fail", "trans_id": "", "amount": "500" }

// Unknown checkout_request_id
{ "status": "pending" }

amount is a string of whole shillings. An id Sozuri has no record of also answers pending, with no other fields.

2. Payment link

Every project with saved payment settings gets a hosted payment page anyone can open and pay from — no code required. Find it, with a QR code and Copy and Preview buttons, on your project’s Payments page.

https://sozuri.net/zuka/pay/{your-payment-link-code}

The page shows your Business Name and paybill number. The customer enters their M-Pesa number, the amount, and optionally a reference of up to 12 characters (your paybill number is used when they leave it blank), then receives an STK Push. The page checks for the result every 5 seconds for up to 2 minutes and shows confirmed, failed or timed out. A confirmed payment produces the same SMS and webhook as a prompt sent through the API. Share the link over WhatsApp, print the QR code on a receipt, or link to it from your portal.

The page needs your Consumer Key, Consumer Secret and Passkey: without them, sending a prompt from it fails with Payment link is not active.