thelastapi
Get started free

Sell a one-time product with a hosted checkout link

Generate a hosted checkout link for a one-time digital product using the CLI, an API call, or the SDK, with no merchant account setup required.

On this page 6 sections

To sell a digital product with a hosted checkout link, generate a checkout session using the API, CLI, or @vibiz/app and redirect the buyer to the returned URL. thelastapi acts as the merchant of record for your project, so you can start charging cards immediately without registering an external merchant account or managing processor keys. The hosted checkout page handles payment collection, adapts to your brand, supports 35 currencies, and triggers a webhook as soon as the purchase completes.

Here is how checkout links work, how to create them for one-off downloads, and how to verify payments in your app.

When a buyer decides to purchase your digital download, your app requests a single-use checkout session. thelastapi returns an HTTPS link to a hosted payment page.

Every checkout link has specific lifecycle rules:

  • It is single-use. A link is created for one buyer. Once paid, it cannot be reused.
  • It expires after one hour. If the customer does not complete the checkout within 60 minutes, the link becomes invalid. You should always generate a new link when the buyer clicks your purchase button rather than storing static URLs.
  • It requires no processor setup. Payments settle directly into your project's ledger balance. Buyers see the transaction on their bank statement as VIBIZ, INC* <SUFFIX>, where the suffix is a custom descriptor you configure.

If you are exploring alternative setups, you can also learn how to take payments online without opening a merchant account or how to sell from a static site with a checkout link.

You can create a checkout link in three ways: through the @vibiz/app server library, via direct HTTP requests, or through the command line.

Using the @vibiz/app library

Install @vibiz/app in your project:

Terminal
npm install @vibiz/app

On your server, use vibiz.payments.checkout to create the session. For one-off items like an ebook, a software bundle, or a template, you can pass amount_cents and name directly without creating a catalog product first:

TypeScript
import { vibiz } from '@vibiz/app';

export async function createCheckout(userId: string) {
  const { url } = await vibiz.payments.checkout({
    amount_cents: 2900, // $29.00 USD
    name: 'Developer Utility Pack',
    user: userId, // your internal user id
    success_url: 'https://example.com/download/success',
    cancel_url: 'https://example.com/pricing',
    metadata: {
      productId: 'pack_dev_utility',
      licenseType: 'single_seat',
    },
  });

  return url;
}

The metadata object accepts up to 20 key-value pairs. thelastapi echoes this metadata back in payment lists and webhook notifications, which helps your backend identify what to unlock.

Using HTTP

If your app runs in Python, Go, or plain shell scripts, call the app checkout endpoint directly using your server's VIBIZ_APP_KEY:

Terminal
curl https://thelastapi.dev/v1/app/payments/checkout \
  -H "Authorization: Bearer $VIBIZ_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_cents": 1500,
    "name": "Design Tokens JSON",
    "user": "usr_9481",
    "success_url": "https://example.com/thanks",
    "cancel_url": "https://example.com/catalog"
  }'

The response returns a JSON payload containing the URL:

JSON
{
  "url": "https://thelastapi.dev/checkout/chk_example123"
}

Using a catalog item and the CLI

If you prefer to define products in advance, you can add them to your catalog with the CLI or create subscriptions (read more about how to add a subscription checkout to a SaaS):

Terminal
# Add a fixed-price product in development
vibiz payments products add "Audio Sample Library" --amount 4500 --lookup-key sample-pack --dev

# Generate a checkout link for testing
vibiz payments checkout sample-pack \
  --success-url http://localhost:3000/thanks \
  --cancel-url http://localhost:3000/pricing \
  --dev

Customizing the checkout with your brand

The checkout page can be styled to match your site's aesthetic. You can define your branding once across the entire project or override it per checkout session.

To update the default appearance for all checkouts in production:

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 Assets",
      "logo_url": "https://example.com/assets/logo.png",
      "button_color": "#111827",
      "background_color": "#f9fafb",
      "font": "inter",
      "border_style": "rounded"
    }
  }'

