API documentation

JSON over HTTPS, OAuth2 client credentials, idempotent writes. Base URL https://route.cloud.or.ke/api/v1 · OpenAPI spec · Integration guide with code samples

1. Authentication

Exchange your client credentials for a bearer token. Tokens live one hour.

curl -X POST https://route.cloud.or.ke/api/v1/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d scope="payments:write payments:read"

{ "access_token": "…", "token_type": "Bearer", "expires_in": 3600,
  "scope": "payments:write payments:read" }

Scopes

2. Endpoints

3. Idempotency

Send an Idempotency-Key header on every write. Replaying the same key with the same body returns the original response instead of moving money twice. Reusing a key with a different body is an error, not a silent overwrite.

curl -X POST https://route.cloud.or.ke/api/v1/payments/stk-push \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: order-88213" \
  -H "Content-Type: application/json" \
  -d '{"msisdn":"254712345678","amount":1500,"account_ref":"SCH-4821"}'

4. Receiving webhooks

Final outcomes are pushed to your endpoint, signed, and retried with exponential backoff until you answer 2xx. Deduplicate on the event id — a retry may arrive after you have already processed it.

<?php
// Verify a RouteCloud webhook (PHP)
$secret  = getenv('ROUTECLOUD_WEBHOOK_SECRET');
$raw     = file_get_contents('php://input');
$header  = $_SERVER['HTTP_X_ROUTECLOUD_SIGNATURE'] ?? '';

// The header is t=<ts>,v1=<sig> and during a secret rotation it carries
// MORE THAN ONE v1 — the new secret's signature and the old one's. Do
// not use parse_str here: it keeps only the last v1, so whichever
// secret you hold, half the time it is not the one you are comparing
// against, and every webhook is rejected mid-rotation.
$timestamp = null;
$signatures = [];

foreach (explode(',', $header) as $part) {
    if (!str_contains($part, '=')) {
        continue;
    }
    [$k, $v] = explode('=', trim($part), 2);
    if ($k === 't')  { $timestamp = $v; }
    if ($k === 'v1') { $signatures[] = $v; }
}

if ($timestamp === null || abs(time() - (int) $timestamp) > 300) {
    http_response_code(400); exit('stale timestamp');
}

$expected = hash_hmac('sha256', $timestamp . '.' . $raw, $secret);

$valid = false;
foreach ($signatures as $candidate) {
    $valid = hash_equals($expected, $candidate) || $valid;
}

if (!$valid) {
    http_response_code(401); exit('bad signature');
}

$event = json_decode($raw, true);

// Deduplicate on $event['id'] — we retry until you return 2xx.
// Respond 2xx as soon as you have persisted it; do the slow work after.
http_response_code(200);
echo 'ok';

5. Errors

Every error is an RFC 7807 problem document, so you parse one shape.

{
  "type":   "https://route.cloud.or.ke/errors/validation_failed",
  "title":  "The request could not be processed. See `errors` for details.",
  "status": 422,
  "code":   "validation_failed",
  "errors": { "msisdn": "Customer mobile number must be a valid Kenyan mobile number." }
}

6. Network notes