API Documentation

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

Secure API Endpoints

Real-time Processing

API Key Required

Getting Started

Authentication

All API requests must be authenticated using your API key. Include the API key in the header of every request:

Header

Authorization: Bearer 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'

PHP

<?php
$url = "https://api.hashback.co.ke/decode";
$data = array(
    'hash' => '4f87c55d393937f18fbf3003512195aa8e62be340946ab547c2eada26cc43c1e',
    'API_KEY' => 'YOUR_API_KEY_HERE'
);

$options = array(
    'http' => array(
        'header'  => "Content-type: application/x-www-form-urlencoded",
        'method'  => 'POST',
        'content' => http_build_query($data)
    )
);

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

Example Response

Success

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

Error

{
  "error": {
    "code": 401,
    "message": "Authentication error: Invalid API key"
  }
}

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

{
  "status": "success",
  "transaction": {
    "id": "ws_CO_17052025174057106701834082",
    "amount": "1",
    "msisdn": "254701834082",
    "reference": "Bronze_70",
    "status": "Completed",
    "timestamp": "2023-12-15T14:30:45Z"
  }
}

API Error Codes

Common Error Codes

Status Code	Error Type	Description
200	OK	Request completed successfully
201	Created	Resource created successfully (STK initiated)
400	Bad Request	Missing or invalid parameters
401	Unauthorized	Invalid or missing API key
402	Payment Required	Insufficient account balance
403	Forbidden	Access denied for this resource
404	Not Found	Resource not found (invalid endpoint)
419	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server error
503	Service Unavailable	Temporarily offline for maintenance

Troubleshooting Tips

Always verify your API key is correct and has not expired
Ensure all required parameters are included in your requests
Check that parameter values are in the correct format
Verify your account has sufficient balance for payment operations
Make sure you're using the latest API version