> ## Documentation Index
> Fetch the complete documentation index at: https://docs.taberna.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Taberna is a crypto payments API. Amounts are priced in fiat (USD or EUR) and paid in crypto.
> Fiat amounts are ALWAYS decimal strings ("9.99"), never numbers. Crypto amounts are integer strings in the asset's smallest unit.
> Authenticate merchant endpoints with `Authorization: Bearer tbrn_live_...`. Every key is bound to one store and carries an explicit scope set, so never pass a store id to a /v1 endpoint.
> A 401 means the credential is bad; a 403 means the key lacks a scope. Never retry or re-authenticate on a 403 — surface it as a configuration error.
> The /v1/checkouts endpoints are deliberately unauthenticated and run in the buyer's browser. Never send an API key to a browser.
> Verify webhook signatures over the RAW request body before parsing JSON, and treat delivery as at-least-once: handlers must be idempotent.
> Never grant value based on a browser redirect to successUrl. Fulfil on a signature-verified webhook, or on a server-side read of GET /v1/orders/{id} or GET /v1/invoices/{id}.
> There is no test mode: every payment method is a live chain moving real funds.

# Introduction

> Taberna lets you charge a customer in crypto, price it in fiat, and settle straight to your own wallet.

Taberna is a payments API for digital goods. You create a charge, send the buyer to a
hosted payment page, and Taberna tells you when the money lands on-chain.

Everything is **priced in fiat** — USD or EUR — and **paid in crypto**. The buyer sees
`$50.00`, picks a token at checkout, and Taberna handles the exchange-rate conversion,
the deposit address, and the on-chain watching. You never touch a wallet, an RPC node,
or a price feed.

<CardGroup cols={2}>
  <Card title="Accept a payment in six steps" icon="rocket" href="/quickstart">
    Create a store, add a product, mint a key, `POST /v1/orders`, redirect, fulfil on
    the webhook.
  </Card>

  <Card title="Browse the API" icon="code" href="/api-reference">
    Every endpoint, generated from the running service's OpenAPI document.
  </Card>
</CardGroup>

## What you get

**13 payment methods across 5 chains.** Native coins and stablecoins on Solana,
Ethereum, Base, Polygon and BNB Chain. You choose which ones your store accepts; the
buyer picks from that list.

| Chain     | `blockchain` | Payment methods                         |
| --------- | ------------ | --------------------------------------- |
| Solana    | `solana`     | `sol`, `usdc_solana`                    |
| Ethereum  | `ethereum`   | `eth`, `usdc_ethereum`, `usdt_ethereum` |
| Base      | `base`       | `eth_base`, `usdc_base`, `usdt_base`    |
| Polygon   | `polygon`    | `matic`, `usdc_polygon`, `usdt_polygon` |
| BNB Chain | `bnb`        | `bnb`, `usdt_bnb`                       |

**Settlement to your own wallet.** You register a payout address per chain. Each
payment lands in a fresh deposit wallet that Taberna generates for that one attempt,
and is then swept on-chain to your address. There is no Taberna balance to withdraw
from and no payout schedule to wait on.

