Join Our WhatsApp Support Group

Get real-time help, share experiences, and stay updated with the latest API changes
Back to Website

API Documentation

Complete developer documentation for integrating HashBack number decoding, HashPay STK Push payment processing, and HashPay Wallet B2C APIs. Build powerful payment solutions with our secure and reliable APIs.

Secure 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 real-time webhooks.

  • STK Push initiation
  • Transaction status
  • Webhook notifications

HashPay Wallet B2C

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

  • Wallet balance
  • Wallet top-up
  • B2C withdrawals

PULL API

Retrieve detailed transaction information for reporting and reconciliation.

  • Transaction lookup
  • Detailed data
  • Real-time response

Getting Started

Authentication

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

{
  "api_key": "YOUR_API_KEY_HERE"
}

Rate Limiting

API requests are limited to 100 requests per minute per API key. Exceeding this limit will result in a 429 error 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 -X POST https://api.hashback.co.ke/decode \
  -d 'hash=4f87c55d393937f18fbf3003512195aa8e62be340946ab547c2eada26cc43c1e' \
  -H 'API_KEY: YOUR_API_KEY_HERE'

Example Response

{
  "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., ACC_ID)
amount String Yes Payment amount
msisdn String Yes Customer phone number (format: 2547XXXXXXXX)
reference String Yes Unique transaction reference (URL encoded)

Example Request

curl -X POST https://api.hashback.co.ke/initiatestk \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key": "YOUR_API_KEY_HERE",
    "account_id": "ACC_ID",
    "amount": "1",
    "msisdn": "254712345678",
    "reference": "BILL_REF"
  }'

Example Response

{
  "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 -X POST https://api.hashback.co.ke/transactionstatus \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key": "YOUR_API_KEY_HERE",
    "account_id": "ACC_ID",
    "checkoutid": "ws_CO_17052025174057106701834082"
  }'

Example Response

{
  "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 sends real-time webhook notifications to your application when payment transactions are completed. This allows automatic payment confirmation handling without polling.

Setting up Webhooks

Configure your webhook URL in the Settings tab of your HashPay portal. The URL must be publicly accessible and capable of receiving POST requests.

  • Set up your webhook URL before initiating transactions
  • Your endpoint must respond with a 2xx HTTP status code
  • Webhooks can only be configured through the portal settings

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 Best Practices

  • Use HTTPS endpoints for 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

Example Request

<?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": 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/v2/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 Nominated Number Note: The STK push will only be successful if the user uses the nominated number added in the Hashpay portal

Example Request

const response = await fetch('https://api.hashback.co.ke/v2/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

{
  "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

Important: API Version Update

The V1 withdrawal endpoint (/processwithdrawal) is obsolete after October 26, 2025. Please migrate to the V2 endpoint below.

POST https://api.hashback.co.ke/V2/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
SecurityCredential String Yes Security credential generated from your portal

Example Request

import requests
import json

url = "https://api.hashback.co.ke/V2/processwithdrawal"
data = {
    "api_key": "API_KEY",
    "msisdn": "07123456789",
    "amount": 20,
    "SecurityCredential": "SECURITY_CREDENTIAL"
}

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

Example Response

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

Deprecated API Version

This V1 endpoint is obsolete and will be removed after October 26, 2025. Please migrate to the V2 endpoint.

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
SecurityCredential String Yes Security credential generated from your portal

Example Request

import requests
import json

url = "https://api.hashback.co.ke/processwithdrawal"
data = {
    "api_key": "API_KEY",
    "msisdn": "07123456789",
    "amount": 20,
    "SecurityCredential": "SECURITY_CREDENTIAL"
}

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

Example Response

{
  "success": true,
  "message": "Withdrawal processed successfully",
  "details": {
    "amount": 50,
    "fee": 5,
    "total": 55,
    "balance": 92,
    "transaction_reference": "HW1WH20250809175842864"
  }
}

PULL API

Retrieve detailed transaction information by transaction ID for reporting and reconciliation purposes.

Get Transaction Details

POST https://api.hashback.co.ke/v1/pullapi

Request Parameters

Parameter Type Required Description
api_key String Yes Your authentication API key
account_id String Yes Your HashPay account ID (e.g., ACCOUNT_ID)
transaction_id String Yes The transaction ID to look up

Example Request

curl -X POST https://api.hashback.co.ke/gettransaction \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key": "API_KEY",
    "account_id": "ACCOUNT_ID",
    "transaction_id": "TRANS_ID"
  }'

Example Response

{
  "success": true,
  "message": "Transaction retrieved successfully",
  "data": {
    "transactionId": "TRANS_ID",
    "trxDate": "2025-05-23T19:02:18+03:00",
    "msisdn": "82987ec40f99583ed3dffc653605f1a02d2d0ea7909640f9134e8f9ab778bf53",
    "billreference": "BILL_REF",
    "amount": 499,
    "AccName": "ACC NAME"
  }
}
{
  "success": false,
  "message": "Transaction not found"
}

Error Codes

Common HTTP status codes and error responses you may encounter when using the API.

Status Code Description Solution
200 Success - Request completed successfully No action needed
400 Bad Request - Invalid parameters Check your request parameters
401 Unauthorized - Invalid API key Verify your API key is correct
429 Too Many Requests - Rate limit exceeded Wait before retrying
500 Internal Server Error Contact support if persists