SYSNAV M-Pesa Payment Gateway

Complete API Reference

← Back to Home Public Endpoints Protected Endpoints

Public Endpoints

These endpoints don't require authentication.

POST /api/v1/clients

register

Register a new M-Pesa client account.

curl -X POST https://payments.navipos.co.ke/api/v1/clients \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Business",
    "email": "admin@mybusiness.com",
    "phone": "254712345678"
  }'
POST /api/v1/webhooks/mpesa

webhook

Receive M-Pesa payment notifications (POST from M-Pesa servers).

// M-Pesa will POST to your webhook with payment results
POST /api/v1/webhooks/mpesa HTTP/1.1
Host: payments.navipos.co.keContent-Type: application/json

{
  "Body": {
    "stkCallback": {
      "MerchantRequestID": "...",
      "CheckoutRequestID": "...",
      "ResultCode": 0,
      "ResultDesc": "The service request has been processed successfully."
    }
  }
}
POST /api/v1/health

health

Check API health and status (GET request).

curl -X GET https://payments.navipos.co.ke/api/v1/health
POST /api/v1/c2b-validation

c2b validation

Receive C2B validation requests from M-Pesa (Safaricom will POST to this URL).

// M-Pesa will POST validation data
POST /api/v1/c2b-validation HTTP/1.1
Host: payments.navipos.co.keContent-Type: application/json

{
  "TransactionType": "C2B",
  "TransID": "R3G3W12345",
  "TransTime": "20240314000000",
  "TransAmount": "100",
  "BusinessShortCode": "123456",
  "BillRefNumber": "ORDER-123",
  "InvoiceNumber": "",
  "OrgAccountBalance": "",
  "ThirdPartyTransID": "",
  "MSISDN": "254712345678",
  "FirstName": "John",
  "MiddleName": "Doe",
  "LastName": ""
}
POST /api/v1/c2b-confirmation

c2b confirmation

Receive C2B confirmation requests from M-Pesa (Safaricom will POST to this URL).

// M-Pesa will POST confirmation data
POST /api/v1/c2b-confirmation HTTP/1.1
Host: payments.navipos.co.keContent-Type: application/json

{
  "TransactionType": "C2B",
  "TransID": "R3G3W12345",
  "TransTime": "20240314000000",
  "TransAmount": "100",
  "BusinessShortCode": "123456",
  "BillRefNumber": "ORDER-123",
  "InvoiceNumber": "",
  "OrgAccountBalance": "",
  "ThirdPartyTransID": "",
  "MSISDN": "254712345678",
  "FirstName": "John",
  "MiddleName": "Doe",
  "LastName": ""
}

Protected Endpoints

These endpoints require API Key authentication via X-API-Key header or Bearer token.

GET /api/v1/clients AUTH REQUIRED

get client

Retrieve client account details.

curl -X GET https://payments.navipos.co.ke/api/v1/clients \
  -H "X-API-Key: your_api_key"
POST /api/v1/clients/{clientId}/credentials AUTH REQUIRED

store credentials

Store M-Pesa Daraja credentials (encrypted in database) with environment.

curl -X POST https://payments.navipos.co.ke/api/v1/clients/CLIENT_ID/credentials \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "consumerKey": "your_daraja_consumer_key",
    "consumerSecret": "your_daraja_consumer_secret",
    "shortcode": "174379",
    "passkey": "bfb279f9aa9bdbcf158e97dd71a467cd2e0c893059b10f78e6b72ada1ed2c919",
    "initiatorName": "testapi",
    "initiatorPassword": "your_initiator_password",
    "environment": "production"
  }'
POST /api/v1/stk-push AUTH REQUIRED

stk push

Initiate M-Pesa STK Push payment request.

curl -X POST https://payments.navipos.co.ke/api/v1/stk-push \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "your_client_id",
    "phoneNumber": "254712345678",
    "amount": 1000,
    "accountReference": "ORDER-123",
    "transactionDesc": "Payment for order"
  }'
POST /api/v1/c2b-register AUTH REQUIRED

c2b register

Register C2B validation and confirmation URLs with Safaricom.

curl -X POST https://payments.navipos.co.ke/api/v1/c2b-register \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "shortCode": "123456",
    "validationUrl": "https://yourapp.com/api/v1/c2b-validation",
    "confirmationUrl": "https://yourapp.com/api/v1/c2b-confirmation"
  }'
POST /api/v1/c2b-simulate AUTH REQUIRED

c2b simulate

Simulate C2B payment (sandbox only).

curl -X POST https://payments.navipos.co.ke/api/v1/c2b-simulate \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "shortCode": "123456",
    "phoneNumber": "254712345678",
    "amount": 100,
    "billRefNumber": "ORDER-123"
  }'
GET /api/v1/transactions AUTH REQUIRED

list transactions

List all transactions for your client account.

curl -X GET "https://payments.navipos.co.ke/api/v1/transactions?status=completed&limit=50" \
  -H "X-API-Key: your_api_key"
GET /api/v1/transactions/{transactionId} AUTH REQUIRED

get transaction

Get details for a specific transaction.

curl -X GET https://payments.navipos.co.ke/api/v1/transactions/TRANSACTION_ID \
  -H "X-API-Key: your_api_key"

Error Handling

All error responses include a standard error object:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid phone number",
    "details": {
      "phone": "Must be 12 digits starting with 254"
    }
  }
}

Response Format

All successful responses follow this format:

{
  "success": true,
  "data": {
    // Response data here
  },
  "meta": {
    "timestamp": 1704067200,
    "version": "v1"
  }
}