Symptom
Payout or transfer execution returns FAILED, or status polling shows failure with wallet-related messages.
Cause
Payouts debit your Dollr wallet (see wallet_id on payout session response). If the wallet balance is too low for the payout amount plus fees, execution fails.
Fix
- Check wallet balance in merchant.heydollr.app → Wallets or Balances
- Ensure collected funds have settled into the wallet you are debiting
- Retry with a new payout session and a new
reference_id only after confirming the prior attempt did not land (poll status first)
Prevention
- Preview fees with Predictions before payout
- Use
fee_bearer awareness — payouts may include gateway fees
- For large payouts, test with a small amount first
Payout session note
You send payout_account_id, amount, and currency on session create. Dollr selects the debiting wallet and returns wallet_id in the response — you do not pass wallet_id on create.
Last modified on June 23, 2026
