ChapSmart – API Documentation

Authentication

All API requests require authentication via API key headers. Contact our team to receive your credentials.

// Required headers for every request
{
  "X-API-Key": "your_api_key",
  "X-API-Secret": "your_api_secret",
  "Content-Type": "application/json"
}

API keys are provided upon approval. Never expose your API secret in client-side code. All calls should be proxied through your backend server.

Tiers & Fee Structure

Fees decrease as cumulative transaction volume grows. Tiers are calculated across all transaction types (remittance + airtime).

Tier	Cumulative Volume	Remittance Fee
Bronze	0 – 5,000,000 TZS	2.20%
Silver	5,000,001 – 25,000,000 TZS	1.87%
Gold	25,000,001+ TZS	1.32%

Authentication

Create anonymous accounts and authenticate users. No personal data required.

POST /api/v1/auth/createAccount Create anonymous account

Creates a new 16-digit anonymous account number. No personal information required.

Request Body

{}

Response 200

{
  "success": true,
  "accountNumber": "1234567890123456",
  "message": "Account created successfully"
}

The account number is the only credential. If lost, the account cannot be recovered. Instruct users to save it securely.

POST /api/v1/auth/login Authenticate with account number

Verifies an account number exists and is active.

Request Body

{
  "accountNumber": "1234567890123456"
}

Response 200

{
  "success": true,
  "accountNumber": "1234567890123456",
  "message": "Login successful"
}

200 OK 404 Not Found

Remittance

Send Bitcoin via Lightning and deliver TZS to any Vodacom M-Pesa number. Flow: Quote → Generate Invoice → Pay → Auto-delivery.

POST /api/v1/invoices/quote Get price quote

Creates a temporary price quote showing exact sats amount, fees, and tier. Quotes expire after 5 minutes and prices update with live BTC rates.

Request Body

{
  "metadata": {
    "amountTZS": 25000,
    "phoneNumber": "0741000000",
    "recipientName": "John Doe",
    "accountNumber": "1234567890123456"
  }
}

Parameter	Type	Required	Description
amountTZS	number	required	Amount in TZS (2,500 – 1,000,000)
phoneNumber	string	required	Vodacom M-Pesa number (07XX format)
recipientName	string	required	First and last name of recipient
accountNumber	string	required	Your 16-digit account number

Response 200

{
  "success": true,
  "quoteId": "abc123...",
  "youPay": {
    "sats": 14680,
    "btc": "0.00014680",
    "feeSats": 270,
    "feePercent": 2.20
  },
  "userTier": "BRONZE"
}

200 Quote Created 400 Validation Error 403 Account Not Found

POST /api/v1/invoices/generate Generate Lightning invoice

Converts a quote into a real Lightning invoice. Returns a BOLT11 string and checkout link. Once paid, M-Pesa delivery is automatic.

Request Body

{
  "quoteId": "abc123..."
}

Response 200

{
  "success": true,
  "invoiceId": "XYZ789...",
  "bolt11": "lnbc...",
  "checkoutLink": "https://pay.chapsmart.com/i/XYZ789",
  "youPay": { "sats": 14680 }
}

If the user has a WebLN-compatible wallet (Alby, etc.), you can call window.webln.sendPayment(bolt11) for one-click payment.

GET /api/v1/invoices/status/{invoiceId} Check payment status

Poll this endpoint after invoice generation to track payment and delivery status. Works for both remittance and airtime transactions.

Response 200

{
  "success": true,
  "invoiceId": "XYZ789...",
  "status": "completed",
  "message": "Payment confirmed and M-Pesa sent!",
  "type": "remittance"
}

Status	Meaning
pending	Waiting for Lightning payment
settled	Payment received, payout processing
completed	Payout delivered to recipient
expired	Invoice expired (not paid in time)
failed	Payout failed (support will resolve)

Recommended polling interval: every 5 seconds. Max timeout: 10 minutes.

Airtime Top-Up

Buy airtime for any Tanzanian mobile number using Lightning. Same flow: Quote → Generate → Pay → Delivered.

POST /api/v1/airtime/quote Get airtime quote

Creates a price quote for airtime top-up.

Request Body

{
  "metadata": {
    "amountTZS": 1000,
    "phoneNumber": "255741000000",
    "accountNumber": "1234567890123456"
  }
}

Parameter	Type	Required	Description
amountTZS	number	required	Airtime amount (500 – 15,000 TZS)
phoneNumber	string	required	Phone number in 255 format (e.g. 255741000000)
accountNumber	string	required	Your 16-digit account number

Airtime phone numbers must be in international format (255XXXXXXXXX). If user enters 07XX, convert to 2557XX before sending.

POST /api/v1/airtime/generate Generate airtime invoice

Same as remittance generate — pass the quoteId to create a Lightning invoice. Once paid, airtime is delivered automatically.

