Banking and spend

Banking and spend covers the money your own Account holds and spends: the Wingspan Wallet and its balances, the bank accounts linked to it, transfers between them, debit cards, a tax withholding savings account, and the bookkeeping that records it all. Everything here lives under /v3/finance.

This is different from paying people. To pay a payee, see Send payments. To get paid by clients, see Get paid.

Pick a task

You want to	Read	Main endpoints
See your Wallet, its numbers, balance, and ledger	Internal accounts and balances	`/v3/finance/internal-accounts`
Move money between the Wallet and a bank account	Move money with transfers	`/v3/finance/transfers`
Download a monthly statement	Account statements	`/v3/finance/internal-accounts/{internalAccountId}/statements`
Link a bank account and verify it	Link and verify a bank account	`/v3/finance/external-bank-accounts`
Rename, reconnect, check, or remove a bank account	Manage a bank account	`/v3/finance/external-bank-accounts/{bankAccountId}`
Find out what a country or currency needs to register a bank account	Bank account countries and institutions	`/v3/finance/bank-account-countries`, `/v3/finance/institutions`
Order a debit card	Issue a card	`/v3/finance/cards`
Set a PIN or limits, show card details, add to a phone wallet	Card controls and digital wallets	`/v3/finance/cards/{cardId}/...`
Set aside tax money and schedule IRS payments	Tax withholding	`/v3/finance/tax-withholdings`
Estimate what you owe	Tax estimates	`/v3/finance/tax-estimates`
Record and categorize income and expenses	Transactions and categories	`/v3/finance/transactions`, `/v3/finance/transaction-categories`
Report profit, income, and expenses	Profit and loss and insights	`/v3/finance/profit-and-loss`, `/v3/finance/insights`
Check or redeem cashback	Cashback	`/v3/finance/cashback`

Cards you save so you can pay with them, PaymentCard, are a different resource. See Payment and payout methods.

Things every endpoint here shares

Scope. Each operation needs one scope. Wallet, transfers, and tax withholding use bookkeeping.business-banking-account:read or :write. Transactions use bookkeeping.transaction:read or :write. Reports and cashback use bookkeeping.service:read or :write. Bank accounts and bank-account countries use payments.funding-source:read or :write. Cards use payments.card:read or :write. Wallet balance uses bookkeeping.business-banking-balance:read. A credential without the scope gets 403.
Which Account. Calls act on the Account your credential belongs to. To act for another Account, send X-Wingspan-Account. See Acting on behalf of accounts.
Money amounts. Amounts are JSON numbers in major units, such as 1250.00 for 1,250 dollars.
Idempotency. Calls that move money require an Idempotency-Key header: creating a transfer, depositing or withdrawing tax money, scheduling or cancelling a tax payment, creating a bank account, and redeeming cashback. Reuse the key to retry. Use a new key for a new request. See Idempotency.
MFA step-up. If you call with a person's login session, bank account changes and money movements can return 403 with code: StepUpMfaRequired. Create a challenge at POST /v3/platform/mfa-challenges, verify it, and retry. Bank account changes ask for requiredFor: "BankAccountChange". Transfers and tax movements ask for requiredFor: "HighRiskWriteAction". A backend using an API key has no session to step up. See Environments and authentication.
Lists. List endpoints take page[size] (default 25, maximum 100) and page[token], and return pagination.nextPageToken. Filters look like filter[status][eq]=Active. See Pagination and Filtering, sorting, and expanding.
Errors. Errors use the standard problem format. See Errors. A 503 with detailCode: finance.UpstreamContractViolation means a Wingspan service returned data this API couldn't use. Retry later, and contact support with the requestId if it persists.