Skip to main content
GET
https://api.fossapay.com
/
v1
/
transactions
List Transactions
curl --request GET \
  --url https://api.fossapay.com/v1/transactions
{
  "status": "success",
  "data": [
    {
      "transaction_id": "txn_abc123",
      "virtual_account_id": "va_xyz789",
      "virtual_account_number": "1234567890",
      "amount": 50000,
      "currency": "NGN",
      "status": "successful",
      "sender_name": "JOHN DOE",
      "sender_account": "0987654321",
      "sender_bank": "GTBank",
      "sender_bank_code": "058",
      "reference": "FP-20240115-001",
      "narration": "Payment from John Doe",
      "session_id": "SESSION123456",
      "settled": true,
      "settlement_id": "stl_def456",
      "metadata": {
        "user_id": "12345",
        "order_id": "ord_789"
      },
      "created_at": "2024-01-15T10:30:45Z"
    },
    {
      "transaction_id": "txn_def456",
      "virtual_account_id": "va_xyz789",
      "virtual_account_number": "1234567890",
      "amount": 75000,
      "currency": "NGN",
      "status": "successful",
      "sender_name": "JANE SMITH",
      "sender_account": "1122334455",
      "sender_bank": "Zenith Bank",
      "sender_bank_code": "057",
      "reference": "FP-20240115-002",
      "narration": "Payment",
      "settled": true,
      "settlement_id": "stl_def456",
      "metadata": {
        "user_id": "12345"
      },
      "created_at": "2024-01-15T14:20:30Z"
    }
  ],
  "pagination": {
    "total": 125,
    "limit": 50,
    "offset": 0,
    "has_more": true
  }
}

​
Query Parameters

​
virtual_account_id
string
Filter by virtual account ID
​
status
string
Filter by status: successful, pending, failed, reversed
​
start_date
string
Start date for filtering (ISO 8601 format)
​
end_date
string
End date for filtering (ISO 8601 format)
​
limit
number
default:"50"
Number of results to return (max 100)
​
offset
number
default:"0"
Number of results to skip for pagination
​
currency
string
Filter by currency: NGN, USD, etc.

​
Request Example

curl "https://api.fossapay.com/v1/transactions?start_date=2024-01-01&limit=50" \
  -H "Authorization: Bearer fp_live_sk_xxxxxxxx"

const transactions = await client.transactions.list({
  start_date: '2024-01-01T00:00:00Z',
  end_date: '2024-01-31T23:59:59Z',
  status: 'successful',
  limit: 50
});

transactions = client.transactions.list(
    start_date='2024-01-01T00:00:00Z',
    end_date='2024-01-31T23:59:59Z',
    status='successful',
    limit=50
)

​
Response

​
status
string
Response status: success or error
​
data
array
​
pagination
object

​
Response Example

{
  "status": "success",
  "data": [
    {
      "transaction_id": "txn_abc123",
      "virtual_account_id": "va_xyz789",
      "virtual_account_number": "1234567890",
      "amount": 50000,
      "currency": "NGN",
      "status": "successful",
      "sender_name": "JOHN DOE",
      "sender_account": "0987654321",
      "sender_bank": "GTBank",
      "sender_bank_code": "058",
      "reference": "FP-20240115-001",
      "narration": "Payment from John Doe",
      "session_id": "SESSION123456",
      "settled": true,
      "settlement_id": "stl_def456",
      "metadata": {
        "user_id": "12345",
        "order_id": "ord_789"
      },
      "created_at": "2024-01-15T10:30:45Z"
    },
    {
      "transaction_id": "txn_def456",
      "virtual_account_id": "va_xyz789",
      "virtual_account_number": "1234567890",
      "amount": 75000,
      "currency": "NGN",
      "status": "successful",
      "sender_name": "JANE SMITH",
      "sender_account": "1122334455",
      "sender_bank": "Zenith Bank",
      "sender_bank_code": "057",
      "reference": "FP-20240115-002",
      "narration": "Payment",
      "settled": true,
      "settlement_id": "stl_def456",
      "metadata": {
        "user_id": "12345"
      },
      "created_at": "2024-01-15T14:20:30Z"
    }
  ],
  "pagination": {
    "total": 125,
    "limit": 50,
    "offset": 0,
    "has_more": true
  }
}

​
Pagination Example

// Get first page
let offset = 0;
let allTransactions = [];

while (true) {
  const response = await client.transactions.list({
    start_date: '2024-01-01',
    limit: 100,
    offset: offset
  });

  allTransactions.push(...response.data);

  if (!response.pagination.has_more) {
    break;
  }

  offset += response.pagination.limit;
}

console.log(`Retrieved ${allTransactions.length} transactions`);
For better performance, use specific date ranges and filter by virtual_account_id when possible.