Pay any Kenyan phone number over Lightning

00What this is

An ordinary LNURL-pay server living at bitcoin.co.ke/.well-known/lnurlp/<phone>, where the username is a Kenyan mobile number. It speaks LUD-16, LUD-06, plus a currency extension for Shilling-denominated amounts, so any Lightning address client already talks to it. Four steps, two of which are just Lightning.

Everything is on one host, https://bitcoin.co.ke. Three endpoints, and you only need the first two.

01Address format

The username part of the address is a Kenyan mobile number in international format, with no + and no spaces.

Only Safaricom ranges resolve today, because M-Pesa delivery is the point. The accepted prefixes after the 254 country code are 70x through 79x, 11x, and 14x, each followed by six digits for twelve digits total. A number outside those ranges gets the non-phone redirect, not a payment.

02Quickstart

Three calls, end to end. Read the limits, ask for an invoice priced in Shillings, pay it with any Lightning wallet, then poll for the M-Pesa receipt.

# 1. What can this address accept right now?
curl "https://bitcoin.co.ke/.well-known/lnurlp/254712345678"

# 2. Ask for an invoice that delivers KES 100 to that number
curl "https://bitcoin.co.ke/.well-known/lnurlp/254712345678?amount=100&currency=KES"

# 3. Pay the returned BOLT11, then poll with its payment hash
curl "https://bitcoin.co.ke/api/payment/<paymentHash>"

If you already have a Lightning address client, step 1 and 2 are what it does natively. Point it at [email protected] and it will work with no changes at all. Step 3 is the only bitcoin.co.ke specific part, and it is optional.

03Step 1: get the current bounds

Call the address with no query string. You get a standard LUD-06 payRequest object, extended with the currency extension's currency block that describes the same limits in Shillings.

curl "https://bitcoin.co.ke/.well-known/lnurlp/254712345678"

{
  "callback": "https://bitcoin.co.ke/.well-known/lnurlp/254712345678",
  "maxSendable": 446622000,
  "minSendable": 135000,
  "metadata": "[[\"text/plain\",\"Payment to Kenyan phone [email protected]\"],[\"text/identifier\",\"[email protected]\"]]",
  "currency": {
    "code": "KES",
    "name": "Kenyan Shillings",
    "symbol": "KSh",
    "decimals": 0,
    "minSendable": 15,
    "maxSendable": 50000,
    "multiplier": 8932
  },
  "tag": "payRequest"
}

04Step 2: get an invoice

Call the same URL again with an amount. With no currency parameter the amount is in millisatoshi, exactly as LUD-06 specifies.

# 500,000 msat = 500 sats
curl "https://bitcoin.co.ke/.well-known/lnurlp/254712345678?amount=500000"

{
  "pr": "lnbc5u1p5q8xvmpp5k2j...xq8lqqqqqgqqyg",
  "routes": [],
  "successAction": {
    "tag": "url",
    "description": "View your M-Pesa receipt",
    "url": "https://bitcoin.co.ke/receipt/880633ee6872e3e7a8d9df184c5656c8f077b0280136b206288054252dc619c1"
  }
}

The payment request is the Lightning invoice. It arrives in the field named pr, which is what the spec calls it, and it is the only field you have to act on: pay it with any Lightning enabled Bitcoin wallet or node. The payment hash in the successAction URL is the same hash as the one inside the invoice, so you can equally decode the BOLT11 and take it from there.

05Pricing in Shillings instead of sats

Add currency=KES and the amount is read as Shillings. This is the more natural mode for most integrations here: you say what the recipient should receive, and we compute the sats required to deliver exactly that many Shillings.

# Deliver KES 100 to this number
curl "https://bitcoin.co.ke/.well-known/lnurlp/254712345678?amount=100&currency=KES"

{
  "pr": "lnbc9020n1p5q8xvmpp5j7f...xq8lqqqqqgqqyg",
  "routes": [],
  "successAction": {
    "tag": "url",
    "description": "View your M-Pesa receipt",
    "url": "https://bitcoin.co.ke/receipt/880633ee6872e3e7a8d9df184c5656c8f077b0280136b206288054252dc619c1"
  },
  "converted": 100
}

Pick KES mode when you are pricing something in Shillings, such as a bill, a salary, or a cart total. Pick msat mode when you are spending a fixed amount of Bitcoin and do not mind what it lands as. The converted field in the response echoes the KES the invoice was priced for, so you can show it back to the payer before they confirm.

06Fees and rounding

There is a flat 1% fee on the conversion. Where it lands depends on which mode you used, and it is worth getting right before you reconcile anything.

