API Documentation

curl -X POST https://api.sunpay.co.ke/api/v1/payments/stk-push \
  -H "Authorization: Bearer sp_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "254712345678",
    "amount": 1000,
    "externalRef": "ORDER-123",
    "settleTo": {
      "type": "paybill",
      "shortcode": "400200",
      "accountReference": "SHOP-42"
    }
  }'

# Forwarding to a Till instead of a Paybill
{
  "amount": 1000,
  "phoneNumber": "254712345678",
  "settleTo": {
    "type": "till",
    "shortcode": "555888"
  }
}

{
  "event": "settlement.completed",
  "timestamp": "2026-05-26T10:30:00.000Z",
  "data": {
    "transactionId": "uuid-transaction-id",
    "settlementRef": "QJG7A5BKLN",
    "amount": "985",
    "settleToShortcode": "400200",
    "settleToType": "paybill",
    "settleToAccountReference": "SHOP-42",
    "resultCode": 0,
    "resultDesc": "The service request is processed successfully."
  }
}

Business → Business (B2B)

Transfer funds from your business to another business's Paybill or Till. Use for supplier payments and inter-company transfers.

curl -X POST https://api.sunpay.co.ke/api/v1/payments/b2b \
  -H "Authorization: Bearer sp_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "receiverShortcode": "600000",
    "amount": 5000,
    "accountReference": "SUPPLIER-PAY-001",
    "remarks": "Payment for goods",
    "commandId": "BusinessPayBill"
  }'

{
  "success": true,
  "message": "B2B payment initiated",
  "conversationId": "AG_20260125_...",
  "originatorConversationId": "uuid..."
}

Look up the current status of a payment by transaction ID.

curl https://api.sunpay.co.ke/api/v1/payments/{transaction_id} \
  -H "Authorization: Bearer sp_your_api_key_here"

{
  "id": "uuid-transaction-id",
  "status": "completed",
  "amount": "100.00",
  "phoneNumber": "254712345678",
  "mpesaRef": "QJG7A5BKLN",
  "createdAt": "2024-01-22T10:30:00Z"
}

Possible status values

// Registered webhooks (Settings → Webhooks)
// Signed with HMAC-SHA256 in X-Webhook-Signature header
{
  "event": "payment.completed",
  "timestamp": "2026-03-16T14:22:05.123Z",
  "data": {
    "transactionId": "uuid-transaction-id",
    "externalRef": "ORDER-123",
    "subReference": null,
    "status": "completed",
    "paymentType": "stk_push",
    "mpesaRef": "QJG7A5BKLN",
    "amount": "100.00",
    "phoneNumber": "254712345678",
    "payerName": "JOHN DOE",
    "resultCode": 0,
    "resultDesc": "The service request is processed successfully."
  }
}

// Per-transaction callbackUrl (passed in your API request)
// Plain POST, no signature — just the data object
{
  "transactionId": "uuid-transaction-id",
  "externalRef": "ORDER-123",
  "subReference": null,
  "status": "completed",
  "paymentType": "stk_push",
  "mpesaRef": "QJG7A5BKLN",
  "amount": "100.00",
  "phoneNumber": "254712345678",
  "payerName": "JOHN DOE",
  "resultCode": 0,
  "resultDesc": "The service request is processed successfully."
}

Payload fields

const crypto = require('crypto');

function verifyWebhook(rawBody, signatureHeader, webhookSecret) {
  const expected = crypto
    .createHmac('sha256', webhookSecret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader),
    Buffer.from(expected)
  );
}

// Express example
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['x-webhook-signature'];
  if (!verifyWebhook(req.body, sig, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  const { event, data } = JSON.parse(req.body);
  console.log('Event:', event, 'Ref:', data.externalRef);
  res.sendStatus(200);
});

Events you can subscribe to

// sunpay.js — drop-in SunPay client for a Node/Express POS backend
// npm install axios express
const axios = require('axios');
const crypto = require('crypto');

const API_KEY        = process.env.SUNPAY_API_KEY;        // sp_xxx
const WEBHOOK_SECRET = process.env.SUNPAY_WEBHOOK_SECRET; // from Settings → Webhooks
const BASE_URL       = 'https://api.sunpay.co.ke/api/v1';

const sp = axios.create({
  baseURL: BASE_URL,
  headers: { Authorization: `Bearer ${API_KEY}` },
  timeout: 15000,
});

