Engineering · 11 min read
For developers
A clean API for collections and payouts.
OAuth2 keys, a sandbox, prompt-to-pay on the customer's phone, and signed webhooks — integrate in an afternoon.
Free sandbox keys in minutes. Live keys after a short review.
# 1. Exchange your key pair for a 1-hour token curl -s https://pesa-bridge.com/api/bridgepay/v1/oauth/token \ -H "Content-Type: application/json" \ -d '{"client_id":"pk_test_…","client_secret":"sk_test_…"}' # 2. Push a payment prompt to the customer's phone curl -s https://pesa-bridge.com/api/bridgepay/v1/partner/stk \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"payer_msisdn":"254708374149","amount":250, "reference":"INV-1001","idem":"inv-1001-1"}'← 200 {"charge_ref":"STK0000123","state":"pending"}→ webhook charge.completed KES 250.00 ok
Quickstart
From zero to a paid order in four steps
Everything runs in the sandbox with test keys, so you can build the whole flow before any real money moves.
- 1
Create an account
Sign up in the developer console. Test and live keys are issued straight away.
/developer/signup - 2
Get a token
Exchange your key pair for a Bearer token that lasts one hour.
POST /oauth/token - 3
Charge a phone
Push a payment prompt. The customer approves on their own phone with their PIN.
POST /partner/stk - 4
Receive the webhook
A signed charge.completed event tells your server the order is paid.
charge.completed
What you can build
One API for money in, money out and everything around it
53 endpoints in 12 groups, with one way to authenticate and one error format.
Where it shows
One integration, on every screen your customers use.
The same API drives the customer's phone, the pay page, the card terminal at the till and the business dashboard.
Designed for money
An API that behaves like a payments system.
Most APIs move data. This one moves money — so it's idempotent, signed, and built around a charge lifecycle you can trust.
Authentication is OAuth2 client-credentials: you exchange a key and secret for a short-lived bearer token. Every state-changing call carries an idempotency key, so a network retry settles exactly once — the single most important property when real money is involved.
A collection is a charge. You push it to a customer's number; a prompt-to-pay lands on their phone; they confirm with a PIN. The charge moves through pending → authorised → completed (or declined / expired / failed), and you learn the outcome two ways: poll the status endpoint, or — better — receive a webhook the moment it changes.
Webhooks are signed with HMAC-SHA256 against a secret only you and PesaBridge share, and retried with backoff until your endpoint acknowledges — so you can build on them without fear of a missed or forged event. Balance and transaction endpoints close the loop for reconciliation, and a sandbox runs the identical contract, so you ship with confidence.
Charge lifecycle
pendingauthorisedcompleteddeclinedexpiredfailed
webhook · charge.completed
{
"event": "charge.completed",
"charge_ref": "STK9F2A",
"amount": 250.00,
"currency": "KES",
"state": "completed",
"signature": "hmac-sha256…"
}Tools
More than an API: the tools around it
Explore, test and debug your integration without writing throwaway code or deploying a server.
API reference
A small, predictable surface.
POST
/oauth/tokenExchange client credentials for a bearer token.POST
/partner/stkPush a charge (prompt-to-pay) to a customer.GET
/partner/statusPoll the state of a charge.GET
/partner/balanceQuery a collection account balance.POST
/biz/requestMerchant request-to-pay.POST
/ussdUSSD menu gateway callback.Security & compliance
Trust is the product.
Financial services live or die on correctness and control. PesaBridge bakes both into the core.
Double-entry by construction
Every movement posts balanced debits and credits — the books reconcile to zero, always.
PIN, KYC & limits
Configurable KYC tiers, per-transaction and daily limits, PIN attempts and wallet locking.
Idempotent & reversible
Idempotency keys stop double charges; a unified reversal engine unwinds any department.
Signed webhooks
HMAC-SHA256 signatures and retries so partner systems can trust every callback.
Full audit trail
Immutable ledger entries and transaction history for regulators and disputes.
Per-country compliance
ID types, KYC rules and tariffs switch with the market, from configuration.
Going live
From sandbox to production without rewriting a line
The same code runs in both modes. The key you use decides which. When your integration is ready, request live access and swap keys.
SandboxReviewLive
- Webhook signatures verified, with a timestamp window
- An idempotency key on every charge and payout
- Secret keys kept only on your server
- A live webhook endpoint with its own signing secret
- Daily reconciliation against the transactions API
190+
Countries you can launch in
6
Native apps, one platform
4
Channels — App · USSD · Web · API
100%
Double-entry, always balanced
Stuck on something?
Our engineers answer integration questions. Send us the request reference and we'll find the exact call.
FAQ
Questions, answered.
Buying PesaBridge
Can we start with part of the platform?
Yes. The Starter plan covers the customer and agent apps with the back office and KYC. Merchants, the developer API, USSD, lending, savings and bulk payments switch on later on the same ledger, so nothing is rebuilt as you grow.
How is PesaBridge priced?
Four ways: the Starter, Growth and Enterprise plans, or a Partnership in which you pay no licence fee and we share net revenue instead. The proposal builder on this site gives your exact price and a draft contract in about 10 minutes.
What do you need from us to launch?
A licence, or a licensed partner that holds the customer funds; accounts with the banks and payment providers you want to connect; your brand; and your tariffs. Once the provider credentials arrive, a first country usually goes live in 4 to 12 weeks.
Can we try it before we sign?
Yes. Request test access and you receive the Android apps for the products you pick, the web portals and test logins by email. Everything runs in a sandbox, so no real money moves. Developers can open a sandbox account on the developer portal at any time.
What support and training do you provide?
Every plan includes support: email on Starter, priority support on Growth, and a service-level agreement with onboarding on Enterprise. During the launch we train your back-office, support and agent-network teams, and the help hub, guides and API docs stay online for everyone.
The platform
Is PesaBridge a platform I share, or my own?
Your own. PesaBridge is a product BridgeERP resells — every operator gets their own deployment, branded and configured for them. No shared database, no shared super-admin.
Which countries and currencies are supported?
Any. Country, currency, language and KYC rules are configuration drawn from the full ISO set — not hardcoded. We have live markets today and stand up new ones without a rewrite.
Does it work on feature phones?
Yes. Over USSD, customers send, withdraw, pay bills, buy goods, buy airtime, check their balance and get a mini statement, settling on the same ledger as the apps.
Can I connect my own banks and payment rails?
Yes. Rails are pluggable adapters — banks, mobile money, cards and PSPs — so you connect only what your market needs.
How fast can we go live?
Weeks, not years. Configure your brand and country, wire your rails, then ship your apps, USSD code and web portals from one platform.
Is it secure and auditable?
Every movement is double-entry and balanced to zero, PIN- and KYC-gated, with signed webhooks and a full audit trail for regulators.
Which apps do operators and their customers get?
Six native Android and iOS apps: a User app for customers, a Send app for transfers abroad, an Agent / Super-agent app for cash-in, cash-out and float, a Merchant app to accept and settle, a Counter app for shop tills, and a Corporate app for bulk payouts with maker-checker approvals, which also runs as a web portal.
How does settlement and reconciliation work?
Funds settle to the relevant wallet in real time. Every transaction produces balanced ledger entries you can reconcile, with statements and exports, and a GL bridge for your accounting system.
Can it handle loans, savings and group finance?
Yes — overdraft credit, MFI loans with schedules and portfolio-at-risk, goal savings, and savings groups (chama / merry-go-round) are part of the platform and switch on per market.
Do you support bulk disbursement for payroll, aid or subsidies?
Yes. The Corporate portal and API run bulk disbursement to thousands of wallets with maker/checker approvals, payee books, scheduling and full reconciliation.
What does it take to run it day-to-day?
A single operator admin console runs brand, tariffs, KYC, the agent and merchant network, the ledger, reversals, support and KPIs — no code required for everyday operations.
Who owns the deployment and the data?
You do. Each operator runs their own deployment with their own database — branded and configured for them. It's a product you resell as your own, not a shared SaaS tenant.
Further reading
Guides from the PesaBridge team
Keep exploring
Where to go next
Ready to launch your wallet?
Book a demo and we'll stand up your brand, country and rails — and walk you through the apps, admin and API.
Prefer to talk? Call +254 746 883809