Introduction

Welcome to the SureBucks SME Loan API documentation. This API enables partners to programmatically manage client businesses and loan requests.

Quick Start

1. Get your API key from the Partner Portal dashboard
2. Include the API key in all requests via the X-API-Key header
3. Create a client business profile
4. Submit loan requests for your clients
5. Track loan status and receive webhook notifications

Authentication

All API requests (except /health) require authentication using an API key.

API Key Format

Providing Your API Key

Option 1: X-API-Key Header (Recommended)

X-API-Key: sb_live_your_api_key_here

Option 2: Authorization Bearer Token

Authorization: Bearer sb_live_your_api_key_here

Example Request

curl -X GET "https://api.surebucks-sme.com/v1/clients" \
  -H "X-API-Key: sb_live_your_api_key_here" \
  -H "Content-Type: application/json"

Rate Limiting

The API implements rate limiting to ensure fair usage and system stability.

Default Limits

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1706824800

Error Handling

All errors follow a consistent JSON format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {}
  }
}

HTTP Status Codes

Error Codes

Health Check

Check API availability. No authentication required.

curl -X GET "https://api.surebucks-sme.com/v1/health"

{
  "success": true,
  "data": {
    "status": "ok",
    "message": "API is healthy",
    "version": "1.1.0",
    "timestamp": "2026-02-01T21:00:00+00:00"
  }
}

Clients

Manage client business profiles.

curl -X POST "https://api.surebucks-sme.com/v1/clients" \
  -H "X-API-Key: sb_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "business_name": "Acme Trading Ltd",
    "registration_number": "RC123456",
    "email": "info@acmetrading.com",
    "business_type": "llc"
  }'

{
  "success": true,
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "business_name": "Acme Trading Ltd",
    "registration_number": "RC123456",
    "business_type": "llc",
    "mono_connected": false,
    "created_at": "2026-02-01T21:00:00+00:00"
  }
}

curl -X GET "https://api.surebucks-sme.com/v1/clients?page=1&per_page=10" \
  -H "X-API-Key: sb_live_your_api_key_here"

Loans

Manage loan requests for your clients.

curl -X POST "https://api.surebucks-sme.com/v1/loans" \
  -H "X-API-Key: sb_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "client_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "loan_amount": 5000000,
    "tenure_months": 12,
    "purpose": "Working capital for inventory"
  }'

{
  "success": true,
  "data": {
    "uuid": "660e8400-e29b-41d4-a716-446655440001",
    "reference_number": "SBL-20260201-A1B2C3D4",
    "status": "draft",
    "loan_amount": 5000000,
    "currency": "NGN",
    "tenure_months": 12,
    "interest_rate": 24.0,
    "monthly_repayment": 473790.12,
    "total_repayment": 5685481.44,
    "processing_fee": 100000,
    "created_at": "2026-02-01T21:00:00+00:00"
  }
}

curl -X POST "https://api.surebucks-sme.com/v1/loans/660e8400-e29b-41d4-a716-446655440001/submit" \
  -H "X-API-Key: sb_live_your_api_key_here"

Webhooks

Test and manage webhook configurations.

curl -X POST "https://api.surebucks-sme.com/v1/webhooks/test" \
  -H "X-API-Key: sb_live_your_api_key_here"

Webhook Events

When events occur, we send POST requests to your configured webhook URL.

Webhook Payload Structure

{
  "event": "loan.status.updated",
  "timestamp": "2026-02-01T21:00:00+00:00",
  "data": {
    "loan_uuid": "660e8400-e29b-41d4-a716-446655440001",
    "reference_number": "SBL-20260201-A1B2C3D4",
    "previous_status": "submitted",
    "new_status": "under_review"
  }
}

Webhook Headers

Verifying Signatures

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'];
$secret = 'your_webhook_secret';

$expectedSignature = hash_hmac('sha256', $payload, $secret);

if (hash_equals($expectedSignature, $signature)) {
    // Signature is valid
    $data = json_decode($payload, true);
    // Process webhook...
}

Event Types

Code Examples

Complete code examples in multiple languages to help you integrate with the SureBucks API.

cURL

Command-line examples for quick testing and scripting.

# Create a new client
curl -X POST "https://api.surebucks-sme.com/v1/clients" \
  -H "X-API-Key: sb_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "business_name": "Acme Trading Ltd",
    "registration_number": "RC123456",
    "email": "info@acmetrading.com",
    "business_type": "llc"
  }'

# Create a loan request
curl -X POST "https://api.surebucks-sme.com/v1/loans" \
  -H "X-API-Key: sb_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "client_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "loan_amount": 500000,
    "tenure_months": 12,
    "purpose": "Working capital"
  }'

# Get loan status
curl -X GET "https://api.surebucks-sme.com/v1/loans/550e8400-e29b-41d4-a716-446655440000/status" \
  -H "X-API-Key: sb_live_your_api_key_here"