// --- 1. STK Push (cashier enters customer phone) ---
async function chargeStkPush({ phone, amount, receiptNo, shop }) {
  const { data } = await sp.post('/payments/stk-push', {
    phoneNumber:  phone,            // "254712345678"
    amount,                         // 1200
    externalRef:  receiptNo,        // "RCPT-2026-0001"
    callbackUrl:  'https://your-pos.com/sunpay/webhook',
    settleTo: shop && {             // optional — route to a specific till/paybill
      type:             shop.type,           // "till" | "paybill"
      shortcode:        shop.shortcode,
      accountReference: shop.accountReference, // required for paybill
    },
  });
  return data; // { transactionId, checkoutRequestId, ... }
}

// --- 2. Paybill / C2B (customer pays from M-Pesa menu) ---
async function expectPaybillPayment({ amount, receiptNo, shop }) {
  const { data } = await sp.post('/payments/expect', {
    amount,
    externalRef: receiptNo,
    callbackUrl: 'https://your-pos.com/sunpay/webhook',
    settleTo: shop && {
      type: shop.type, shortcode: shop.shortcode, accountReference: shop.accountReference,
    },
  });
  // data.instructions = { paybill, accountNumber, amount } — show this on the POS screen
  return data;
}

// --- 3. Poll for status (fallback when webhook is slow/blocked) ---
async function getPayment(transactionId) {
  const { data } = await sp.get(`/payments/${transactionId}`);
  return data; // { id, status: "pending"|"completed"|"failed", mpesaRef, ... }
}

async function waitForPayment(transactionId, { timeoutMs = 60_000, intervalMs = 2000 } = {}) {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const tx = await getPayment(transactionId);
    if (tx.status === 'completed' || tx.status === 'failed') return tx;
    await new Promise(r => setTimeout(r, intervalMs));
  }
  throw new Error('Payment timeout');
}

