TukuPay Docs

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…UseStart with
Take payments or pay out from my server (a shop, a school system, a booking site)An API key and the gatewayQuickstart
Put a payment form on my website, with no code on my serverThe paypoint embed scriptEmbed a paypoint
Ask an AI assistant (Claude, Cursor, VS Code, Windsurf) about my balances, or have it send a payment promptThe MCP serverMCP for AI assistants
Let other TukuPay users connect my app to their accountConsentCustomers and consent

Words you will see

WordMeans
AppYour project, registered in TukuPay under Developers → My apps. Keys, limits and webhooks belong to an app.
SandboxPractice mode. Reads your real account but never moves real money. Keys start tkk_test_.
LiveReal money. Keys start tkk_live_.
Key id + key secretLike a username and password for your server, except the secret is never sent: it signs each request.
Payout secretA second secret, needed only to send money out.
WalletWhere money sits in TukuPay. Every account has a Main Wallet; you use its number (wallet_id).
ReferenceTukuPay's id for a payment (e.g. TP8K2M4Q9X). Your own id for it is external_reference.
PaypointA 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/v1

Every 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.