TreasuryWireAPI docsSign inGet API keys

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.

BodyTypeDescription
typerequiredstringwallet, nostro, clearingCollect, clearingPayout, income or expense. Use wallet for customers.
ownerRefrequiredstringYour ID for the customer.
currencyrequiredstringThree-letter currency code, such as NGN.
emailstringRequired for a wallet unless the customer already has an email on file.
phoneNumberstringThe customer's phone number.
bvnstringThe customer's 11-digit BVN.
firstName / lastNamestringNeeded by some providers when creating the virtual account.
addressstringThe customer's address.
dateOfBirthstringFormat YYYY/MM/DD. Needed by some providers.
201 Created
{
  "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"
      }
    ]
  }
}
StatusMeaning
201Account created.
409This owner already has an account of this type and currency, or your provider account isn't set up yet (providerSetupIncomplete is true).
422Validation 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.

QueryTypeDescription
typestringOnly accounts of this type, such as wallet.
currencystringOnly accounts in this currency.
Response
{
  "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.

Response
{
  "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"
  }
}
StatusMeaning
200Balance returned.
404No 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.

QueryTypeDescription
pageintegerPage number, starting at 1. Default 1.
limitintegerLines per page, 1 to 100. Default 20.
Response
{
  "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"