Overview Docs API Reference Examples Playground Webhooks OpenAPI JSON
← Developers
NganyaPay Developer Platform

API Docs

Build SACCO-safe integrations for vehicles, trips, passenger payments, fuel approvals, route data, fare tables, revenue visibility, and webhooks.

Base URL
https://nganyapay.online/api/v1
Auth
Authorization: Bearer ngp_sk_...

Authentication

NganyaPay APIs use Stripe-style Bearer authentication with server-side secret keys. Every key is SACCO-scoped and permissioned through API scopes. 

Authorization: Bearer ngp_sk_test_xxxxxxxxx
Never expose secret keys in frontend JavaScript, mobile apps, public repositories, screenshots, or browser clients.

Environments

Test mode

Use test keys for sandbox integrations, API testing, webhook validation, and developer onboarding.

Live mode

Live keys are for production SACCO operations and must be protected carefully.

Quick request

export NGP_API_KEY="ngp_sk_test_xxxxxxxxx"

curl https://nganyapay.online/api/v1/me \
  -H "Authorization: Bearer $NGP_API_KEY"

API Endpoints

These endpoints allow SACCO systems, fleet ERPs, finance tools, dashboards, and third-party mobility platforms to integrate with NganyaPay infrastructure.

Method Endpoint Scope Purpose
GET/healthactive keyAPI health and environment check
GET/meactive keyInspect authenticated key, SACCO, environment, and scopes
GET/vehiclesvehicles:readList SACCO vehicles
GET/vehicles/<id>/statusvehicles:readVehicle live status, GPS, driver, conductor, owner, and capacity
GET/vehicles/<id>/active-triptrips:readCurrent active trip and active-trip revenue for one vehicle
GET/tripstrips:readTrip history, statuses, start/end time, and total collected
GET/revenue/summaryrevenue:readSuccessful payments count and gross revenue summary
GET/paymentspayments:readPassenger payment records, M-Pesa checkout IDs, result codes, and transaction status
GET/fuel/paymentsfuel:readFuel requests, owner approvals, and payment status
GET/fuel/payments/<id>fuel:readSingle fuel payment detail
GET/routesroutes:readRoute catalog for the SACCO
GET/stagesroutes:readRoute stages, GPS coordinates, and ordering
GET/faresfares:readFare matrix by route, pickup, destination, and time category
GET/passengers/sessionspassengers:readPassenger sessions, payment state, receipts, seats, and attempts
GET/webhooks/eventswebhooks:readWebhook event catalog
POST/webhooks/testwebhooks:testSandbox webhook test payload validation

Common Filters

List endpoints support pagination using limit and offset. Some endpoints support additional filters. 

GET /api/v1/payments?status=success&vehicle_id=1&limit=50&offset=0
GET /api/v1/fuel/payments?approval_status=pending&vehicle_id=1
GET /api/v1/stages?route_id=1
GET /api/v1/fares?route_id=1
GET /api/v1/passengers/sessions?trip_id=16&status=paid

Example: Payments

curl https://nganyapay.online/api/v1/payments?status=success \
  -H "Authorization: Bearer $NGP_API_KEY"

Example: Fuel Payments

curl https://nganyapay.online/api/v1/fuel/payments \
  -H "Authorization: Bearer $NGP_API_KEY"

Example: Webhook Test

curl https://nganyapay.online/api/v1/webhooks/test \
  -X POST \
  -H "Authorization: Bearer $NGP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "payment.success",
    "data": {
      "vehicle_id": 1,
      "amount": "100.00",
      "currency": "KES"
    }
  }'

Webhook Events

payment.success
Passenger payment confirmed
payment.failed
Passenger payment failed
trip.started
Vehicle trip opened
trip.ended
Vehicle trip closed
fuel.requested
Fuel request submitted
fuel.approved
Owner approved fuel request
fuel.rejected
Owner rejected fuel request
fuel.confirmed
Fuel payment confirmed
vehicle.status.updated
Vehicle operational status changed

Scopes

vehicles:read
Read SACCO vehicles and vehicle status
trips:read
Read SACCO trips and active trip state
revenue:read
Read SACCO revenue summaries
payments:read
Read passenger payment records
fuel:read
Read fuel requests, approvals, and payment state
routes:read
Read routes and stages
fares:read
Read fare tables
passengers:read
Read passenger sessions
webhooks:read
Read webhook event catalog
webhooks:test
Run sandbox webhook test calls

Standard Response Format

{
  "success": true,
  "request_id": "req_xxxxx",
  "data": [],
  "meta": {
    "limit": 50,
    "offset": 0,
    "total": 100,
    "has_more": true
  }
}

Errors

{
  "error": {
    "message": "Missing Bearer token",
    "status_code": 401
  },
  "request_id": "req_xxxxx"
}

Rate limits