PesaBridge
Docs/Premiers pas/Quickstart: your first payment

Premiers pas

Quickstart: your first payment

Get a token, push a payment prompt to a phone and receive the signed result on your server, all with sandbox keys.

5 min de lecture

Les guides développeurs sont rédigés en anglais pour que le code, les noms de champs et les messages d'erreur correspondent exactement à l'API.

Sur cette page
  1. Before you start
  2. 1. Get an access token
  3. 2. Tell us where to send results
  4. 3. Push a payment prompt
  5. 4. Receive the result
  6. 5. Or check the status yourself
  7. Next steps

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:

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.

Request
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_…"}'
Response
{
  "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.

Shell
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"}'
No public server yet? Use the built-in PesaBridge Echo receiver: GET /partner/echo/url returns a URL that captures deliveries and verifies their signatures, and you can inspect them in the developer console.

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.

Request
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"}'
Response
{
  "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:

HTTP
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:

Shell
curl -s "https://pesa-bridge.com/api/bridgepay/v1/partner/status?charge_ref=STK0000123" -H "Authorization: Bearer $TOKEN"
JSON
{ "charge_ref": "STK0000123", "state": "completed", "transaction": "PB7H2K9Qmn" }

Next steps

Suivant Authentication

Nos ingénieurs répondent aux questions d'intégration. Envoyez-nous la référence de la requête et nous retrouverons l'appel exact.

Contacter le support