Engineering · 11 min read
For developers
A clean API for collections and payouts.
OAuth2 keys, a sandbox, a Daraja-style prompt-to-pay, 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 ✓
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.
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
4
Native apps, one platform
4
Channels — App · USSD · Web · API
100%
Double-entry, always balanced
FAQ
Questions, answered.
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. The full wallet runs over USSD — send, withdraw, pay bill, buy goods, airtime, balance and statements — 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?
Four native Android apps: a User app for customers, an Agent / Super-agent app for cash-in, cash-out and float, a Merchant app to accept and settle, and a Corporate app for bulk payouts with maker-checker approvals, which also runs as a web portal. iOS versions are on the roadmap.
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