Response Format

All Cashfin Business API responses follow a consistent JSON structure for easy parsing and error handling.

Success Responses

Standard Success Response

{
  "success": true,
  "message": "Operation completed successfully",
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "title": "Premium Widget",
    "price": 1999.99
  }
}

List Response (with Pagination)

{
  "success": true,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "title": "Premium Widget",
      "price": 1999.99
    },
    {
      "_id": "507f191e810c19729de860ea",
      "title": "Standard Widget",
      "price": 999.99
    }
  ],
  "meta": {
    "total": 45,
    "page": 1,
    "limit": 10,
    "pages": 5
  }
}

Creation Response

{
  "success": true,
  "message": "Product created successfully",
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "title": "New Product",
    "sku": "PRD-001",
    "price": 1999.99,
    "stock": 100
  }
}

Update Response

{
  "success": true,
  "message": "Product updated successfully",
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "modified": 1
  }
}

Response Fields

Common Fields

Field	Type	Description
success	boolean	Indicates if the request was successful
message	string	Human-readable status message
data	object or array	The response payload
meta	object	Pagination and metadata (for lists)

Resource Fields

Most resources include these standard fields:

Field	Type	Description
_id	string	Unique identifier (MongoDB ObjectID)
createdat	string	ISO 8601 creation timestamp
updatedat	string	ISO 8601 last update timestamp
active	boolean	Whether the resource is active
sourceorigin	string	Origin of the resource (api, dashboard, etc.)

Error Responses

Error responses include additional fields for debugging:

{
  "success": false,
  "error": "Brief error description",
  "errors": {
    "field": "Field-specific error"
  },
  "message": "Detailed error message"
}

See Error Handling for complete error documentation.

Data Types in Responses

Timestamps

All timestamps are returned in ISO 8601 format (UTC):

{
  "createdat": "2024-01-15T10:30:00.000Z",
  "updatedat": "2024-01-16T14:45:00.000Z"
}

ObjectIDs

MongoDB ObjectIDs are returned as 24-character hex strings:

{
  "_id": "507f1f77bcf86cd799439011",
  "businessid": "507f191e810c19729de860ea"
}

Monetary Values

Currency amounts are returned as floating-point numbers:

{
  "price": 1999.99,
  "amount": 5000.0,
  "fees": 50.5
}

Currency

All monetary values are in the business's configured currency (usually KES for Kenyan Shillings).

Nested Objects

Related data may be included as nested objects:

{
  "_id": "507f1f77bcf86cd799439011",
  "title": "Premium Subscription",
  "customer": {
    "_id": "507f191e810c19729de860ea",
    "name": "John Doe",
    "email": "[email protected]"
  },
  "product": {
    "_id": "507f1f77bcf86cd799439012",
    "title": "Monthly Plan",
    "price": 999.0
  }
}

Arrays

Arrays contain collections of objects:

{
  "items": [
    {
      "itemid": "507f1f77bcf86cd799439011",
      "title": "Widget A",
      "quantity": 2,
      "rate": 500.0
    },
    {
      "itemid": "507f1f77bcf86cd799439012",
      "title": "Widget B",
      "quantity": 1,
      "rate": 750.0
    }
  ]
}

Pagination Metadata

List endpoints include pagination information in the meta object:

{
  "meta": {
    "total": 150,
    "page": 2,
    "limit": 10,
    "pages": 15
  }
}

Field	Description
total	Total number of records
page	Current page number
limit	Records per page
pages	Total number of pages

Handling Responses

JavaScript/TypeScript

interface ApiResponse<T> {
  success: boolean;
  message?: string;
  data: T;
  meta?: {
    total: number;
    page: number;
    limit: number;
    pages: number;
  };
}

interface Product {
  _id: string;
  title: string;
  price: number;
  stock: number;
}

async function getProducts(): Promise<Product[]> {
  const response = await fetch(
    "https://api.cashfin.africa/business/product/list",
    {
      headers: { Authorization: API_KEY },
    }
  );

  const result: ApiResponse<Product[]> = await response.json();

  if (!result.success) {
    throw new Error("Failed to fetch products");
  }

  return result.data;
}

PHP

<?php
function getProducts(): array
{
    $response = file_get_contents(
        'https://api.cashfin.africa/business/product/list',
        false,
        stream_context_create([
            'http' => [
                'header' => "Authorization: {$apiKey}\r\n"
            ]
        ])
    );

    $result = json_decode($response, true);

    if (!$result['success']) {
        throw new Exception('Failed to fetch products');
    }

    return $result['data'];
}

Python

from typing import TypedDict, List

class Product(TypedDict):
    _id: str
    title: str
    price: float
    stock: int

def get_products() -> List[Product]:
    response = requests.get(
        'https://api.cashfin.africa/business/product/list',
        headers={'Authorization': API_KEY}
    )

    result = response.json()

    if not result['success']:
        raise Exception('Failed to fetch products')

    return result['data']

HTTP Status Codes

The API uses standard HTTP status codes:

Code	Meaning	Response Body
200	Success	{ "success": true, ... }
201	Created	{ "success": true, ... }
400	Bad Request	{ "success": false, "error": "..." }
401	Unauthorized	{ "success": false, "message": "..." }
404	Not Found	{ "success": false, "error": "..." }
429	Rate Limited	{ "success": false, "error": "...", "retry_after": 30 }
500	Server Error	{ "success": false, "error": "..." }