​
Overview

The transaction history captures every money movement on the platform for the authenticated user. This includes wallet top-ups, withdrawals, escrow fund locks, releases, refunds, platform fees, and dispute fees.

​
Fetching transactions

GET /transaction-list
Authorization: Bearer <token>
Supports filtering and cursor pagination: 
GET /transaction-list?category=escrow&limit=20

​
Query parameters

ParameterTypeDescription
categorystringFilter by category: deposit, withdrawal, or escrow
escrow_iduuidFilter to transactions related to a specific escrow
statusstringFilter by status: pending, succeeded, failed, canceled
limitintegerMax records to return (default 20, max 100)
beforeISO 8601Cursor — return records created before this timestamp

​
Response

{
  "success": true,
  "status": 200,
  "data": [
    {
      "id": "t1u2v3w4-x5y6-7890-abcd-ef1234567890",
      "type": "escrow_release",
      "category": "escrow",
      "direction": "in",
      "amount": 490000,
      "currency": "NGN",
      "status": "succeeded",
      "description": "Escrow release — iPhone 15 Pro Max 256GB",
      "escrow_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
      "milestone_id": null,
      "created_at": "2026-04-20T10:00:00Z",
      "completed_at": "2026-04-20T10:01:32Z"
    }
  ]
}

​
Categories and types

Transactions are grouped into three client-facing categories, each covering multiple raw types:
CategoryTransaction types included
depositwallet_topup
withdrawalwallet_withdrawal
escrowescrow_lock, escrow_release, escrow_refund, kyc_lock, kyc_unlock, platform_fee, dispute_fee
Use category for top-level filtering in your UI (e.g. a tab bar). Use type for detailed line-item labelling.

​
Direction

DirectionMeaning
inMoney credited to the user’s wallet
outMoney debited from the user’s wallet
feePlatform or dispute fee charged

​
Pagination

Use before with the created_at of the last item returned to load the next page: 
GET /transaction-list?limit=20&before=2026-04-20T10:00:00Z
When the response contains fewer items than limit, you have reached the end of the list.