Internext Pay API

RESTful API for processing M-Pesa payments via the platform's payment gateway.

Base URL: https://your-domain.com/api
Content-Type: application/json
API Version: v1
Rate Limit: 1000 requests/minute per API key

STK push requests use the platform's payment gateway integration to prompt the customer's M-Pesa app for payment authorization. Once the customer approves, the funds are collected by the platform and then disbursed to the recipient's phone, Till, Paybill, or bank account.

Authentication

All API requests (except registration and login) require an X-API-Key and X-API-Secret pair. You can generate and manage API keys from your web dashboard at Settings → API Keys.

Header Method

Headers 
X-API-Key: your_api_key_here
X-API-Secret: your_api_secret_here

Bearer Token Method (Compact)

Headers 
Authorization: Bearer your_api_key.your_api_secret

Register (No Auth Required)

POST   /api/auth/register 
Content-Type: application/json

{
  "full_name": "John Doe",
  "email": "john@example.com",
  "phone": "2547XXXXXXXX",
  "password": "securepassword123",
  "confirm_password": "securepassword123"
}

Response: Returns api_key and api_secret along with the user ID.

Login

POST   /api/auth/login 
Content-Type: application/json

{
  "email": "john@example.com",
  "password": "securepassword123"
}

Get Profile

GET   /api/auth/profile 
X-API-Key: your_api_key
X-API-Secret: your_api_secret

API Key Management

Generate, rotate, and revoke API keys from your web dashboard. Navigate to Settings → API Keys to manage your credentials.

Generate an API Key

Web Form 
POST /settings.php
Content-Type: application/x-www-form-urlencoded
csrf_token: <your_csrf_token>
action: create_api_key
label: Production Server
expires_days: 0

On success, the response renders your new API Key and API Secret on the page. Store these securely — they are only shown once.

Delete an API Key

Web Form 
POST /settings.php
Content-Type: application/x-www-form-urlencoded
csrf_token: <your_csrf_token>
action: delete_api_key
key_id: 5

API key management (generation and revocation) is performed through the authenticated web dashboard. API key pairs are used for authenticating programmatic API calls, not for generating other keys.

STK Push

Send an STK push prompt to a phone number. The amount is collected through the platform's payment gateway integration and then made available for disbursement to any recipient method.

POST   /api/payments/stk_push 
Content-Type: application/json
X-API-Key: your_api_key
X-API-Secret: your_api_secret

{
  "phone": "2547XXXXXXXX",
  "amount": 100,
  "reference": "Invoice #1234",
  "description": "Payment for goods"
}
Response (200) 
{
  "status": "success",
  "message": "STK push initiated successfully",
  "data": {
    "checkout_request_id": "wsbkcc-2c8a-4e3e-9c5c-1234567890",
    "amount": 100,
    "phone": "2547XXXXXXXX",
    "reference": "Invoice #1234"
  }
}

Check Payment Status

GET   /api/payments/status/{checkout_request_id} 
X-API-Key: your_api_key
X-API-Secret: your_api_secret

Disbursement

Disburse funds to any recipient via M-Pesa B2C, B2B, or Bank.

POST   /api/payments/disburse 
Content-Type: application/json
X-API-Key: your_api_key
X-API-Secret: your_api_secret

{
  "recipient_type": "phone",
  "phone": "2547XXXXXXXX",
  "amount": 500,
  "reference": "Payout #001",
  "description": "Commission payment"
}

Recipient Types

Examples 
// Phone
{
  "recipient_type": "phone",
  "phone": "2547XXXXXXXX",
  "amount": 500
}

// Till
{
  "recipient_type": "till",
  "till": "123456",
  "amount": 500
}

// Paybill
{
  "recipient_type": "paybill",
  "paybill": "123456",
  "amount": 500
}
Bank 
// Bank
{
  "recipient_type": "bank",
  "account_number": "1234567890",
  "bank_code": "02",
  "bank_name": "Equity Bank",
  "amount": 500
}

Send to Saved Recipient

POST   /api/payments/disburse 
Content-Type: application/json

{
  "recipient_type": "recipient",
  "recipient_id": 5,
  "amount": 500
}

Transactions

GET   /api/transactions 
GET /api/transactions?limit=50&offset=0&status=completed&type=b2c
X-API-Key: your_api_key
X-API-Secret: your_api_secret

Query params: limit, offset, status, type, direction