In KES mode the payer covers the fee on top, so the recipient gets the round number you asked for. In sats mode the invoice is exactly what you asked for, so the fee comes out of the delivered value. The KES payout is floored to a whole Shilling, since M-Pesa does not move cents.

07The receipt link (LUD-09)

Every invoice we mint for an M-Pesa payout comes back with a LUD-09 successAction of type url. It points at a page that shows the real M-Pesa receipt for the payout, keyed by the Lightning payment hash.

{
  "successAction": {
    "tag": "url",
    "description": "View your M-Pesa receipt",
    "url": "https://bitcoin.co.ke/receipt/<paymentHash>"
  }
}

If you are building a wallet, show it the way LUD-09 says: display the description after the payment settles and let the user open the url. The page polls in the background and fills in the M-Pesa confirmation code as soon as the payout lands, so it is safe to open immediately.

If you are building a server integration you may prefer to skip the page and poll the JSON API in the next section, which is exactly what that page does under the hood. The URL is also a perfectly good thing to hand a customer in an email or an SMS, since it is stable and needs no login.

08Step 3: poll for the M-Pesa receipt

One GET, keyed by the 64 character hex payment hash. It returns the same data the receipt page renders, in JSON.

curl "https://bitcoin.co.ke/api/payment/880633ee6872e3e7a8d9df184c5656c8f077b0280136b206288054252dc619c1"

{
  "success": true,
  "transaction": {
    "status": "completed",
    "isPaid": true,
    "paymentNetworkReceipt": "TIA7QK4M2P",
    "payToAccount": "254712345678",
    "merchantName": "JANE W MWANGI",
    "currencyAmount": 100,
    "currencyAmountSent": 100,
    "baseCurrency": "KES",
    "satsAmount": 893,
    "tandoFees": 8.93,
    "totalSatsAmount": 901.93,
    "exchangeRate": 0.00000008932,
    "paymentHash": "880633ee6872e3e7a8d9df184c5656c8f077b0280136b206288054252dc619c1",
    "dateTime": "2026-09-22T18:41:07.512Z",
    "completedAt": "2026-09-22T18:41:19.860Z"
  }
}

{
  "success": false,
  "error": {
    "errorCode": "transaction-not-found",
    "message": "Transaction not found"
  }
}

Reading the status

Treat a payment as settled only when status is completed, isPaid is true, and paymentNetworkReceipt is present. That last field is the M-Pesa confirmation code, the same ten character code the recipient sees in their SMS, and it is the only proof the Shillings actually moved.

Field reference

A polling loop that behaves

async function waitForReceipt(paymentHash, { intervalMs = 3000, timeoutMs = 120000 } = {}) {
  const url = `https://bitcoin.co.ke/api/payment/${paymentHash}`;
  const deadline = Date.now() + timeoutMs;
  let notFoundStreak = 0;

  while (Date.now() < deadline) {
    const res = await fetch(url);

    if (res.status === 404) {
      // The row is written moments after the invoice is issued.
      // Give it a few tries before calling it unknown.
      if (++notFoundStreak > 7) throw new Error("Unknown payment hash");
    } else if (res.ok) {
      const { transaction: tx } = await res.json();
      if (tx.status === "completed" && tx.isPaid && tx.paymentNetworkReceipt) {
        return tx;  // tx.paymentNetworkReceipt is the M-Pesa code
      }
      if (tx.status === "failed") {
        throw new Error(`Payout failed: ${tx.failureReason}`);
      }
    }

    await new Promise(r => setTimeout(r, intervalMs));
  }
  throw new Error("Timed out waiting for the M-Pesa receipt");
}

Three seconds is the cadence our own receipt page uses, and two minutes is a generous ceiling. Most payouts confirm within seconds of the Lightning payment. A payment that is still received after two minutes is not lost, it is delayed on the M-Pesa side, so surface it as pending rather than failed and keep the payment hash.

09Claimed numbers

A Kenyan can claim their own number at bitcoin.co.ke/claim-lightning-address and point it at any Lightning address they control. After that, their number stops being an M-Pesa payout and becomes an alias for their own wallet. The address string does not change, so as a payer you do nothing differently.

What changes for you

The limits point is the one that bites integrations. A claimed number backed by a wallet with a 5,000,000 sat ceiling will advertise exactly that, which is far above our KES ceiling, and a number backed by a custodial wallet with a 1,000 sat floor will advertise that instead. This is another reason to read minSendable and maxSendable per request rather than hardcoding the Shilling range.

Telling the two apart

You usually do not need to, but the metadata response tells you. A claimed number returns a callback carrying an opaque fwd parameter, and no currency block unless the destination sent one.

