Build with NganyaPay API v1

Practical examples for connecting SACCO ERPs, fleet tools, finance systems, dashboards, and mobility apps to NganyaPay infrastructure.

Security: Keep secret keys on your server. Never expose ngp_sk_... keys in browser JavaScript, mobile apps, screenshots, or public repositories.

cURL quickstart

REST

Start by inspecting your API key context.

export NGP_API_KEY="ngp_sk_test_xxxxxxxxx"

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

Python: fetch payments

requests

Pull passenger payment records into a SACCO finance or accounting system.

import os
import requests

API_KEY = os.environ["NGANYAPAY_API_KEY"]

response = requests.get(
    "https://nganyapay.online/api/v1/payments",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Accept": "application/json",
    },
    params={
        "status": "success",
        "limit": 50,
        "offset": 0,
    },
    timeout=20,
)

response.raise_for_status()
data = response.json()

for payment in data.get("data", []):
    print(payment["id"], payment["amount"], payment["status"])

Node.js: active vehicle trip

fetch

Read live active-trip revenue for a specific vehicle.

const apiKey = process.env.NGANYAPAY_API_KEY;
const vehicleId = 1;

const response = await fetch(
  `https://nganyapay.online/api/v1/vehicles/${vehicleId}/active-trip`,
  {
    headers: {
      Authorization: `Bearer ${apiKey}`,
      Accept: "application/json",
    },
  }
);

const data = await response.json();
console.log(data);

Fuel intelligence integration

OPEX

Pull fuel requests and approval states into a fleet expense dashboard.

curl "https://nganyapay.online/api/v1/fuel/payments?approval_status=pending&limit=20&offset=0" \
  -H "Authorization: Bearer $NGP_API_KEY"

Fuel payment data helps SACCOs reconcile revenue against operating expenses and reduce unauthorized fuel spending.

Routes, stages, and fares

Network data

Use route and fare APIs to sync a SACCO's transport network into external systems.

# List routes
curl "https://nganyapay.online/api/v1/routes?limit=50&offset=0" \
  -H "Authorization: Bearer $NGP_API_KEY"

# List stages for a route
curl "https://nganyapay.online/api/v1/stages?route_id=1&limit=50&offset=0" \
  -H "Authorization: Bearer $NGP_API_KEY"

# List fares for a route
curl "https://nganyapay.online/api/v1/fares?route_id=1&limit=50&offset=0" \
  -H "Authorization: Bearer $NGP_API_KEY"

Passenger sessions

Operations

Pull session state for seats, payment attempts, passenger status, and receipts.

curl "https://nganyapay.online/api/v1/passengers/sessions?trip_id=16&status=paid&limit=50&offset=0" \
  -H "Authorization: Bearer $NGP_API_KEY"

Webhook test event

POST

Validate your integration flow with a sandbox webhook test payload.

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"
    }
  }'

Error handling

{
  "error": {
    "message": "Invalid or revoked API key",
    "status_code": 401
  },
  "request_id": "req_xxxxxxxxx"
}

Always log request_id when debugging integrations with NganyaPay support teams.