PocketPesa API uses JWT (JSON Web Tokens) for authentication. All protected endpoints require a valid JWT token in the Authorization header.

Required Headers

Authorization: Bearer <access_token>
Content-Type: application/json
Accept: application/json

Error Response Format

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The given data was invalid",
    "details": {
      "phone": ["The phone field is required"],
      "amount": ["The amount must be at least 500"]
    }
  },
  "timestamp": "2024-01-01T12:00:00Z",
  "request_id": "req_abc123"
}

HTTP Status Codes

Common Error Codes

PocketPesa sends webhooks to notify your application about transaction status changes and other important events.

Webhook Events

Webhook Payload

{
  "event": "transaction.completed",
  "data": {
    "transaction_id": "txn_abc123",
    "user_id": "usr_def456",
    "type": "topup",
    "amount": "10000.00",
    "currency": "UGX",
    "status": "completed",
    "relworx_reference": "d3ae5e14f05fcc58427331d38cb11d42",
    "completed_at": "2024-01-01T12:01:30Z"
  },
  "timestamp": "2024-01-01T12:01:31Z",
  "signature": "sha256=abc123..."
}

Webhook Verification

Verify webhook authenticity using HMAC-SHA256:

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_POCKETPESA_SIGNATURE'];
$expected = hash_hmac('sha256', $payload, $webhook_secret);

if (!hash_equals($signature, $expected)) {
    http_response_code(401);
    exit('Invalid signature');
}

Webhook Endpoints

API requests are rate limited to ensure fair usage and system stability.

Rate Limits

Rate Limit Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1609459200

Rate Limit Exceeded Response

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again later.",
    "details": {
      "retry_after": 60,
      "limit": 10,
      "window": "1 minute"
    }
  },
  "timestamp": "2024-01-01T12:00:00Z"
}