Wallet balance

A wallet's availableBalance is the money the account can move right now. Transfers out of a wallet reduce it immediately; incoming funds count only once their wallet transaction is completed.

Empty or negative wallets don't incur fees, but a negative balance limits the account's ability to move funds until it's covered.

Check a balance with the API

Provide the walletID and/or accountID path parameters to the following endpoints to view a wallet's balance:

List wallets - Lists all wallets associated with an account
Retrieve a wallet - Gets details of a specific wallet

The response will contain the availableBalance object.

To get an account ID (also called X-Account-ID), see find your account ID.

Navigate to the Wallet section of the Dashboard and click the menu option in the wallet summary section. You'll be able to copy the wallet ID to your clipboard. You can also retrieve a wallet ID by providing accountID to the list payment methods GET endpoint.

Reconcile a balance

Every change to a balance is a wallet transaction that points back to what caused it: a transfer, a dispute, a fee, or a sweep. To explain a day's balance, work from wallet transactions:

List the day's completed transactions with the list wallet transactions endpoint, using status=completed, completedStartDateTime, and completedEndDateTime. Pending credits don't count toward the balance until they complete.
Group them by transactionType. For example, card-payment and payment are money in; refund, dispute, and ach-reversal are money taken back; moov-fee is fees; and payout, cash-out, and auto-sweep are money out. See every type in wallet transactions.
Match each one to its source with sourceType and sourceID. One you can't match to a transfer of yours is usually a dispute, a fee, or an adjustment.
Check the closing balance. The availableBalance on the day's last completed transaction equals the opening balance plus the day's credits, minus its debits.
Match payouts to bank deposits. For a sweep, filter wallet transactions by sweepID to see exactly what went into one payout, and match it to the deposit by its statement descriptor (swp_…).

Amounts can cross days: card payments land the next banking day after the brand's cutoff, ACH debits after a two-day hold, and sweeps pay out what's available at their 4:00 PM ET close. Transfers models the timing for any flow, and reconcile card activity walks through a card example. Fees are reconciled against each account's plan in merchant billing. To reconcile in a data warehouse, data sync sends your Moov data to BigQuery.

Avoid a negative balance

Moov will use an account's wallet to settle refunds, disputes, ACH reversals and Moov fees, which could result in a negative balance.

For example, an ACH debit can be returned and the transfer reversed up to 60 days after its ACH effective date; Moov deducts the amount from the wallet that received the funds. To stay covered:

Keep a minimum balance and set a pullPaymentMethodID on the wallet's sweep so Moov debits a bank account when the balance goes negative
Watch balance.updated webhooks and fund the wallet when it drops below what you need

A transfer out of a wallet that can't cover the amount and any fees fails with failureReason wallet-insufficient-funds; fund the wallet and send a new transfer.

See ACH returns for return scenarios.

Get notified of balance changes

Subscribe to the wallet balance.updated event to be notified of balance changes. See the event payload.

Manage wallets

Create a general wallet with the create wallet endpoint, and rename any wallet or close a general wallet with the update wallet endpoint:

curl -X PATCH "https://api.moov.io/accounts/{accountID}/wallets/{walletID}" \
  -H "Authorization: Bearer {token}" \
  -H "x-moov-version: v2026.07.00" \
  -d '{ "name": "Vendor payouts", "description": "Funds for vendor invoices" }'

const result = await moov.wallets.update({
  walletID: "9f1c6e07-aae8-40e6-b290-502bb1bc486e",
  accountID: "e4aad2fb-201d-4390-b4d3-6de7716152e1",
  patchWallet: {
    name: "My second wallet",
    description: "My new description",
    metadata: {
      "optional": "metadata",
    },
  },
});

res = moov.wallets.update(wallet_id="9f1c6e07-aae8-40e6-b290-502bb1bc486e", account_id="e4aad2fb-201d-4390-b4d3-6de7716152e1", name="My second wallet", description="My new description", metadata={
    "optional": "metadata",
})