// --- 4. Signed webhook receiver (mount on your Express app) ---
function verifySignature(rawBody, signatureHeader) {
  if (!signatureHeader) return false;
  const expected = crypto.createHmac('sha256', WEBHOOK_SECRET).update(rawBody).digest('hex');
  const a = Buffer.from(signatureHeader);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

function mountWebhook(app, handler) {
  app.post('/sunpay/webhook',
    require('express').raw({ type: 'application/json' }),
    (req, res) => {
      if (!verifySignature(req.body, req.headers['x-webhook-signature'])) {
        return res.status(401).send('bad signature');
      }
      const { event, data } = JSON.parse(req.body.toString('utf8'));
      // Reply 200 immediately, process async — never block the webhook
      res.sendStatus(200);
      Promise.resolve(handler(event, data)).catch(err =>
        console.error('webhook handler error', err)
      );
    }
  );
}

module.exports = {
  chargeStkPush, expectPaybillPayment, getPayment, waitForPayment, mountWebhook,
};

/* ---------- Example usage in your POS server ---------- */
// const express = require('express');
// const sunpay  = require('./sunpay');
// const app = express();
//
// app.post('/api/sales/:id/charge', express.json(), async (req, res) => {
//   const sale = await db.sales.find(req.params.id);
//   const tx = await sunpay.chargeStkPush({
//     phone:     req.body.phone,
//     amount:    sale.total,
//     receiptNo: sale.receiptNo,
//     shop:      { type: 'paybill', shortcode: sale.shop.paybill, accountReference: sale.shop.code },
//   });
//   res.json({ transactionId: tx.transactionId });
// });
//
// sunpay.mountWebhook(app, async (event, data) => {
//   if (event === 'payment.completed') {
//     await db.sales.markPaid(data.externalRef, { mpesaRef: data.mpesaRef });
//     printer.printReceipt(data.externalRef);
//   }
// });
//
// app.listen(3000);

# sunpay.py — drop-in SunPay client for a Python/Flask POS backend
# pip install requests flask
import os, hmac, hashlib, time, json
import requests
from flask import request, abort

API_KEY        = os.environ['SUNPAY_API_KEY']
WEBHOOK_SECRET = os.environ['SUNPAY_WEBHOOK_SECRET']
BASE_URL       = 'https://api.sunpay.co.ke/api/v1'

_session = requests.Session()
_session.headers.update({'Authorization': f'Bearer {API_KEY}'})

def _settle_to(shop):
    if not shop: return None
    return {
        'type':             shop['type'],            # "till" | "paybill"
        'shortcode':        shop['shortcode'],
        'accountReference': shop.get('accountReference'),
    }

# --- 1. STK Push ---
def charge_stk_push(phone, amount, receipt_no, shop=None):
    payload = {
        'phoneNumber': phone, 'amount': amount, 'externalRef': receipt_no,
        'callbackUrl': 'https://your-pos.com/sunpay/webhook',
    }
    if shop: payload['settleTo'] = _settle_to(shop)
    r = _session.post(f'{BASE_URL}/payments/stk-push', json=payload, timeout=15)
    r.raise_for_status()
    return r.json()

# --- 2. Paybill / C2B ---
def expect_paybill_payment(amount, receipt_no, shop=None):
    payload = {
        'amount': amount, 'externalRef': receipt_no,
        'callbackUrl': 'https://your-pos.com/sunpay/webhook',
    }
    if shop: payload['settleTo'] = _settle_to(shop)
    r = _session.post(f'{BASE_URL}/payments/expect', json=payload, timeout=15)
    r.raise_for_status()
    return r.json()  # ['instructions'] = { paybill, accountNumber, amount }

# --- 3. Poll ---
def get_payment(transaction_id):
    r = _session.get(f'{BASE_URL}/payments/{transaction_id}', timeout=15)
    r.raise_for_status()
    return r.json()

def wait_for_payment(transaction_id, timeout_s=60, interval_s=2):
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        tx = get_payment(transaction_id)
        if tx['status'] in ('completed', 'failed'):
            return tx
        time.sleep(interval_s)
    raise TimeoutError('payment timeout')

# --- 4. Signed webhook (Flask) ---
def _verify(raw_body: bytes, signature: str) -> bool:
    if not signature: return False
    expected = hmac.new(WEBHOOK_SECRET.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

def webhook_view(handler):
    """Wire as: app.add_url_rule('/sunpay/webhook', view_func=webhook_view(my_handler), methods=['POST'])"""
    def view():
        raw = request.get_data()
        if not _verify(raw, request.headers.get('X-Webhook-Signature', '')):
            abort(401)
        body = json.loads(raw)
        try:
            handler(body['event'], body['data'])
        except Exception as e:
            # Log it, but still 200 — never make Safaricom/SunPay retry forever
            print('webhook handler error', e)
        return '', 200
    view.__name__ = 'sunpay_webhook'
    return view

# ---------- Example usage ----------
# from flask import Flask
# import sunpay, db, printer
#
# app = Flask(__name__)
#
# def on_event(event, data):
#     if event == 'payment.completed':
#         db.mark_paid(data['externalRef'], data['mpesaRef'])
#         printer.print_receipt(data['externalRef'])
#
# app.add_url_rule('/sunpay/webhook', view_func=sunpay.webhook_view(on_event), methods=['POST'])
#
# @app.post('/sales/<sale_id>/charge')
# def charge(sale_id):
#     sale = db.find(sale_id)
#     tx = sunpay.charge_stk_push(
#         phone=request.json['phone'], amount=sale.total, receipt_no=sale.receipt_no,
#         shop={'type': 'paybill', 'shortcode': sale.shop.paybill, 'accountReference': sale.shop.code},
#     )
#     return tx

<?php
// sunpay.php — drop-in SunPay client for a PHP POS backend
// Requires PHP 7.4+ with curl extension

class SunPay {
    private string $apiKey;
    private string $webhookSecret;
    private string $baseUrl = 'https://api.sunpay.co.ke/api/v1';

    public function __construct(string $apiKey, string $webhookSecret) {
        $this->apiKey = $apiKey;
        $this->webhookSecret = $webhookSecret;
    }

    // ---- 1. STK Push ----
    public function chargeStkPush(string $phone, int $amount, string $receiptNo, ?array $shop = null): array {
        $body = [
            'phoneNumber' => $phone, 'amount' => $amount, 'externalRef' => $receiptNo,
            'callbackUrl' => 'https://your-pos.com/sunpay/webhook',
        ];
        if ($shop) $body['settleTo'] = $shop; // ['type'=>'till|paybill','shortcode'=>'..','accountReference'=>'..']
        return $this->post('/payments/stk-push', $body);
    }

    // ---- 2. Paybill / C2B ----
    public function expectPaybillPayment(int $amount, string $receiptNo, ?array $shop = null): array {
        $body = [
            'amount' => $amount, 'externalRef' => $receiptNo,
            'callbackUrl' => 'https://your-pos.com/sunpay/webhook',
        ];
        if ($shop) $body['settleTo'] = $shop;
        return $this->post('/payments/expect', $body); // ['instructions'] = paybill+accountNumber+amount
    }

    // ---- 3. Poll ----
    public function getPayment(string $transactionId): array {
        return $this->get("/payments/{$transactionId}");
    }

    public function waitForPayment(string $transactionId, int $timeoutS = 60, int $intervalS = 2): array {
        $deadline = time() + $timeoutS;
        while (time() < $deadline) {
            $tx = $this->getPayment($transactionId);
            if (in_array($tx['status'], ['completed', 'failed'], true)) return $tx;
            sleep($intervalS);
        }
        throw new RuntimeException('payment timeout');
    }

    // ---- 4. Webhook verification ----
    public function verifyWebhook(string $rawBody, string $signature): bool {
        $expected = hash_hmac('sha256', $rawBody, $this->webhookSecret);
        return hash_equals($expected, $signature);
    }

    // ---- HTTP helpers ----
    private function post(string $path, array $body): array {
        return $this->request('POST', $path, $body);
    }
    private function get(string $path): array {
        return $this->request('GET', $path, null);
    }
    private function request(string $method, string $path, ?array $body): array {
        $ch = curl_init($this->baseUrl . $path);
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_CUSTOMREQUEST  => $method,
            CURLOPT_TIMEOUT        => 15,
            CURLOPT_HTTPHEADER     => [
                'Authorization: Bearer ' . $this->apiKey,
                'Content-Type: application/json',
            ],
            CURLOPT_POSTFIELDS     => $body !== null ? json_encode($body) : null,
        ]);
        $resp = curl_exec($ch);
        $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        $err  = curl_error($ch);
        curl_close($ch);
        if ($resp === false) throw new RuntimeException("HTTP error: $err");
        if ($code >= 400) throw new RuntimeException("SunPay $code: $resp");
        return json_decode($resp, true);
    }
}

