Hunting Seven Digits: How We Built a Binance P2P Auto-Release System for M-Pesa

At 10 or 20 transactions per day, manual processing may still be manageable. At hundreds of orders, repetitive verification becomes a serious operational bottleneck. The goal was therefore much more ambitious: automate the complete payment-to-release lifecycle while keeping release decisions strictly verified. 

The system was designed as an event-driven service connecting exchange order events with incoming M-Pesa payment callbacks.

The architecture was straightforward. The difficult question was how to reliably associate an asynchronous M-Pesa payment with the correct Binance P2P order.

22933168290608160768

M-Pesa provides a reference field such as BillRefNumber. Asking a buyer to manually enter a 20-digit exchange identifier on a smartphone proved unrealistic. References could be mistyped, replaced with phone numbers or filled with unrelated text.

As soon as a new SELL order was detected, the bot sent the buyer a message containing the seven-digit payment reference. This dramatically simplified the mobile payment flow while preserving a deterministic link back to the full exchange order identifier.

One evening, the safety system suspended an automatic release because it believed an incoming M-Pesa payment contained an invalid reference.

! Auto-Release Suspended (Action Required)
Reason: Missing or invalid BillRefNumber

M-Pesa Payment:
Receipt: UIFKX6WZCW
Amount: 93000.00 KES
Ref: 8160768

There was only one problem with the error message: the reference was correct. 

The payment amount was correct. The M-Pesa reference was 8160768. The Binance order existed and ended with exactly the same seven digits. Yet the matching engine refused to release.

The only way to understand the failure was to reconstruct the exact event sequence from the service logs.

journalctl -u MpesaP2PayBot.service --since "2026-09-15 16:20:00"

The original matching implementation searched the current in-memory order list for an order number ending with the supplied reference:

raw_active = getattr(self.binance, "orders", [])
active_list = [o for o in raw_active]

if clean_ref:
    for o in active_list:
        cand_no = str(o.get("orderNumber", ""))

        if cand_no.endswith(clean_ref):
            matched_order = self.binance.getUserOrderDetail(cand_no)
            break

    if not matched_order and len(clean_ref) >= 15:
        matched_order = self.binance.getUserOrderDetail(clean_ref)

The flaw was subtle. Direct order lookup was available only when the reference contained a nearly complete order number. Our seven-digit reference therefore depended entirely on the temporary contents of the in-memory active order list.

A WebSocket reconnect, incomplete polling response, pagination timing or another synchronization event could temporarily remove an otherwise valid order from that collection. If the payment callback arrived during that window, matching failed.

The answer was not to poll Binance more aggressively. More polling would increase API traffic without fixing the architectural weakness.

The system already maintained SQLite persistent storage in WAL mode for discovered orders. The matching engine simply needed to use it as a fallback when runtime state could not resolve the seven-digit reference.

for o in active_list:
    cand_no = str(o.get("orderNumber", ""))

    if cand_no.endswith(clean_ref):
        matched_order = self.binance.getUserOrderDetail(cand_no)

        if matched_order:
            break

if not matched_order:
    try:
        from app.orders_state import get_connection

        with get_connection() as conn:
            row = conn.execute(
                "SELECT order_number FROM orders "
                "WHERE order_number LIKE ? "
                "ORDER BY created_at DESC LIMIT 1;",
                (f"%{clean_ref}",)
            ).fetchone()

            if row:
                found_order_no = row["order_number"]
                matched_order = self.binance.getUserOrderDetail(found_order_no)

    except Exception as ex_db:
        log.logging(f"[MATCHING ENGINE DB FALLBACK ERROR] {ex_db}")

The important distinction is that SQLite does not authorize the release by itself. It recovers the full order identifier. The current order state can then be checked against Binance before the release workflow proceeds.

The objective of an auto-release system is not to release cryptocurrency as fast as technically possible. It is to release it as fast as possible after the payment and order have been verified. 

Once the exchange reports the order as completed, the workflow can continue with post-trade communication. Instead of requiring the merchant to manually send the same message after every successful trade, a background worker can respond to the completed-order event.

✅ Trade completed successfully.

Thank you for trading with us!

⭐ If you are satisfied with the fast transaction,
we'd appreciate your positive feedback.

See you again!

At that point the workflow covers the complete operational cycle: order detection, payment instructions, M-Pesa callback processing, resilient matching, exchange verification, crypto release and post-trade communication.