Overview Docs API Reference Examples Playground Webhooks OpenAPI JSON
← Developers
API Reference

NganyaPay API v1 Reference

Full public reference for SACCO-scoped transport infrastructure endpoints. All examples use sandbox credentials.

Base URL: https://nganyapay.online/api/v1
Authentication: Authorization: Bearer ngp_sk_test_xxxxxxxxx
GET

Health Check

/api/v1/health
active key

Check API availability, environment, and request ID behavior. 

curl https://nganyapay.online/api/v1/health \
  -H "Authorization: Bearer ngp_sk_test_xxxxxxxxx"
GET

Authenticated Key Context

/api/v1/me
active key

Inspect the authenticated API key, SACCO context, environment, and scopes. 

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

List Vehicles

/api/v1/vehicles
vehicles:read

List vehicles owned by the authenticated SACCO. 

curl "https://nganyapay.online/api/v1/vehicles?limit=50&offset=0" \
  -H "Authorization: Bearer ngp_sk_test_xxxxxxxxx"
GET

Vehicle Status

/api/v1/vehicles/<id>/status
vehicles:read

Read one vehicle's operational status, capacity, GPS, assigned driver, conductor, owner, and route. 

curl https://nganyapay.online/api/v1/vehicles/1/status \
  -H "Authorization: Bearer ngp_sk_test_xxxxxxxxx"
GET

Vehicle Active Trip

/api/v1/vehicles/<id>/active-trip
trips:read

Read the current active trip and active-trip revenue for a specific vehicle. 

curl https://nganyapay.online/api/v1/vehicles/1/active-trip \
  -H "Authorization: Bearer ngp_sk_test_xxxxxxxxx"
GET

List Trips

/api/v1/trips
trips:read

List SACCO trips, statuses, timestamps, vehicle assignment, and collected totals. 

curl "https://nganyapay.online/api/v1/trips?limit=50&offset=0" \
  -H "Authorization: Bearer ngp_sk_test_xxxxxxxxx"
GET

Revenue Summary

/api/v1/revenue/summary
revenue:read

Read a SACCO-scoped summary of successful payments and gross revenue. 

curl https://nganyapay.online/api/v1/revenue/summary \
  -H "Authorization: Bearer ngp_sk_test_xxxxxxxxx"
GET

List Passenger Payments

/api/v1/payments
payments:read

List passenger payment records, checkout IDs, M-Pesa references, payment state, and revenue-recording status. 

curl "https://nganyapay.online/api/v1/payments?limit=50&offset=0" \
  -H "Authorization: Bearer ngp_sk_test_xxxxxxxxx"
GET

List Fuel Payments

/api/v1/fuel/payments
fuel:read

List fuel requests, owner approval state, station details, amount, and payment status. 

curl "https://nganyapay.online/api/v1/fuel/payments?limit=50&offset=0" \
  -H "Authorization: Bearer ngp_sk_test_xxxxxxxxx"
GET

Fuel Payment Detail

/api/v1/fuel/payments/<id>
fuel:read

Read full details for one SACCO-owned fuel payment request. 

curl https://nganyapay.online/api/v1/fuel/payments/1 \
  -H "Authorization: Bearer ngp_sk_test_xxxxxxxxx"
GET

List Routes

/api/v1/routes
routes:read

List SACCO route catalog data. 

curl "https://nganyapay.online/api/v1/routes?limit=50&offset=0" \
  -H "Authorization: Bearer ngp_sk_test_xxxxxxxxx"
GET

List Stages

/api/v1/stages
routes:read

List route stages, GPS coordinates, and ordering. Supports route_id filtering. 

curl "https://nganyapay.online/api/v1/stages?route_id=1&limit=50&offset=0" \
  -H "Authorization: Bearer ngp_sk_test_xxxxxxxxx"
GET

List Fares

/api/v1/fares
fares:read

List fare matrix entries by route, pickup stage, destination stage, and time category. 

curl "https://nganyapay.online/api/v1/fares?route_id=1&limit=50&offset=0" \
  -H "Authorization: Bearer ngp_sk_test_xxxxxxxxx"
