Accounts & balances
A wallet holds one customer's money in one currency. You identify the customer with an ownerRef: your own ID for them.
Create an account
POST/ledger/account
Creates an account for an owner. Wallets also get a virtual bank account number, so the customer can fund the wallet by bank transfer.
| Body | Type | Description |
|---|---|---|
typerequired | string | wallet, nostro, clearingCollect, clearingPayout, income or expense. Use wallet for customers. |
ownerRefrequired | string | Your ID for the customer. |
currencyrequired | string | Three-letter currency code, such as NGN. |
email | string | Required for a wallet unless the customer already has an email on file. |
phoneNumber | string | The customer's phone number. |
bvn | string | The customer's 11-digit BVN. |
firstName / lastName | string | Needed by some providers when creating the virtual account. |
address | string | The customer's address. |
dateOfBirth | string | Format YYYY/MM/DD. Needed by some providers. |
{
"message": "Account created",
"status": "OK",
"account": {
"_id": "665f1c2e9a3b4c0012ab34cd",
"type": "wallet",
"ownerRef": "cust_1001",
"currency": "NGN",
"balance": 0,
"mode": "test",
"virtualAccounts": [
{
"provider": "flutterwave",
"accountNumber": "7824822527",
"accountName": "Ada Obi",
"bankName": "WEMA BANK"
}
]
}
}| Status | Meaning |
|---|---|
201 | Account created. |
409 | This owner already has an account of this type and currency, or your provider account isn't set up yet (providerSetupIncomplete is true). |
422 | Validation error, or a wallet with no email available. |
If a provider couldn't issue a virtual account, the account is still created and the response adds a virtualAccountFailures array explaining why.
curl -X POST "https://usetreasurywire.com/api/v1/ledger/account" \
-H "Authorization: Bearer $TREASURYWIRE_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "wallet",
"ownerRef": "cust_1001",
"currency": "NGN",
"email": "ada@example.com",
"firstName": "Ada",
"lastName": "Obi"
}'Get an owner's balances
GET/ledger/account/by-owner/{ownerRef}
Returns every account an owner has. An owner with no accounts gets an empty list, not a 404.
| Query | Type | Description |
|---|---|---|
type | string | Only accounts of this type, such as wallet. |
currency | string | Only accounts in this currency. |
{
"message": "Balances retrieved",
"status": "OK",
"accounts": [
{
"_id": "665f1c2e9a3b4c0012ab34cd",
"type": "wallet",
"ownerRef": "cust_1001",
"currency": "NGN",
"balance": 250000,
"mode": "test",
"virtualAccounts": [
{
"provider": "flutterwave",
"accountNumber": "7824822527",
"accountName": "Ada Obi",
"bankName": "WEMA BANK"
}
],
"formattedBalance": "₦2,500.00"
}
]
}balance is in minor units (kobo), so 250000 is ₦2,500.00.
curl -X GET "https://usetreasurywire.com/api/v1/ledger/account/by-owner/cust_1001?currency=NGN" \
-H "Authorization: Bearer $TREASURYWIRE_KEY"Get one account's balance
GET/ledger/account/{accountId}/balance
accountId is the _id returned when the account was created.
{
"message": "Balance retrieved",
"status": "OK",
"account": {
"_id": "665f1c2e9a3b4c0012ab34cd",
"type": "wallet",
"ownerRef": "cust_1001",
"currency": "NGN",
"balance": 250000,
"mode": "test",
"virtualAccounts": [
{
"provider": "flutterwave",
"accountNumber": "7824822527",
"accountName": "Ada Obi",
"bankName": "WEMA BANK"
}
],
"formattedBalance": "₦2,500.00"
}
}| Status | Meaning |
|---|---|
200 | Balance returned. |
404 | No such account in this mode. |
curl -X GET "https://usetreasurywire.com/api/v1/ledger/account/665f1c2e9a3b4c0012ab34cd/balance" \
-H "Authorization: Bearer $TREASURYWIRE_KEY"Get an account's transaction history
GET/ledger/account/{accountId}/transactions
Statement lines for the account, newest first.
| Query | Type | Description |
|---|---|---|
page | integer | Page number, starting at 1. Default 1. |
limit | integer | Lines per page, 1 to 100. Default 20. |
{
"message": "Transaction history retrieved",
"status": "OK",
"transactions": [
{
"transactionId": "665f2a0b9a3b4c0012ab3501",
"type": "collection",
"status": "posted",
"description": "Deposit",
"drCr": "credit",
"amount": 250000,
"currency": "NGN",
"balanceAfter": 250000,
"createdAt": "2026-06-04T10:21:44.000Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 1
}
}drCr is credit when money came in and debit when it went out. Amounts are in minor units.
curl -X GET "https://usetreasurywire.com/api/v1/ledger/account/665f1c2e9a3b4c0012ab34cd/transactions?page=1&limit=20" \
-H "Authorization: Bearer $TREASURYWIRE_KEY"