The Paysasa Developer Platform: REST APIs, API Keys and Signed Webhooks

Payments are rarely a separate activity. They happen inside an online shop, a marketplace, a school system, an ERP or a mobile app. The Paysasa developer platform lets you bring Paysasa into your own products through REST APIs and webhooks, so payments flow automatically.

This deep dive gives developers and technical decision-makers an overview of what is possible.

The basics

• Base URL: `https://api.paysasa.com/api/v1`
• Authentication: a composite API key in the `x-api-key` header, in the format `apk_live_xxx.secret` or `apk_test_xxx.secret`.
• Where to get keys: Businesses → API Keys in your Paysasa dashboard.
• Scope: each key is scoped to a single business — use one key per business.

Keys must stay on the server. Never expose them in client-side code or public repositories, and revoke them from the Businesses page if needed.

What you can build

Checkout and payment links

Create checkout sessions with a hosted payment page and redirects, initiate payments for cashier flows, cancel sessions and create reusable payment links. Optional split payouts route portions of each payment to other wallets in the same business.

Invoices and subscriptions

Issue itemised invoices with a hosted `payment_url`, send them by email or SMS, and build recurring billing with customers, products, prices and subscriptions.

Lengo and Deni

Create Lengo save-now-buy-later offers and resolve them for embed widgets. Record Deni IOUs with public pay pages, reminders and acknowledgements.

Wallet-as-a-Service

Run end-user balances through one master wallet with virtual accounts, M-Pesa deposits and withdrawals.

Payroll, POS and more

Manage payroll employees and runs, connect POS Lite to your catalogue, create donation campaigns and work with eTIMS fiscal documents where enabled. Reconciliation endpoints help match payments to your records.

Principles that keep integrations safe

Minor units

All money-moving APIs use integer minor units. For KES and USD, 100 = 1.00. Zero-decimal currencies such as UGX use 1 = 1. Only currencies enabled for your account are accepted.

Idempotency

Send an `X-Idempotency-Key` on money-moving requests. It is required for P2P transfers and checkout payments, and recommended for payouts, conversions and invoice payments. Replays return the original result.

Compliance gates

Money movement is gated by verification. Unverified businesses receive `403` responses with codes such as `business_unverified` or `owner_kyc_unverified`. Treat these as onboarding states. Trust tiers (Gold and Platinum) are read-only in the API.

Payment rails

M-Pesa checkout and withdrawals require KES; PayPal settles USD.

Webhooks

Configure endpoints in your business webhook settings and Paysasa will `POST` events to your server — for example, checkout payments, invoices and subscriptions, Lengo and Deni lifecycle events, and WaaS deposits and withdrawals.

• Each webhook is signed with HMAC-SHA256 using your webhook secret. Verify the signature over the raw body with a constant-time comparison.
• Failed deliveries are retried three times with exponential back-off (about 1, 5 and 30 minutes).
• Make handlers idempotent and return `2xx` quickly.

Signed requests

Business API calls use a tenant signature header, so a captured request cannot be replayed from another host — one of the controls described on the Paysasa security page.

Limits and operational notes

• Default rate limits: 120 reads and 60 writes per minute per IP or API key, with `X-RateLimit-*` headers.
• Checkout sessions expire after 30 minutes by default.
• Use test keys while building, then switch to live keys.

A typical integration pattern

Most integrations follow the same pattern. Your server creates the payment object — a checkout session, invoice or Lengo offer — and stores its ID alongside your own order or customer record using metadata. The customer completes payment on a Paysasa hosted page. Your webhook handler verifies the signature, looks up the record by ID or metadata and updates it. A periodic reconciliation job then compares your records with Paysasa's to catch anything missed.

Who uses the API?

• E-commerce stores adding M-Pesa and card checkout.
• Marketplaces routing payments and holding balances.
• Schools, clinics and organisations connecting billing systems.
• SaaS products charging subscriptions.
• Agencies building payment flows for clients.

Getting started

1. Create and verify your business.
2. Generate a test API key under Businesses → API Keys.
3. Read the Paysasa API docs and try a checkout session.
4. Set up a webhook endpoint and verify signatures.
5. Go live with a live key once tests pass.

Conclusion

The Paysasa developer platform turns payments into building blocks: checkout, billing, savings, IOUs, wallets and payouts, all with clear authentication, idempotency and signed webhooks. Build the experience your users need, and let Paysasa handle the money movement.

Ready to start building? Explore the Paysasa API docs or contact the Paysasa partnerships team about your integration.