# List all clients with pagination
curl -X GET "https://api.surebucks-sme.com/v1/clients?page=1&per_page=20" \
  -H "X-API-Key: sb_live_your_api_key_here"

Python

Using the requests library for HTTP calls.

import requests
from typing import Dict, Any, Optional

class SureBucksAPI:
    """SureBucks SME Loan API Client for Python"""
    
    def __init__(self, api_key: str, base_url: str = "https://api.surebucks-sme.com/v1"):
        self.api_key = api_key
        self.base_url = base_url
        self.session = requests.Session()
        self.session.headers.update({
            "X-API-Key": api_key,
            "Content-Type": "application/json"
        })
    
    def _request(self, method: str, endpoint: str, data: Optional[Dict] = None) -> Dict[str, Any]:
        """Make an API request"""
        url = f"{self.base_url}{endpoint}"
        response = self.session.request(method, url, json=data)
        response.raise_for_status()
        return response.json()
    
    # Client Methods
    def create_client(self, business_name: str, registration_number: str, **kwargs) -> Dict:
        """Create a new client business"""
        data = {
            "business_name": business_name,
            "registration_number": registration_number,
            **kwargs
        }
        return self._request("POST", "/clients", data)
    
    def get_client(self, client_uuid: str) -> Dict:
        """Get client details by UUID"""
        return self._request("GET", f"/clients/{client_uuid}")
    
    def list_clients(self, page: int = 1, per_page: int = 20) -> Dict:
        """List all clients with pagination"""
        return self._request("GET", f"/clients?page={page}&per_page={per_page}")
    
    # Loan Methods
    def create_loan(self, client_uuid: str, loan_amount: float, tenure_months: int = 12, **kwargs) -> Dict:
        """Create a new loan request"""
        data = {
            "client_uuid": client_uuid,
            "loan_amount": loan_amount,
            "tenure_months": tenure_months,
            **kwargs
        }
        return self._request("POST", "/loans", data)
    
    def get_loan(self, loan_uuid: str) -> Dict:
        """Get loan details by UUID"""
        return self._request("GET", f"/loans/{loan_uuid}")
    
    def get_loan_status(self, loan_uuid: str) -> Dict:
        """Get current loan status"""
        return self._request("GET", f"/loans/{loan_uuid}/status")
    
    def submit_loan(self, loan_uuid: str) -> Dict:
        """Submit loan for review"""
        return self._request("POST", f"/loans/{loan_uuid}/submit")
    
    def cancel_loan(self, loan_uuid: str, reason: str) -> Dict:
        """Cancel a loan request"""
        return self._request("POST", f"/loans/{loan_uuid}/cancel", {"reason": reason})


# Usage Example
if __name__ == "__main__":
    # Initialize the API client
    api = SureBucksAPI("sb_live_your_api_key_here")
    
    # Create a new client
    client = api.create_client(
        business_name="Acme Trading Ltd",
        registration_number="RC123456",
        email="info@acmetrading.com",
        business_type="llc"
    )
    print(f"Created client: {client['data']['uuid']}")
    
    # Create a loan request
    loan = api.create_loan(
        client_uuid=client['data']['uuid'],
        loan_amount=500000,
        tenure_months=12,
        purpose="Working capital"
    )
    print(f"Created loan: {loan['data']['uuid']}")
    
    # Check loan status
    status = api.get_loan_status(loan['data']['uuid'])
    print(f"Loan status: {status['data']['status']}")

PHP

Using cURL for HTTP requests in PHP.

<?php
/**
 * SureBucks SME Loan API Client for PHP
 */
class SureBucksAPI {
    private string $apiKey;
    private string $baseUrl;
    
    public function __construct(string $apiKey, string $baseUrl = 'https://api.surebucks-sme.com/v1') {
        $this->apiKey = $apiKey;
        $this->baseUrl = $baseUrl;
    }
    
    /**
     * Make an API request
     */
    private function request(string $method, string $endpoint, array $data = []): array {
        $ch = curl_init();
        $url = $this->baseUrl . $endpoint;
        
        $headers = [
            'X-API-Key: ' . $this->apiKey,
            'Content-Type: application/json',
            'Accept: application/json'
        ];
        
        curl_setopt_array($ch, [
            CURLOPT_URL => $url,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER => $headers,
            CURLOPT_CUSTOMREQUEST => $method,
            CURLOPT_TIMEOUT => 30
        ]);
        
        if (!empty($data) && in_array($method, ['POST', 'PUT', 'PATCH'])) {
            curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
        }
        
        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        $error = curl_error($ch);
        curl_close($ch);
        
        if ($error) {
            throw new Exception("cURL Error: $error");
        }
        
        $decoded = json_decode($response, true);
        
        if ($httpCode >= 400) {
            throw new Exception($decoded['message'] ?? 'API Error', $httpCode);
        }
        
        return $decoded;
    }
    
