Developers

API reference

Build on By Lipa with RESTful JSON APIs — automate mobile money ↔ USDT exchange for users, or accept crypto payments as a merchant. Stripe-style keys, predictable responses, webhook signatures.

REST · JSON TLS required Version v1

Choose your integration

User API

Exchange & wallet automation

Programmatic buy/sell, wallet balance, on-chain send, and P2P transfers. Authenticate with API key + secret generated from the user app.

Read User API docs → Merchant API

Crypto checkout & settlement

Create USDT/BTC payment requests, track confirmations, withdraw to mobile money or on-chain. Authenticate with a single live API key (sc_live_).

Read Merchant API docs →

Base URL

All requests are made to the API gateway. Replace the host with your production domain.

Base URL

https://bylipa.com/api

User endpoints live under /v1/…. Merchant endpoints live under /v1/merchant/….

Authentication overview

API	Headers	Get credentials
User API	`X-Api-Key` + `X-Api-Secret`	User app → Profile → Developer API
Merchant API	`X-Api-Key` (or `Authorization: Bearer`)	Merchant portal → Settings
Session (browser app)	`Authorization: Bearer <token>`	`POST /v1/auth/login`

Errors

Errors return JSON with a message field. HTTP status codes follow conventional REST semantics.

Status	Meaning
`400`	Malformed request
`401`	Missing or invalid credentials
`403`	Step-up verification required (large withdrawal)
`404`	Resource not found
`422`	Validation failed — check `message`
`429`	Rate limited
`500`	Server error — retry with backoff

Error response

{
  "message": "Invalid API credentials."
}

Idempotency & references

Orders return a unique reference (e.g. ORD-…) — store it to poll status.
Merchant payments require external_reference — must be unique per merchant.
Use HTTPS only. Never embed secrets in client-side mobile or web apps.