Enterprise Payment Gateway
for Multi-Client Ecosystems

A secure, high-performance middleware designed to centralize Selcom integration for all your internal applications and external partners.

Register as Developer Access Portal
🏢

Multi-Tenant Architecture

Easily manage multiple API clients with independent credentials, IP whitelists, and transaction logs.

📢

Asynchronous Webhooks

Reliable, queue-backed webhook delivery with automatic retries and live status tracking.

🚀

Integration Lab

Test your HMAC-SHA256 logic and execute live API calls instantly using our secure sandbox playground.

Launch Lab

Integration Guide

Connect your application with PrimeStack Pay Middleware using our secure API. Follow the guide below to authenticate and process transactions.

1. Authentication

All requests must be authenticated using a custom HMAC-SHA256 signature.

Header Description
Content-Type application/json
X-App-ID Your unique App Identifier (e.g., MOBILE_APP_01)
X-Timestamp Current Unix timestamp (integer). Used for signature and replay protection.
X-Signature Base64 encoded HMAC-SHA256 signature.

2. API Endpoints

Collection (Receive Money)

POST /api/v1/transact

Initiate a USSD push payment to a customer's mobile wallet.

{
    "action": "collection",
    "amount": 1000,
    "msisdn": "255700000000",
    "reference": "ORDER_101",
    "callback_url": "https://yourapp.com/callback"
}
Sample Response: 
{
    "status": "success",
    "transaction_id": "901",
    "payment_status": "PENDING",
    "provider_response": {
        "result": "SUCCESS",
        "resultcode": "000",
        "message": "Payment notification logged"
    }
}

Disbursement (Send Money)

POST /api/v1/transact

Send funds to various channels. Specify channel to route correctly.

Mobile Wallet & Selcom Pesa 
{
    "action": "disbursement",
    "amount": 5000,
    "msisdn": "255700000000",
    "channel": "CASHIN",
    "reference": "PAYOUT_001"
}
Sample Response: 
{
    "status": "success",
    "transaction_id": "902",
    "payment_status": "SUCCESS",
    "financials": {
        "system_profit": 55,
        "provider_fee": 345,
        "total_deductible": 5400
    }
}
Bank Transfer (Qwiksend) 
{
    "action": "disbursement",
    "channel": "BANK",
    "amount": 50000,
    "msisdn": "255700000000", // Sender phone
    "recipient_bank_code": "CRDB",
    "recipient_account": "01J12345678900",
    "recipient_name": "John Doe",
    "reference": "SALARY_BATCH_01",
    "remarks": "February Salary"
}

Name Lookup

POST /api/v1/lookup

Validate recipient details before sending funds.

Wallet Lookup 
{
    "type": "wallet",
    "channel": "vodacom",
    "msisdn": "255754000000"
}
Bank Lookup 
{
    "type": "bank",
    "bank_code": "CRDB",
    "account_number": "01J..."
}
Sample Response: 
{
    "status": "success",
    "name": "Jane Doe",
    "original_data": { ... }
}

Transaction Query

POST /api/v1/query 
{
    "reference": "ORDER_101"
}
Response: 
{
    "status": "SUCCESS",
    "payment_status": "SUCCESS"
}

Account Summary

POST /api/v1/summarize 
{} // No body required
Response: 
{
    "status": "SUCCESS",
    "data": { ... }
}

3. Webhooks (Callbacks)

The middleware will notify your system asynchronously when the status of a transaction changes (e.g., payment completed or failed).

Sample Webhook Payload

{
    "transid": "7945454515",
    "reference": "ORDER_101",
    "result": "SUCCESS",
    "payment_status": "COMPLETED",
    "amount": "1000",
    "msisdn": "255700000000"
}

Verifying Webhook Signatures

To ensure the webhook came from the middleware, you MUST verify the X-Middleware-Signature header.

Algorithm: Base64( HMAC_SHA256( Payload + X-Timestamp, Your_Shared_Secret ) )

// PHP Example 
$payload = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_TIMESTAMP'];
$signature = $_SERVER['HTTP_X_MIDDLEWARE_SIGNATURE'];

$expected = base64_encode(hash_hmac('sha256', $payload . $timestamp, $secret, true));

if ($signature === $expected) {
    // Verified!
}

Testing Webhooks

You can verify your webhook integration without waiting for a real transaction. Use the Webhook Testing tool in the Developer Portal to send a simulated ping event to your registered URL.

Note: Simulated events will have the event type test_ping.

4. Transaction Reference Codes

Common result codes you might encounter in API responses and Webhooks.

Code Description Action Required
000 Success Transaction completed successfully. Deliver value.
021 Pending Transaction initiated. Wait for callback or poll status.
009 Failed Generic failure. Check account status or entered details.
052 Insufficient Balance Customer has insufficient funds in their wallet.
056 User Cancelled Customer cancelled the USSD push request.
INS_FUNDS Insufficient App Balance Your middleware application balance is too low for this disbursement (including fees).

5. Supported Channels & Banks

Use these codes in the `channel` and `recipient_bank_code` fields respectively.

Mobile Networks

Channel Code Network
CASHIN Universal (Any carrier)
vodacom M-Pesa
airtel Airtel Money
tigo Tigo Pesa
halotel HaloPesa
zantel EzyPesa
ttcl T-Pesa
SELCOM_PESA Selcom Pesa

Popular Banks (Qwiksend)

Bank Code Bank Name
CRDB CRDB Bank
NMB NMB Bank
NBC NBC Bank
EXIM Exim Bank
STANBIC Stanbic Bank
ABSA Absa Bank
DTB Diamond Trust Bank
KCB KCB Bank

Start Integrating Now