Go back to Main website

API Documentation

Comprehensive documentation for integrating HashBack number decoding, HashPay STK Push payment processing, and HashPay Wallet B2C APIs. This documentation provides detailed information on endpoints, request parameters, response formats, and error handling.

Secure API Endpoints
Real-time Processing
API Key Required

HashBack API

Decode hashed phone numbers to their original MSISDN format using our secure algorithm.

  • Hash decoding
  • MSISDN recovery
  • Secure processing

HashPay STK Push

Initiate M-Pesa STK Push payments and check transaction status with our HashPay API.

  • STK Push initiation
  • Transaction status
  • Real-time webhooks

HashPay Wallet B2C

Manage wallet operations including balance checks, top-ups, and withdrawals for your customers.

  • Wallet balance
  • Wallet top-up
  • B2C withdrawals

Getting Started

Authentication

All API requests must be authenticated using your API key. Include the API key in the request parameters:

Parameter
"api_key": "YOUR_API_KEY_HERE"

Rate Limiting

API requests are limited to 100 requests per minute per API key. If you exceed this limit, you will receive a 429 Too Many Requests response.

Rate Limit Response
{
  "error": {
    "code": 429,
    "message": "Too many requests. Please try again later."
  }
}

HashBack Decode API

Decode hashed phone numbers to their original MSISDN format using our secure algorithm.

Decode Numbers

POST https://api.hashback.co.ke/decode

Request Parameters

Parameter Type Required Description
hash String Yes The hash string to decode
API_KEY String Yes Your authentication API key

Example Request

cURL
curl -X POST https://api.hashback.co.ke/decode \
  -d 'hash=4f87c55d393937f18fbf3003512195aa8e62be340946ab547c2eada26cc43c1e' \
  -H 'API_KEY: YOUR_API_KEY_HERE'

Example Response

Success
{
  "ResultCode": "0",
  "MSISDN": "254712345678"
}

HashPay STK Push API

Initiate M-Pesa STK Push payments and check transaction status with our HashPay API.

Initiate STK Push

POST https://api.hashback.co.ke/initiatestk

Request Parameters

Parameter Type Required Description
api_key String Yes Your authentication API key
account_id String Yes Your HashPay account ID (e.g., HP105181)
amount String Yes Payment amount
msisdn String Yes Customer phone number (format: 2547XXXXXXXX)
reference String Yes Unique transaction reference (URL encoded)

Example Request

cURL
curl -X POST https://api.hashback.co.ke/initiatestk \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key": "YOUR_API_KEY_HERE",
    "account_id": "HP105181",
    "amount": "1",
    "msisdn": "254701834082",
    "reference": "Bronze_70",

  }'

Example Response

Success
{
  "success": true,
  "message": "STK push initiated successfully",
  "checkout_id": "ws_CO_17052025174057106701834082"
}

Check Transaction Status

POST https://api.hashback.co.ke/transactionstatus

Request Parameters

Parameter Type Required Description
api_key String Yes Your authentication API key
account_id String Yes Your HashPay account ID
checkoutid String Yes Transaction ID from STK initiation

Example Request

cURL
curl -X POST https://api.hashback.co.ke/transactionstatus \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key": "YOUR_API_KEY_HERE",
    "account_id": "HP105181",
    "checkoutid": "ws_CO_17052025174057106701834082"
  }'

Example Response

Success
{
  "ResponseCode": "0",
  "ResponseDescription": "The service request has been accepted successfully",
  "MerchantRequestID": "29115-34620561-1",
  "CheckoutRequestID": "ws_CO_191220191020363925",
  "ResultCode": "0",
  "ResultDesc": "The service request is processed successfully."
}

Webhook Callbacks

HashPay can send real-time webhook notifications to your application when payment transactions are completed. This allows you to handle payment confirmations automatically without polling the transaction status endpoint.

Setting up Webhooks

To receive webhook notifications, you need to configure your webhook URL in the Settings tab of your HashPay portal. This URL should be publicly accessible and capable of receiving POST requests.

Important:

  • Set up your webhook URL before initiating any transactions
  • Your webhook endpoint must respond with a 2xx HTTP status code to acknowledge receipt of notifications
  • Webhook URLs can only be configured through the portal settings, not via API requests

