thelastapi
Console
Agent guides

Payments: how money moves

Fees, the 7-day hold, who may refund or withdraw, and the agent flow for selling a plan.

Open as .md

thelastapi is the merchant. A project's app can take payments (one-time and subscriptions) from its first call, in test mode and live, with no identity check (KYC) and no Stripe account of the owner's: identity and a bank are asked for only when the owner withdraws. Alternatively the owner can connect their own Stripe account and be paid out by it directly (below). The money is the project's balance until the owner withdraws it.

Environments

Every vibiz_payments call takes env.

  • development = test mode: test cards (4242 4242 4242 4242, any future date, any CVC), no real money, no hold. Agents may do everything here, including simulate.
  • production = live. Agents may read (customer emails masked) and create products, prices and checkouts. Refunds, cancels, withdrawals and webhook/statement settings are the owner's: a Limited key gets 403 owner_only, because a Limited key never moves live money. The owner does them in the console (project ▸ Payments) or with a full-access key.

Fees

Also on vibiz_payments get → fees, which is the source of truth.

  • Card processing: 2.9% + 30¢ for most US cards, taken from each payment.
  • thelastapi fee: 2% by default, fees.platform_bps in basis points (200 = 2%; 0 = none). It is set per account (an admin can change it), so read it rather than assume it; on the owner's own Stripe account it is fees.own_account_bps (also 200 by default).
  • On $100 with the defaults: $3.20 processing + $2.00 thelastapi fee, $94.80 to the balance. fees.example has the numbers for this account.
  • Refunds don't return the processing fee or the thelastapi fee. A dispute takes the amount plus a $15 fee.

When the money can be withdrawn

Live payments are pending for fees.hold_days (7) days, then available (balance.next_available_at says when). Test mode has no hold.

Getting paid out

The owner verifies their identity and adds a bank account once (console ▸ Payments ▸ Get paid; payouts.status goes not_started → needs_info/verifying → ready). Then Withdraw (console, or vibiz payments withdraw with a full-access key) sends the available balance to the bank; the payout account pays out on its own schedule. thelastapi does not promise an arrival date: withdrawal.estimated_arrival shows one once the bank payout is scheduled. A development withdrawal only moves test money.

The owner's own Stripe account

Payments through thelastapi are the default (vibiz_payments get → account.mode: "vibiz"). Send the owner the own-account link only when it fits: they say they already have a Stripe account, or want sales paid out by their own Stripe account. Then:

  1. vibiz_payments { action: "connect_own_account", project_id, env: "production" } (or vibiz payments connect) → url.
  2. Give the owner the url. They sign in to the console, read what changes and choose: connect their Stripe account, or keep payments through thelastapi. You can't complete it, and only they can disconnect it.
  3. Afterwards get shows account.mode: "own". New sales are charged on their account and paid out by it: no hold and no Withdraw for them. thelastapi keeps fees.own_account_bps there. Money already in the thelastapi balance stays there and is withdrawn as before. The app's code (checkout, hasActive, webhooks) doesn't change.

Several projects? The owner can connect their Stripe once in Settings ▸ Payments for every project: vibiz_payments { action: "connect_account_own", env: "production" } (or vibiz payments account connect) gives the link; there they turn on Use for every project (new projects start on it) and Apply to all projects (existing ones switch, each listed first; frozen, opted-out or projects on another Stripe account are skipped). account_own_status shows where each project stands, and a project on it has account.own.source: "account". Same rules: old balances stay to withdraw, subscriptions sold through thelastapi keep billing there, and only the owner completes, applies or disconnects.

Don't push it: the default needs nothing from the owner until they withdraw. account.own.available: false means it isn't offered right now.

Never take card numbers

A buyer pays on the hosted checkout page. To charge someone, create a checkout (lookup_key/price_id, or amount_cents + name) and send them its url. Never pass a card number to a tool or an API.

Agent flow for a plan

  1. vibiz_payments create_product { name: "Pro", price: { unit_amount_cents: 1500, type: "recurring", interval: "month", lookup_key: "pro-monthly" } } with env: "development" first; the same again with env: "production" to go live: catalogs are separate per environment.
  2. The app creates checkouts with @vibiz/app (vibiz_docs app-payments).
  3. vibiz_payments simulate payment (development) runs a real test charge through the ledger and the app's webhooks.
  4. Webhooks: vibiz_payments webhook (vibiz_docs webhooks).