Integration Guide

Node.js SDK

Setup

# No npm install — just copy the file
cp sdk/node/nexuspay.js your-project/lib/

Charge a card

import NexusPay from './lib/nexuspay.js';

const client = new NexusPay({
    apiKey:    'npk_live_...',
    secretKey: 'sk_live_...',  // only needed for webhook verification
});

const charge = await client.charge({
    amount:      100000,          // KES 1,000.00 (smallest unit)
    currency:    'KES',
    description: 'Order #10042',
    metadata:    { order_id: '10042' },
    card: {
        number:    '4242424242424242',
        exp_month: '12',
        exp_year:  '2027',
        cvv:       '123',
        name:      'Jane Wanjiku',
    },
});

console.log(charge.reference);   // TXN-20250601-A1B2C3D4
console.log(charge.auth_code);   // F3A92C

M-Pesa STK Push

const push = await client.mpesaPush({
    phone:     '0712345678',
    amount:    500,              // KES 500 (whole number)
    reference: 'Order-10042',
});

// Block until customer enters PIN (up to 2 minutes)
const result = await client.mpesaWait(push.checkout_request_id, {
    intervalMs: 3000,
    onPoll: (s) => console.log('Status:', s.status),
});

if (result.status === 'completed') {
    console.log('Paid! Receipt:', result.mpesa_receipt_number);
}

Refund

// Full refund
const refund = await client.refund('TXN-20250601-A1B2C3D4');

// Partial refund (KES 500)
const partial = await client.refund('TXN-20250601-A1B2C3D4', 50000);

Webhook verification (Express)

import express from 'express';

const app = express();

app.post('/webhooks', express.raw({ type: 'application/json' }), async (req, res) => {
    const sig   = req.headers['x-nexuspay-signature'];
    const valid = await client.verifyWebhook(req.body, sig);

    if (!valid) return res.status(401).json({ error: 'Invalid signature' });

    const event = JSON.parse(req.body);

    if (event.event === 'payment.success') {
        // fulfil the order
    }

    res.json({ received: true });
});

FX Rates + Payment Links

// Live exchange rates
const fx   = await client.getFxRates();
console.log('1 USD =', fx.rates.KES, 'KES');

// Convert
const conv = await client.convertCurrency(100, 'USD', 'KES');
console.log('$100 =', conv.converted, 'KES');

// Hosted payment link
const link = await client.createPaymentLink({
    amount:       250000,
    currency:     'KES',
    description:  'Invoice #089',
    expires_hours: 48,
});
console.log('Share:', link.url);

Python SDK

Setup

# No pip install needed — just copy the file
cp sdk/python/nexuspay.py your-project/

# Optional: pip install requests  (SDK uses it automatically if present)

Charge a card

from nexuspay import NexusPay, NexuPayError

client = SawiPay(
    api_key    = 'npk_live_...',
    secret_key = 'sk_live_...',
)

try:
    charge = client.charge(
        amount      = 100000,
        currency    = 'KES',
        description = 'Order #10042',
        metadata    = {'order_id': '10042'},
        card = {
            'number':    '4242424242424242',
            'exp_month': '12',
            'exp_year':  '2027',
            'cvv':       '123',
            'name':      'Jane Wanjiku',
        },
    )
    print(charge['reference'])   # TXN-20250601-A1B2C3D4

except NexuPayError as e:
    print(f'Error [{e.code}]: {e}')

M-Pesa STK Push

push = client.mpesa_push(
    phone     = '0712345678',
    amount    = 500,
    reference = 'Order-10042',
)

result = client.mpesa_wait(
    push['checkout_request_id'],
    interval_s = 3,
    max_wait_s = 120,
    on_poll    = lambda s: print('.', end='', flush=True),
)

if result['status'] == 'completed':
    print('Paid! Receipt:', result['mpesa_receipt_number'])

Refund

refund = client.refund('TXN-20250601-A1B2C3D4')          # full
partial = client.refund('TXN-20250601-A1B2C3D4', 50000) # partial KES 500

Webhook verification (Flask)

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhooks', methods=['POST'])
def handle_webhook():
    sig   = request.headers.get('X-NexusPay-Signature', '')
    valid = client.verify_webhook(request.get_data(), sig)

    if not valid:
        return jsonify(error='Invalid signature'), 401

    event = request.get_json()
    if event['event'] == 'payment.success':
        pass  # fulfil order

    return jsonify(received=True)

