Quickstart: your first payment

Before you start#

Create a free developer account at pesa-bridge.com/developer/signup. You get two key sets straight away: pk_test_… / sk_test_… for the sandbox and pk_… / sk_… for production. The key you authenticate with decides the mode, so test traffic never touches real money.

Every call in this guide goes to one base URL:

https://pesa-bridge.com/api/bridgepay/v1

1. Get an access token#

Exchange your key pair for a Bearer token. Tokens last one hour; request a new one before expires_in runs out.

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_…"}'

{
  "access_token": "at_9f3…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "mode": "test",
  "sandbox": true
}

2. Tell us where to send results#

Payments finish on the customer's phone, so the result reaches you by webhook. Register an endpoint once; the response includes a signing secret that is shown only once. Store it: you use it to verify every delivery.

curl -s https://pesa-bridge.com/api/bridgepay/v1/partner/webhooks/endpoints \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Orders","url":"https://your-app.com/webhook","events":"*","mode":"test"}'

3. Push a payment prompt#

Send the customer's number in international format and the amount. Add your own reference so you can match the result to your order, and an idem key so a retry after a timeout can never charge twice.

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"}'

{
  "charge_ref": "STK0000123",
  "state": "pending",
  "amount": 250.0,
  "expiry": "2026-09-27T12:05:00Z"
}

The customer approves on their own phone with their PIN. You never see or handle it.

4. Receive the result#

When the charge settles we POST a signed event to your endpoint:

POST /webhook
X-PesaBridge-Event: charge.completed
X-PesaBridge-Signature: …e9 (hex HMAC-SHA256 of the raw body)

{
  "event": "charge.completed",
  "charge_ref": "STK0000123",
  "reference": "INV-1001",
  "amount": 250.0,
  "currency": "KES",
  "payer": "254708374149",
  "state": "completed",
  "transaction": "PB7H2K9Qmn"
}

Verify the signature, mark the order paid, and answer with any 2xx. See Webhooks for verification code in several languages.

5. Or check the status yourself#

Webhooks are the source of truth, but you can always ask:

curl -s "https://pesa-bridge.com/api/bridgepay/v1/partner/status?charge_ref=STK0000123" -H "Authorization: Bearer $TOKEN"

{ "charge_ref": "STK0000123", "state": "completed", "transaction": "PB7H2K9Qmn" }

Next steps#

• Authentication: key modes, token caching and rotation.
• Accept payments: QR, till and pay bill (C2B), invoices and standing orders.
• Hosted checkout: a payment page with no front-end work.
• Go-live checklist: everything to confirm before switching to live keys.