https://api.novacash.bi/v1Transactions API
The Transactions API provides comprehensive tracking and management of all financial transactions within the NovaCash system. This API allows you to create, retrieve, update, and reverse transactions, monitor transaction status, perform bulk operations, and access detailed analytics and statistics.
Transaction Object
The Transaction object represents a financial transaction in the NovaCash system. Each transaction contains detailed information about the financial movement, including amounts, status, references, and metadata for various service types like deposits, withdrawals, transfers, and payments.
Key Attributes
| Attribute | Type | Description |
|---|---|---|
| id | string | Unique identifier for the transaction |
| type | string | Transaction type: deposit, withdrawal, transfer, payment, airtime_sale, bill_payment, credit_disbursement, credit_repayment, commission, fee |
| service_type | string | Service type: lumicash_deposit, lumicash_withdrawal, airtime_sale, bill_payment, money_transfer |
| amount | number | Transaction amount (positive for deposits, negative for withdrawals) |
| currency | string | Currency code: BIF, USD, EUR |
| status | string | Transaction status: pending, active, blocked, suspended, rejected, completed, failed, reversed |
| description | string | Human-readable description of the transaction |
| wallet_id | string | ID of the wallet associated with the transaction |
| user_id | string | ID of the user who initiated the transaction |
| reference | string | External reference ID for the transaction |
| metadata | object | Additional transaction metadata (provider details, fees, etc.) |
| balance_before | number | Balance before the transaction |
| balance_after | number | Balance after the transaction |
| created_at | string | Timestamp when the transaction was created |
| updated_at | string | Timestamp when the transaction was last updated |
| completed_at | string | Timestamp when the transaction was completed |
GET /transactions
Description
Retrieve a list of all transactions with advanced filtering
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| page | number | Optional | Page number for pagination |
| limit | number | Optional | Number of items per page |
| type | string | Optional | Filter by transaction type (deposit, withdrawal, transfer, payment, airtime_sale, bill_payment, credit_disbursement, credit_repayment, commission, fee) |
| status | string | Optional | Filter by transaction status (pending, active, blocked, suspended, rejected, completed, failed, reversed) |
| wallet_id | string | Optional | Filter by wallet ID |
| user_id | string | Optional | Filter by user ID |
| start_date | string | Optional | Start date for filtering (ISO format) |
| end_date | string | Optional | End date for filtering (ISO format) |
| min_amount | number | Optional | Minimum transaction amount |
| max_amount | number | Optional | Maximum transaction amount |
| service_type | string | Optional | Filter by service type (lumicash_deposit, lumicash_withdrawal, airtime_sale, bill_payment, money_transfer) |
Possible Errors
| Status | Error Code | Description |
|---|---|---|
| 401 | Unauthorized | Authentication credentials were missing or incorrect |
| 403 | Forbidden | The request is understood, but it has been refused due to permissions |
API Playground
You are using simulated data. Switch to real API mode to call actual endpoints.
Query Parameters
Page number for pagination
Number of items per page
Filter by transaction type (deposit, withdrawal, transfer, payment, airtime_sale, bill_payment, credit_disbursement, credit_repayment, commission, fee)
Filter by transaction status (pending, active, blocked, suspended, rejected, completed, failed, reversed)
Filter by wallet ID
Filter by user ID
Start date for filtering (ISO format)
End date for filtering (ISO format)
Minimum transaction amount
Maximum transaction amount
Filter by service type (lumicash_deposit, lumicash_withdrawal, airtime_sale, bill_payment, money_transfer)
GET /transactions/{id}
Description
Retrieve a specific transaction by ID
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Required | Transaction ID |
Possible Errors
| Status | Error Code | Description |
|---|---|---|
| 401 | Unauthorized | Authentication credentials were missing or incorrect |
| 403 | Forbidden | Insufficient permissions to access this transaction |
| 404 | Not Found | Transaction not found |
API Playground
You are using simulated data. Switch to real API mode to call actual endpoints.
Path Parameters
Transaction ID
POST /transactions
Description
Create a new transaction (manual entry)
Possible Errors
| Status | Error Code | Description |
|---|---|---|
| 400 | Bad Request | Invalid input data |
| 401 | Unauthorized | Authentication credentials were missing or incorrect |
| 403 | Forbidden | Insufficient permissions to create transactions |
| 404 | Not Found | Wallet not found |
API Playground
You are using simulated data. Switch to real API mode to call actual endpoints.
PUT /transactions/{id}
Description
Update transaction information (limited fields)
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Required | Transaction ID |
Possible Errors
| Status | Error Code | Description |
|---|---|---|
| 400 | Bad Request | Invalid input data |
| 401 | Unauthorized | Authentication credentials were missing or incorrect |
| 403 | Forbidden | Insufficient permissions to update this transaction |
| 404 | Not Found | Transaction not found |
API Playground
You are using simulated data. Switch to real API mode to call actual endpoints.
Path Parameters
Transaction ID
DELETE /transactions/{id}
Description
Delete a transaction (soft delete)
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Required | Transaction ID |
Possible Errors
| Status | Error Code | Description |
|---|---|---|
| 401 | Unauthorized | Authentication credentials were missing or incorrect |
| 403 | Forbidden | Insufficient permissions to delete this transaction |
| 404 | Not Found | Transaction not found |
| 409 | Conflict | Cannot delete completed transaction - use reverse instead |
API Playground
You are using simulated data. Switch to real API mode to call actual endpoints.
Path Parameters
Transaction ID
POST /transactions/{id}/reverse
Description
Reverse a completed transaction
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Required | Transaction ID |
Possible Errors
| Status | Error Code | Description |
|---|---|---|
| 400 | Bad Request | Transaction cannot be reversed |
| 401 | Unauthorized | Authentication credentials were missing or incorrect |
| 403 | Forbidden | Insufficient permissions to reverse this transaction |
| 404 | Not Found | Transaction not found |
| 409 | Conflict | Transaction is not in a reversible state |
API Playground
You are using simulated data. Switch to real API mode to call actual endpoints.
Path Parameters
Transaction ID
GET /transactions/search
Description
Search transactions by various criteria
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| query | string | Required | Search query (reference, description, user phone, etc.) |
| page | number | Optional | Page number for pagination |
| limit | number | Optional | Number of items per page |
| type | string | Optional | Filter by transaction type |
| status | string | Optional | Filter by transaction status |
| service_type | string | Optional | Filter by service type |
Possible Errors
| Status | Error Code | Description |
|---|---|---|
| 400 | Bad Request | Invalid search query |
| 401 | Unauthorized | Authentication credentials were missing or incorrect |
API Playground
You are using simulated data. Switch to real API mode to call actual endpoints.
Query Parameters
Search query (reference, description, user phone, etc.)
Page number for pagination
Number of items per page
Filter by transaction type
Filter by transaction status
Filter by service type
GET /transactions/stats
Description
Get transaction statistics and analytics
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| period | string | Optional | Time period (today, week, month, year, custom) |
| start_date | string | Optional | Start date for custom period (ISO format) |
| end_date | string | Optional | End date for custom period (ISO format) |
| wallet_id | string | Optional | Filter by wallet ID |
| user_id | string | Optional | Filter by user ID |
| service_type | string | Optional | Filter by service type |
Possible Errors
| Status | Error Code | Description |
|---|---|---|
| 401 | Unauthorized | Authentication credentials were missing or incorrect |
| 403 | Forbidden | Insufficient permissions to access statistics |
API Playground
You are using simulated data. Switch to real API mode to call actual endpoints.
Query Parameters
Time period (today, week, month, year, custom)
Start date for custom period (ISO format)
End date for custom period (ISO format)
Filter by wallet ID
Filter by user ID
Filter by service type
POST /transactions/bulk
Description
Create multiple transactions in bulk
Possible Errors
| Status | Error Code | Description |
|---|---|---|
| 400 | Bad Request | Invalid input data or validation errors |
| 401 | Unauthorized | Authentication credentials were missing or incorrect |
| 403 | Forbidden | Insufficient permissions to create bulk transactions |
API Playground
You are using simulated data. Switch to real API mode to call actual endpoints.