API Documentation

Complete guide to integrating the M-Pesa Hash Decoding API into your applications. Simple REST endpoints with comprehensive examples.

Quick Start

Get started with the M-Pesa Hash Decoding API in minutes. No complex setup required - just make HTTP requests to our endpoints.

cURL Example 
curl -X POST https://mpesadecode.efficio.co.ke/api/decode \
  -H "Content-Type: application/json" \
  -d '{
    "hash": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2g3h4i5j6k7l8m9n0o1p2q3r4s5t6u7v8w9x0y1z2"
  }'

Authentication

For production use, you'll need an API key. Free tier users can make up to 5 requests per month without authentication.

API Key Required

Include your API key in the Authorization header for authenticated requests.

With Authentication 
curl -X POST https://mpesadecode.efficio.co.ke/api/decode \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "hash": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2g3h4i5j6k7l8m9n0o1p2q3r4s5t6u7v8w9x0y1z2"
  }'

Decode Endpoint

Decode a SHA-256 hash to retrieve the original phone number.

Endpoint
POST /api/decode
Cost
KES 0.8 per request
Request Body
JSON 
{
  "hash": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2g3h4i5j6k7l8m9n0o1p2q3r4s5t6u7v8w9x0y1z2"
}
Response
Success Response 
{
  "phone_number": "254712345678",
  "remaining_free": 4
}

Hash Endpoint

Generate a SHA-256 hash from a phone number for testing purposes.

Endpoint
POST /api/hash
Cost
Free
Request Body
JSON 
{
  "phone_number": "254712345678"
}
Response
Success Response 
{
  "hash": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2g3h4i5j6k7l8m9n0o1p2q3r4s5t6u7v8w9x0y1z2",
  "phone_number": "254712345678"
}

Rate Limits

Rate limits are applied to prevent abuse and ensure fair usage.

Endpoint Rate Limit Window
/api/decode 10 requests 1 minute
/api/hash 20 requests 1 minute

Error Codes

Standard HTTP status codes and error messages.

Status Code Error Description
400 Bad Request Invalid request format or missing parameters
402 Payment Required Insufficient credits or free limit reached
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Hash decode failed or service unavailable

Code Examples

Ready-to-use code examples in popular programming languages.

JavaScript (Fetch)
JavaScript 
async function decodeHash(hash) {
  const response = await fetch('https://mpesadecode.efficio.co.ke/api/decode', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_API_KEY'
    },
    body: JSON.stringify({ hash })
  });
  
  return await response.json();
}
PHP (cURL)
PHP 
function decodeHash($hash) {
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, 'https://mpesadecode.efficio.co.ke/api/decode');
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['hash' => $hash]));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json',
        'Authorization: Bearer YOUR_API_KEY'
    ]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    curl_close($ch);
    
    return json_decode($response, true);
}
Python (requests)
Python 
import requests

def decode_hash(hash_value):
    url = 'https://mpesadecode.efficio.co.ke/api/decode'
    headers = {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_API_KEY'
    }
    data = {'hash': hash_value}
    
    response = requests.post(url, json=data, headers=headers)
    return response.json()

Ready to Get Started?

Get your API key and start decoding M-Pesa hashes today

Create Free Account Try Demo