---
name: vibiz-payments
description: Sell with thelastapi payments - take money with no identity check and no Stripe account (thelastapi is the merchant; KYC only when the owner withdraws) or through the owner's own Stripe account, sell in iOS and Android apps (App Store and Google Play in-app purchases through the owner's own RevenueCat account, no thelastapi fee), create a plan, add a checkout or Upgrade button, wire and verify payment webhooks, check subscriptions, and answer questions about fees (2% thelastapi fee plus card processing), the 7-day hold, refunds and withdrawing. Use when a thelastapi project (a vibiz.json in the folder, or the vibiz MCP tools) needs to take money or someone asks what a payment leaves them.
---

# thelastapi payments

**Connect first.** Not logged in (a tool answers `unauthorized` with `reason: not_logged_in`, or the CLI says "Not logged in")? Run `npx @vibiz/cli login`: show the person the link it prints and ask them to click Authorize (their account is opened on the way if they have none), then go on. Or connect the remote MCP server, nothing to install: `claude mcp add --transport http vibiz https://thelastapi.dev/mcp` (the client opens the same sign-in on first use). Never ask the person to paste a key into the chat. **Keep the CLI current:** a command named here that your `vibiz` doesn't have (an unknown-command or usage error) means the CLI is out of date, not that thelastapi can't do it: run `npm install -g @vibiz/cli@latest` (or `npx -y @vibiz/cli@latest <command>`) and retry, and refresh these skills with `vibiz skills add --global`. Never tell the person something isn't possible because an old CLI lacks the command.

Two ways to take money; say which one applies before anything else:

1. **Through thelastapi (the default, nothing to set up).** thelastapi is the merchant: a project sells from its first call, in test mode (`development`) and live (`production`), with **no identity check (KYC) and no Stripe account of the owner's**. Sales land in the project's thelastapi balance. Identity and a bank are asked for only when the **owner withdraws** (once, console ▸ Payments ▸ Get paid).
2. **The owner's own Stripe account (optional).** The owner connects it themselves (Stripe's own sign-in, from a link you give them; only the account owner can, in the console). New sales are then charged on their account and paid out by it directly: no thelastapi balance, no hold, no Withdraw.

## Before you start

- The project id is in `./vibiz.json` (`project_id`). Don't ask the user for it.
- Tools: the `vibiz` MCP server (`vibiz_payments`, `vibiz_docs`, `vibiz_dev_env`). Without it, the CLI (`vibiz payments …`) or HTTP (`https://thelastapi.dev/v1/projects/<id>/payments/…`, `Authorization: Bearer $VIBIZ_API_KEY`).
- Work in `development` first. Catalogs are separate per environment: create the product again with `env: production` to sell it live.

## Sell a plan

1. Create the product and price in development:
   `vibiz_payments { action: "create_product", project_id, env: "development", name: "Pro", price: { unit_amount_cents: 1500, type: "recurring", interval: "month", lookup_key: "pro-monthly" } }`
