Billyangu API
Base URL https://billyangu.co.ke/api/v1. Authenticate with an API key from your dashboard: Authorization: Bearer by_live_…. Amounts are whole Kenya shillings.
Start an M-Pesa payment (STK push)
POST /api/v1/payments/stk
{ "amount": 500, "phone": "0712345678", "reference": "ORDER-1001",
"description": "Order 1001", "callback_url": "https://example.com/webhook" }
Returns 201 with the payment (status: "pending"). The customer gets a PIN prompt. reference is your own ID; a reference that is already paid is refused with 409.
Check a payment
GET /api/v1/payments/BYP-1A2B3C4D
{ "id": "BYP-1A2B3C4D", "status": "success", "amount": 500, "fee": 8, "net": 492, "currency": "KES",
"mpesa_receipt": "RKT1ABC2DE", "reference": "ORDER-1001", "phone": "2547****678", ... }
Other endpoints
GET /api/v1/payments?limit=50 GET /api/v1/balance GET /api/v1/account (your paybill account number)
Webhooks
We POST {"event":"payment.succeeded"|"payment.failed","data":{…payment…}} to your webhook URL (or the payment's callback_url). Retries back off for about 4 hours until you answer 2xx.
Verify the X-Billyangu-Signature: t=<unix time>,v1=<hex> header: v1 = HMAC_SHA256(webhook_secret, t + "." + raw_body). Reject if t is more than 5 minutes old.
// Node.js
const [t, v1] = sig.split(',').map(p => p.split('=')[1]);
const ok = crypto.timingSafeEqual(Buffer.from(v1, 'hex'),
crypto.createHmac('sha256', secret).update(t + '.' + rawBody).digest());
Paybill payments
Customers can also pay directly: Paybill …, account number = your Billyangu account number, optionally followed by -yourref. These arrive as payment.succeeded with source: "c2b".