https://api.novacash.bi/v1Wallets API
The Wallets API provides comprehensive management of mobile money wallets within the NovaCash system. This API allows you to create, retrieve, update, and delete wallets, manage wallet balances, perform financial transactions, and handle various wallet-related operations across different mobile money providers.
Wallet Object
The Wallet object represents a mobile money wallet in the NovaCash system. Each wallet is linked to a user and contains financial information, provider details, transaction capabilities, and balance information for mobile money operations.
Key Attributes
| Attribute | Type | Description |
|---|---|---|
| id | string | Unique identifier for the wallet |
| user_id | string | ID of the user who owns the wallet |
| type | string | Wallet type: mobile_money, bank, card |
| provider | string | Mobile money provider: lumicash, econet, orange_money |
| phone_number | string | Phone number linked to the wallet |
| balance | number | Current wallet balance |
| available_balance | number | Balance available for transactions |
| currency | string | Currency code: BIF, USD, EUR |
| status | string | Wallet status: active, inactive, suspended |
| is_primary | boolean | Whether this is the primary wallet |
| account_number | string | Provider account number |
| created_at | string | Timestamp when the wallet was created |
| updated_at | string | Timestamp when the wallet was last updated |
| last_sync_at | string | Timestamp of the last balance sync |
GET /wallets
Description
Retrieve a list of all wallets 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 wallet type (mobile_money, bank, card) |
| provider | string | Optional | Filter by provider (lumicash, econet, orange_money) |
| status | string | Optional | Filter by wallet status (active, inactive, suspended) |
| user_id | string | Optional | Filter by user ID |
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 wallet type (mobile_money, bank, card)
Filter by provider (lumicash, econet, orange_money)
Filter by wallet status (active, inactive, suspended)
Filter by user ID
POST /wallets
Description
Create a new wallet for a user
Possible Errors
| Status | Error Code | Description |
|---|---|---|
| 400 | Bad Request | Invalid input data |
| 404 | Not Found | User not found |
| 409 | Conflict | Phone number already linked to another wallet |
API Playground
You are using simulated data. Switch to real API mode to call actual endpoints.
GET /wallets/{id}
Description
Retrieve a specific wallet by ID
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Required | Wallet ID |
Possible Errors
| Status | Error Code | Description |
|---|---|---|
| 401 | Unauthorized | Authentication credentials were missing or incorrect |
| 403 | Forbidden | Insufficient permissions to access this wallet |
| 404 | Not Found | Wallet not found |
API Playground
You are using simulated data. Switch to real API mode to call actual endpoints.
Path Parameters
Wallet ID
PUT /wallets/{id}
Description
Update wallet information and settings
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Required | Wallet 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 wallet |
| 404 | Not Found | Wallet not found |
API Playground
You are using simulated data. Switch to real API mode to call actual endpoints.
Path Parameters
Wallet ID
DELETE /wallets/{id}
Description
Delete a wallet
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Required | Wallet ID |
Possible Errors
| Status | Error Code | Description |
|---|---|---|
| 401 | Unauthorized | Authentication credentials were missing or incorrect |
| 403 | Forbidden | Insufficient permissions to delete this wallet |
| 404 | Not Found | Wallet not found |
| 409 | Conflict | Cannot delete wallet with positive balance |
API Playground
You are using simulated data. Switch to real API mode to call actual endpoints.
Path Parameters
Wallet ID
GET /wallets/{id}/transactions
Description
Get wallet transaction history
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Required | Wallet ID |
| page | number | Optional | Page number for pagination |
| limit | number | Optional | Number of items per page |
| type | string | Optional | Filter by transaction type |
| start_date | string | Optional | Start date for filtering (ISO format) |
| end_date | string | Optional | End date for filtering (ISO format) |
Possible Errors
| Status | Error Code | Description |
|---|---|---|
| 401 | Unauthorized | Authentication credentials were missing or incorrect |
| 403 | Forbidden | Insufficient permissions to access this wallet's transactions |
| 404 | Not Found | Wallet not found |
API Playground
You are using simulated data. Switch to real API mode to call actual endpoints.
Path Parameters
Wallet ID
Query Parameters
Page number for pagination
Number of items per page
Filter by transaction type
Start date for filtering (ISO format)
End date for filtering (ISO format)
GET /wallets/{id}/balance
Description
Get wallet current balance
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Required | Wallet ID |
Possible Errors
| Status | Error Code | Description |
|---|---|---|
| 401 | Unauthorized | Authentication credentials were missing or incorrect |
| 403 | Forbidden | Insufficient permissions to access this wallet's balance |
| 404 | Not Found | Wallet not found |
API Playground
You are using simulated data. Switch to real API mode to call actual endpoints.
Path Parameters
Wallet ID
POST /wallets/{id}/deposit
Description
Deposit funds into a wallet
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Required | Wallet ID |
Possible Errors
| Status | Error Code | Description |
|---|---|---|
| 400 | Bad Request | Invalid amount |
| 401 | Unauthorized | Authentication credentials were missing or incorrect |
| 403 | Forbidden | Insufficient permissions to deposit to this wallet |
| 404 | Not Found | Wallet not found |
| 409 | Conflict | Wallet is inactive or suspended |
API Playground
You are using simulated data. Switch to real API mode to call actual endpoints.
Path Parameters
Wallet ID
POST /wallets/{id}/withdraw
Description
Withdraw funds from a wallet
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Required | Wallet ID |
Possible Errors
| Status | Error Code | Description |
|---|---|---|
| 400 | Bad Request | Invalid amount or insufficient funds |
| 401 | Unauthorized | Authentication credentials were missing or incorrect |
| 403 | Forbidden | Insufficient permissions to withdraw from this wallet |
| 404 | Not Found | Wallet not found |
| 409 | Conflict | Wallet is inactive, suspended, or below minimum balance |
API Playground
You are using simulated data. Switch to real API mode to call actual endpoints.
Path Parameters
Wallet ID
POST /wallets/{id}/transfer
Description
Transfer funds between wallets
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Required | Source Wallet ID |
Possible Errors
| Status | Error Code | Description |
|---|---|---|
| 400 | Bad Request | Invalid amount, insufficient funds, or same wallet transfer |
| 401 | Unauthorized | Authentication credentials were missing or incorrect |
| 403 | Forbidden | Insufficient permissions to transfer from this wallet |
| 404 | Not Found | Source or destination wallet not found |
| 409 | Conflict | Wallet is suspended, closed, or currencies mismatch |
API Playground
You are using simulated data. Switch to real API mode to call actual endpoints.
Path Parameters
Source Wallet ID
GET /wallets/user/{user_id}
Description
Get all wallets for a specific user
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| user_id | string | Required | User ID |
| type | string | Optional | Filter by wallet type |
Possible Errors
| Status | Error Code | Description |
|---|---|---|
| 401 | Unauthorized | Authentication credentials were missing or incorrect |
| 403 | Forbidden | Insufficient permissions to access this user's wallets |
| 404 | Not Found | User not found |
API Playground
You are using simulated data. Switch to real API mode to call actual endpoints.
Query Parameters
User ID
Filter by wallet type