How to get started with our api's
Base URL, Authentication, and Error Handling.
All API requests must be authenticated using a Bearer Token in the Authorization header. Your API key serves as this token. All endpoint paths listed below are relative to this base URL.
Base URL:
https://bridge.hostpay.africa/api
Authentication Header:
Authorization: Bearer YOUR_API_KEY
Successful API calls (200 OK) will include "success": true. Data is encapsulated within a "data" key.
Login
{
"success": true,
"message": "Operation completed successfully.",
"data": {
// ... returned data here ...
}
}
API errors return appropriate HTTP status codes and "success": false.
401 Unauthorized: Invalid API key.403 Forbidden: Key lacks required scopes.404 Not Found: Endpoint does not exist.400 Bad Request: Validation fails.402 Payment Required: Insufficient credits.409 Conflict: Transaction already processed.500 Internal Server Error: Server error.IMPORTANT: All API clients (cURL, Postman, etc.) must include the Accept header:
Accept: application/json
User authentication and registration.
Login to get an auth token.
Form Data:
email (string, required): Your account email.password (string, required): Your account password.Sample Response:
{
"success": true,
"token": "YOUR_AUTH_TOKEN_HERE",
"message": "Login successful."
}
Get details for the authenticated user. (Requires Bearer Token)
Sample Response:
{
"success": true,
"data": {
"id": 1,
"name": "Demo User",
"email": "user@example.com",
"phone_number": "2547XXXXXXXX"
}
}
Initiate the new user registration process.
Form Data:
name (string, required): User's full name.email (string, required): User's email.phone_number (string, required): User's phone (e.g., 2547XXXXXXXX).Sample Response:
{
"success": true,
"message": "Registration initiated. Please check your email and phone for OTPs."
}
Verify the OTP sent to your email.
Form Data:
email (string, required): User's email.otp (string, required): The OTP from the email.Sample Response:
{
"success": true,
"message": "Email verified successfully."
}
Verify the OTP sent to your phone and complete registration.
Form Data:
phone_number (string, required): User's phone number.otp (string, required): The OTP from the SMS.Sample Response:
{
"success": true,
"message": "Phone verified. Registration complete.",
"token": "YOUR_NEW_AUTH_TOKEN"
}
Allows submitting hashed M-Pesa MSISDNs for decoding to reveal the original phone number. (Requires Bearer Token)
Decode a hashed MSISDN.
Form Data:
msisdn_hash (string, required): The hashed MSISDN string to decode.Sample Response:
{
"success": true,
"message": "MSISDN decoded successfully.",
"original_hash": "5aa741336e9403679020b4a0ff3c247c...",
"decoded_msisdn": "2547XXXXXXXX",
"cost": 1.00,
"new_balance": 99.00
}
Allows listing your configured M-Pesa account endpoints (webhooks). (Requires Bearer Token)
List all M-Pesa account endpoints.
Sample Response:
{
"success": true,
"data": [
{
"id": 1,
"mpesa_account_id": 1,
"name": "My Callback URL",
"url": "https://example.com/callback",
"description": "Webhook for payments",
"specific_shortcode": "174379",
"is_active": true,
"created_at": "2025-01-10 08:00:00"
}
]
}
Allows reading your configured M-Pesa accounts (Paybill/Till numbers). (Requires Bearer Token)
List all your M-Pesa accounts.
Sample Response:
{
"success": true,
"data": [
{
"id": 1,
"company_business_name": "My Business",
"account_type": "paybill",
"paybill_shortcode": "174379",
"till_shortcode": null,
"is_active": true,
"created_at": "2024-01-01 10:00:00"
}
]
}
Show details for a specific M-Pesa Account.
Query Parameters:
id (integer, required): The ID of the account to show.Sample Response:
{
"success": true,
"data": {
"id": 1,
"company_business_name": "My Business",
"account_type": "paybill",
"paybill_shortcode": "174379",
"till_shortcode": null,
"is_active": true,
"created_at": "2024-01-01 10:00:00"
}
}
Allows managing SMS operations, including sending messages and checking credits. (Requires Bearer Token)
Send an SMS to a recipient.
Form Data:
recipient_phone (string, required): Phone number (e.g., 2547XXXXXXXX).message (string, required): The message content.Sample Response:
{
"success": true,
"message": "SMS sent successfully!",
"data": {
"provider_response": "Message queued successfully."
}
}
Check remaining SMS credits.
Sample Response:
{
"success": true,
"message": "SMS credits retrieved successfully.",
"credits": 123.45
}
Allows initiating and managing M-Pesa STK Push requests. (Requires Bearer Token)
Initiate an STK Push payment request.
Form Data:
shortcode (string, required): The Paybill or Till Shortcode.amount (number, required): The amount to request (minimum 1 Ksh).phone_number (string, required): The client's Safaricom phone number (e.g., 2547XXXXXXXX).reason (string, optional): Reason for the payment request.account_reference (string, optional): Account reference (BillRefNumber).Sample Response:
{
"success": true,
"message": "STK Push initiated successfully. Client should receive a prompt.",
"stk_push_id": 123,
"checkout_request_id": "ws_CO_...",
"status": "initiated"
}
List all initiated STK Push requests.
Sample Response:
{
"success": true,
"data": [
{
"id": 1,
"amount": 100.00,
"status": "initiated",
"phone_number": "2547...",
"created_at": "2025-06-14 23:00:00"
}
]
}
Get details of a specific STK Push request by its ID.
Sample Response:
{
"success": true,
"data": {
"id": 13,
"amount": 500,
"phone_number": "254712345678",
"checkout_request_id": "dummy-checkout-req-id",
"mpesa_receipt_number": "ABCDEF1234",
"status": "completed",
"reason": "Dummy Payment Reason",
"created_at": "2025-06-14T09:00:00.000000Z"
}
}
Query the status of a specific STK Push request.
Query Parameters:
checkout_request_id (string, required): The CheckoutRequestID from the initiate response.Sample Response:
{
"success": true,
"data": {
"id": 123,
"amount": "100.00",
"phone_number": "2547XXXXXXXX",
"checkout_request_id": "ws_CO_1749941116758702455243",
"result_code": 0,
"result_desc": "The service request is processed successfully",
"mpesa_receipt_number": "TFF9X13IFT",
"status": "completed"
}
}
Query Third-Party STK Push status by its internal ID.
Query Parameters:
id (integer, required): The internal database ID of the third-party push.Sample Response:
{
"success": true,
"data": {
"id": 6,
"amount": "1.00",
"phone_number": "254702455243",
"third_party_account": "03704275146150",
"third_party_destination": "542542",
"checkout_request_id": "ws_CO_1749941116758702455243",
"mpesa_receipt_number": "TFF9X13IFT",
"status": "completed"
}
}
Allows reading and verifying your M-Pesa transaction history. (Requires Bearer Token)
List all transactions (paginated, filterable) or retrieve a single transaction.
Query Parameters (Optional):
limit (integer): Number of items per page (e.g., 200).search (string): Search by M-Pesa receipt, TransID, amount, or MSISDN.status (string): Filter by status (e.g., "Completed", "Pending").start_date (string): Filter from date (YYYY-MM-DD).end_date (string): Filter up to date (YYYY-MM-DD).BusinessShortCode (string): Filter by a specific Shortcode.id (integer): Retrieve a single transaction by its ID.TransID (string): Retrieve a single transaction by M-Pesa TransID.Sample Paginated Response:
{
"success": true,
"data": {
"current_page": 1,
"data": [
{
"id": 101,
"TransID": "DUMMYXYZ123",
"TransTime": "2025-01-01 10:00:00",
"TransAmount": "50.00",
"BusinessShortCode": "1234567",
"BillRefNumber": "INV-001",
"MSISDN": "2547XXXXXXXX",
"status": "Completed"
}
],
"total": 1
}
}
Verify the status of a transaction for a payment gateway.
Form Data:
trans_id (string, required): The M-Pesa Transaction ID (e.g., TFF4ZCF0UC).bill_ref_number (string, required): The bill reference number (e.g., invoice ID).amount (number, required): The expected amount.business_short_code (string, required): The M-Pesa Business Short Code.gateway_type (string, optional): e.g., "WHMCS".Sample Response:
{
"success": true,
"message": "Transaction verified and marked as used.",
"data": {
"id": 26,
"TransID": "TFF4ZCF0UC",
"TransAmount": "1.00",
"BusinessShortCode": "7180379",
"BillRefNumber": "11792",
"MSISDN": "254712345678",
"status": "USED BY WHMCS"
}
}
To make your work easier for integration, we have developed libraries and SDKs for popular languages. Get started quickly by installing our package and using these examples.
Installation (Composer):
composer require hostpay/laravel-sdk
Example Usage (Query STK Status):
use HostPay\Facades\HostPay;
// Your API Key is set in .env
// HOSTPAY_API_KEY=YOUR_API_KEY
$checkoutRequestId = 'ws_CO_...';
$response = HostPay::stkPush()->query($checkoutRequestId);
if ($response->isSuccessful()) {
// $response->getData() contains the transaction details
$status = $response->getData()['status'];
$receipt = $response->getData()['mpesa_receipt_number'];
} else {
// Handle error
$error = $response->getMessage();
}
Find the full library on GitHub.
Installation (Pip):
pip install hostpay-python
Example Usage (Verify Transaction):
from hostpay import HostPayClient
# Set your API key from environment variables
client = HostPayClient(api_key='YOUR_API_KEY')
try:
response = client.transactions.verify(
transaction_id='TFF4ZCF0UC',
bill_ref_number='11792',
amount=1.00,
business_short_code='7180379'
)
if response['success']:
print(f"Transaction verified: {response['data']['TransID']}")
else:
print(f"Verification failed: {response['message']}")
except Exception as e:
print(f"An error occurred: {e}")
Find the full library on GitHub.
Installation (NPM):
npm install @hostpay/api-client
Example Usage (Send SMS):
const { HostPayClient } = require('@hostpay/api-client');
// Set your API key from environment variables
const client = new HostPayClient('YOUR_API_KEY');
(async () => {
try {
const response = await client.sms.send({
recipient_phone: '2547XXXXXXXX',
message: 'Your order is confirmed!'
});
if (response.success) {
console.log('SMS sent!', response.data);
} else {
console.error('SMS failed:', response.message);
}
} catch (error) {
console.error('An error occurred:', error.message);
}
})();
Find the full library on GitHub.