**One processing fee, and nothing else.** The standard rate is 3%, set per store and
visible in the dashboard. It is deducted on-chain during the sweep, so you receive the
payment amount minus your rate. The buyer pays their own network fee to send the
payment; the sweep's gas is paid by Taberna, not out of your funds. Processors that
quote a percentage and then add network or withdrawal fees on top deduct more than one
line — here the processing fee is the whole deduction. See
[Settlement](/payment-lifecycle#settlement).

**A hosted checkout you don't have to build.** Coin selection, live exchange rates,
the deposit address and QR, confirmation progress, receipts and digital delivery are
all handled on Taberna's pages.

## Core concepts

<AccordionGroup>
  <Accordion title="Store" icon="store">
    Your merchant account. A store owns products, invoices, API keys, payout
    wallets, and one webhook endpoint. Everything an API key can reach belongs to
    exactly one store — the key carries the store identity, so you never pass a
    store id to `/v1` endpoints.
  </Accordion>

  <Accordion title="Product" icon="box">
    A fixed-price item in your catalogue, with an optional digital delivery
    attached (a pool of licence keys, a shared file, a redirect). Orders are always
    for products. See [Products and delivery](/products-and-delivery).
  </Accordion>

  <Accordion title="Order" icon="cart-shopping">
    A cart of one or more products, each with a quantity. Created through
    `POST /v1/orders`, it returns a `checkoutUrl` to send the buyer to. Expires 30
    minutes after creation unless you widen the window. See [Orders](/orders).
  </Accordion>

  <Accordion title="Invoice" icon="file-invoice">
    A bill with line items and amounts you compose per request — no product setup.
    The right tool whenever the amount is decided at request time. Carries a
    per-store sequential `number`, arbitrary `metadata`, and its own hosted page.
    See [Invoices](/invoices).
  </Accordion>

  <Accordion title="Payment attempt" icon="clock">
    A short-lived payment session under an order or an invoice. It is created when
    the buyer picks a token: Taberna locks a crypto quote for up to 30 minutes on a
    freshly generated deposit wallet and watches the chain. If the quote lapses
    unpaid, the parent order or invoice stays payable and the buyer simply picks a
    token again. See [Payment lifecycle](/payment-lifecycle).
  </Accordion>

  <Accordion title="Checkout" icon="credit-card">
    The buyer-facing hosted page, plus the unauthenticated `/v1/checkouts`
    endpoints that drive it. One resource serves both orders and invoices, keyed by
    the public short id. See [Checkout](/checkout).
  </Accordion>

  <Accordion title="API key and scopes" icon="key">
    A bearer token bound to one store, carrying an explicit set of scopes — the set
    of `/v1` endpoints it may reach. There is no implicit full-access key. See
    [Authentication](/authentication).
  </Accordion>

  <Accordion title="Webhook" icon="tower-broadcast">
    One HTTP endpoint per store that Taberna POSTs lifecycle events to, signed with
    HMAC-SHA256 and retried for days on failure. This is the completion signal you
    should build on. See [Webhooks](/webhooks).
  </Accordion>
</AccordionGroup>

## Two ways to charge

<Tabs>
  <Tab title="Orders (catalogue)">
    Best when you sell a **fixed set of things** at fixed prices — plans, tiers,
    licences, downloads.

    Create the products once (in the dashboard), then reference them by id:

    ```json theme={null}
    { "items": [{ "productId": "0197f8a0-…", "quantity": 2 }] }
    ```

    Taberna computes the total, reserves any finite delivery stock for the order's
    lifetime, and attaches the delivery to the completed order.
  </Tab>

  <Tab title="Invoices (dynamic amounts)">
    Best when the **amount is decided per request** — account credits, usage
    top-ups, consulting fees, one-off bills.

    No product setup at all; you compose the line items in the create call:

    ```json theme={null}
    { "items": [{ "name": "124 credits", "quantity": 1, "unitAmount": "124" }] }
    ```

    Invoices also carry `metadata`, a sequential `number`, a customer name and memo,
    and can be emailed to the customer.
  </Tab>
</Tabs>

## Dashboard versus API

The split is deliberate: anything that **configures** the store is a human action in
the dashboard; anything that **transacts** is available to your server.

| In the dashboard (logged-in human)             | Via API key (your server)                                        |
| ---------------------------------------------- | ---------------------------------------------------------------- |
| Create the store, set its name and image       | Read the store — `GET /v1/store`                                 |
| Enable payment methods, set payout wallets     | —                                                                |
| Create and edit products, configure delivery   | Read products, append delivery stock — `/v1/products`            |
| Create and edit invoice templates              | List templates — `GET /v1/invoice-templates`                     |
| Mint and revoke API keys                       | —                                                                |
| Set the webhook URL, rotate the signing secret | List and resend deliveries — `/v1/webhook-deliveries`            |
| Browse and manage orders and invoices          | Create, read, expire, void, email — `/v1/orders`, `/v1/invoices` |

<Note>
  There is no API-key route to create products, stores, invoice templates or API
  keys. That is a current limitation, stated plainly in
  [Errors and limits](/errors-and-limits#current-limitations).
</Note>

## Conventions

These hold everywhere in the API, in both directions.

| Convention         | Format                                                                                                                                                                                           |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Fiat amounts**   | Human decimal strings, never numbers — `"50"`, `"9.99"`. Up to 3 decimal places, no trailing-zero padding, so `"50"` means \$50.00.                                                              |
| **Crypto amounts** | Integer strings in the asset's smallest unit — wei, lamports, token base units. `"50010000"` is 50.01 USDC (6 decimals).                                                                         |
| **Timestamps**     | ISO-8601, UTC — `"2026-07-09T12:30:00.000Z"`.                                                                                                                                                    |
| **Resource ids**   | Orders and invoices use a **public short id** — a short base58 string like `CcvnKdAXzvW8h3JaS1VJe`, the value that appears in checkout links. Products, stores and webhook deliveries use UUIDs. |
| **Errors**         | `{ "error": "…" }`, with one documented exception: the invoice-send endpoint adds `code` and `retryAfterSeconds`. See [Errors and limits](/errors-and-limits).                                   |

## Base URL

```
https://api.taberna.io
```

Programmatic endpoints live under the versioned `/v1` prefix. The buyer-facing hosted
pages live on a separate host, and Taberna returns their full URLs (`checkoutUrl` for
orders, `url` for invoices) when you create the resource — never construct them
yourself.