Transactions
Transactions represent the immutable movement of funds between accounts on SwitchLock. Every transaction is strictly atomic.
How to read a transaction
Because transactions can involve multiple parties (like a buyer, a seller, and platform fees), the API does not use simple sender and receiver fields. Instead, every transaction contains an entries array showing exactly which accounts were impacted.
Money left this account. The balance_after will be lower than the balance_before.
Money entered this account. The balance_after will be higher than the balance_before.
Transactions are immutable. Once a transaction is recorded, it cannot be deleted or updated. If a mistake is made, a new reversing transaction must be issued.
List ledger transactions
Retrieves all transactions that impacted any account within a specific ledger. This is the best endpoint for showing a user their overall activity.
curl "https://api.switchlock.co.zw/v1/ledger/ldg_01HABC.../transactions" \
-H "x-api-key: zl_sk_your_key_here" \
-H "x-company-id: cmp_01HXYZ..."[
{
"id": "tx_01HXYZ...",
"type": "TRANSFER",
"status": "COMPLETED",
"amount": "1500",
"reference": "SWITCHLOCK-100234",
"created_at": "2026-06-23T10:15:00.000Z",
"entries": [
{
"id": "ent_1...",
"direction": "DEBIT",
"amount": "1500",
"balance_before": "5000",
"balance_after": "3500",
"account": {
"id": "acc_01HABC...",
"type": "USER",
"currency": "USD"
}
},
{
"id": "ent_2...",
"direction": "CREDIT",
"amount": "1500",
"balance_before": "1000",
"balance_after": "2500",
"account": {
"id": "acc_01HDEF...",
"type": "ESCROW",
"currency": "USD"
}
}
]
}
]Get account statement
Retrieves the transaction history for a specific account, optionally filtered by a date range. Useful for generating monthly statements.
curl "https://api.switchlock.co.zw/v1/ledger/accounts/acc_01HABC.../statement?startDate=2026-06-01T00:00:00Z&endDate=2026-06-30T23:59:59Z" \
-H "x-api-key: zl_sk_your_key_here" \
-H "x-company-id: cmp_01HXYZ..."Get company escrow history
A specialized endpoint that returns a flattened view of escrow-related transactions across your entire company. It pre-calculates platform revenue and identifies the buyer and seller, making it ideal for admin dashboards.
curl "https://api.switchlock.co.zw/v1/ledger/escrow/history?startDate=2026-06-01T00:00:00Z" \
-H "x-api-key: zl_sk_your_key_here" \
-H "x-company-id: cmp_01HXYZ..."[
{
"id": "tx_01HXYZ...",
"status": "COMPLETED",
"type": "PAYMENT",
"total_amount": "50000",
"company_revenue": "1500",
"system_revenue": "500",
"reference": "SWITCHLOCK-100235",
"created_at": "2026-06-23T11:00:00.000Z",
"buyer": {
"id": "usr_01HBUY...",
"first_name": "Alice"
},
"seller": {
"id": "usr_01HSELL...",
"first_name": "Bob"
},
"source_ledger": {
"name": "User Ledger - Alice",
"type": "USER",
"account_type": "USER"
},
"destination_ledger": {
"name": "User Ledger - Bob",
"type": "USER",
"account_type": "USER"
}
}
]