# Payouts: the 7-day hold and withdrawing to your bank

> Live payments clear after a 7-day hold, moving from pending to available balance so you can withdraw to your bank account without payout fees.

**Live payments stay in a pending hold for 7 days before moving to your available balance for withdrawal to your bank.** This hold protects against early chargebacks and refunds while allowing you to charge cards immediately on day one without waiting for merchant underwriting. After the hold period ends, your funds become available in your project balance, ready to withdraw directly to your bank account whenever you choose.

Because thelastapi acts as the merchant on record, you can [take payments online without opening a merchant account](https://thelastapi.dev/blog/take-payments-without-merchant-account). Here is how the 7-day hold period works, how fees and refunds affect your ledger balance, and how to verify your identity to withdraw funds to your bank.

## How the 7-day payout hold works

When a customer buys a subscription or one-off product through your checkout, the card charge processes instantly. However, the money does not immediately land in your bank or in your withdrawable balance. Instead, the net amount enters your project ledger as `pending`.

```text
 buyer ──card──▶ thelastapi (merchant, statement "VIBIZ, INC* <APP>")
                    │
                    ▼
       project balance   pending ── 7 days ──▶ available
                    │
                    │  owner: Get paid (identity + bank, once), then Withdraw
                    ▼
               the owner's bank
```

Here is the exact lifecycle of those funds:

1. **Transaction cleared:** The buyer completes checkout on your hosted payment page. The payment processor charges their card and deducts card processing fees.
2. **Pending status:** The net revenue enters your project balance under `pending`.
3. **The 7-day hold:** The money sits in `pending` for exactly 7 days (`fees.hold_days: 7`). You can check `balance.next_available_at` in the API to see the timestamp when your next batch of pending funds unlocks.
4. **Available balance:** Exactly 7 days after the charge, the funds transfer from `pending` to `available`.
5. **Withdrawal:** The account owner triggers a withdrawal, sending available funds to their connected bank account.

In test mode (`env=development`), there is no hold period. Charges clear instantly so you can test fulfillment logic and app balances right away. You can read more about ledger movement in the guide to [how money moves](https://thelastapi.dev/docs/guides/payments).

## Fees, refunds, and your balance during the hold

Every card transaction carries standard processing fees. These are deducted at the moment of payment, meaning the amount entering your pending balance is already net of standard card charges.

| Transaction type | Cost / Fee | Impact on balance |
| --- | --- | --- |
| Card processing | 2.9% + 30¢ (most US cards) | Deducted immediately; remaining net amount enters pending balance |
| thelastapi fee | Set by platform (`fees.platform_bps`) | Deducted from payment |
| Withdrawal | No thelastapi fee | Reduces available balance by the withdrawn amount |
| Refund | Refunded amount | Deducted from balance; processor and platform fees are not returned |
| Dispute | Disputed amount + $15 dispute fee | Deducted from balance immediately; $15 fee returned if won |

You can check current fee settings for any project using the API:

```bash
curl https://thelastapi.dev/v1/projects/prj_123/payments?env=production \
  -H "Authorization: Bearer $VIBIZ_API_KEY"
```

The response includes the current fee breakdown and a worked example:

```json
"fees": {
  "platform_bps": 200,
  "own_account_bps": 200,
  "card_fee_bps": 290,
  "card_fee_fixed_cents": 30,
  "dispute_fee_cents": 1500,
  "hold_days": 7,
  "example": {
    "amount_cents": 10000,
    "card_fee_cents": 320,
    "platform_fee_cents": 200,
    "net_cents": 9480
  }
}
```

If a customer asks for a refund while a payment is still within its 7-day hold, the refund is deducted from your total balance (available plus pending). A project's first sale can always be refunded in full. If excessive refunds or disputes cause your balance to drop below zero, you will receive an `insufficient_balance` or `negative_balance` error, and withdrawals remain blocked until new sales return the balance to positive.

## How to complete the one-time bank verification

Before you can withdraw cleared funds, you must complete the identity verification step called **Get paid**. This is done once per project by the account owner.

### Step 1: Open verification in the console

Log into the console, navigate to your project, click **Payments**, and select **Get paid**. This opens an embedded verification form. thelastapi never sees or stores your government ID number or raw bank routing and account numbers; they are handled securely by our banking compliance partner.

### Step 2: Check payout readiness

Supported payout countries currently include the United States, Canada, the United Kingdom, Switzerland, and member countries of the European Economic Area (EEA).

During verification, `payouts.status` tracks your progress:
- `not_started`: No details have been submitted.
- `needs_info`: Verification is incomplete, or additional documents are required. The field `payouts.requirements` lists missing items in plain words.
- `verifying`: Information has been submitted and is undergoing review.
- `ready`: Bank details and identity are confirmed. You are ready to withdraw.

## How to withdraw your available balance

Once `payouts.status` is `ready` and your payments have cleared the 7-day hold, you can withdraw your funds at any time.

### Withdrawing via the console

In the console, go to **Payments** and click **Withdraw**. By default, this initiates a transfer for your entire available balance.

### Withdrawing via the CLI

If you use a full-access key, you can request a withdrawal directly from your terminal:

```bash
# Withdraw your entire available balance
vibiz payments withdraw

# Or withdraw a specific amount in cents ($50.00)
vibiz payments withdraw --amount 5000
```

The CLI shows the amount to be withdrawn and asks for confirmation. Once submitted, the withdrawal progresses through three states:
1. `pending`: The withdrawal request has been received.
2. `in_transit`: The transfer has been dispatched to the banking network.
3. `paid`: The funds have been delivered to your bank. If an issue occurs (such as an incorrect routing number), the status changes to `failed` with a descriptive `failure_message`.

When payouts dispatch and land, the system sends webhook notifications. You can configure your endpoint to listen for `withdrawal.paid` and `withdrawal.failed` events, as detailed in our guide on [webhooks](https://thelastapi.dev/docs/guides/webhooks).

Note that AI agents and team members using Limited API keys cannot withdraw funds or issue refunds in production. Attempting to withdraw with a Limited key returns `403 Forbidden` with `reason: owner_only`.

## Common payout errors and how to handle them

When requesting a withdrawal via API or CLI, you might encounter specific error responses:

| Error response | Reason | Solution |
| --- | --- | --- |
| `409 Conflict` | `payouts_not_ready` | The project owner must complete the **Get paid** flow in the console. |
| `409 Conflict` | `nothing_available` | Funds are still in the 7-day hold period. Wait until `balance.next_available_at`. |
| `409 Conflict` | `negative_balance` | Past refunds or chargebacks exceed earnings. Earn back the balance with new sales. |
| `409 Conflict` | `withdrawal_in_progress` | Another withdrawal transfer is currently processing. Wait a few moments. |
| `403 Forbidden` | `owner_only` | A Limited key was used. Production withdrawals require the owner or a full-access key. |

## Testing holds and withdrawals in development

You do not need to wait 7 days to test your billing and ledger logic. In development, the 7-day hold is omitted, allowing you to simulate every stage of the payment lifecycle.

```bash
# 1. Simulate a successful customer payment
vibiz payments simulate payment --amount 2500 --dev

# 2. Release any simulated hold immediately
vibiz payments simulate release_hold --dev

# 3. Simulate a withdrawal with mock bank details
vibiz payments withdraw --amount 2000 --dev
```

When walking through the development verification flow, use standard test values: date of birth `1901-01-01`, SSN last four `0000`, routing number `110000000`, and account number `000123456789`. No real money will move, but your project ledger and webhooks will behave exactly as they do in production.

Now that you understand the payout schedule, you can [put your brand on the checkout page](https://thelastapi.dev/blog/brand-your-checkout-page) or explore how to [add a subscription checkout to a SaaS](https://thelastapi.dev/blog/subscription-checkout-saas). For full API route parameters, review the complete [Payments documentation](https://thelastapi.dev/docs/payments).

## Frequently asked questions

### Why is there a 7-day hold on live payments?

The 7-day hold protects against early chargebacks, payment disputes, and immediate customer refunds while allowing your business to accept card payments instantly without waiting weeks for traditional merchant account underwriting.

### Can an AI agent or Limited API key initiate a bank withdrawal?

No. In production, withdrawals, refunds, and plan cancellations are strictly restricted to the account owner or full-access API keys, returning a `403 owner_only` error if attempted by a Limited key.

### Does thelastapi charge a fee when I withdraw money to my bank?

No, thelastapi does not charge any withdrawal fee when sending available project funds to your bank account.

### Which countries are supported for bank payouts?

Bank payouts are currently available for business owners with bank accounts located in the United States, Canada, the United Kingdom, Switzerland, and member nations of the European Economic Area (EEA).

---

Published 2026-11-15 · https://thelastapi.dev/blog/payouts-hold-withdraw