Request Body

{
  "quoteId": "airtime_quote_id..."
}

Buy Sats

Purchase Bitcoin with M-Pesa. Flow: Quote → User pays M-Pesa → Submit transaction ID + BOLT11 → Sats delivered.

POST /api/v1/buy/quote Get buy sats quote

Returns how many sats the user will receive for a given TZS amount, based on live BTC/TZS rates.

Request Body

{
  "amountTZS": 10000,
  "accountNumber": "1234567890123456"
}

Response 200

{
  "success": true,
  "quoteId": "buy_quote_id...",
  "calculatedSats": 5870,
  "btcPrice": 97500
}

Parameter	Type	Required	Description
amountTZS	number	required	Amount to spend (1,000 – 100,000 TZS)
accountNumber	string	required	Your 16-digit account number

POST /api/v1/buy/send-sats Submit payment & receive sats

After the user pays via M-Pesa, submit the M-Pesa transaction ID and a BOLT11 invoice. The server verifies the payment and pays the user's invoice.

Request Body

{
  "quoteId": "buy_quote_id...",
  "mpesaId": "XKR4MPT9QZN",
  "bolt11": "lnbc5870n1p..."
}

Response 200

{
  "success": true,
  "satsSent": 5870,
  "message": "Sats delivered to your wallet"
}

Data & History

Retrieve transaction history and account statistics.

POST /api/v1/history Get transaction history

Returns all completed transactions for an account, sorted newest first. Includes remittance, airtime, and buy-sats types.

Request Body

{
  "accountNumber": "1234567890123456"
}

Response 200

{
  "success": true,
  "transactions": [
    {
      "type": "remittance",
      "amount": 25000,
      "status": "completed",
      "phoneNumber": "0741***890",
      "createdAt": "2026-03-14T09:41:00Z"
    }
  ],
  "stats": {
    "totalTransactions": 12
  }
}

GET /api/v1/user/stats?accountNumber={id} Get user tier & stats

Returns the user's current tier, cumulative volume, fee rate, and progress to the next tier.

Response 200

{
  "success": true,
  "userTier": "BRONZE",
  "feePercent": 2.20,
  "cumulativeAmount": 450000,
  "progressToNext": 4550000,
  "nextTier": "SILVER",
  "progressPercent": 9
}

Error Handling

All errors return a consistent JSON structure with an error message.

{
  "success": false,
  "error": "Description of what went wrong"
}

Code	Meaning
400	Bad request — missing or invalid parameters
403	Forbidden — account not found or inactive
404	Not found — resource doesn't exist
409	Conflict — quote already used
410	Gone — quote has expired
500	Server error — contact support

LNbits Extension

ChapSmart is available as an open-source LNbits extension. Install it on any LNbits instance to enable Bitcoin-to-M-Pesa cashouts directly from your Lightning wallet.

Version

v0.0.6

License

MIT

Status

Production Tested

The LNbits extension is the first integration that bridges Lightning Network payments to African mobile money. Any LNbits instance worldwide can send TZS to M-Pesa.

At a Glance

Detail	Value
Minimum	2,500 TZS (~$1 USD)
Maximum	1,000,000 TZS (~$390 USD)
Fee	2.2% of TZS amount
Speed	M-Pesa arrives in ~10 seconds
Network	Vodacom M-Pesa (Tanzania)
LNbits Version	v1.5.4 or later
Lightning Backend	Any (Blink, LND, CLN, OpenNode, Alby)

How It Works

From the user's perspective, the process takes about 30 seconds:

Step	Action
1	Open the ChapSmart extension in LNbits, select your wallet
2	Enter the recipient's Vodacom number (074/075/076), full name, and TZS amount
3	Click "GET QUOTE" — see exactly how many sats will be deducted
4	Click "SEND M-PESA" — sats are deducted, M-Pesa arrives in seconds

Extension API Endpoints

These endpoints are exposed within LNbits at /chapsmart/api/v1/:

POST /chapsmart/api/v1/quote Get sats quote for TZS amount

Returns how many sats will be deducted for a given TZS amount, based on live exchange rates. Requires LNbits Invoice key.

Response 200

{
  "quoteId": "6cqdmAqYu2nsVfPOgm1G",
  "amountTzs": 5000,
  "amountSats": 2578,
  "feeSats": 57,
  "expiresAt": "2026-05-17T09:15:00Z"
}

POST /chapsmart/api/v1/send Execute cashout (pay + deliver M-Pesa)

Pays the Lightning invoice from the user's wallet and triggers M-Pesa delivery. Requires LNbits Admin key.

200 Payment Sent 400 Validation Error 500 Payment Failed

GET /chapsmart/api/v1/status/{id} Check M-Pesa delivery status

Poll this endpoint to track M-Pesa delivery after sending. Requires Invoice key.

