# Fund and spend from a wallet

> Check a Moov wallet balance, fund it with an ACH debit from a verified bank account, pay out from the wallet, and automate it with sweeps.

> AI agents: search and read all Moov docs with the docs MCP server at https://docs.moov.io/mcp (no API key). Setup: https://docs.moov.io/guides/developer-tools/mcp-ai/docs-mcp/index.md

Load money into a Moov wallet from a bank account, spend it on payouts, and let sweeps keep the balance where you want it.

A Moov wallet holds funds inside Moov. Card and ACH payments settle into a wallet, and payouts are paid from one. In this recipe, a business account (your partner account, or a connected business you manage) checks its wallet, funds it with an ACH debit from its own bank account, pays a recipient from the wallet, and then sets up a sweep so payouts and top-ups happen automatically.

## Prerequisites

- Everything in [Before you start](/guides/get-started/recipes/index.md#before-you-start): test mode API keys, authentication headers, your partner account ID, and a webhook endpoint
- A business account with `wallet.balance` and `send-funds.ach` enabled. Add `send-funds.instant-bank` to pay out with instant payments (RTP or FedNow).
- A recipient with a linked bank account for step 5. The [bank payout recipe](/guides/get-started/recipes/bank-payout/index.md) shows how to set one up.

## Steps

### Find the wallet and check its balance

Accounts with `wallet.balance` enabled get a default wallet. List the account's wallets with the list wallets [endpoint](/api/sources/wallets/list/index.md):

```zsh
curl -X GET "https://api.moov.io/accounts/{accountID}/wallets" \
  -H "Authorization: Bearer {token}" \
  -H "X-Moov-Version: v2026.07.00"
```

Each wallet in the response has a `walletID`, a `walletType` (`default` or `general`), a `status`, and an `availableBalance` with `value` in cents. Only the available balance can be spent; funds from pending ACH debits and card payments don't count until they settle. To get one wallet, use the get wallet [endpoint](/api/sources/wallets/get/index.md). To keep funds for different purposes apart, create more wallets; see [multiple wallets](/guides/wallets/multiple-wallets/index.md). Deeper guide: [wallet balance](/guides/wallets/balance/index.md).

### Link and verify the funding bank account

ACH debits need a verified bank account. Link the business's bank account with the link bank account [endpoint](/api/sources/bank-accounts/create/index.md), then verify it.

```zsh
curl -X POST "https://api.moov.io/accounts/{accountID}/bank-accounts" \
  -H "Authorization: Bearer {token}" \
  -H "X-Moov-Version: v2026.07.00" \
  -d '{
    "account": {
      "holderName": "Whole Body Fitness LLC",
      "holderType": "business",
      "accountNumber": "12345654321",
      "bankAccountType": "checking",
      "routingNumber": "322271627"
    }
  }'
```

Start instant micro-deposit verification with `POST /accounts/{accountID}/bank-accounts/{bankAccountID}/verify`, then submit the code with `PUT` on the same path (`{"code": "0001"}` in test mode). Until the bank account's `status` is `verified`, it has no `ach-debit-fund` payment method. Deeper guide: [bank account verification](/guides/sources/bank-accounts/verification/index.md).

### Get the funding payment methods

Funding the wallet is a transfer from the bank account's `ach-debit-fund` payment method to the wallet's `moov-wallet` payment method, both on the same account. List them with the list payment methods [endpoint](/api/sources/payment-methods/list/index.md):

```zsh
curl -X GET "https://api.moov.io/accounts/{accountID}/payment-methods" \
  -H "Authorization: Bearer {token}" \
  -H "X-Moov-Version: v2026.07.00"
```

From the response, save the `paymentMethodID` with `paymentMethodType: ach-debit-fund` (its `bankAccount.bankAccountID` matches your verified account) and the one with `paymentMethodType: moov-wallet` (its `wallet.walletID` matches the wallet from step 1). Use `ach-debit-fund` for moving your own money; `ach-debit-collect` is for collecting payments from someone else. Deeper guide: [payment methods](/guides/money-movement/payment-methods/index.md).

### Fund the wallet with an ACH debit

Create the funding transfer with the create transfer [endpoint](/api/money-movement/transfers/create/index.md):

```zsh
curl -X POST "https://api.moov.io/accounts/{partnerAccountID}/transfers" \
  -H "Authorization: Bearer {token}" \
  -H "X-Moov-Version: v2026.07.00" \
  -H "X-Idempotency-Key: 3c9d1e7f-5a2b-4c8d-9e0f-1a2b3c4d5e6f" \
  -d '{
    "source": { "paymentMethodID": "{achDebitFundPaymentMethodID}" },
    "destination": { "paymentMethodID": "{walletPaymentMethodID}" },
    "amount": { "currency": "USD", "value": 500000 },
    "description": "Wallet top-up"
  }'
```

This pulls $5,000.00 from the bank account. Moov processes ACH debits same-day when it can, but with standard processing it holds debited funds for two banking days before they're available in the wallet, to cover possible returns. Accounts approved for faster processing skip the hold. In test mode, weekday ACH transfers complete in about an hour. Deeper guides: [fund a wallet](/guides/wallets/funding/index.md) and [ACH processing speeds](/guides/money-movement/ach/ach-processing-speeds/index.md).

### Pay out from the wallet

Once the funds are available, spend them. A payout uses the wallet as the source and a recipient's bank credit payment method as the destination. Get the recipient's `ach-credit-same-day`, `ach-credit-standard`, or `instant-bank-credit` payment method ID from their list payment methods response, then create the transfer:

```zsh
curl -X POST "https://api.moov.io/accounts/{partnerAccountID}/transfers" \
  -H "Authorization: Bearer {token}" \
  -H "X-Moov-Version: v2026.07.00" \
  -H "X-Idempotency-Key: 8a7b6c5d-4e3f-4a1b-9c8d-7e6f5a4b3c2d" \
  -d '{
    "source": { "paymentMethodID": "{walletPaymentMethodID}" },
    "destination": { "paymentMethodID": "{recipientAchCreditSameDayPaymentMethodID}" },
    "amount": { "currency": "USD", "value": 125000 },
    "description": "Weekly instructor payout"
  }'
```

The wallet's available balance drops as soon as the transfer is created. If the balance is too low, the transfer fails with `failureReason: wallet-insufficient-funds`. You can also pay another Moov account's `moov-wallet` payment method; wallet-to-wallet transfers complete almost instantly. Review every movement with the list wallet transactions [endpoint](/api/sources/wallets/list-transactions/index.md). Deeper guides: [send funds](/guides/send-payments/send-funds/index.md) and [wallet transactions](/guides/wallets/transactions/index.md).

### Automate with sweeps

Instead of moving funds by hand, a sweep settles the wallet to a bank account every day. Payment and fee activity accrues during the day; at the daily close (4:00 PM ET by default), Moov pays out the positive balance above your minimum or debits the bank account to cover a negative one. Create one with the create sweep config [endpoint](/api/money-movement/sweeps/create-config/index.md):

```zsh
curl -X POST "https://api.moov.io/accounts/{accountID}/sweep-configs" \
  -H "Authorization: Bearer {token}" \
  -H "X-Moov-Version: v2026.07.00" \
  -d '{
    "walletID": "{walletID}",
    "status": "enabled",
    "pushPaymentMethodID": "{ownAchCreditSameDayPaymentMethodID}",
    "pullPaymentMethodID": "{achDebitFundPaymentMethodID}",
    "minimumBalance": "1000.00",
    "statementDescriptor": "WBF PAYOUT"
  }'
```

`pushPaymentMethodID` is a credit payment method on the account's own bank account (`ach-credit-standard`, `ach-credit-same-day`, or `instant-bank-credit`). `pullPaymentMethodID` is the `ach-debit-fund` payment method Moov uses if the wallet goes negative, for example after a refund or dispute. `minimumBalance` keeps $1,000.00 in the wallet. Deeper guide: [sweeps](/guides/wallets/sweeps/index.md).

## What to watch for

| Signal                                                                   | What it means                                                                        | What to do                                                     |
|--------------------------------------------------------------------------|--------------------------------------------------------------------------------------|----------------------------------------------------------------|
| `transfer.updated` with `source.achDetails.status` `completed`           | The ACH debit cleared                                                                | Expect `availableBalance` to update once any hold ends         |
| `transfer.updated` with `status` `failed` and `source.achDetails.return` | The funding debit was returned during clearing, for example `R01` insufficient funds | No funds were added; fix the bank account or retry later       |
| `transfer.updated` with `status` `reversed`                              | A debit was returned after funds became available                                    | Moov deducts the amount from the wallet, which can go negative |
| `balance.updated`                                                        | The wallet's balance changed                                                         | Refresh the balance you show users                             |
| `walletTransaction.updated`                                              | A wallet transaction is pending or completed                                         | Reconcile against your ledger                                  |
| `sweep.created`, `sweep.updated`                                         | A sweep period opened, or a sweep's status changed                                   | Match the sweep's transfer to your payout records              |

To test a funding failure, send an ACH debit for `5501` ($55.01, `R01`). See [ACH returns](/guides/money-movement/ach/returns/index.md) for how each return code affects the wallet and bank account.

## Next steps

- [Cash out](/guides/wallets/cash-out/index.md): Withdraw a wallet balance to a bank account or debit card on demand.
- [Issue cards](/guides/issue-cards/index.md): Spend wallet funds with virtual cards.
- [Pay out to a bank account](/guides/get-started/recipes/bank-payout/index.md): Set up a recipient and pay them by ACH or instant payments.
- [Accept a card payment](/guides/get-started/recipes/accept-card-payment/index.md): Bring money into a merchant's wallet from card payments.