GET

Passenger Sessions

/api/v1/passengers/sessions
passengers:read

List passenger sessions, seat numbers, payment statuses, receipts, and attempts. 

curl "https://nganyapay.online/api/v1/passengers/sessions?limit=50&offset=0" \
  -H "Authorization: Bearer ngp_sk_test_xxxxxxxxx"
GET

Dashboard Summary

/api/v1/dashboard/summary
dashboard:read

Main SACCO dashboard metrics including revenue, passengers, active trips, fleet, and operational KPIs. 

curl https://nganyapay.online/api/v1/dashboard/summary \\n  -H "Authorization: Bearer ngp_sk_test_xxxxxxxxx"
GET

Fleet Status

/api/v1/fleet/status
vehicles:read

Fleet-wide operational status including live revenue, fuel costs, passengers, and trip visibility. 

curl "https://nganyapay.online/api/v1/fleet/status?limit=50&offset=0" \\n  -H "Authorization: Bearer ngp_sk_test_xxxxxxxxx"
GET

Route Performance

/api/v1/routes/performance
routes:read

Route-level revenue, trip volume, and operational performance metrics. 

curl https://nganyapay.online/api/v1/routes/performance \\n  -H "Authorization: Bearer ngp_sk_test_xxxxxxxxx"
GET

Management Summary

/api/v1/management/summary
management:read

Counts and summaries for vehicles, drivers, conductors, owners, routes, stages, and fares. 

curl https://nganyapay.online/api/v1/management/summary \\n  -H "Authorization: Bearer ngp_sk_test_xxxxxxxxx"
GET

Management Resources

/api/v1/management/resources
management:read

Read-only management resources for ERP integrations. 

curl "https://nganyapay.online/api/v1/management/resources?limit=50&offset=0" \\n  -H "Authorization: Bearer ngp_sk_test_xxxxxxxxx"
GET

Trip Integrity Report

/api/v1/integrity/trips
management:read

Read-only trip lifecycle integrity audit showing stale trips, duplicate active trips, driver mismatches, vehicle mismatches, and route integrity issues. 

curl "https://nganyapay.online/api/v1/integrity/trips?stale_hours=18" \\n  -H "Authorization: Bearer ngp_sk_test_xxxxxxxxx"
GET

Vehicle Monitor

/api/v1/vehicles/<id>/monitor
vehicles:read

Live vehicle monitoring including trip activity, payments, fuel activity, and operational state. 

curl https://nganyapay.online/api/v1/vehicles/1/monitor \\n  -H "Authorization: Bearer ngp_sk_test_xxxxxxxxx"
GET

List Payouts

/api/v1/payouts
payouts:read

Owner, driver, conductor, SACCO, and NganyaPay payout transactions. 

curl "https://nganyapay.online/api/v1/payouts?limit=50&offset=0" \\n  -H "Authorization: Bearer ngp_sk_test_xxxxxxxxx"
GET

Payout Detail

/api/v1/payouts/<id>
payouts:read

Read a single payout transaction. 

curl https://nganyapay.online/api/v1/payouts/1 \\n  -H "Authorization: Bearer ngp_sk_test_xxxxxxxxx"
GET

Daily Revenue Reports

/api/v1/reports/daily-revenue
reports:read

Daily revenue, fuel cost, net revenue, and payout split reports. 

curl "https://nganyapay.online/api/v1/reports/daily-revenue?limit=50&offset=0" \\n  -H "Authorization: Bearer ngp_sk_test_xxxxxxxxx"
GET

Webhook Event Catalog

/api/v1/webhooks/events
webhooks:read

List supported NganyaPay webhook event names. 

curl https://nganyapay.online/api/v1/webhooks/events \
  -H "Authorization: Bearer ngp_sk_test_xxxxxxxxx"
POST

Webhook Test Event

/api/v1/webhooks/test
webhooks:test

Submit a sandbox webhook test payload for validation. 

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

Standard Response

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