Webhook Payload

When a payment is completed successfully, HashPay will send a POST request to your callback URL with the following payload:

Webhook Payload
{
  "ResponseCode": 0,
  "ResponseDescription": "Success. Request accepted for processing",
  "MerchantRequestID": "ws_CO_XXXXXX",
  "CheckoutRequestID": "ws_CO_15XXXXXX",
  "TransactionID": "transid",
  "TransactionAmount": 100,
  "TransactionReceipt": "transref",
  "TransactionDate": 20250815001939,
  "TransactionReference": "billref",
  "Msisdn": 2547123456
}

Security Considerations

To ensure webhook security:

  • Use HTTPS endpoints for your callback URLs
  • Validate webhook payloads before processing
  • Implement idempotency to handle duplicate webhooks
  • Log webhook events for debugging and monitoring
  • Set up proper error handling and timeouts

HashPay Wallet B2C API

Manage wallet operations including balance checks, top-ups, and withdrawals for your customers.

Check Wallet Balance

POST https://api.hashback.co.ke/walletbalance

Request Parameters

Parameter Type Required Description
api_key String Yes Your authentication API key
account_id String Yes Your HashPay wallet ID (e.g., WALLET_ID)

Example Request

cURL
curl -X POST https://api.hashback.co.ke/walletbalance \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key": "api_keyxxxxx",
    "account_id": "WALLET_ID"
  }'
PHP
<?php
$url = "https://api.hashback.co.ke/walletbalance";
$data = array(
    'api_key' => 'api_keyxxxxx',
    'account_id' => 'WALLET_ID'
);

$options = array(
    'http' => array(
        'header'  => "Content-type: application/json",
        'method'  => 'POST',
        'content' => json_encode($data)
    )
);

$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
echo $result;
?>

Example Response

Success
{
  "success": true,
  "walletId": "WALLET_ID",
  "balance": 47,
  "status": "Active",
  "currency": "KES",
  "timestamp": "2025-08-09 17:44:37"
}

Top Up Wallet

POST https://api.hashback.co.ke/topup

Request Parameters

Parameter Type Required Description
api_key String Yes Your authentication API key
walletid String Yes Your HashPay wallet ID
amount String Yes Top-up amount
msisdn String Yes Customer phone number for M-Pesa payment

Example Request

cURL
curl -X POST https://api.hashback.co.ke/topup \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key": "api_keyxxxxx",
    "walletid": "WALLET_ID",
    "amount": "1",
    "msisdn": "0712345678"
  }'
JavaScript
const response = await fetch('https://api.hashback.co.ke/topup', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    api_key: 'api_keyxxxxx',
    walletid: 'WALLET_ID',
    amount: '1',
    msisdn: '0712345678'
  })
});

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

Example Response

Success
{
  "MerchantRequestID": "600a-43bc-b541-2abbc241283a938725",
  "CheckoutRequestID": "ws_CO_090820251748176701834082",
  "ResponseCode": "0",
  "ResponseDescription": "Success. Request accepted for processing",
  "CustomerMessage": "Success. Request accepted for processing"
}

Process Withdrawal

POST https://api.hashback.co.ke/processwithdrawal

Request Parameters

Parameter Type Required Description
api_key String Yes Your authentication API key
msisdn String Yes Customer phone number to receive withdrawal
amount String Yes Withdrawal amount

Example Request

cURL
curl -X POST https://api.hashback.co.ke/processwithdrawal \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key": "api_keyxxxxx",
    "msisdn": "0712345678",
    "amount": "50"
  }'
Python
import requests
import json

url = "https://api.hashback.co.ke/processwithdrawal"
data = {
    "api_key": "api_keyxxxxx",
    "msisdn": "0712345678",
    "amount": "50"
}

response = requests.post(url, json=data)
result = response.json()
print(json.dumps(result, indent=2))

Example Response

Success
{
  "success": true,
  "message": "Withdrawal processed successfully",
  "details": {
    "amount": 50,
    "fee": 5,
    "total": 55,
    "balance": 92,
    "transaction_reference": "HW1WH20250809175842864"
  }
}
Insufficient Funds
{
  "success": false,
  "message": "Insufficient funds. You need KES 18.00 more (KES 50.00 + KES 5.00 fee)"
}