Build a resident app
Sign residents in with OAuth 2.0 and PKCE, show the accounts and invoices each one may see through the Consumer API, and open an M-Pesa payment.
What you will build#
A web or mobile app where a resident signs in with their own account, sees the service accounts linked to them, reads their invoices and pays one. The app never holds an API key: it gets an access token on the resident's behalf through the Authorization Code flow with PKCE (S256) and calls the Consumer API ($CONSUMER_API) with that token. Every response contains only what belongs to that resident.
The examples/resident-pkce sample covers steps 1 to 4 in a static HTML page with no build step.
Prerequisites#
- A sandbox and a resident user with at least one linked service account (the
account.linkedevent marks the moment a resident gains access to an account). - An OAuth client registered by the server operator under
security.oauth.clients, withkindset tomobile(ordesktop) and your app'sredirect_uris:
security:
oauth:
clients:
- id: resident-app
name: Resident app
kind: mobile
redirect_uris:
- http://localhost:3000/callback
The token endpoint accepts public clients only (token_endpoint_auth_methods_supported is none), so there is no client secret: PKCE is what proves that whoever redeems the code is whoever asked for it.
1. Read the authorization server's settings#
curl -sS "https://api.gota.umbeluzi.com/.well-known/oauth-authorization-server"
2. Send the resident to the sign-in screen#
Generate a random code_verifier, keep it in the browser session, and send only its hash in the authorization request. The helpers come from examples/resident-pkce/pkce.js.
import { generateCodeVerifier, generateCodeChallenge, buildAuthorizeURL } from "./pkce.js";
const verifier = generateCodeVerifier();
sessionStorage.setItem("pkce_verifier", verifier);
const state = crypto.randomUUID();
sessionStorage.setItem("pkce_state", state);
window.location.assign(buildAuthorizeURL({
authorizationEndpoint: discovery.authorization_endpoint,
clientId: "resident-app",
redirectUri: "http://localhost:3000/callback",
scope: "openid profile offline_access",
state,
codeChallenge: await generateCodeChallenge(verifier),
}));
3. Exchange the code for tokens#
curl -sS -X POST "https://api.gota.umbeluzi.com/oauth/token" \
-d grant_type=authorization_code \
-d client_id=resident-app \
-d redirect_uri=http://localhost:3000/callback \
-d code="$AUTH_CODE" \
-d code_verifier="$CODE_VERIFIER"
4. Show the resident's accounts#
curl -sS "$CONSUMER_API/accounts" \
-H "Authorization: Bearer $CONSUMER_ACCESS_TOKEN"
Response, abridged:
{
"data": [
{
"id": "act_3eQrF3JmTj2ZXpkFlbdO36UPXGP",
"tenant_id": "ten_3HclVhrn01Vsbj8CEBWAUk6h4MV",
"customer_id": "cus_3Byj2A4oNoD4aVDMGLeWCWY5CWP",
"property_id": "prp_35XwcW0AgJucy3jX5j2mk9J1XgP",
"property_address": "Rua da Resistência 1187, Bairro Central",
"account_number": "CTA-000044",
"billing_entity_id": "ten_3HclVhrn01Vsbj8CEBWAUk6h4MV",
"status": "active",
"permissions": ["account.read", "invoice.read", "payment.create", "reading.create"]
}
],
"has_more": false
}
5. List invoices and open a payment#
curl -sS "$CONSUMER_API/invoices?account_id=act_3eQrF3JmTj2ZXpkFlbdO36UPXGP" \
-H "Authorization: Bearer $CONSUMER_ACCESS_TOKEN"
curl -sS -X POST "$CONSUMER_API/payment-sessions" \
-H "Authorization: Bearer $CONSUMER_ACCESS_TOKEN" \
-H "Idempotency-Key: 6f1d2c9a-3b47-4e1f-9a0c-5d8e7b2a4c61" \
-H "Content-Type: application/json" \
-d '{"invoice_id":"inv_3z9cS8ItYBqz0D66bvqNC7QSn8E","method":"mpesa","phone":"+258841234567"}'
Test it#
Poll GET $CONSUMER_API/payment-sessions/pss_3SUDQUDOqwxJDioVEQHBzy13wYD until status changes. The sandbox has no real approval, so POST $CONSUMER_API/payment-sessions/pss_3SUDQUDOqwxJDioVEQHBzy13wYD/sandbox/confirm plays the provider: it records the payment and receipt and returns the session as confirmed. On the utility's side, payment.received arrives and, when the balance has reached zero, invoice.paid follows.
An invoice with nothing left to pay is refused with invoice.no_balance, and while the utility's payments are not active the answer is 403 with capability.inactive.