Guides API reference Use cases Changelog

Sweeps

A sweep moves a wallet's accrued balance to a bank account once a day, and pulls from a bank account when the wallet goes negative. Use sweeps to settle merchants automatically instead of creating cash-out transfers yourself.

Before you start

Configure a sweep

Create or edit a wallet and turn on automated payouts. See automated payouts.

Set the payout payment method in pushPaymentMethodID: ach-credit-same-day, ach-credit-standard, instant-bank-credit, or rtp-credit. Use instant-bank-credit rather than rtp-credit, which will be deprecated.

If a same-day ACH sweep exceeds $500,000 or an instant sweep exceeds $1,000,000, Moov sends it with standard ACH instead. Sweep transfers are charged according to the account's fee plan.

To remediate negative balances, you must configure an ach-debit-fund for the pullPaymentMethodID. Bank accounts used for push (payouts) and pull (debits) sweeps can be different.

If a payment method becomes disabled due to a bank account issue, payouts are paused until a new bank account is verified and configured in the sweep.

Keep a minimum balance

Optionally, you can specify a minimum daily wallet balance to support ongoing operations or protect against refunds, disputes, and fees. If set, Moov ensures this balance is maintained when calculating sweep amounts. If not set, the default maintained balance is $0.

Default statement descriptor

By default, Moov uses the companyName from your account’s ACH settings for sweep transfers. You may customize the ACH statement descriptor in the sweep configuration. The default descriptor is a 10 character ID, that is also available on each sweep for reconciliation (swp_xxxxxx).

Payout timing

Funds accrue into the open sweep as you process payments. Each sweep closes at 4:00 PM ET on banking days; Moov then creates the payout transfer and opens a new sweep. Sweeps don't close on weekends or bank holidays, so that activity pays out the next banking day. To use a different close time, contact Moov.

Card payment funds are typically credited to the Moov wallet by 1:00 PM ET the next banking day following the card payment. You can refer to card brand timetables for details on specific brand cut-off times to know what is included in the next day funding. ACH processing speeds can vary, but funds are generally available the morning of the second banking day after the transfer is created.

After a sweep closes at 4:00 PM ET, the bank account receives the payout by:

pushPaymentMethodID type Bank account receives funds by
instant-bank-credit Within seconds of the sweep closing (RTP or FedNow)
rtp-credit Within seconds of the sweep closing
ach-credit-same-day 6:00 PM ET the same day
ach-credit-standard 10:00 AM ET the next banking day

Reconciliation

The accruedAmount represents the amount typically expected to transfer for a sweep period. In certain cases, such as when a sweep is first enabled or when a minimum balance is newly applied, the transferred amount may differ. In those one-off cases, Moov calculates the amount to transfer accordingly:

transferAmount = availableBalance at sweep close - minimumBalance

The get sweep and list sweeps endpoints include subtotals grouped by transactionType. These breakdowns help you:

  • Reconcile sweep activity
  • Track payout sources
  • Report totals such as sales, fees, and refunds to end users

A sweepID is assigned to all debit or credit sweep transactions in a Moov wallet and can be used to access all sweep activity. For detailed reporting and reconciliation of sweeps, we recommend supplying the sweepID as a query parameter with the list wallet transactions GET endpoint. Using the returned list, you can match the amount received in the bank account with the corresponding transactions.

  "subtotals": [
    {
      "amount": {
        "currency": "USD",
        "valueDecimal": "50.00"
      },
      "count": 1,
      "type": "moov-fee"
    },
    {
      "amount": {
        "currency": "USD",
        "valueDecimal": "50.00"
      },
      "count": 1,
      "type": "account-funding"
    }
  ],

Negative sweeps

In some cases, you can accrue a negative balance. For example, if you receive $100, but also receive a refund request for a previous payment of $200, the wallet balance would be -$100. Moov allows for a one-day grace period to account for any incoming payments. If the balance remains negative, a debit is initiated the following day.

Negative sweeps are not initiated for amounts less than $1. There is a two-day hold on ACH debit transactions, so payouts will only resume once the debit transfer completes.

Handle failed sweeps

When a payout can’t be completed, Moov sends a sweep.updated webhook event with a status of failed and the transferID of the failed payout.

The transfer's failureReason indicates the reason for the failure and may also disable the associated bank account. A bank account becoming disabled will trigger a bankAccount.updated webhook event.

Failed sweeps aren’t automatically retried and no payouts will be made until a new bank account is added and verified.

While awaiting a resolution, the sweep continues accruing with a status of action-required. Once a valid payment method is configured, payouts resume on the normal sweep schedule.