/* ---------- Example usage: webhook receiver (webhook.php) ---------- */
// $sp = new SunPay(getenv('SUNPAY_API_KEY'), getenv('SUNPAY_WEBHOOK_SECRET'));
// $raw = file_get_contents('php://input');
// $sig = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
// if (!$sp->verifyWebhook($raw, $sig)) { http_response_code(401); exit('bad signature'); }
// $body = json_decode($raw, true);
// if ($body['event'] === 'payment.completed') {
//     $d = $body['data'];
//     mark_sale_paid($d['externalRef'], $d['mpesaRef'], $d['amount']);
//     print_receipt($d['externalRef']);
// }
// http_response_code(200);

/* ---------- Example usage: charge endpoint (charge.php) ---------- */
// $sp = new SunPay(getenv('SUNPAY_API_KEY'), getenv('SUNPAY_WEBHOOK_SECRET'));
// $input = json_decode(file_get_contents('php://input'), true);
// $sale  = find_sale($input['saleId']);
// $tx = $sp->chargeStkPush($input['phone'], $sale['total'], $sale['receiptNo'], [
//     'type' => 'paybill', 'shortcode' => $sale['shop']['paybill'], 'accountReference' => $sale['shop']['code'],
// ]);
// header('Content-Type: application/json');
// echo json_encode($tx);

const axios = require('axios');

const API_KEY = 'sp_your_api_key_here';
const BASE_URL = 'https://api.sunpay.co.ke/api/v1';

async function initiatePayment(phone, amount, orderId) {
  const { data } = await axios.post(`${BASE_URL}/payments/stk-push`, {
    phoneNumber: phone,
    amount,
    externalRef: orderId,
    callbackUrl: 'https://your-site.com/webhook',
  }, {
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
    },
  });
  return data;
}

initiatePayment('254712345678', 100, 'ORDER-456')
  .then(r => console.log('Initiated:', r))
  .catch(e => console.error('Error:', e.response?.data));

import requests

API_KEY = 'sp_your_api_key_here'
BASE_URL = 'https://api.sunpay.co.ke/api/v1'

def initiate_payment(phone, amount, order_id):
    r = requests.post(
        f'{BASE_URL}/payments/stk-push',
        json={
            'phoneNumber': phone,
            'amount': amount,
            'externalRef': order_id,
            'callbackUrl': 'https://your-site.com/webhook',
        },
        headers={
            'Authorization': f'Bearer {API_KEY}',
            'Content-Type': 'application/json',
        },
    )
    return r.json()

print(initiate_payment('254712345678', 100, 'ORDER-789'))