res = s.wallets.update(wallet_id: '9f1c6e07-aae8-40e6-b290-502bb1bc486e', account_id: 'e4aad2fb-201d-4390-b4d3-6de7716152e1', patch_wallet: Models::Components::PatchWallet.new(
  name: 'My second wallet',
  description: 'My new description',
  metadata: {
    'optional' => 'metadata',
  }
))

UpdateWalletResponse res = sdk.wallets().update()
        .walletID("9f1c6e07-aae8-40e6-b290-502bb1bc486e")
        .accountID("e4aad2fb-201d-4390-b4d3-6de7716152e1")
        .patchWallet(PatchWallet.builder()
            .name("My second wallet")
            .description("My new description")
            .metadata(Map.ofEntries(
                Map.entry("optional", "metadata")))
            .build())
        .call();

var res = await sdk.Wallets.UpdateAsync(
    walletID: "9f1c6e07-aae8-40e6-b290-502bb1bc486e",
    accountID: "e4aad2fb-201d-4390-b4d3-6de7716152e1",
    body: new PatchWallet() {
        Name = "My second wallet",
        Description = "My new description",
        Metadata = new Dictionary<string, string>() {
            { "optional", "metadata" },
        },
    }
);

$patchWallet = new Components\PatchWallet(
    name: 'My second wallet',
    description: 'My new description',
    metadata: [
        'optional' => 'metadata',
    ],
);

$response = $sdk->wallets->update(
    walletID: '9f1c6e07-aae8-40e6-b290-502bb1bc486e',
    accountID: 'e4aad2fb-201d-4390-b4d3-6de7716152e1',
    patchWallet: $patchWallet

);

To close a general wallet, send "status": "closed". Closing is permanent and also disables the wallet's payment method. A wallet can be closed only when:

It has no pending inbound transfers
Its balance is zero and it's had no activity in the past 75 days
It's a general wallet; default wallets can't be closed

Past transactions are kept. A closed wallet can still take exceptions such as disputes, refunds, or ACH returns, which can leave it negative, so resolve any negative balance promptly.

In the Dashboard

Navigate to the Balances section of the Dashboard to manage your wallets and view your available balance. Select a wallet from the list to view all wallet transactions. Each account has a default wallet and can have additional general wallets, each with its own balance and transaction history. See wallet types for details.

Wallet transaction list view in Moov Dashboard

Create a wallet

On the main balances view, click Create wallet. Give the wallet a name and description. If you enable automated payouts (sweeps), you'll also be able to:

Select or add a bank account
Choose a processing speed
Set a minimum balance (optional)
Set a custom statement descriptor (optional)

Create a wallet in Moov Dashboard

Edit a wallet

Select any general wallet and click Edit wallet. In addition to updating the name and description of the wallet, you can enable automated payouts.

Close a wallet

Check the rules for closing a wallet first. Open the wallet's menu and select Close wallet.

Automated payouts

A sweep automatically initiates daily transfers to external bank accounts on a set schedule. Enabling sweeps will either pay out funds from a wallet or pull funds to cover fees and chargebacks. You can configure sweeps from multiple places in the Dashboard, such as editing a wallet or navigating to an account's settings page.

Once you've enabled sweeps, you'll see the menu option to view automated payouts directly below the wallet balance. Expanding the menu will show you:

Upcoming payouts
Payout transactions
Associated bank account

A sweep's daily Accrued amount is what typically can be expected to transfer to the associated bank account. However, when a sweep is first enabled, or a minimum balance is first set, Moov calculates the Transfer amount from the wallet's available balance in order to maintain the balance in the configuration:

transferAmount = availableBalance at sweep close - minimumBalance

See the sweeps guide for information about reconciliation, negative sweeps, and failures.

Transactions in the Dashboard

The transaction list overview will show you the date, type, memo, amount, and remaining wallet balance for each transaction.

Click on an individual transaction to see more detail, such as the transaction source, destination, and ID. Click See details in the transaction source section to enter the Transfers section of the Dashboard, where you can view all the details associated with the transfer.

By default, the list shows all transactions, but you can quickly filter for just completed or pending transactions. You can also use the search bar to search by source or sweep ID. Additional filters can be accessed by clicking on the Filter menu. You can filter by one or multiple transaction types, as well as specify date ranges.

Was this helpful?