# Claimed: note the fwd token on the callback
{
  "callback": "https://bitcoin.co.ke/.well-known/lnurlp/254712345678?fwd=aHR0cHM6Ly9...",
  "minSendable": 1000,
  "maxSendable": 500000000,
  "metadata": "[[\"text/plain\",\"Payment to Kenyan phone [email protected]\"],[\"text/identifier\",\"[email protected]\"]]",
  "commentAllowed": 200,
  "tag": "payRequest"
}

Follow the callback exactly as returned, fwd token and all, and append your amount to it. Any extra parameters you send, such as comment or nostr, are forwarded to the destination untouched, and its invoice comes back to you unchanged.

10Errors

LNURL errors follow LUD-01: a JSON body with status set to ERROR and a human-readable reason. Parse the body, do not switch on the HTTP status code.

curl "https://bitcoin.co.ke/.well-known/lnurlp/254712345678?amount=5&currency=KES"

{"status":"ERROR","reason":"Amount below minimum. Min 15 KES."}

curl "https://bitcoin.co.ke/.well-known/lnurlp/254712345678?amount=1000"

{"status":"ERROR","reason":"Amount below minimum. Min 135000 msat."}

11Testing

Free to call, all day

Metadata reads cost nothing and issue nothing. Build and debug your whole integration against step 1, since that is where the bounds, the rate, and the claimed versus M-Pesa branch all show up.

# Safe to run as often as you like
curl -s "https://bitcoin.co.ke/.well-known/lnurlp/254712345678" | jq .

# Error paths are free too: these are refused before anything is minted
curl -s "https://bitcoin.co.ke/.well-known/lnurlp/254712345678?amount=1&currency=KES"
curl -s "https://bitcoin.co.ke/.well-known/lnurlp/254712345678?amount=999999&currency=KES"

# Unknown hash, to shape your polling code against a real 404
curl -s "https://bitcoin.co.ke/api/payment/$(printf '0%.0s' {1..64})"

The smallest real end to end test

KES 15 is the floor, which is roughly 135 sats at current rates. Send it to a number you control and watch the whole chain work.

# 1. Mint a 15 KES invoice to your own number
curl -s "https://bitcoin.co.ke/.well-known/lnurlp/254712345678?amount=15&currency=KES" | jq -r .pr

# 2. Pay it from any wallet or node within 120 seconds
lncli payinvoice <the pr value>

# 3. Poll until the M-Pesa code appears
curl -s "https://bitcoin.co.ke/api/payment/<paymentHash>" \
  | jq '.transaction | {status, isPaid, paymentNetworkReceipt, currencyAmountSent}'

Expect the M-Pesa SMS on the destination handset at about the same moment status flips to completed. If the SMS arrives and the API still says received, give it a few more seconds, since the confirmation reaches us just after the recipient.

Wallet compatibility check

If you are testing from a wallet rather than code, paste [email protected] into its send field. Anything that supports Lightning addresses will resolve it. Wallets that also implement the currency extension will offer you a KES amount field, and wallets that implement LUD-09 will show the receipt link after paying. We keep a public tracker of which wallets support what at tando-me/bitcoin-wallet-compatibility, so check there before blaming your code.

Checklist before you go live

• You re-read the metadata immediately before every invoice request, and never cache bounds.
• You handle a LUD-01 error body arriving with an HTTP 200.
• You treat a 404 from the status API as "not yet", up to a handful of tries.
• You only mark a payment complete on completed plus isPaid plus a receipt code.
• You store the payment hash against your own order, since it is the key to every lookup and any support conversation.
• You handle a claimed number advertising limits nothing like our KES range.

12Limits and gotchas

Things that surprise people

• The ceiling moves. It is the lesser of our configured maximum and the Shillings we can actually pay out at that moment, so a 50,000 quote at breakfast can be lower by lunchtime.
• The rate moves between your two calls. We re-price and re-validate at invoice time, so an amount that passed the metadata check can still be refused seconds later. Handle the error rather than assuming step 1 guarantees step 2.
• Errors come back with HTTP 200. That is LUD-01, not a bug. Check the body for status: "ERROR" on every response.
• The status API is keyed by payment hash only. There is no listing endpoint and no lookup by phone number, by design. Keep your hashes.
• A number can be claimed between your calls. Rare, but it means the callback you were given can behave differently from the metadata you read. Re-reading the metadata per payment handles this too.
• Comments are not supported on the M-Pesa flow. We do not advertise commentAllowed, so a comment you send is ignored rather than attached to the M-Pesa payout.

13Spec support

Specs live at github.com/lnurl/luds if you want the letter of any of the above.