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	1.87%
Silver	5,000,001 – 25,000,000 TZS	1.55%
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": "4071156462128684",
  "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": "4071156462128684"
}

Response 200

{
  "success": true,
  "accountNumber": "4071156462128684",
  "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": "4071156462128684"
  }
}

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": 1.87
  },
  "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": "4071156462128684"
  }
}

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": "4071169462128684"
}

Response 200

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

Parameter	Type	Required	Description
amountTZS	number	required	Amount to spend (1,000 – 20,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": "4071169462128684"
}

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": 1.87,
  "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

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

Support