Start here
Introduction
TukuPay lets your software use your own TukuPay account: take M-Pesa payments, read balances and statements, and pay out within limits you set.
TukuPay is a Kenyan wallet and payments app. Everything is in Kenyan shillings (KES). Developers reach it through one door, the developer gateway: a short list of web addresses (endpoints) that answer JSON. Every call is signed with a key, so nobody else can make it.
Pick your path
| I want to… | Use | Start with |
|---|---|---|
| Take payments or pay out from my server (a shop, a school system, a booking site) | An API key and the gateway | Quickstart |
| Put a payment form on my website, with no code on my server | The paypoint embed script | Embed a paypoint |
| Ask an AI assistant (Claude, Cursor, VS Code, Windsurf) about my balances, or have it send a payment prompt | The MCP server | MCP for AI assistants |
| Let other TukuPay users connect my app to their account | Consent | Customers and consent |
Words you will see
| Word | Means |
|---|---|
| App | Your project, registered in TukuPay under Developers → My apps. Keys, limits and webhooks belong to an app. |
| Sandbox | Practice mode. Reads your real account but never moves real money. Keys start tkk_test_. |
| Live | Real money. Keys start tkk_live_. |
| Key id + key secret | Like a username and password for your server, except the secret is never sent: it signs each request. |
| Payout secret | A second secret, needed only to send money out. |
| Wallet | Where money sits in TukuPay. Every account has a Main Wallet; you use its number (wallet_id). |
| Reference | TukuPay's id for a payment (e.g. TP8K2M4Q9X). Your own id for it is external_reference. |
| Paypoint | A named place to pay you (a counter, a product, a fee) with its own page and QR code. |
The rules that keep money safe
- Your own account. Every call acts on the account that owns the app, unless another person connects your app to theirs.
- No passwords, no PINs ever go through the API. If anything asks you for a TukuPay PIN, it is not TukuPay.
- Money out is limited. It goes at once only within limits you set; anything above them, and anything above KES 50,000, waits for you to approve it in the TukuPay app with your PIN.
- Stop buttons. You can stop your app at any time, and TukuPay can stop an app, a developer or the whole gateway.
The address
https://gateway.tukupay.dev/v1Every path in these docs is under /v1 on that address. Amounts are decimal strings ("1500.00"), never floats.
Use https://gateway.tukupay.dev in anything new. Apps set up before 12 November 2026 on the old address keep working: same routes, same keys.