Django webhook view

from django.http import JsonResponse
from django.views.decorators.csrf import csrf_exempt

@csrf_exempt
def nexuspay_webhook(request):
    if request.method != 'POST':
        return JsonResponse({'error': 'Method not allowed'}, status=405)

    sig   = request.headers.get('X-Nexuspay-Signature', '')
    valid = client.verify_webhook(request.body, sig)

    if not valid:
        return JsonResponse({'error': 'Invalid signature'}, status=401)

    event = json.loads(request.body)
    # handle event...
    return JsonResponse({'received': True})

PHP SDK

Setup

# No Composer needed — just copy the file
cp sdk/php/NexusPay.php your-project/lib/

Charge a card

<?php
require 'lib/NexusPay.php';

use SawiPay\Client;
use NexusPay\NexuPayException;

$client = new Client([
    'api_key'    => 'npk_live_...',
    'secret_key' => 'sk_live_...',
]);

try {
    $charge = $client->charge([
        'amount'      => 100000,
        'currency'    => 'KES',
        'description' => 'Order #10042',
        'card' => [
            'number'    => '4242424242424242',
            'exp_month' => '12',
            'exp_year'  => '2027',
            'cvv'       => '123',
            'name'      => 'Jane Wanjiku',
        ],
    ]);

    echo $charge['reference'];  // TXN-20250601-A1B2C3D4

} catch (NexuPayException $e) {
    echo "Error [{$e->errorCode}]: {$e->getMessage()}";
}

M-Pesa STK Push

$push = $client->mpesaPush([
    'phone'  => '0712345678',
    'amount' => 500,
]);

$result = $client->mpesaWait(
    checkoutRequestId: $push['checkout_request_id'],
    intervalSeconds:   3,
    maxWaitSeconds:    120,
    onPoll: function(array $s): void { echo '.'; }
);

if ($result['status'] === 'completed') {
    echo "Paid! Receipt: {$result['mpesa_receipt_number']}";
}

Webhook verification

$rawBody   = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_NEXUSPAY_SIGNATURE'] ?? '';

if (!$client->verifyWebhook($rawBody, $signature)) {
    http_response_code(401);
    exit(json_encode(['error' => 'Invalid signature']));
}

$event = json_decode($rawBody, true);

match ($event['event']) {
    'payment.success' => fulfillOrder($event['data']),
    'refund.processed'=> handleRefund($event['data']),
    default           => null,
};

http_response_code(200);
echo json_encode(['received' => true]);

Laravel integration

// config/services.php
'nexuspay' => [
    'key'    => env('NEXUSPAY_API_KEY'),
    'secret' => env('NEXUSPAY_SECRET_KEY'),
],

// AppServiceProvider::register()
$this->app->singleton(\NexusPay\Client::class, fn() =>
    new \NexusPay\Client([
        'api_key'    => config('services.nexuspay.key'),
        'secret_key' => config('services.nexuspay.secret'),
    ])
);

// In a controller or job:
public function pay(Request $request, \NexusPay\Client $nexuspay)
{
    $charge = $nexuspay->charge([
        'amount'   => $request->amount,
        'currency' => 'KES',
        'card'     => $request->card,
    ]);
    // ...
}

WooCommerce — Quick Setup

1. Upload woocommerce-sawipay as a zip via Plugins → Add New → Upload Plugin
2. Activate, then go to WooCommerce → Settings → Payments → SawiPay
3. Paste your API Key + Secret Key from Dashboard → API Keys
4. Copy the shown webhook URL into Dashboard → Settings → Webhooks
5. Enable the gateway — customers now see "Card / M-Pesa (SawiPay)" at checkout

Shopify — Quick Setup

1. Deploy the shopify-sawipay Node app (Heroku, Railway, Fly.io, etc.)
2. Install on your store via the generated OAuth URL
3. Paste your SawiPay API Key + Secret Key into the app's settings page
4. Add a Manual Payment method named to include "SawiPay" or "M-Pesa"
5. New orders using that method automatically get a SawiPay checkout link — paid orders are marked paid in Shopify automatically