Quickstart

Zero to a confirmed payment. You'll need a sandbox client_id and client_secret from the Developer portal (Credentials).

1. Get an access token

cURL

curl -X POST https://<your-operator>/api/bridgepay/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{"client_id":"pk_test_xxx","client_secret":"sk_test_xxx"}'

# -> { "status":"ok", "data":{ "access_token":"at_...", "expires_in":3600 } }

Node.js

const base = "https://<your-operator>/api/bridgepay/v1";
const r = await fetch(`${base}/oauth/token`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ client_id: CID, client_secret: SECRET }),
});
const { data } = await r.json();
const token = data.access_token;

Python

import requests
r = requests.post(f"{BASE}/oauth/token",
                  json={"client_id": CID, "client_secret": SECRET})
token = r.json()["data"]["access_token"]

2. Request a payment (PesaBridge Express)

cURL

curl -X POST https://<your-operator>/api/bridgepay/v1/partner/stk \
  -H "Authorization: Bearer at_..." -H "Content-Type: application/json" \
  -d '{"payer_msisdn":"2547xxxxxxxx","amount":250,"reference":"INV-1001","idem":"a1"}'

# -> { "status":"ok", "data":{ "charge_ref":"STK0000123", "state":"pending" } }

Node.js

const r = await fetch(`${base}/partner/stk`, {
  method: "POST",
  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    payer_msisdn: "2547xxxxxxxx", amount: 250,
    reference: "INV-1001", idem: "a1",
  }),
});
const { data } = await r.json();   // { charge_ref, state: "pending" }

Python

r = requests.post(f"{BASE}/partner/stk",
    headers={"Authorization": f"Bearer {token}"},
    json={"payer_msisdn": "2547xxxxxxxx", "amount": 250,
          "reference": "INV-1001", "idem": "a1"})
charge = r.json()["data"]   # { "charge_ref": "...", "state": "pending" }

The customer sees a prompt on their phone and confirms with their PIN.

3. Receive the result (webhook)

We POST to your callback URL the instant the charge settles. Verify the signature, then fulfil the order:

// POST https://your-app.com/webhook
// X-PesaBridge-Event: charge.completed
// X-PesaBridge-Signature: <hmac-sha256 of the raw body>
{ "event":"charge.completed", "charge_ref":"STK0000123",
  "reference":"INV-1001", "amount":250, "state":"completed",
  "transaction":"BP2600000118" }

4. (Or) poll the status

curl "https://<your-operator>/api/bridgepay/v1/partner/status?charge_ref=STK0000123" -H "Authorization: Bearer at_..."