Internal accounts and balances

An internal account is an account Wingspan holds for you. Your Wingspan Wallet is one, and so is the tax withholding savings account. You read them, check their balances, and move money in and out of them with transfers.

Prerequisites

A credential with bookkeeping.business-banking-account:read. Reading a balance needs bookkeeping.business-banking-balance:read. Reading the ledger needs bookkeeping.transaction:read. Opening an account needs bookkeeping.business-banking-account:write.
An Account that has a Wallet. If the list is empty, create one as shown below.

List your internal accounts

Call GET /v3/finance/internal-accounts. Narrow the list with filter[type][eq].

`type`	What it is
`Banking`	Your Wingspan Wallet
`TaxWithholding`	Your tax withholding savings account. See Tax withholding.
`Clearing`, `CardClearing`, `InternationalClearing`	Accounts Wingspan uses to settle payments
`ApPrefunding`, `ApPayouts`	Accounts Wingspan uses to fund and send payouts

This list isn't paginated. The data array holds every match and pagination.nextPageToken is always empty. An unknown type returns 422.

curl "https://api.wingspan.app/v3/finance/internal-accounts?filter[type][eq]=Banking" \
  -H "Authorization: Bearer $WINGSPAN_TOKEN"

// 200 OK (trimmed)
{
  "data": [
    {
      "id": "Ia4Kq9Wn2Lx7Tz5Bm8Hc3V",
      "type": "Banking",
      "name": "Wingspan Wallet",
      "status": "Active",
      "currency": "USD",
      "capabilities": ["Charge", "Payout"],
      "numbers": { "account": "000123456789", "routing": "021000021" },
      "events": { "createdAt": "2026-03-02T14:11:09Z", "openedAt": "2026-03-02T14:11:12Z" }
    }
  ],
  "pagination": { "nextPageToken": "" }
}

status is Pending, Active, Inactive, or Closed. numbers holds the account and routing numbers when the account has them.

Read one account with GET /v3/finance/internal-accounts/{internalAccountId}. An ID that isn't yours returns 404.

Read a balance

Call GET /v3/finance/internal-accounts/{internalAccountId}/balance.

// 200 OK
{
  "balance": 4200.50,
  "available": 4000.50,
  "hold": 200.00,
  "pending": 0.00,
  "currency": "USD",
  "updatedAt": "2026-10-20T15:02:11Z"
}

balance is the total. available is what you can move now. hold is money set aside, and pending is money still settling.

Open an account

Call POST /v3/finance/internal-accounts with type and currency. Both are required. name, subject, and metadata are optional.

curl -X POST "https://api.wingspan.app/v3/finance/internal-accounts" \
  -H "Authorization: Bearer $WINGSPAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "type": "TaxWithholding", "currency": "USD" }'

The response is 201 with the new account. Which types and currencies you can open:

`type`	Currencies
`Banking`, `Clearing`, `TaxWithholding`	`USD` only
`ApPrefunding`	`USD`, `CAD`, `EUR`, `GBP`, `CZK`, `PLN`
`ApPayouts`	`USD`, `CAD`, `EUR`
`InternationalClearing`	`USD`, `CAD`
`CardClearing`	Can't be created directly

For ApPayouts and InternationalClearing, a repeat call for the same currency returns the account you already have.

Read the ledger

Call GET /v3/finance/internal-accounts/{internalAccountId}/transactions for the account's ledger entries.

Parameter	Notes
`filter[status][eq]`	`Active`, `Pending`, or `Inactive`
`filter[startDate][eq]`, `filter[endDate][eq]`	`YYYY-MM-DD`
`sort[effectiveAt]`	`asc` or `desc`
`page[size]`, `page[token]`	See Pagination

Each entry has direction (Credit or Debit), amount, a running balance, description, and effectiveAt.

These are ledger entries for money in the account. They are not the bookkeeping transactions you categorize for taxes. See Transactions and categories.

Errors

Status	Meaning
`403`	Your credential is missing the scope for this call
`404`	The account doesn't exist or isn't yours
`422`	The `type` filter isn't a known type, the `type` and `currency` pair can't be opened, or a date filter isn't `YYYY-MM-DD`

Webhook events

InternalAccount.Created, InternalAccount.Opened, InternalAccount.Updated, and InternalAccount.Closed are published. InternalAccount.BalanceChanged is published when a balance changes. See Webhooks and events.