Quick Start Guide

<?php
require 'vendor/autoload.php';
use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;

class PaynexusClient {
    private $client;
    private $baseUrl;
    private $secretKey;
    
    public function __construct($secretKey) {
        $this->baseUrl = 'https://paynexus.mcbankske.space/api';
        $this->secretKey = $secretKey;
        $this->client = new Client([
            'base_uri' => $this->baseUrl,
            'headers' => [
                'X-API-Key' => $secretKey,
                'Content-Type' => 'application/json'
            ]
        ]);
    }
    
    public function getPaymentAccounts() {
        $response = $this->client->get('/merchant/payment-accounts');
        return json_decode($response->getBody(), true);
    }
    
    public function validatePhone($phone) {
        $response = $this->client->post('/mpesa/validate-phone', [
            'json' => ['phone' => $phone]
        ]);
        return json_decode($response->getBody(), true);
    }
    
    public function initiatePayment($paymentAccountId, $amount, $phone, $accountReference, $description = null) {
        $response = $this->client->post('/mpesa/payment/initiate', [
            'json' => [
                'payment_account_id' => $paymentAccountId,
                'amount' => $amount,
                'phone' => $phone,
                'account_reference' => $accountReference, // CRITICAL: Must be set correctly
                'description' => $description ?: 'Payment via PayNexus',
                'remark' => 'Website Payment'
            ]
        ]);
        
        return json_decode($response->getBody(), true);
    }
}

// COMPLETE USAGE EXAMPLE WITH PROPER ACCOUNT REFERENCE HANDLING
$paynexus = new PaynexusClient('sk_your_secret_key_here');

try {
    // Step 1: Get payment accounts to determine account type
    $accountsResponse = $paynexus->getPaymentAccounts();
    if (!$accountsResponse['success']) {
        die('Failed to get payment accounts');
    }
    
    $mpesaAccount = null;
    foreach ($accountsResponse['data'] as $account) {
        if ($account['provider'] === 'mpesa') {
            $mpesaAccount = $account;
            break;
        }
    }
    
    if (!$mpesaAccount) {
        die('No M-Pesa payment account found');
    }
    
    // Step 2: Validate phone number
    $phoneValidation = $paynexus->validatePhone('0798808796');
    if (!$phoneValidation['success'] || !$phoneValidation['data']['valid']) {
        die('Invalid phone number');
    }
    $normalizedPhone = $phoneValidation['data']['normalized'];
    
    // Step 3: CRITICAL - Determine account reference based on account type
    if ($mpesaAccount['type'] === 'paybill') {
        // FOR PAYBILL: Use merchant's account number for proper fund routing
        $accountReference = $mpesaAccount['account_number'];
        if (!$accountReference) {
            die('Paybill account number is required for proper routing');
        }
        $accountReference = substr($accountReference, 0, 12); // M-Pesa limit
        echo "📊 Using Paybill account - Account Reference: $accountReference\n";
    } elseif ($mpesaAccount['type'] === 'till') {
        // FOR TILL: Can use order reference (not used for routing)
        $accountReference = 'ORDER_' . time();
        $accountReference = substr($accountReference, 0, 12);
        echo "📊 Using Till account - Account Reference: $accountReference\n";
    } else {
        die('Unsupported payment account type: ' . $mpesaAccount['type']);
    }
    
    // Step 4: Initiate payment with correct account reference
    $result = $paynexus->initiatePayment(
        $mpesaAccount['id'],     // Payment account ID
        100,                 // Amount in KES
        $normalizedPhone,
        $accountReference,   // CRITICAL: Correct account reference
        'Payment for website order'
    );
    
    if ($result['success']) {
        echo "✅ Payment initiated successfully!\n";
        echo "📝 Checkout Request ID: " . $result['data']['checkout_request_id'] . "\n";
        echo "📊 Account Type: " . $mpesaAccount['type'] . "\n";
        echo "🔑 Account Reference Used: $accountReference\n";
    } else {
        echo "❌ Payment failed: " . ($result['error'] ?? 'Unknown error') . "\n";
    }
    
} catch (Exception $e) {
    echo "❌ Error: " . $e->getMessage() . "\n";
}
?>

const axios = require('axios');

class PaynexusClient {
    constructor(secretKey) {
        this.client = axios.create({
            baseURL: 'https://paynexus.mcbankske.space/api',
            headers: { 'X-API-Key': secretKey }
        });
    }
    
    async getPaymentAccounts() {
        const response = await this.client.get('/merchant/payment-accounts');
        return response.data;
    }
    
    async validatePhone(phone) {
        const response = await this.client.post('/mpesa/validate-phone', { phone });
        return response.data;
    }
    
    async initiatePayment(paymentAccountId, amount, phone, accountReference, description = null) {
        const response = await this.client.post('/mpesa/payment/initiate', {
            payment_account_id: paymentAccountId,
            amount: amount,
            phone: phone,
            account_reference: accountReference, // CRITICAL: Must be set correctly
            description: description || 'Payment via PayNexus',
            remark: 'Website Payment'
        });
        
        return response.data;
    }
}

