DEV Community

Stanley Chege Thuita
Stanley Chege Thuita

Posted on

what happens when the M-Pesa callback is slow?

tweet

series: Bitcoin to M-Pesa off-ramp

Nia asked exactly the right question on my off-ramp thread:

Nice use of hold invoices. What happens when the M-Pesa result callback is slow? Long holds tie up liquidity along the route, so curious what timeout you picked before refunding.

Short answer: after 60 seconds with no callback I ask M-Pesa for the payout's status. I only refund on a final failure answer, never on a blind timer. That choice protects funds but it does tie up route liquidity, so here is the full trade-off, the code, and what I still need to fix.

Code: altradits/offramp (MIT). All paths below are in that repo.

The timeline

t=0s    sats lock (ACCEPTED) -> we send B2C payout, journal PAYING first
t=0-60s normal: result callback arrives -> settle (PAID) or cancel (REFUNDED)
t=60s   no callback yet -> TransactionStatusQuery (same OriginatorConversationID)
        -> status answer arrives on /daraja/status
        -> Completed => settle | Failed/Cancelled/Expired => cancel
        -> still processing / no answer => ask again later
Enter fullscreen mode Exit fullscreen mode

The three numbers that control this are defaults in createOfframp (src/offramp.mjs):

cltvExpiry = 144, invoiceExpirySec = 600, statusAfterMs = 60_000
Enter fullscreen mode Exit fullscreen mode
  • statusAfterMs = 60_000: wait 60s in PAYING before the first status query.
  • invoiceExpirySec = 600: the hold invoice expires for new payments after 10 minutes.
  • cltvExpiry = 144: the HTLC safety margin (~24h of blocks).

What the code actually does

The watchdog lives in the tick loop:

} else if (o.state === "PAYING" && Date.now() - Date.parse(o.updatedAt) > statusAfterMs && !o.asked) {
  o.asked = true;
  await daraja.status({ originatorId: o.id });
  log(`[${o.id.slice(0, 8)}] no result yet: asked M-Pesa for the payout's status`);
}
Enter fullscreen mode Exit fullscreen mode

o.id is reused as OriginatorConversationID, so the query refers to the exact payout and a retry can never become a second payment. PAYING is journaled before the B2C request is sent, so a crash in the middle restarts as PAYING and asks instead of re-paying. That is the "killed the server mid-payout" test: paid exactly once, receipt recovered.

The status query itself is Daraja's TransactionStatusQuery (src/daraja.mjs). The answer arrives later on a different callback URL and in a different shape — the payout's ID is buried inside ResultParameters — so parseResult reads both shapes:

final: Number(r.ResultCode) === 0 &&
  ["Completed", "Failed", "Cancelled", "Expired"].includes(params.TransactionStatus),
Enter fullscreen mode Exit fullscreen mode

And the result handler only finishes on a final answer:

if (r.ok) {
  await lnd.settle(o.preimageHex);   // PAID
} else if (r.final) {
  await lnd.cancel(o.hashHex);       // REFUNDED
} else {
  o.asked = false; // not final yet (e.g. still processing): ask again later
}
Enter fullscreen mode Exit fullscreen mode

Why 60 seconds, and why no blind refund

Daraja's own docs treat B2C as async: the POST only means "accepted", the money moves later, and the result/timeout callbacks can lag under load. 60s is long enough to avoid spamming status queries on every normal payout (my lab payouts confirm in ~1-3s) and short enough that a genuinely lost callback is chased while the customer is still watching.

The harder part of Nia's question: there is no timer that cancels the hold invoice just because M-Pesa is quiet. That is deliberate, and it is also the weakest point of the current code:

  • If I refund after N minutes while M-Pesa later completes the payout, I lose the KES and return the sats. Double loss.
  • So today the hold stays open until M-Pesa gives a final answer, or the invoice/CLTV expiry forces the issue. Once the invoice is ACCEPTED, the 600s invoice expiry stops new payments but the locked HTLC lives until settle/cancel or the CLTV branch — up to ~144 blocks in the worst case.

Nia is right that this ties up liquidity along the whole route for the duration. For a small, slow lane (one payout every few minutes) that is tolerable. For real volume it is not.

What I am changing next

  1. Bounded hold with status-gated cancel. If the status query itself returns final Failed/Cancelled/Expired (or "not found" after retries), cancel immediately — that is already a safe refund. Only the truly-unknown case (no callback and no status answer) should ever reach a human.
  2. Shorter, staggered queries. One query at 60s, then backoff (e.g. 60s / 5min / 15min) instead of asking again on the very next tick after a non-final answer.
  3. Operator surface. Surface PAYING-older-than-N-minutes with the last Daraja answer, so a stuck order is one screen, not one log grep.
  4. Lower cltvExpiry for small payouts. 144 is the LND-ish default; small tickets can carry a smaller worst-case lock.

If you run routing nodes: what worst-case hold would you tolerate from a service like this before you start failing its routes? I want the next timeout value to come from operators, not from me guessing.

Try it yourself

git clone https://github.com/altradits/offramp.git
cd offramp
npm test   # 10 tests: paid, refused, crash-mid-payout, overlapping ticks, forged callbacks
Enter fullscreen mode Exit fullscreen mode

Then the full lab with real Lightning on regtest is in the README. Issues labelled good first issue / help wanted are open — MTN MoMo, Airtel Money, Vodacom M-Pesa and Telebirr adapters all have the same pay / status / parseResult shape.

Thank you Nia — this is exactly the review open source is for. 🧡

Top comments (0)