Supported branding fields include:

  • name: Displayed at the top of the hosted form if no logo is provided.
  • logo_url and icon_url: Direct HTTPS links to PNG or JPG files (maximum 2,000 characters).
  • button_color and background_color: Hex values (#rgb or #rrggbb).
  • font: Supported typography options such as default, inter, roboto, lato, montserrat, and lora (26 fonts available).
  • border_style: Choose between pill, rounded, or rectangular.

When passing brand inside vibiz.payments.checkout(), session-level values override your project-wide defaults.

Fulfilling digital orders with webhooks

Because digital downloads require instant access, you should deliver files or generate license keys when receiving a verified payment.succeeded webhook.

In production, the platform sends payment webhooks to https://<your-domain>/api/vibiz/webhook automatically. In development, point the CLI to your local server:

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

When handling the webhook, always verify the raw request body against the signature. Using @vibiz/app, this requires only 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 the raw body and checks Vibiz-Signature using VIBIZ_APP_KEY
    event = await vibiz.webhooks.receive(req);
  } catch {
    return new Response('Invalid signature', { status: 400 });
  }

  if (event.type === 'payment.succeeded') {
    const payment = event.data.object;
    const userId = payment.user;
    const productId = payment.metadata?.productId;

    // Fulfill the digital order
    await grantDigitalProductAccess(userId, productId);
  }

  return new Response('ok');
}

If you do not use @vibiz/app, verify the raw text body against the Vibiz-Signature header manually using VIBIZ_WEBHOOK_SECRET and HMAC-SHA256. Webhooks that fail or time out (after 10 seconds) are retried over three days, so remember to deduplicate actions based on event.id.

For complete payload references, see the guide on Payments in the app (@vibiz/app) and the Webhooks guide.

Fees, currencies, and withdrawing funds

When taking payments directly through thelastapi, there are no ongoing platform subscriptions. Fees are deducted as payments occur.

WhatAmountDetails
Card processing2.9% + 30¢Standard rate for most US card transactions
Platform fee200 bps (2.0%)Platform transaction fee
Disputed chargeDisputed amount + $15Deducted when opened; returned if won
RefundsOriginal payment amountProcessing and platform fees are not returned
Withdrawals$0No fee from thelastapi to transfer to your bank

Multi-currency checkouts

You can charge buyers in 35 different currencies, including usd, eur, gbp, cad, aud, and jpy. For non-USD sales, pass currency in lowercase:

TypeScript
await vibiz.payments.checkout({
  amount_cents: 3500, // €35.00
  currency: 'eur',
  name: 'European Edition Bundle',
  user: 'usr_521',
  success_url: 'https://example.com/thanks',
  cancel_url: 'https://example.com/store',
});

All balances settle in USD. Sales made in other currencies convert at the day's exchange rate minus the processor's currency-conversion fee (typically 1–2%). Amounts must meet the minimum threshold for that currency (50 cents for USD/EUR, 30 pence for GBP, or ¥50 for JPY).

Receiving payouts

  1. Verify identity once: In the project dashboard under Payments ▸ Get paid, complete the embedded identity and bank details form.
  2. Funds hold: In live mode, payments remain pending for a 7-day hold period (fees.hold_days) before becoming available to withdraw. Test mode has no hold period.
  3. Withdraw: Run vibiz payments withdraw or click Withdraw in the dashboard to move available funds to your bank account.

To test your end-to-end purchasing process locally without using real money, run vibiz payments simulate payment --dev. For details on account balances and payout mechanics, check the full Payments reference.

Frequently asked questions

Can a buyer reuse an existing checkout link to buy a second product?

No. Every checkout URL is single-use, created for a single buyer session, and expires automatically after one hour. You should generate a new link every time a customer clicks your checkout button.

How long does it take for money from a digital sale to become available for withdrawal?

In production, live card payments remain in a pending balance for 7 days (`fees.hold_days`) before moving to your available balance. In the development environment, there is no hold period.

What statement descriptor will my buyers see on their card statements?

Transactions appear on the buyer's credit card statement as `VIBIZ, INC* <SUFFIX>`, where the suffix is a custom 1–10 character descriptor you configure on your project.

What happens if a customer asks for a refund on a digital item?

You can issue refunds from the dashboard or through the API as long as your balance covers the amount. The original card processing fee and thelastapi platform fee are not returned upon refund.