    // Client Methods
    public function createClient(array $data): array {
        return $this->request('POST', '/clients', $data);
    }
    
    public function getClient(string $uuid): array {
        return $this->request('GET', "/clients/$uuid");
    }
    
    public function listClients(int $page = 1, int $perPage = 20): array {
        return $this->request('GET', "/clients?page=$page&per_page=$perPage");
    }
    
    public function updateClient(string $uuid, array $data): array {
        return $this->request('PUT', "/clients/$uuid", $data);
    }
    
    // Loan Methods
    public function createLoan(array $data): array {
        return $this->request('POST', '/loans', $data);
    }
    
    public function getLoan(string $uuid): array {
        return $this->request('GET', "/loans/$uuid");
    }
    
    public function getLoanStatus(string $uuid): array {
        return $this->request('GET', "/loans/$uuid/status");
    }
    
    public function submitLoan(string $uuid): array {
        return $this->request('POST', "/loans/$uuid/submit");
    }
    
    public function cancelLoan(string $uuid, string $reason): array {
        return $this->request('POST', "/loans/$uuid/cancel", ['reason' => $reason]);
    }
}

// Usage Example
try {
    $api = new SureBucksAPI('sb_live_your_api_key_here');
    
    // Create a new client
    $client = $api->createClient([
        'business_name' => 'Acme Trading Ltd',
        'registration_number' => 'RC123456',
        'email' => 'info@acmetrading.com',
        'business_type' => 'llc'
    ]);
    echo "Created client: " . $client['data']['uuid'] . "\n";
    
    // Create a loan request
    $loan = $api->createLoan([
        'client_uuid' => $client['data']['uuid'],
        'loan_amount' => 500000,
        'tenure_months' => 12,
        'purpose' => 'Working capital'
    ]);
    echo "Created loan: " . $loan['data']['uuid'] . "\n";
    
    // Check loan status
    $status = $api->getLoanStatus($loan['data']['uuid']);
    echo "Loan status: " . $status['data']['status'] . "\n";
    
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

Node.js

Using axios for HTTP requests in Node.js.

const axios = require('axios');

/**
 * SureBucks SME Loan API Client for Node.js
 */
class SureBucksAPI {
    constructor(apiKey, baseUrl = 'https://api.surebucks-sme.com/v1') {
        this.client = axios.create({
            baseURL: baseUrl,
            headers: {
                'X-API-Key': apiKey,
                'Content-Type': 'application/json'
            },
            timeout: 30000
        });
        
        // Response interceptor for error handling
        this.client.interceptors.response.use(
            response => response.data,
            error => {
                const message = error.response?.data?.message || error.message;
                throw new Error(message);
            }
        );
    }
    
    // Client Methods
    async createClient(data) {
        return this.client.post('/clients', data);
    }
    
    async getClient(uuid) {
        return this.client.get(`/clients/${uuid}`);
    }
    
    async listClients(page = 1, perPage = 20) {
        return this.client.get('/clients', { params: { page, per_page: perPage } });
    }
    
    async updateClient(uuid, data) {
        return this.client.put(`/clients/${uuid}`, data);
    }
    
    // Loan Methods
    async createLoan(data) {
        return this.client.post('/loans', data);
    }
    
    async getLoan(uuid) {
        return this.client.get(`/loans/${uuid}`);
    }
    
    async getLoanStatus(uuid) {
        return this.client.get(`/loans/${uuid}/status`);
    }
    
    async submitLoan(uuid) {
        return this.client.post(`/loans/${uuid}/submit`);
    }
    
    async cancelLoan(uuid, reason) {
        return this.client.post(`/loans/${uuid}/cancel`, { reason });
    }
    
    async listLoans(page = 1, perPage = 20, filters = {}) {
        return this.client.get('/loans', { params: { page, per_page: perPage, ...filters } });
    }
}

// Usage Example
async function main() {
    const api = new SureBucksAPI('sb_live_your_api_key_here');
    
    try {
        // Create a new client
        const client = await api.createClient({
            business_name: 'Acme Trading Ltd',
            registration_number: 'RC123456',
            email: 'info@acmetrading.com',
            business_type: 'llc'
        });
        console.log('Created client:', client.data.uuid);
        
        // Create a loan request
        const loan = await api.createLoan({
            client_uuid: client.data.uuid,
            loan_amount: 500000,
            tenure_months: 12,
            purpose: 'Working capital'
        });
        console.log('Created loan:', loan.data.uuid);
        
        // Check loan status
        const status = await api.getLoanStatus(loan.data.uuid);
        console.log('Loan status:', status.data.status);
        
    } catch (error) {
        console.error('Error:', error.message);
    }
}

main();

// ES Module export (for modern Node.js)
module.exports = SureBucksAPI;