Ahadi Pay Documentation

pip install requests

import requests, os

def register_reservable_item(item_id: str, item_data: dict) -> dict:
    # Step 1 — Save to YOUR database first (reservable_product_id is null for now)
    db.execute("""
        INSERT INTO your_items (id, name, price, capacity, reservable_product_id)
        VALUES (%s, %s, %s, %s, NULL)
    """, [item_id, item_data["name"], item_data["price"], item_data["capacity"]])

    # Step 2 — Register with Ahadi Pay
    response = requests.post(
        "https://api.loniwacapital.com/ahadipay/v1/products",
        headers={"X-Api-Key": os.environ["AHADI_API_KEY"]},
        json={
            "name":             item_data["name"],
            "industry_type":    item_data["industry_type"],  # e.g. "events"
            "price_cents":      item_data["price"] * 100,
            "deposit_percent":  item_data["deposit_percent"],
            "max_reservations": item_data["capacity"],
            "refund_policy": {
                "deadline_minutes":   item_data["deadline_days"] * 1440,
                "refundable_percent": item_data["refundable_percent"],
                "release_percent":    item_data["release_percent"],
            },
            # metadata is yours — pass whatever your domain needs
            # we store it and return it, we never interpret it
            "metadata": item_data.get("metadata", {}),
        }
    )
    product = response.json()

    # Step 3 — Write product_id back to YOUR database
    db.execute("""
        UPDATE your_items SET reservable_product_id = %s WHERE id = %s
    """, [product["id"], item_id])

    return product

AhadiPay.open({
  // Required — from your database (stored in step 2)
  product_id:   "prod_...",

  // Required — your internal customer identifier
  customer_ref: "cust_...",

  // Required — customer's M-Pesa registered phone number
  phone_number: "07XX XXX XXX",

  // Called when the customer completes the deposit payment
  on_success: function(reservation) {
    // reservation.id        — save this to your booking record
    // reservation.status    — "reserved"
    // reservation.percent_paid — e.g. 40 (deposit percent)
    saveBooking(reservation.id)
    showLockedTicket()
  },

  // Called if the customer cancels or an error occurs
  on_error: function(error) {
    showError(error.message)
  },
})

# Customer pays KES 2,000 installment
response = requests.post(
    f"https://api.loniwacapital.com/ahadipay/v1/public/reservations/{reservation_id}/pay",
    headers={"X-Api-Key": os.environ["AHADI_API_KEY"]},
    json={
        "amount_cents":     200000,    # KES 2,000
        "payment_provider": "mpesa",
        "phone_number":     "0712345678",
    }
)
# status: "pending" — STK push sent
# Poll GET /public/reservations/{id} to confirm

import hmac, hashlib, os
from flask import Blueprint, request, jsonify

webhook_bp = Blueprint("webhook", __name__)

@webhook_bp.route("/webhooks/ahadi", methods=["POST"])
def ahadi_webhook():
    signature = request.headers.get("X-Ahadi-Signature", "")
    raw_body  = request.get_data()

    expected = "sha256=" + hmac.new(
        os.environ["AHADI_WEBHOOK_SECRET"].encode(),
        raw_body,
        hashlib.sha256
    ).hexdigest()

    # Always use compare_digest — prevents timing attacks
    if not hmac.compare_digest(signature, expected):
        return jsonify({"error": "Invalid signature"}), 401

    payload = request.get_json()

    if payload["event"] == "payment.received":
        pct = payload["percent_paid"]
        if payload["status"] == "reserved" and pct < 100:
            # First payment — create locked ticket
            create_locked_ticket(payload["reservation_id"])
        if pct == 100:
            # Balance cleared — unlock ticket, send QR
            unlock_ticket(payload["reservation_id"])

    elif payload["event"] == "reservation.cancelled":
        cancel_ticket(payload["reservation_id"])
        notify_customer_refund(payload["reservation_id"])

    elif payload["event"] == "reservation.expired":
        expire_ticket(payload["reservation_id"])

    # Always return 200 quickly
    return jsonify({"received": True}), 200