Transactions API

Retrieve payment transaction records for your business.

The Transactions API gives you read access to all payment transactions processed through Cashfin — mobile money payments, invoice payments, subscription charges, and more. Use it to build reconciliation tools, financial dashboards, or sync transaction data to accounting systems.

Read-Only

The Transactions API is read-only. Transactions are created automatically when payments are processed.

Use Cases

• Reconciliation: Match transactions against your bank records or ERP
• Financial Reporting: Pull daily, weekly, or monthly transaction summaries
• Accounting Sync: Push transaction data to external accounting software

Endpoints

Method	Endpoint	Description
GET	/business/transaction/list	List all transactions
GET	/business/transaction/details/:id	Get transaction details

---

List Transactions

Retrieve a paginated list of transactions.

GET /business/transaction/list

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number
limit	integer	10	Results per page (max: 100)
search	string	-	Search by title, transaction code, or reference
status	string	-	Filter by status: pending, completed, failed, cancelled
type	string	-	Filter by type: credit, debit
channel	string	-	Filter by channel: mpesa, invoice, subscription, order, manual

Example Request

cURL

curl -X GET "https://api.cashfin.africa/business/transaction/list?page=1&limit=10&status=completed" \
  -H "Authorization: cs_your_client_secret"

JavaScript

const response = await fetch(
  "https://api.cashfin.africa/business/transaction/list?page=1&limit=10&status=completed",
  {
    headers: { Authorization: "cs_your_client_secret" },
  }
);
const data = await response.json();

PHP

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL            => "https://api.cashfin.africa/business/transaction/list?page=1&limit=10",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER     => ["Authorization: cs_your_client_secret"],
]);

$result = json_decode(curl_exec($curl), true);

Python

import requests

response = requests.get(
    'https://api.cashfin.africa/business/transaction/list',
    headers={'Authorization': 'cs_your_client_secret'},
    params={
        'page': 1,
        'limit': 10,
        'status': 'completed',
        'channel': 'mpesa'
    }
)

Success Response

{
  "success": true,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439050",
      "title": "M-Pesa Payment - INV-2024-001",
      "code": "TXN-2024-001",
      "amount": 12500.0,
      "type": "credit",
      "status": "completed",
      "channel": "mpesa",
      "reference": "QHG2K4L8MN",
      "createdat": "2024-01-15T14:22:00.000Z"
    }
  ],
  "pagination": {
    "total": 148,
    "page": 1,
    "limit": 10,
    "pages": 15
  }
}

---

Get Transaction Details

Retrieve full details of a specific transaction.

GET /business/transaction/details/:id

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Transaction ID (MongoDB ObjectID)

Example Request

cURL

curl -X GET "https://api.cashfin.africa/business/transaction/details/507f1f77bcf86cd799439050" \
  -H "Authorization: cs_your_client_secret"

JavaScript

const txId = "507f1f77bcf86cd799439050";

const response = await fetch(
  `https://api.cashfin.africa/business/transaction/details/${txId}`,
  {
    headers: { Authorization: "cs_your_client_secret" },
  }
);
const data = await response.json();

Python

import requests

tx_id = '507f1f77bcf86cd799439050'

response = requests.get(
    f'https://api.cashfin.africa/business/transaction/details/{tx_id}',
    headers={'Authorization': 'cs_your_client_secret'}
)

Success Response

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439050",
    "title": "M-Pesa Payment - INV-2024-001",
    "code": "TXN-2024-001",
    "amount": 12500.0,
    "type": "credit",
    "status": "completed",
    "channel": "mpesa",
    "reference": "QHG2K4L8MN",
    "note": "Payment for office supplies invoice",
    "createdat": "2024-01-15T14:22:00.000Z",
    "updatedat": "2024-01-15T14:22:45.000Z"
  }
}

---

Transaction Statuses

Status	Description
pending	Payment initiated, awaiting confirmation
completed	Payment successfully processed
failed	Payment failed or declined
cancelled	Payment cancelled

Transaction Types

Type	Description
credit	Money received (payment in)
debit	Money paid out

Transaction Channels

Channel	Description
mpesa	M-Pesa mobile money payment
invoice	Payment received against an invoice
subscription	Recurring subscription charge
order	Payment for a shop order
manual	Manually recorded transaction

---

Error Responses

Transaction Not Found

{
  "success": false,
  "error": "Transaction not found"
}

Invalid Transaction ID

{
  "success": false,
  "error": "Invalid transaction ID format"
}