thelastapi
Get started free

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.

On this page 8 sections

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:

ActionDevelopment (Test Mode)Production (Live Mode)
Create products, prices, and checkoutsAllowedAllowed
Read balances, transactions, subscriptionsAllowedAllowed (customer emails masked, bank details hidden)
Simulate charges, disputes, and hold releasesAllowedNot available
Collect raw card numbers directlyNever allowedNever allowed
Issue refunds or cancel live subscriptionsAllowed (test money)Blocked (403 owner_only)
Withdraw funds to a bank accountAllowed (test money)Blocked (403 owner_only)
Change production webhook URLs or secretsAllowedBlocked (403 owner_only)
Archive production productsAllowedBlocked (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.

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:

Terminal
# 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:

Terminal
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.

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:

Terminal
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:

TypeScript
'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:

Terminal
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:

TypeScript
// 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) 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.

TypeScript
// 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 or read the guide on Webhooks: thelastapi tells the app when someone pays 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:

Terminal
# 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. For complete payout parameters, review the documentation on Payments: how money moves and Payments.

To start letting your agents build payment flows safely, create your account at 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.