Billyangu

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