// COMPLETE USAGE EXAMPLE WITH PROPER ACCOUNT REFERENCE HANDLING
const paynexus = new PaynexusClient('sk_your_secret_key_here');

const processPayment = async () => {
    try {
        // Step 1: Get payment accounts to determine account type
        const accountsResponse = await paynexus.getPaymentAccounts();
        if (!accountsResponse.success) {
            console.error('❌ Failed to get payment accounts');
            return;
        }
        
        const mpesaAccount = accountsResponse.data.find(acc => acc.provider === 'mpesa');
        if (!mpesaAccount) {
            console.error('❌ No M-Pesa payment account found');
            return;
        }
        
        // Step 2: Validate phone number
        const phoneValidation = await paynexus.validatePhone('0798808796');
        if (!phoneValidation.success || !phoneValidation.data.valid) {
            console.error('❌ Invalid phone number');
            return;
        }
        const normalizedPhone = phoneValidation.data.normalized;
        
        // Step 3: CRITICAL - Determine account reference based on account type
        let accountReference;
        if (mpesaAccount.type === 'paybill') {
            // FOR PAYBILL: Use merchant's account number for proper fund routing
            accountReference = mpesaAccount.account_number;
            if (!accountReference) {
                console.error('❌ Paybill account number is required for proper routing');
                return;
            }
            accountReference = accountReference.substring(0, 12); // M-Pesa limit
            console.log('📊 Using Paybill account - Account Reference:', accountReference);
        } else if (mpesaAccount.type === 'till') {
            // FOR TILL: Can use order reference (not used for routing)
            accountReference = 'ORDER_' + Date.now();
            accountReference = accountReference.substring(0, 12);
            console.log('📊 Using Till account - Account Reference:', accountReference);
        } else {
            console.error('❌ Unsupported payment account type:', mpesaAccount.type);
            return;
        }
        
        // Step 4: Initiate payment with correct account reference
        const result = await paynexus.initiatePayment(
            mpesaAccount.id,     // Payment account ID
            100,                 // Amount in KES
            normalizedPhone,
            accountReference,   // CRITICAL: Correct account reference
            'Payment for website order'
        );
        
        if (result.success) {
            console.log('✅ Payment initiated successfully!');
            console.log('📝 Checkout Request ID:', result.data.checkout_request_id);
            console.log('📊 Account Type:', mpesaAccount.type);
            console.log('🔑 Account Reference Used:', accountReference);
        } else {
            console.error('❌ Payment failed:', result.error || 'Unknown error');
        }
        
    } catch (error) {
        console.error('❌ Error:', error.message);
    }
};

processPayment();

import requests

# Initialize session with your secret API key
session = requests.Session()
session.headers.update({'X-API-Key': 'sk_your_secret_key_here'})
base_url = 'https://paynexus.mcbankske.space/api'

def check_payment_status(payment_reference):
    """Check payment status using payment reference"""
    try:
        response = session.get(f'{base_url}/payments/{payment_reference}')
        result = response.json()
        
        if result['success']:
            payment = result['data']
            print(f"Payment Status: {payment['status']}")
            print(f"Amount: {payment['amount']} {payment['currency']}")
            print(f"Phone: {payment['phone']}")
            print(f"Created: {payment['created_at']}")
            if payment.get('provider_transaction_id'):
                print(f"MPESA Transaction ID: {payment['provider_transaction_id']}")
        else:
            print(f"Error: {result['message']}")
            
    except requests.exceptions.RequestException as error:
        print(f"Request failed: {error}")

def check_status_by_checkout_id(checkout_request_id):
    """Check payment status using checkout request ID"""
    try:
        response = session.post(f'{base_url}/payments/status-by-checkout-id', json={
            'checkout_request_id': checkout_request_id
        })
        result = response.json()
        
        if result['success']:
            payment = result['data']
            print(f"Payment Status: {payment['status']}")
            print(f"Reference: {payment['reference']}")
            print(f"Amount: {payment['amount']} {payment['currency']}")
        else:
            print(f"Error: {result['message']}")
            
    except requests.exceptions.RequestException as error:
        print(f"Request failed: {error}")

# Example usage
check_payment_status('ORDER_123')  # Use your actual payment reference
check_status_by_checkout_id('ws_CO_123456789')  # Use your actual checkout request ID

<?php
// webhook.php
header('Content-Type: application/json');

$payload = json_decode(file_get_contents('php://input'), true);

if ($payload['ResultCode'] == 0) {
    // Payment successful
    $transactionId = $payload['TransactionID'];
    $amount = $payload['Amount'];
    
    // Update your database
    // Mark order as paid
    // Send confirmation email
    
    echo json_encode(['ResultCode' => 0, 'ResultDesc' => 'Success']);
} else {
    // Payment failed
    echo json_encode(['ResultCode' => 0, 'ResultDesc' => 'Received']);
}
?>