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

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

## How hosted checkout links work

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](https://thelastapi.dev/blog/take-payments-without-merchant-account) or how to [sell from a static site with a checkout link](https://thelastapi.dev/blog/sell-from-static-site).

## Creating a one-time 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:

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

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

```bash
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](https://thelastapi.dev/blog/subscription-checkout-saas)):

```bash
# 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:

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

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

```ts
// 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)](https://thelastapi.dev/docs/guides/app-payments) and the [Webhooks guide](https://thelastapi.dev/docs/guides/webhooks).

## Fees, currencies, and withdrawing funds

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

| What | Amount | Details |
| --- | --- | --- |
| Card processing | 2.9% + 30¢ | Standard rate for most US card transactions |
| Platform fee | 200 bps (2.0%) | Platform transaction fee |
| Disputed charge | Disputed amount + $15 | Deducted when opened; returned if won |
| Refunds | Original payment amount | Processing and platform fees are not returned |
| Withdrawals | $0 | No 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:

```ts
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](https://thelastapi.dev/docs/payments).

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

---

Published 2026-11-15 · https://thelastapi.dev/blog/sell-one-time-product-checkout-link
