Getting Started

Quick Start Guide

Get up and running in 5 minutes. From registration to your first M-Pesa payment.

Prerequisites

  • PayNexus merchant account
  • API keys from the PayNexus dashboard
  • Web server with HTTPS capability (for webhooks)
  • HTTP client library (curl, Guzzle, axios, requests, etc.)

1. Register and Get API Keys

Sign up at paynexus.co.ke/register and generate your API keys from the dashboard.

1

Create Account

Register with your email and verify your account.

2

Add Business

Register your business details in the dashboard.

3

Add Payment Account

Link your M-Pesa Till or Paybill number.

4

Get Keys

Copy your public key (pk_...) and secret key (sk_...).

2. Make Your First Payment

Send a single cURL request to initiate an STK Push payment. The system auto-normalizes the phone number and selects your default payment account.

bash 
curl -X POST "https://paynexus.co.ke/api/mpesa/payment/initiate" \
  -H "X-API-Key: sk_your_secret_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10,
    "phone": "0746990866",
    "description": "Order #12345"
  }'
Auto-Features

The API automatically normalizes phone numbers (0746990866 → 254746990866) and selects your default M-Pesa payment account.

3. Check Payment Status

Use the payment reference returned from the initiate call to check status:

bash 
curl -X GET "https://paynexus.co.ke/api/payments/PNXABC123DEF" \
  -H "X-API-Key: pk_your_public_key_here"

4. Set Up Webhooks

Register a webhook to receive real-time payment notifications:

bash 
curl -X POST "https://paynexus.co.ke/api/webhooks/register" \
  -H "X-API-Key: sk_your_secret_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Payment Webhook",
    "url": "https://your-domain.com/webhook/mpesa",
    "events": ["payment.completed", "payment.failed"]
  }'

5. Test in Sandbox

Use sandbox API keys (prefix sb_) to test without real money:

bash 
curl -X POST "https://paynexus.co.ke/api/mpesa/payment/initiate" \
  -H "X-API-Key: sb_your_sandbox_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10,
    "phone": "0746990866",
    "description": "Test payment"
  }'
Sandbox Limits

Maximum 50 KES per payment, 30 API calls per day. Test payments route to PayNexus test till 5374081.