Get Transaction by UUID

GET   /api/transactions/{uuid} 
X-API-Key: your_api_key
X-API-Secret: your_api_secret

Get Statistics

GET   /api/transactions/stats 
X-API-Key: your_api_key
X-API-Secret: your_api_secret

Recipients

GET   /api/recipients 
X-API-Key: your_api_key
X-API-Secret: your_api_secret

Add Recipient

POST   /api/recipients 
Content-Type: application/json

{
  "recipient_type": "phone",
  "recipient_value": "2547XXXXXXXX",
  "recipient_name": "Jane Doe"
}

Delete Recipient

DELETE   /api/recipients/{id} 
X-API-Key: your_api_key
X-API-Secret: your_api_secret

Wallet

GET   /api/wallet 
X-API-Key: your_api_key
X-API-Secret: your_api_secret
Response (200) 
{
  "status": "success",
  "data": {
    "balance": 1250.50,
    "pending_balance": 0,
    "currency": "KES"
  }
}

Webhooks & Callbacks

Configure callback URLs in your .env to receive real-time payment notifications from the payment gateway.

Event URL Description
STK Callback /callbacks/stk_callback.php STK push result (success/failed)
B2C Callback /callbacks/b2c_callback.php Phone disbursement result
B2B Callback /callbacks/b2b_callback.php Till/Paybill disbursement result
Bank Callback /callbacks/bank_callback.php Bank transfer result

STK Callback Payload

JSON 
// The gateway sends POST with JSON body:
{
  "Body": {
    "stkCallback": {
      "MerchantRequestID": "263432-1234-4abc-b4d2-1234567890",
      "CheckoutRequestID": "wsbkcc-2c8a-4e3e-9c5c-1234567890",
      "ResultCode": 0,
      "ResultDesc": "The service request has been accepted successfully.",
      "CallbackMetadata": {
        "Item": [
          { "Name": "Amount", "Value": 100 },
          { "Name": "MpesaReceiptNumber", "Value": "LJ23GHJ4B2" },
          { "Name": "TransactionDate", "Value": 20250101120000 },
          { "Name": "PhoneNumber", "Value": 254700000000 }
        ]
      }
    }
  }
}

ResultCode 0 = success. The platform processes the callback and updates the transaction status automatically.

Error Codes

HTTP Code Message Description
400Bad RequestInvalid input or missing parameters
401UnauthorizedMissing or invalid API credentials
403ForbiddenInsufficient permissions
404Not FoundEndpoint or resource not found
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer-side error
Error Response 
{
  "status": "error",
  "message": "Invalid API credentials"
}

SDKs & Examples

PHP Example

PHP 
<?php
$apiKey = 'your_api_key';
$apiSecret = 'your_api_secret';
$baseUrl = 'https://your-domain.com/api';

// Send STK push
$payload = [
    'phone' => '2547XXXXXXXX',
    'amount' => 1000,
    'reference' => 'Invoice #1234',
];

$ch = curl_init("$baseUrl/payments/stk_push");
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER   => true,
    CURLOPT_HTTPHEADER       => [
        'Content-Type: application/json',
        "X-API-Key: $apiKey",
        "X-API-Secret: $apiSecret",
    ],
    CURLOPT_POSTFIELDS    => json_encode($payload),
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

if ($response['status'] === 'success') {
    echo "STK sent! Checkout ID: " . $response['data']['checkout_request_id'];
} else {
    echo "Error: " . $response['message'];
}

Python Example

Python 
import requests

api_key = 'your_api_key'
api_secret = 'your_api_secret'
base_url = 'https://your-domain.com/api'

headers = {
    'Content-Type': 'application/json',
    'X-API-Key': api_key,
    'X-API-Secret': api_secret,
}

# Send STK Push
payload = {
    'phone': '2547XXXXXXXX',
    'amount': 1000,
    'reference': 'Invoice #1234',
}

response = requests.post(
    f"{base_url}/payments/stk_push",
    json=payload,
    headers=headers
)

data = response.json()
print(data)

JavaScript (Browser) Example

JavaScript 
// Using fetch
const response = await fetch('/api/payments/stk_push', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-API-Key': 'your_api_key',
        'X-API-Secret': 'your_api_secret',
    },
    body: JSON.stringify({
        phone: '2547XXXXXXXX',
        amount: 1000,
        reference: 'Invoice #1234',
    }),
});

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