# Put your brand on the checkout page

> Customize your checkout page branding with your own logo, brand colors, fonts, and border styles using the thelastapi payments API or CLI.

**You customize your checkout page branding by setting your logo, colors, font, and company name on your project, or by passing custom brand overrides when generating a checkout session.** Every hosted checkout link then displays your identity instead of generic payment styling. Your brand settings apply across both development and production environments, giving your buyers a recognizable payment flow without requiring you to manage custom frontend payment forms.

When you [take payments online without opening a merchant account](https://thelastapi.dev/blog/take-payments-without-merchant-account), thelastapi acts as the merchant of record while keeping your business front and center. This guide covers how to set your global brand styles, override them on specific checkouts, configure bank statement names, and test your changes.

## What branding controls can you set on the checkout page?

The checkout styling engine lets you match the hosted page to your application. Rather than leaving the checkout interface unstyled, you can configure your visual assets, typography, and container geometry.

Your branding configuration supports the following fields:

| Field | Accepted values | How it appears to the buyer |
| --- | --- | --- |
| `name` | String | Displayed as plain text at the top of the checkout form if no logo is provided. |
| `logo_url` | Direct HTTPS URL (PNG or JPG, max 2000 chars) | Displayed at the top of the checkout form. It replaces the plain text `name`. |
| `icon_url` | Direct HTTPS URL (PNG or JPG, max 2000 chars) | Displayed as the favicon in the buyer's browser tab. |
| `background_color` | Hex code (`#rgb` or `#rrggbb`) | The background color of the full checkout page. |
| `button_color` | Hex code (`#rgb` or `#rrggbb`) | The accent color used on primary payment and submission buttons. |
| `font` | One of 26 supported font keys (e.g., `default`, `inter`, `roboto`, `lato`, `montserrat`, `open_sans`, `noto_sans`, `nunito`, `raleway`, `source_sans_pro`, `lora`, `pt_serif`) | Sets the typography across labels, buttons, and input fields. |
| `border_style` | `pill`, `rounded`, or `rectangular` | Sets the border radius on inputs, cards, and buttons. |

Direct image URLs are required for both `logo_url` and `icon_url`. You must link straight to an image file ending in `.png` or `.jpg`, rather than an HTML landing page. When both `logo_url` and `icon_url` are present, the logo renders at the top of the payment container, and the icon renders as the tab favicon.

## How to set brand styles across your entire project

Setting branding at the project level ensures that every checkout link your application creates inherits your design automatically. Project branding is managed per environment (`development` or `production`), which allows you to test brand redesigns in your test sandbox before applying them live.

You can configure project-level defaults by sending a `PATCH` request to the [Payments API](https://thelastapi.dev/docs/payments). Use your account key (`vz_sk_…`) in the `Authorization` header:

```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://acme.example.com/assets/logo.png",
      "icon_url": "https://acme.example.com/assets/icon.png",
      "background_color": "#f8fafc",
      "button_color": "#0f172a",
      "font": "inter",
      "border_style": "rounded"
    }
  }'
```

If you ever need to clear an individual property from your configuration, set that key's value to `null` in a subsequent `PATCH` call. To reset all brand customization back to default unstyled values, pass `"brand": null` in the request body.

Remember to run this call for both environments when getting started:
1. First, call `PATCH /v1/projects/:id/payments?env=development` to verify the design in test mode.
2. Next, call `PATCH /v1/projects/:id/payments?env=production` so that live checkouts show the updated styling.

## How to override brand styling on a single checkout

Sometimes an application needs different branding for specific checkout links. For instance, you might sell a specialized product line that uses an alternate logo, or run a seasonal campaign that uses an ad-hoc button color.

When you create a checkout session, you can supply a `brand` object directly in the creation payload. Any field passed here overrides the project's base brand on a field-by-field basis. Unspecified fields fall back to your project-level settings.

### In server-side code using `@vibiz/app`

If you are building an application in Node.js or Next.js, use the `@vibiz/app` package as explained in the guide on [Payments in the app (@vibiz/app)](https://thelastapi.dev/docs/guides/app-payments). The client handles routing using your `VIBIZ_APP_KEY`:

```ts
import { vibiz } from '@vibiz/app';

export async function createCheckout(userId: string) {
  const { url } = await vibiz.payments.checkout({
    lookup_key: 'pro-monthly',
    user: userId,
    success_url: 'https://acme.example.com/billing/success',
    cancel_url: 'https://acme.example.com/pricing',
    brand: {
      name: 'Acme Special Edition',
      button_color: '#2563eb',
      border_style: 'pill',
    },
  });

  return url;
}
```

This pattern works well whether you [add a subscription checkout to a SaaS](https://thelastapi.dev/blog/subscription-checkout-saas) or [sell a one-time product with a hosted checkout link](https://thelastapi.dev/blog/sell-one-time-product-checkout-link).

### From the command-line interface

When creating links manually with the `vibiz` CLI, you can pass individual branding flags directly to `vibiz payments checkout`:

```bash
vibiz payments checkout pro-monthly \
  --success-url "https://acme.example.com/billing/success" \
  --cancel-url "https://acme.example.com/pricing" \
  --brand-name "Acme Quick Checkout" \
  --brand-color "#16a34a" \
  --brand-border rectangular \
  --brand-font montserrat \
  --dev
```

This prints a unique checkout URL containing your overrides. Because hosted checkout pages expire after 1 hour and are designed for one buyer, always generate a fresh link when a user clicks to purchase.

## What does the buyer see on their bank statement?

Branding does not stop at the visual checkout page; it also extends to what appears on your customer's credit card statement. Recognizing the transaction prevents chargebacks and confusion.

Because thelastapi acts as the merchant of record, credit card charges appear with the company's identifier alongside your chosen statement suffix:

`VIBIZ, INC* <SUFFIX>`

You can configure the suffix to match your app or brand name. The suffix rules are:
- Must be between 1 and 10 characters long.
- Can include letters (`A–Z`), numbers (`0–9`), spaces, dots (`.`), and hyphens (`-`).
- Must contain at least one letter.

Statement suffix configuration on live accounts can only be updated by the project owner in the console or with a full-access key. Setting this clearly avoids unexpected disputes. If a customer files a dispute, the disputed amount plus a $15 fee is withheld from your balance until the dispute is resolved.

## Testing your branded checkout before launch

Before accepting real customer money, inspect how your logo, fonts, and colors render on the hosted checkout page.

Run your local development environment with `vibiz dev`. This sets up your `.env.development.local` file containing your development `VIBIZ_APP_KEY`. Then, create a test product and generate a test checkout:

```bash
# Add a product to the development catalog
vibiz payments products add "Starter Plan" --amount 1200 --interval month --lookup-key starter-monthly --dev

# Create a test checkout session
vibiz payments checkout starter-monthly \
  --success-url "http://localhost:3000/thanks" \
  --cancel-url "http://localhost:3000/pricing" \
  --dev
```

Open the resulting URL in your browser. Verify the following checklist:
1. **Logo resolution:** Ensure your image renders clearly at the top without stretching or distortion.
2. **Tab icon:** Ensure the browser tab loads your custom icon from `icon_url`.
3. **Contrast:** Make sure your `button_color` provides enough visual contrast against standard text colors.
4. **Font matching:** Check that your selected typography aligns with your main website's look and feel.

You can simulate completing the payment in development using the CLI:

```bash
vibiz payments simulate payment --dev
```

This triggers the payment ledger and sends a `payment.succeeded` event to your local endpoint, as detailed in our guide on [webhooks](https://thelastapi.dev/docs/guides/webhooks). Once the test transaction looks correct, update your production brand settings and publish your changes to live users.

## Next steps

To complete your payment workflow, connect your webhook handler so your application receives fulfillment events when users check out. Learn how event signing and payloads work in our reference for [webhooks: how thelastapi tells the app when someone pays](https://thelastapi.dev/docs/guides/webhooks), or review our overview of [payments and balance holds](https://thelastapi.dev/docs/guides/payments).

## Frequently asked questions

### Can I use different branding on different checkout links in the same project?

Yes. You can define default brand settings on your project, and then pass custom brand fields in individual checkout calls to override the defaults field by field.

### What image formats and dimensions are required for logos and icons?

Logos and icons must be direct HTTPS links to PNG or JPG files, up to 2000 characters in length. Web page links that embed images are not supported.

### How long does a branded checkout page remain active?

Every hosted checkout link expires after 1 hour and is designed for a single buyer. You should create a fresh checkout link each time a buyer clicks to purchase.

### What font choices are available for the checkout form?

You can choose from 26 typography options, including `default`, `inter`, `roboto`, `lato`, `montserrat`, `open_sans`, `noto_sans`, `nunito`, `raleway`, `source_sans_pro`, `lora`, and `pt_serif`.

---

Published 2026-11-15 · https://thelastapi.dev/blog/brand-your-checkout-page
