Ctrl K
List Transactions
GET/api/v1/transaction
Returns paginated transactions for the authenticated business. Note: the route is registered with the singular transaction.
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| limit | number | No | Default 20, maximum 100. |
| cursor | string | No | Pagination on created_at. |
| start_date | string | No | Filter start. |
| end_date | string | No | Filter end. |
| wallet_id | string | No | Filter by wallet. |
| status | string | No | "pending", "successful", "failed", or "partial". |
| type | string | No | "credit" or "debit". |
| category | string | No | e.g. "p2p", "bank-outflow", "pocket-inflow". |
| collapse_batch | string | No | Set to "1" to merge batch rows for list display. |
| batch_transaction_id | string | No | When combined with "get_batch_info=1", adds batch summary to the response. |
| get_batch_info | string | No | Set to "1" to include "batchInfo" when a batch id is provided. |
1
Request Example
(cURL)
curl -X GET "https://api.piggyvest.business/api/v1/transaction?limit=20" \-H "Authorization: Bearer YOUR_SECRET_KEY"2
Success Response(200)
(JSON)
{ "status": true, "message": "Transactions fetched successfully", "data": { "edges": [], "pageInfo": { "hasNextPage": true, "endCursor": "string | null", "previousCursor": "string | null" }, "batchInfo": { "name": "string", "total_amount": 0, "total_split": 0, "successful_split": 0, "failed_split": 0, "status": "string", "type": "string" } }}Note: batchInfo only appears when batch_transaction_id and get_batch_info=1 are both provided. Each element of edges follows the transaction row schema below.
Transaction row schema (edges[] — core fields)
| Name | Type | Description |
|---|---|---|
| id | string | Transaction id. |
| amount | number | Amount in kobo. |
| type | string | "credit" or "debit". |
| status | string | "pending", "successful", "failed", or "partial" (batch aggregates). |
| category | string | Transaction category. |
| description | string | Narration. |
| wallet_id | string | Wallet id. |
| wallet_type | string | Wallet type. |
| created_at | string | Timestamp. |
| third_party_reference | string | Merchant reference when set. |
| peer_reference_id | string | P2P pairing reference when set. |
| batch_transaction_id | string | Batch id when applicable. |
| batch_total_split | number | When batch is collapsed in UI. |
| batch_successful_split | number | When batch is collapsed. |
| failed_split | number | When batch is collapsed. |
Transaction status values
pendingStill processing.
successfulCompleted successfully.
failedTerminal failure.
partialBatch / split payment — not all legs succeeded (successful_split < total_split in batch context).