TeronaPay documentation

Build payments for businesses in Kenya, Uganda, and Tanzania. M-Pesa, MTN MoMo, Airtel Money, Tigo Pesa, card, and bank transfer — through a single REST API with webhooks, refunds, partial refunds, and statement reporting built in.

Quick path: Sign up for an account, grab your API key, then follow the quickstart to run your first payment in under five minutes.

What's in this documentation

• Quickstart — sign up, get a test API key, and capture your first payment.
• Concepts — deep dives on how payments, wallets, refunds, webhooks, and idempotency work.
• REST API reference — every endpoint, with request/response shapes and code samples.
• Webhook events — payload reference for the six event types we emit.
• Errors — the error envelope, the type catalog, and how to recover.

Base URL

Production:

https://api.teronapay.com

Sandbox (use real Daraja credentials in M-Pesa sandbox mode):

https://api.sandbox.teronapay.com

Amounts

All monetary amounts — in requests and responses — are decimal numbers in the currency's major unit: 125.00 means KES 125.00, 10.50 means KES 10.50. Send and read them as plain JSON numbers; there are no "cents" / minor-unit fields on the REST API.

Note: M-Pesa settles in whole shillings, so for mpesa_stk_push / mpesa_c2b any fractional part of a KES amount is rounded down at the M-Pesa step.

Authentication

Every request to /v1/* (except /v1/auth/*) uses HTTP Basic auth with your API key id as the username and the secret as the password:

curl https://api.teronapay.com/v1/payments \
  -u "np_xxxxxxxxxxxxxxxxxxxxxxxx:<your_secret>"

API keys are issued in the dashboard under Developer → Settings or via the signup flow. Treat the secret like a password — never embed it in client-side code.

SDKs

Server-side SDKs (these are separate repos):

SDKs handle Basic auth, JSON encoding, error mapping, retry semantics, idempotency-key generation, and webhook signature verification. See per-language READMEs for usage.

Get help

• Email dev@teronapay.com for integration questions.
• File issues on the SDK repos for SDK bugs.
• Email security@teronapay.com for security concerns.