Status	Meaning
pending	Quote created, awaiting payment
paid	Lightning payment confirmed, M-Pesa processing
completed	M-Pesa delivered to recipient
failed	Payout failed — contact support

GET /chapsmart/api/v1/cashouts List all cashouts for a wallet

Returns all cashout records for the authenticated wallet. Requires Invoice key.

Installation

Step	Action
1	In LNbits admin, go to Settings → Extensions → Extension Sources, add: `https://raw.githubusercontent.com/bmosha00/lnbits-chapsmart/main/manifest.json`
2	Go to Extensions → ALL tab, find ChapSmart, click INSTALL (v0.0.6)
3	Configure API credentials (contact support@chapsmart.com to get your keys)
4	Connect a real Lightning backend (LND, CLN, Blink, etc.)

ChapSmart LNbits extension is fully open source under the MIT license. View the code, report issues, or contribute at github.com/bmosha00/lnbits-chapsmart

Use Cases

Remittances — Send TZS to family from anywhere with a Lightning wallet
Freelancer cashout — Convert sats earned on Nostr/Lightning to M-Pesa
Merchant settlement — BTCPay stores can auto-settle to M-Pesa
Cross-border transfers — Anyone worldwide with Lightning can send TZS to Tanzania

BTCPay Server Plugin

Auto-cashout Bitcoin payments to M-Pesa. When a customer pays a BTCPay invoice, the plugin converts sats to TZS and delivers to your M-Pesa — automatically.

Version

v1.0.0

License

MIT

Language

C# / .NET

The BTCPay plugin is for merchants who accept Bitcoin and need TZS liquidity. Customer pays in BTC → merchant receives M-Pesa. No exchange, no bank, no waiting.

At a Glance

Detail	Value
Trigger	Automatic on invoice settlement, or manual from dashboard
Minimum	2,500 TZS (~$1 USD)
Maximum	1,000,000 TZS (~$390 USD)
Fee	Tiered: Bronze 2.20%, Silver 1.87%, Gold 1.32%
Speed	M-Pesa arrives in seconds after Lightning settlement
Network	Vodacom M-Pesa (Tanzania)
BTCPay Version	Latest (Docker deployment)
Multi-store	Yes — separate config per store

Cashout Modes

Mode	How It Works
Automatic	Plugin watches for settled invoices and triggers cashout automatically. No manual action needed.
Manual	Merchant visits the plugin dashboard, enters TZS amount, reviews quote, clicks "Cashout."

How It Works

Step	Action
1	Customer pays a BTCPay invoice via Lightning
2	BTCPay confirms settlement, plugin receives event
3	Plugin gets a live TZS quote from ChapSmart API
4	Plugin pays the ChapSmart invoice from the store's Lightning wallet
5	M-Pesa arrives on the merchant's phone — no manual action needed

Use Cases

Small merchants — Coffee shop accepts Lightning, auto-cashes out to M-Pesa for daily supplies
E-commerce — WooCommerce + BTCPay settles to M-Pesa after each sale
Tourism — Safari operator accepts Bitcoin from tourists, receives TZS
Freelancers — Invoice clients in Bitcoin via BTCPay, cash out to M-Pesa
Partial cashout — Keep some sats as savings, cash out a portion for expenses

Installation

Method	Steps
Plugin Marketplace	BTCPay Dashboard → Manage Plugins → Search "ChapSmart" → Install → Restart
Manual (Docker)	Set `BTCPAY_EXTRA_PLUGINS=chapsmart-btcpay-plugin` in your docker-compose, then restart
Build from Source	`git clone github.com/bmosha00/chapsmart-btcpay-plugin && dotnet build`

Configuration

Setting	Required	Description
API Key	required	ChapSmart API key
API Secret	required	HMAC signing secret
Account Number	required	ChapSmart account identifier
M-Pesa Phone	required	Merchant's Vodacom number for cashout
Recipient Name	required	Name matching M-Pesa registration
Auto Cashout	optional	Enable automatic cashout on invoice settlement
Min Threshold	optional	Minimum TZS to trigger auto cashout

LNbits vs BTCPay — Which One?

	LNbits Extension	BTCPay Plugin
For	Individual Lightning users	Merchants accepting Bitcoin
Trigger	Manual (user clicks Send)	Automatic on invoice settlement
Recipient	Any phone number (per transaction)	Merchant's registered phone
Status	v0.0.6 — Production tested	v1.0.0 — Built and packaged

Open source under MIT license. View the code, report issues, or contribute at github.com/bmosha00/chapsmart-btcpay-plugin

Support

Need help integrating? Contact our developer support team.

Email

support@chapsmart.com

+255 763 052 308

ChapSmart API

Authentication

Tiers & Fee Structure

Authentication

Remittance

Airtime Top-Up

Buy Sats

Data & History

Error Handling

LNbits Extension

BTCPay Server Plugin

Support