# Let an AI agent set up payments safely

> AI agents can create products, checkouts, and webhooks safely because live money moves, refunds, and withdrawals are locked behind owner permissions.

**AI agents can safely build, test, and run checkout flows because payment architectures can let agents define pricing and generate payment links while strictly blocking them from moving live funds.** When using thelastapi, your autonomous agents (such as Claude Code, Cursor, or Codex) can create products, generate checkout URLs, and configure webhooks, but they can never view raw customer card numbers, issue live refunds, or withdraw real money to a bank account. 

Setting up online billing used to require handing an agent full administrative access to a payment dashboard. If an agent misread a prompt, hallucinated a shell command, or leaked an environment variable, live balances could be drained or customer accounts disrupted. A safer approach divides billing into two distinct halves: operational configuration that agents can automate, and financial custody that remains locked to human owners.

## What an AI agent can and cannot do

When building with thelastapi, agents and developers work across two environments: `development` (a test sandbox using simulated charges) and `production` (live commerce). 

To keep funds secure, permissions are enforced at the API level. If an agent authenticates using a Limited key, it is blocked from destructive live actions:

| Action | Development (Test Mode) | Production (Live Mode) |
| --- | --- | --- |
| Create products, prices, and checkouts | Allowed | Allowed |
| Read balances, transactions, subscriptions | Allowed | Allowed (customer emails masked, bank details hidden) |
| Simulate charges, disputes, and hold releases | Allowed | Not available |
| Collect raw card numbers directly | Never allowed | Never allowed |
| Issue refunds or cancel live subscriptions | Allowed (test money) | Blocked (`403 owner_only`) |
| Withdraw funds to a bank account | Allowed (test money) | Blocked (`403 owner_only`) |
| Change production webhook URLs or secrets | Allowed | Blocked (`403 owner_only`) |
| Archive production products | Allowed | Blocked (`403 owner_only`) |

If an agent attempts an owner-only task in production, the API answers with HTTP status `403` and `reason: owner_only`. The response body includes `details.next_step` naming the exact steps a human owner must take in the web console (for example, navigating to `Payments ▸ the payment ▸ Refund` or `Payments ▸ Withdraw`).

