Mall House Services API documentation

cURL

curl https://mallhouseservices.com/api/v1/account/ \
  -H "Authorization: Bearer $MHS_API_KEY"

Python

import os
import requests

API_KEY = os.environ["MHS_API_KEY"]
BASE_URL = "https://mallhouseservices.com/api/v1"

response = requests.get(
    f"{BASE_URL}/account/",
    headers={"Authorization": f"Bearer {API_KEY}"},
    timeout=15,
)
response.raise_for_status()
account = response.json()["data"]
print(account["balance"], account["currency"])

Node.js

// Node.js 18+ (built-in fetch)
const API_KEY = process.env.MHS_API_KEY;
const BASE_URL = "https://mallhouseservices.com/api/v1";

const res = await fetch(`${BASE_URL}/account/`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});
const body = await res.json();
if (!body.success) throw new Error(body.error.message);
console.log(body.data.balance, body.data.currency);

PHP

<?php
$apiKey = getenv('MHS_API_KEY');
$ch = curl_init('https://mallhouseservices.com/api/v1/account/');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $apiKey"],
    CURLOPT_TIMEOUT => 15,
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);

echo $body['data']['balance'] . ' ' . $body['data']['currency'];

cURL

curl "https://mallhouseservices.com/api/v1/packages/?network=mtn" \
  -H "Authorization: Bearer $MHS_API_KEY"

Python

response = requests.get(
    f"{BASE_URL}/packages/",
    params={"network": "mtn"},
    headers={"Authorization": f"Bearer {API_KEY}"},
    timeout=15,
)
for package in response.json()["data"]:
    print(package["id"], package["size_gb"], "GB", package["price"])

Node.js

const res = await fetch(`${BASE_URL}/packages/?network=mtn`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});
const { data: packages } = await res.json();
packages.forEach((p) => console.log(p.id, `${p.size_gb}GB`, p.price));

PHP

<?php
$ch = curl_init('https://mallhouseservices.com/api/v1/packages/?network=mtn');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $apiKey"],
]);
$packages = json_decode(curl_exec($ch), true)['data'];
curl_close($ch);

foreach ($packages as $p) {
    echo "{$p['id']}: {$p['size_gb']}GB - {$p['price']}\n";
}

cURL

curl -X POST https://mallhouseservices.com/api/v1/orders/ \
  -H "Authorization: Bearer $MHS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "network": "mtn",
    "size_gb": 5,
    "phone_number": "0241234567",
    "reference": "INV-1001"
  }'

Python

payload = {
    "network": "mtn",          # or send "package_id": 12 instead
    "size_gb": 5,
    "phone_number": "0241234567",
    "reference": "INV-1001",   # your own unique ID - safe to retry
}
response = requests.post(
    f"{BASE_URL}/orders/",
    json=payload,
    headers={"Authorization": f"Bearer {API_KEY}"},
    timeout=30,
)
body = response.json()
if body["success"]:
    order = body["data"]
    print("Order", order["id"], "is", order["status"])
else:
    print("Failed:", body["error"]["code"], body["error"]["message"])

Node.js

const res = await fetch(`${BASE_URL}/orders/`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    network: "mtn",            // or package_id: 12
    size_gb: 5,
    phone_number: "0241234567",
    reference: "INV-1001",     // your own unique ID - safe to retry
  }),
});
const body = await res.json();
if (body.success) {
  console.log(`Order ${body.data.id} is ${body.data.status}`);
} else {
  console.error(body.error.code, body.error.message);
}

PHP

<?php
$payload = json_encode([
    'network' => 'mtn',          // or 'package_id' => 12
    'size_gb' => 5,
    'phone_number' => '0241234567',
    'reference' => 'INV-1001',   // your own unique ID - safe to retry
]);

$ch = curl_init('https://mallhouseservices.com/api/v1/orders/');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $apiKey",
        'Content-Type: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);

if ($body['success']) {
    echo "Order {$body['data']['id']} is {$body['data']['status']}";
} else {
    echo "Failed: {$body['error']['code']} - {$body['error']['message']}";
}

cURL

# By id
curl https://mallhouseservices.com/api/v1/orders/42/ \
  -H "Authorization: Bearer $MHS_API_KEY"

# By your own reference
curl "https://mallhouseservices.com/api/v1/orders/?reference=INV-1001" \
  -H "Authorization: Bearer $MHS_API_KEY"

Python

response = requests.get(
    f"{BASE_URL}/orders/42/",
    headers={"Authorization": f"Bearer {API_KEY}"},
    timeout=15,
)
print(response.json()["data"]["status"])  # pending | processing | complete | cancelled

Node.js

const res = await fetch(`${BASE_URL}/orders/?reference=INV-1001`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});
const { data } = await res.json();
console.log(data[0]?.status);

PHP

<?php
$ch = curl_init('https://mallhouseservices.com/api/v1/orders/42/');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $apiKey"],
]);
$order = json_decode(curl_exec($ch), true)['data'];
curl_close($ch);

echo $order['status'];

cURL

# Simulate a delivery to your own endpoint while developing:
BODY='{"event":"order.complete","data":{"id":42,"status":"complete"}}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$MHS_WEBHOOK_SECRET" | sed 's/^.* //')
curl -X POST https://example.com/webhooks/mhs \
  -H "Content-Type: application/json" \
  -H "X-MHS-Signature: sha256=$SIG" \
  -d "$BODY"

Python

# Flask example
import hashlib
import hmac
import os

from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["MHS_WEBHOOK_SECRET"].encode()

@app.post("/webhooks/mhs")
def mhs_webhook():
    expected = "sha256=" + hmac.new(SECRET, request.get_data(), hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, request.headers.get("X-MHS-Signature", "")):
        abort(401)
    event = request.get_json()
    order = event["data"]
    print(event["event"], order["id"], order["reference"])
    return "", 200

Node.js

// Express example
import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.MHS_WEBHOOK_SECRET;

app.post("/webhooks/mhs", express.raw({ type: "application/json" }), (req, res) => {
  const expected = "sha256=" +
    crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");
  const given = req.get("X-MHS-Signature") || "";
  if (given.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected))) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body);
  console.log(event.event, event.data.id, event.data.reference);
  res.sendStatus(200);
});

PHP

<?php
$secret = getenv('MHS_WEBHOOK_SECRET');
$raw = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $raw, $secret);
$given = $_SERVER['HTTP_X_MHS_SIGNATURE'] ?? '';

if (!hash_equals($expected, $given)) {
    http_response_code(401);
    exit;
}

$event = json_decode($raw, true);
$order = $event['data'];
error_log("{$event['event']} order {$order['id']} ({$order['reference']})");
http_response_code(200);