API overview
NetPay exposes a merchant-scoped M2M API. Authenticate with client credentials, initiate STK Push, and consume payment state from provider-backed evidence.
1. Authenticate (M2M)
Exchange client id and secret for a short-lived bearer token. Tokens are scoped to a merchant. Never embed secrets in public apps.
2. Merchant integration
Onboard each merchant with their Daraja consumer key/secret, passkey, and shortcode. Credentials are encrypted at rest. OAuth success proves authentication capability, not every Daraja product permission.
3. STK Push
Initiate a prompt with amount (KES), phone, and client reference. Use an idempotency key on mutating calls. Acceptance of initiation is not confirmation of payment.
4. Callbacks and events
NetPay hosts STK callback URLs per integration. Results are correlated and deduplicated. Optional signed webhooks deliver durable payment events to your systems.
Example
POST /api/v1/payments/stk-push
Authorization: Bearer <access-token>
Idempotency-Key: order-123-attempt-1
Content-Type: application/json
{
"integration_id": "<merchant-integration-id>",
"client_reference": "order-123",
"amount_minor": 250000,
"currency": "KES",
"phone_number": "0712345678",
"description": "Order payment"
}Response is a payment resource. Final success/failure follows provider evidence—not this HTTP acknowledgement alone.
Limits to plan around
- Transaction Status and some Daraja products need extra initiator configuration.
- C2B external validation rules are basic unless you enable and configure C2B.
- Dashboard sign-in is not the integration path until NetHub identity ships.