Because thelastapi acts as the merchant of record, there are no separate merchant accounts to configure and no processor keys to expose inside application code. You can learn more about how this model functions in [taking payments online without opening a merchant account](https://thelastapi.dev/blog/take-payments-without-merchant-account).

## Building the checkout catalog with an agent

An agent can configure your entire product catalog through the CLI or standard HTTP calls. Catalogs are scoped per environment, meaning items are built and tested in development first, then defined in production when ready to launch.

An agent can define a subscription plan using the CLI:

```bash
# Set up a subscription product in development
vibiz payments products add Pro --amount 1500 --interval month --lookup-key pro-monthly --dev

# Add the product again for live buyers
vibiz payments products add Pro --amount 1500 --interval month --lookup-key pro-monthly
```

Or execute the equivalent HTTP request directly:

```bash
curl https://thelastapi.dev/v1/projects/prj_123/payments/products?env=development \
  -H "Authorization: Bearer $VIBIZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro",
    "price": {
      "unit_amount_cents": 1500,
      "type": "recurring",
      "interval": "month",
      "lookup_key": "pro-monthly"
    }
  }'
```

Amounts are specified in the currency's smallest unit (`1500` equals $15.00 USD). Standard currencies default to `usd`, though 35 currencies are supported (including `eur`, `gbp`, and zero-decimal currencies like `jpy` where `5000` equals ¥5,000). For details on recurring billing workflows, read about how to [add a subscription checkout to a SaaS](https://thelastapi.dev/blog/subscription-checkout-saas).

## Customizing checkout branding

An agent can also customize how checkout pages look without needing design files or direct access to sensitive settings. Hosted pages can match your application's visual identity using the project brand settings:

```bash
curl -X PATCH https://thelastapi.dev/v1/projects/prj_123/payments?env=production \
  -H "Authorization: Bearer $VIBIZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brand": {
      "name": "Acme Tools",
      "logo_url": "https://example.com/logo.png",
      "button_color": "#1a73e8",
      "font": "inter",
      "border_style": "rounded"
    }
  }'
```

Field options include `name`, direct image URLs for `logo_url` and `icon_url`, hex values for `button_color` and `background_color`, border shapes (`pill`, `rounded`, `rectangular`), and 26 system fonts such as `inter`, `roboto`, and `lato`.

## Generating secure checkout sessions

Agents should never accept raw credit card details or handle payment forms directly. Card numbers must never be passed into prompt contexts, agent scratchpads, or backend logs. 

Instead, the agent programs your server to request a hosted checkout session and redirect the user. Checkouts are created on demand, expire after 1 hour, and are single-use.

Using `@vibiz/app` in a Next.js server action:

```ts
'use server';

import { redirect } from 'next/navigation';
import { vibiz } from '@vibiz/app';

export async function upgrade() {
  const sessionUser = { id: 'usr_456' };

  const { url } = await vibiz.payments.checkout({
    lookup_key: 'pro-monthly',
    user: sessionUser.id,
    success_url: 'https://app.example.com/billing/success',
    cancel_url: 'https://app.example.com/pricing',
  });

  redirect(url);
}
```

The underlying HTTP route uses the application's server key (`VIBIZ_APP_KEY`), keeping sensitive project keys out of the browser:

```bash
curl https://thelastapi.dev/v1/app/payments/checkout \
  -H "Authorization: Bearer $VIBIZ_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lookup_key": "pro-monthly",
    "user": "usr_456",
    "success_url": "https://app.example.com/billing/success",
    "cancel_url": "https://app.example.com/pricing"
  }'
```

Your app can also query an end user's current subscription status or open a billing portal where customers manage their own plans:

```ts
// Check whether an end user has an active subscription
const isSubscribed = await vibiz.payments.hasActive('usr_456', 'pro-monthly');

// Get a self-serve portal link for cancellations or updates
const { url: portalUrl } = await vibiz.payments.portal('usr_456', {
  return_url: 'https://app.example.com/account',
});
```

Consult the documentation on [Payments in the app (@vibiz/app)](https://thelastapi.dev/docs/guides/app-payments) for complete SDK references.

## Handling webhooks safely

When a buyer completes a purchase, the server receives an asynchronous webhook. The agent can write the endpoint logic and verify payloads without needing manual access to shared webhook signing secrets.

When you install `@vibiz/app`, the client uses `VIBIZ_APP_KEY` behind the scenes to fetch and cache the signing secret directly from the API.

```ts
// app/api/vibiz/webhook/route.ts
import { vibiz } from '@vibiz/app';

export async function POST(req: Request) {
  let event;
  try {
    // Verifies the raw request body and the Vibiz-Signature header
    event = await vibiz.webhooks.receive(req);
  } catch {
    return new Response('bad signature', { status: 400 });
  }

  switch (event.type) {
    case 'payment.succeeded':
      // Access event.data.object (e.g., amount_cents, user, metadata)
      break;
    case 'subscription.created':
    case 'subscription.updated':
    case 'subscription.canceled':
      break;
    case 'invoice.paid':
    case 'invoice.payment_failed':
      break;
  }

  return new Response('ok');
}
```

Because delivery failures are retried for up to 3 days using exponential backoff, endpoints must remain idempotent by tracking `event.id`. Review [how to verify payment webhooks safely](https://thelastapi.dev/blog/verify-payment-webhooks) or read the guide on [Webhooks: thelastapi tells the app when someone pays](https://thelastapi.dev/docs/guides/webhooks) for implementation details.

## End-to-end testing with simulations

An agent does not need a physical credit card to test payment logic. In development, your agent can simulate entire payment lifecycles from the command line:

```bash
# Set a local webhook destination during development
vibiz payments webhook http://localhost:3000/api/vibiz/webhook --dev

# Simulate an incoming payment event
vibiz payments simulate payment --dev

# Inspect the ledger
vibiz payments --dev
```

The CLI can also simulate dispute events (`vibiz payments simulate dispute --dev`) or release pending funds (`vibiz payments simulate release_hold --dev`). This lets an agent verify database mutations, UI state changes, and webhook responses in an isolated environment without touching real banking rails.

## How money moves to the human owner

All customer payments settle into the project ledger. Understanding how balances clear protects you from unexpected cash flow limits:

```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
```

- **Processing Fees**: Card processing costs 2.9% + 30¢ for most US cards, deducted automatically from the payment amount. On a $100 sale with standard settings, processing takes $3.20 and the platform fee takes $2.00, crediting **$94.80** to the balance.
- **Settlement Hold**: Live payments remain pending for a hold period of 7 days before shifting to the available balance. Test transactions have no hold.
- **Disputes**: A dispute immediately takes the disputed amount plus a $15 fee from your balance. If the dispute is won, the fee is returned.
- **Payouts**: To withdraw funds, the project owner completes an identity check and registers a bank account once under console ▸ project ▸ Payments ▸ Get paid. Available funds can then be withdrawn to the owner's bank account with no additional withdrawal fee.
- **Own Processing Account**: If the owner wants sales charged directly through their own processor account, an agent can generate a connection link using `vibiz payments connect` (or `POST /v1/projects/:id/payments/own-account/link`). Only the human owner can complete the onboarding flow.

If your architecture requires giving an agent programmatic control over the broader application stack, read our guide on using [one API key for an AI agent: hosting, database, email, payments and models](https://thelastapi.dev/blog/one-api-key-for-ai-agent). For complete payout parameters, review the documentation on [Payments: how money moves](https://thelastapi.dev/docs/guides/payments) and [Payments](https://thelastapi.dev/docs/payments).

To start letting your agents build payment flows safely, create your account at [thelastapi.dev/start](https://thelastapi.dev/start).

## Frequently asked questions

### Can an AI agent accidentally withdraw live funds or issue refunds?

No. In production, refund, cancellation, and withdrawal endpoints return HTTP 403 with `reason: owner_only` whenever called by an agent with a Limited key. Live balance transfers can only be initiated by the human owner using the console or a full-access key.

### How can an agent test subscriptions without using real credit cards?

Agents use the `development` environment flag (`--dev` in the CLI or `?env=development` over HTTP). In development, agents can trigger charges using test card details or run `vibiz payments simulate payment` to send test webhook events through the ledger.

### How long are customer funds held before they can be withdrawn?

Live credit card payments remain pending in the project ledger for 7 days (`hold_days`) before converting into an available balance. Development environment transactions clear immediately with no holding period.

---

Published 2026-11-15 · https://thelastapi.dev/blog/ai-agent-set-up-payments-safely