2. Write the Upgrade action on the server with `@vibiz/app` (`vibiz.payments.checkout({ lookup_key, user, success_url, cancel_url })` then redirect). Install it with `npm install @vibiz/app`; a project that can't add a dependency calls `POST /v1/app/payments/checkout` with `fetch` and `VIBIZ_APP_KEY`. See `references/guide-app-payments.md`.
3. Create a checkout on every click. Never hard-code a checkout URL: each is for one buyer and expires after 1 hour.
4. Gate features with `vibiz.payments.hasActive(userId, 'pro-monthly')` (or `GET /v1/app/payments/subscriptions?user=`). A "Manage billing" button: `const { url } = await vibiz.payments.portal(userId, { return_url })`.
5. Webhooks: set the URL (`vibiz_payments { action: "webhook", webhook_url }`, development) and verify in the route with `const event = await vibiz.webhooks.receive(req)`: it reads the raw body and checks the signature with only `VIBIZ_APP_KEY` (it fetches the signing secret itself). Never ask the person to add `VIBIZ_WEBHOOK_SECRET` to a host: the app key is the one key. Dedupe on `event.id`. See `references/guide-webhooks.md`.
6. Test: `vibiz_payments { action: "simulate", simulate: "payment" }` (development), then `vibiz_payments { action: "deliveries" }` to see the webhook's status code.
7. Going live: create the same product with `env: "production"`. The live webhook defaults to the app's real site: `https://<slug>.vibiz.app/api/vibiz/webhook` when it's deployed on thelastapi, or `https://<its domain>/api/vibiz/webhook` when it runs on another host and that domain is on the project (`vibiz domains add <domain> --elsewhere`). The secret is in the app's env, so the app's route must be `/api/vibiz/webhook`. **Always check** `webhook.url` (`vibiz_payments { action: "get", env: "production" }`) against where the app is actually live (ask the person if you don't know). To point it elsewhere on the app's own site, a Limited key may set a live URL on the project's `<slug>.vibiz.app` address or one of its domains, over HTTP: `PATCH /v1/projects/<id>/payments?env=production { "webhook_url": "https://<domain>/api/vibiz/webhook" }` (the `vibiz_payments webhook` tool and `vibiz payments webhook` from a Limited key change development only); any other URL, the events filter and the statement suffix are the owner's (console ▸ Payments ▸ Webhooks).

**A site that sells through its own checkout** (not thelastapi payments): Mission Control's Payments check looks for it in the priced page, the site's own scripts and the pages its plan cards link to. Also send `vibiz('event', 'Checkout Redirect')` when a buyer is sent to pay and `vibiz('event', 'Checkout Error')` when it breaks: the check reads them (7 days), says Failing after 3 errors with none through, and warns when the site shows a price with no checkout it can find.

## iOS and Android apps (App Store and Google Play)

In-app purchases in an iOS or Android app go through **the owner's own RevenueCat account**, wrapped behind the same key: no receipt code to write, and Apple or Google pay the owner directly (**no thelastapi fee** on store purchases). Never call their account's API by hand and never ask for the owner's RevenueCat key in the chat.

1. **Connect once (the owner).** `vibiz_payments { action: "app_store_status" }`. Not connected: `vibiz_payments { action: "connect_app_store" }` (or `vibiz payments app-store connect`) → give the owner the `url`. They paste a V2 secret key from their RevenueCat dashboard ▸ Project settings ▸ API keys (read & write on Project configuration, read on Customer information). You can't complete it.
2. **Plans** are this project's products with prices that have a `lookup_key` (Sell a plan, step 1), in each environment.
3. **Set up** (one RevenueCat project per app: it has one current offering; setup refuses a shared one with `store_project_in_use`). Read the bundle id from `app.json` (`expo.ios.bundleIdentifier`, `expo.android.package`) or the Xcode target, then `vibiz_payments { action: "app_store_setup", project_id, env: "development", ios_bundle_id: "com.acme.bakery" }` (`vibiz payments app-store setup --ios com.acme.bakery --dev`), and again with `env: "production"`. It creates the app in their RevenueCat account, a product per price, one entitlement per plan (`Pro` → `pro`), a default offering, the webhook, and answers `ios.public_key` (also `VIBIZ_REVENUECAT_IOS_KEY` in the app's env) and `next`. Re-run it after changing prices; it never duplicates.
4. **Tell the owner `next`**, word for word: create the products with exactly the returned ids in App Store Connect (`com.acme.bakery.pro_monthly`) and Play Console, upload the store credentials in their RevenueCat dashboard, and add the webhook there if it wasn't registered. Purchases are read live until then.
5. **The app.** Expo/React Native: `npx expo install react-native-purchases` (a development build, not Expo Go); Swift: the RevenueCat SDK (`purchases-ios-spm`). Configure it with the public key (in Expo as `EXPO_PUBLIC_REVENUECAT_IOS_KEY`; it is safe to ship) and **`Purchases.logIn(userId)` with the same user id the app passes to `vibiz.payments.checkout`**, then sell `offerings.current` packages.
6. **Gate on the server**: `await vibiz.payments.hasActive(userId, 'pro')` answers for web checkout and the stores alike. Pass the entitlement key (`pro`): it is matched first, and a string that is an entitlement key matches only as one; otherwise a lookup key, price id or store product id. `vibiz.payments.entitlements(userId)` lists what they have with `source` (`web`, `app_store`, `play_store`). Store subscriptions show in `subscriptions` with their `source`; only the buyer cancels them, in the store (`409 store_subscription` here). The app's webhook gets `subscription.*` events for them too.
7. **Test** with an App Store sandbox tester: sandbox purchases land in `development`.

See `references/guide-app-store.md` and `references/app-store.md`.

## Your brand on the checkout

The checkout page should look like the business. Set the project's brand once per environment, from the business's own site (its name, logo URL and main color; `vibiz_web_design` reads them):
`vibiz_payments { action: "brand", project_id, env: "production", brand: { name: "Bakery Labs", logo_url: "https://bakery.com/logo.png", button_color: "#1a73e8" } }` (over HTTP: `PATCH /v1/projects/<id>/payments { "brand": { … } }`).
A checkout can override any field: `vibiz.payments.checkout({ …, brand: { button_color: "#000000" } })`. Through thelastapi the page always shows the project's name, never thelastapi, on a white page with a dark button until a brand is set; on the owner's own Stripe account their dashboard's branding applies unless a brand is set. Fields: `name`, `logo_url`, `icon_url` (https), `background_color`, `button_color` (hex), `font` (`inter`, `roboto`…), `border_style` (`pill`, `rounded`, `rectangular`); `brand: null` clears it.
- `logo_url` and `icon_url` must open the image itself: a direct https link to a PNG or JPG (`https://site.com/logo.png`), not a page or an avatar URL with `?size=`. A wide logo replaces the name at the top; without one, the name shows.

## Currencies

Prices and ad-hoc checkouts take `currency` (`usd` by default): usd, eur, gbp, cad, aud, nzd, chf, sek, nok, dkk, pln, czk, huf, ron, bgn, mxn, brl, cop, clp, pen, ars, jpy, krw, inr, sgd, hkd, twd, thb, myr, php, idr, zar, aed, ils, try, mad.
- Amounts are in the currency's **smallest unit**: `1400` with `eur` is €14.00; jpy, krw and clp are whole units (`1500` with `jpy` is ¥1,500). Each has a minimum (50 for usd/eur, 30 for gbp, ¥50): the error says it.
- A price sells in its own currency; make one price per currency (`lookup_key: "pro-monthly-eur"`). One buyer can't subscribe in two currencies.
- Through thelastapi the **balance stays in USD**: a sale is added at what the processor converted it for that day, minus its conversion fee (about 1–2%). The payment shows `amount_cents` + `currency` and `settled_usd_cents`; `fee_cents` and `net_cents` are USD. Don't quote a fixed exchange rate.

## The owner's own Stripe account (when to send the link)

Payments through thelastapi are the default and need nothing from the owner. Offer the alternative only when the owner says they already have a Stripe account, want sales paid out by their own Stripe, or ask why money is held by thelastapi:

1. `vibiz_payments { action: "connect_own_account", project_id, env: "production" }` (or `vibiz payments connect`) → `url`.
2. Give the owner that `url`. They open it signed in to the console and choose: connect their Stripe account, or keep payments through thelastapi. Only they can complete it (or disconnect it later); don't retry or try to finish it yourself.
3. `vibiz_payments get` → `account.mode` is `own` once they have. New sales are then charged on their Stripe account and paid out by it on its own schedule (no hold, no Withdraw for them); thelastapi keeps `fees.own_account_bps` on each sale (2% by default); money already in the thelastapi balance stays to withdraw, and subscriptions sold through thelastapi keep billing through thelastapi. The app's code doesn't change.

**Once for every project.** If the owner has several projects (or will make more), offer the account-level link instead: `vibiz_payments { action: "connect_account_own", env: "production" }` (or `vibiz payments account connect`). They connect their Stripe once in console ▸ Settings ▸ Payments, turn on **Use for every project** (every new project starts on it) and press **Apply to all projects** (existing ones switch for new sales; the console lists them first, and frozen, opted-out or projects on another Stripe account are skipped with why). `vibiz_payments { action: "account_own_status" }` shows each environment and each project; a project on it has `account.own.source: "account"`. A project can still opt out in its own Payments or use a different Stripe account. Balances already in thelastapi stay to withdraw and subscriptions sold through thelastapi keep billing through thelastapi. If the owner disconnects it in Settings, the projects that used it go back to payments through thelastapi for new sales (each project's Payments says so). Toggling, applying in production and disconnecting are the owner's: you hand out the link and read the status.

The link lasts 24 hours and only the signed-in account owner can use it (anyone else gets `owner_only`). `account.own.available: false`, or `provider_unavailable` with `reason: own_account_unavailable`, means it isn't offered right now: keep payments through thelastapi. Disconnecting is the owner's too (console ▸ Payments, or `vibiz payments disconnect` with a full-access key).

## Facts to repeat exactly

`vibiz_payments get` → `fees` is the source of truth (the fee is set per account, and an admin can change it, for projects on their own Stripe account too): read it and quote `fees.example` rather than these defaults:

- Card processing 2.9% + 30¢ (most US cards; `card_fee_bps: 290`, `card_fee_fixed_cents: 30`).
- thelastapi fee: **2%** of each payment by default (`platform_bps: 200`; on the owner's own Stripe account `own_account_bps`, also 200 by default).
- **$100 → $3.20 processing + $2.00 thelastapi fee → $94.80** to the balance (`fees.example`: `card_fee_cents: 320`, `platform_fee_cents: 200`, `net_cents: 9480`).
- Live payments are pending **7 days** (`hold_days`), then available; `balance.next_available_at` says when. Test mode has no hold.
- Refunds don't return the processing fee or the thelastapi fee. A dispute takes the amount plus $15 (`dispute_fee_cents: 1500`), returned if it is won.
- Withdrawing: the **owner**, once, verifies identity and adds a bank (console ▸ Payments ▸ Get paid), then Withdraw. Don't promise when it reaches the bank: `estimated_arrival` shows it once scheduled.
- With the owner's own Stripe account connected (`account.mode: "own"`), none of the hold or withdrawing applies to new sales: their Stripe pays them out.

## Never

- Never take, ask for or pass a card number. Send a checkout link.
- Never retry an `owner_only` error with the same key. Tell the user `details.next_step` (live refunds, cancels, withdrawals, webhook and statement settings need full access, and this key was set to Limited): it links where to do it and `key_url`, where the owner can give the key full access.
- Never put `VIBIZ_APP_KEY` or `VIBIZ_WEBHOOK_SECRET` in client code or `NEXT_PUBLIC_` variables, and never print them.

**Console links**: payments, subscriptions and the payments account come back with `console_url`, the page in the web console (with `env` and the item open). When the owner has to act (refund, withdraw, webhooks), give them that link. `vibiz_docs console-urls` lists every page and its parameters.

## Not hosted on thelastapi?

Payments need no resource and no hosting: `vibiz init <name> --resources none`, and the app on its own host calls `vibiz.payments.checkout` with its one key (`VIBIZ_APP_KEY`); `success_url` and `cancel_url` are any `https` page on their site. Add the site's domain (`vibiz domains add shop.example.com --elsewhere`); once it is trusted (its TXT record verified, or the owner confirmed it), the live webhook defaults to `https://shop.example.com/api/vibiz/webhook`, and one left on the unused `<slug>.vibiz.app` address moves there by itself. Check `webhook.url` and set it as in step 7 if needed. The route verifies with `vibiz.webhooks.receive(req)` and only `VIBIZ_APP_KEY`. On a host outside thelastapi the app needs only `VIBIZ_APP_KEY`: tell the owner the one-key sentence with the exact link (`app_key_console_url` from `vibiz_project_env`; the vibiz skill, "One key = everything"). The vibiz-use-one skill has every step.

## Limits: tell the owner up front

- **The caps and their defaults** (`vibiz_usage` → `limits` shows this account's): daily spend $5 per account (AI, web data and other actions, texts, calls; up to $1,000), project AI budget $1 per project per day, projects per plan (Free 2, Pro 10), 30 builds per project per day, 50 app emails per project per day, 200 texts and 50 calls per project per day, and no marketing email from agents until the owner allows a monthly number. Daily caps reset at 00:00 UTC.
- **The owner raises or lowers them:** daily spend in the console ▸ Billing ▸ Daily safety cap, or `PATCH /v1/billing {"daily_spend_limit_usd": 50}`; a project's AI budget in the project ▸ AI ▸ Daily AI budget, or `PATCH /v1/projects/<id>/ai {"daily_budget_usd": 10}` (`null`: no project budget); agents' email in the project ▸ Email ▸ Settings, or `PATCH /v1/billing {"agent_email_limit_per_month": 5000}`. Projects, builds, app email, texts and calls: delete what's unused, wait for the reset, or write to support@vibiz.ai.
- **thelastapi tells the owner:** one email at 80 % and one at 100 % of each cap (once per day, or month), and a banner on Overview and Usage, each with a link that opens the setting. `vibiz_usage` → `limits.alerts` lists caps at 80 % or more. A refusal carries `details.reason`, `raise_url` and `next_step`: give the owner the `raise_url`; retrying won't help.
- **When you build an app that uses AI or another capped product:** tell the owner the cap it runs under and what you expect it to cost a day, set the project AI budget to fit the expected traffic, and if the app adds a cap of its own keep it under the platform's and make it tell the owner when it's hit. Never let an app stop silently.

## References

- `references/payments.md`: the product page (pricing, limits, errors, what agents can do).
- `references/guide-payments.md`, `references/guide-app-payments.md`, `references/guide-webhooks.md`: the agent guides (`vibiz_docs`).
- `references/app-store.md`, `references/guide-app-store.md`: iOS and Android in-app purchases through the owner's own RevenueCat account.
- `references/errors.md`: every error code.
