thelastapi
Get started free

Test payments in development without real money

Test card payments in development using test card numbers, simulated charges, and instant webhooks without real money or bank accounts.

On this page 8 sections

You can test card payments in development without real money by using test mode, standard test card numbers, and simulation commands. thelastapi gives every project a dedicated development environment where charges do not touch real banks, payments settle without the live 7-day hold, and webhooks fire directly to your local server. You can walk through complete checkouts, trigger disputes, test refunds, and verify subscription renewals before going live.

This guide walks you through testing card payments end to end, from creating your first sandbox price to simulating refunds and handling local webhooks.

How development mode differs from production

Every payment feature in thelastapi accepts an environment setting: development or production. In development, you work in a sandbox that mirrors the live ledger while keeping real money completely out of the loop.

FeatureDevelopment (test mode)Production (live)
Card numbers4242 4242 4242 4242 (any future date, any CVC)Real credit and debit cards
Payout holdNone (immediately available)7 days (fees.hold_days)
Real money movedNoneYes
Product catalogSeparate test catalogSeparate live catalog
Agent / Limited key permissionsCan simulate, refund, dispute, and withdrawRead-only and checkout creation; refunds/withdrawals are 403 owner_only
Webhook endpointSupports http://localhostRequires public production URL
Bank verification detailsMock values (SSN 0000, routing 110000000)Real identity and bank accounts

Because catalogs are separate per environment, a product you set up in development does not appear in your live store until you create it for production. This prevents test pricing or sandbox items from appearing in front of real customers. To learn more about how production ledger balances clear, see our guide on how money moves and taking payments online without opening a merchant account.

Setting up test products and prices

Before testing a checkout, create a product and price inside your development environment. You can use the CLI with the --dev flag or send an HTTP request with ?env=development.

Using the CLI:

Terminal
# Add a recurring monthly plan in development
vibiz payments products add Pro --amount 1500 --interval month --lookup-key pro-monthly --dev

# Inspect the development product catalog
vibiz payments products --dev

If you prefer HTTP requests, pass an account key (vz_sk_...) and the env=development query parameter:

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 always specified in the currency's smallest unit (1500 cents equals $15.00). If you want to charge in another currency like Euros or Yen during testing, check out how to sell in multiple currencies.

Testing checkouts in your application

When integrating checkout flows into a web application, use the @vibiz/app package on your server. Your development environment automatically uses the development app key from .env.development.local when you run vibiz dev.

Creating a test checkout session

Install the library:

Terminal
npm install @vibiz/app

Then create an endpoint or server action that generates a hosted checkout session:

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

export async function handleUpgrade(userId: string) {
  const { url } = await vibiz.payments.checkout({
    lookup_key: 'pro-monthly',
    user: userId,
    success_url: 'http://localhost:3000/thanks',
    cancel_url: 'http://localhost:3000/pricing',
  });

  // Redirect the user to the hosted payment page
  redirect(url);
}

Because VIBIZ_APP_KEY in development points to test mode, the generated checkout page operates safely in sandbox mode. Checkout URLs expire after 1 hour and are designed for a single buyer, so generate a new session on every click rather than caching URLs.

Completing the payment on the hosted page

When you open the checkout URL, enter the standard test card:

  • Card number: 4242 4242 4242 4242
  • Expiration date: Any valid future month and year (such as 12/28)
  • CVC: Any 3 digits (such as 123)
  • Postal code: Any alphanumeric string (such as 94107)

After submitting, the checkout finishes immediately and sends you to your success_url. Read our guide on adding a subscription checkout to a SaaS to see full application patterns.

Simulating payments and edge cases from the CLI

You do not need to open a browser and type test card numbers every time you want to verify your backend logic. The CLI provides simulation commands specifically for development.

Instant test payments

To trigger an immediate test payment without visiting a hosted checkout page:

Terminal
# Simulates a completed test payment and fires webhooks
vibiz payments simulate payment --dev

# Simulates a payment with a specific custom amount in cents
vibiz payments simulate payment --amount 2500 --dev

This runs a realistic transaction through your project's development ledger and dispatches real webhook events to your registered endpoint.

Simulating refunds and disputes

Handling edge cases is critical before launching live billing. You can simulate disputes and refunds directly:

Terminal
# View recent payments to find a payment ID
vibiz payments list --dev

# Simulate refunding a specific development payment
vibiz payments simulate refund pay_123

# Simulate an inbound charge dispute
vibiz payments simulate dispute --amount 1500

Simulating a dispute immediately applies the disputed amount plus the $15 dispute fee against your development balance, matching how disputes function in production.

Verifying webhooks locally

To fulfill purchases, grant user permissions, and handle subscription lifecycle changes, your application must listen for webhooks. For full configuration options, refer to the payments documentation and webhooks guide.

1. Register your local webhook route

In development, you can register a localhost URL directly:

Terminal
vibiz payments webhook http://localhost:3000/api/vibiz/webhook --dev

2. Handle events in your API route

Your route handler must verify the raw request body using @vibiz/app and VIBIZ_APP_KEY:

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

export async function POST(req: Request) {
  let event;

  try {
    // Reads raw body and verifies Vibiz-Signature using VIBIZ_APP_KEY
    event = await vibiz.webhooks.receive(req);
  } catch {
    return new Response('Invalid webhook signature', { status: 400 });
  }

  switch (event.type) {
    case 'payment.succeeded': {
      const payment = event.data.object;
      console.log(`Payment confirmed for user ${payment.user}: ${payment.amount_cents} cents`);
      break;
    }
    case 'subscription.created':
    case 'subscription.updated': {
      const sub = event.data.object;
      console.log(`Subscription ${sub.id} status is now ${sub.status}`);
      break;
    }
    case 'payment.refunded': {
      console.log('Payment was refunded:', event.data.object.id);
      break;
    }
    case 'dispute.created': {
      console.log('Dispute received:', event.data.object.id);
      break;
    }
  }

  return new Response('ok');
}

Whenever you run vibiz payments simulate payment --dev, your local server receives a genuine payment.succeeded event payload. Always check event.id to deduplicate events, as webhooks retry automatically when an endpoint fails to respond with a 2xx code.

Testing payouts and bank details

Before you withdraw real money from sales, the project owner must verify identity and banking details once under Payments ▸ Get paid. You can test this entire verification and withdrawal workflow in development without sharing personal data.

When going through the setup in development, use these test inputs:

  • Date of birth: 1901-01-01
  • SSN (last 4 digits): 0000
  • Routing number: 110000000
  • Account number: 000123456789

Once verified in test mode, you can test balance withdrawals:

Terminal
vibiz payments withdraw --amount 5000 --dev

In development, the balance transfers instantly without moving actual money or contacting real financial networks.

Next steps

Once your checkout flow, status checks via vibiz.payments.hasActive(), and webhook listeners are tested and working in development, recreate your product catalog with env=production and deploy your app. To dive deeper into client methods, read the docs on payments in the app.

Frequently asked questions

What test credit card number should I use for development checkouts?

Use card number `4242 4242 4242 4242` with any future expiration date (such as 12/28) and any 3-digit CVC.

How do I test webhooks on my local machine without deploying?

Register your local URL using `vibiz payments webhook http://localhost:3000/api/vibiz/webhook --dev`, which is allowed when running in development mode.

Is there a 7-day hold on payments in development?

No, the standard 7-day hold applies only to live production payments; development transactions settle immediately into your available balance.

Can AI coding agents perform refunds and payouts during testing?

Yes, in development test mode, agents and Limited keys can simulate charges, issue refunds, and test withdrawals, whereas production reserves live money movements for account owners.