> ## 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. > A merchant can run an entire shop with no code: the dashboard creates products and invoices, and every store can host a storefront at {slug}.taberna.io with its own theme, sections, branding and optional custom domain. Never assume the reader has an API integration. > Taberna issues no refunds and performs no KYC. A refund is something the merchant sends from their own payout wallet, off-platform. # Retrieve an order > One order by its short id. Requires the `orders:read` scope. The payment fields (`paymentMethod`, `cryptoAmount`, `receivedAmount`, `transactions`) all describe a single payment attempt: the one that completed the order, else the best-funded one, else the most recent. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/orders/{id} openapi: 3.1.0 info: title: Taberna API description: >- Accept crypto payments for digital goods. Create orders and invoices, hand the buyer a hosted checkout link, and let webhooks tell you when the money lands. Authenticate merchant endpoints with a store API key as a bearer token (`Authorization: Bearer tbrn_live_…`). Every key is bound to one store and carries an explicit set of scopes; the scope a route requires is stated in its description and in the `x-required-scope` extension. A key without the scope gets a 403 — mint one with the scope rather than retrying. The Checkout endpoints are the exception: they are unauthenticated and meant to be called from the buyer's browser. Possession of the checkout id is the credential there, so never ship an API key to a page. Conventions: ids in links are short ids; fiat amounts are decimal strings ("9.99"); crypto amounts are integer strings in the asset's smallest unit; timestamps are ISO-8601 UTC. Errors carry `{ "error": "…" }` unless documented otherwise. version: 1.0.0 servers: - url: https://api.taberna.io description: Taberna API security: [] tags: - name: Orders description: Carts of products, paid through a hosted checkout. - name: Invoices description: Merchant-issued bills with their own payment page. - name: Invoice Templates description: Saved invoice presets, referenced by `templateId` when creating one. - name: Products description: Catalogue reads and delivery stock top-ups. - name: Store description: What the calling API key is and what it may do. - name: Webhook Deliveries description: Delivery history for the store webhook, and replay. - name: Checkout description: >- Buyer-facing hosted-page endpoints. Unauthenticated by design — never send an API key. paths: /v1/orders/{id}: get: tags: - Orders summary: Retrieve an order description: >- One order by its short id. Requires the `orders:read` scope. The payment fields (`paymentMethod`, `cryptoAmount`, `receivedAmount`, `transactions`) all describe a single payment attempt: the one that completed the order, else the best-funded one, else the most recent. operationId: getV1OrdersById parameters: - in: path name: id schema: type: string pattern: ^[1-9A-HJ-NP-Za-km-z]{21,22}$ example: 7Kq2mVn8pRt3XwYz5Bd4L required: true description: >- The order to act on. Base58 short id, 21–22 characters (never `0`, `O`, `I` or `l`), e.g. `7Kq2mVn8pRt3XwYz5Bd4L` — the value that appears in checkout and invoice links, and the one this API takes as a path id. responses: '200': description: The order. content: application/json: schema: type: object properties: id: type: string description: >- The order's id. Base58 short id, 21–22 characters (never `0`, `O`, `I` or `l`), e.g. `7Kq2mVn8pRt3XwYz5Bd4L` — the value that appears in checkout and invoice links, and the one this API takes as a path id. example: 7Kq2mVn8pRt3XwYz5Bd4L status: type: string enum: - pending - completed - partial - expired description: >- Where the order is in its lifecycle. `pending` — created, waiting for the buyer to pay. `completed` — paid in full; any digital delivery has been released. `partial` — funds arrived but fell short of the locked quote. `expired` — the payment window closed without full payment, and any reserved stock went back to the pool. example: pending priceAmount: type: string description: >- Total the buyer owes. Decimal string in the resource's fiat currency, e.g. `"49.99"` — a string, never a JSON number, so no precision is lost in transit. example: '49.99' priceCurrency: type: string enum: - usd - eur description: >- The fiat currency every amount on this resource is priced in. Crypto is quoted against it at payment time. example: usd successUrl: anyOf: - type: string - type: 'null' description: >- Where the hosted checkout sends the buyer after a successful payment. Null when none was set at creation. example: https://example.com/thanks cancelUrl: anyOf: - type: string - type: 'null' description: >- Where the hosted checkout sends the buyer if they back out. Null when none was set at creation. example: https://example.com/cart customerEmail: anyOf: - type: string - type: 'null' description: >- Buyer email for the receipt and any digital delivery, either supplied at creation or entered on the checkout page. Null when neither happened. example: buyer@example.com extraContext: anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: 'null' description: >- The arbitrary JSON object you attached at creation, returned untouched. Taberna never interprets it — use it to carry your own order or user reference. example: internalOrderId: A-1042 paymentMethod: anyOf: - type: string enum: - sol - usdc_solana - eth_base - usdc_base - usdt_base - eth - usdc_ethereum - usdt_ethereum - matic - usdc_polygon - usdt_polygon - bnb - usdt_bnb - type: 'null' description: >- The token and chain the buyer pays with, named `_`; a bare `sol`, `eth`, `matic` or `bnb` is that chain's native coin. So `usdc_base` is USDC on Base and `eth` is ether on Ethereum mainnet. The `matic` key is Polygon's native coin, now called POL — the key keeps its original name and does not change. Null until the buyer picks one. cryptoAmount: anyOf: - type: string - type: 'null' description: >- The quoted amount for the attempt this order is reported against. Null until the buyer starts one. Integer string in the asset's own smallest unit, NOT a decimal token amount: lamports for SOL (1 SOL = `"1000000000"`), wei for ETH/POL/BNB (1 ETH = `"1000000000000000000"`), base units for USDC/USDT (1 USDC = `"1000000"`). receivedAmount: anyOf: - type: string - type: 'null' description: >- How much of that quote actually arrived. Integer string in the asset's own smallest unit, NOT a decimal token amount: lamports for SOL (1 SOL = `"1000000000"`), wei for ETH/POL/BNB (1 ETH = `"1000000000000000000"`), base units for USDC/USDT (1 USDC = `"1000000"`). transactions: type: array items: type: object properties: blockchain: type: string enum: - solana - base - ethereum - polygon - bnb description: The chain the transfer was observed on. example: base txHash: type: string description: >- On-chain transaction identifier — a `0x`-prefixed hash on EVM chains, a base58 signature on Solana. Use it to look the transfer up in a block explorer. example: >- 0x3d7f2b91c4e08a5619d3fb27ac60e845912f7b3d0c6a48e152b9df3706ac81be fromAddress: anyOf: - type: string - type: 'null' description: >- The payer's address, as reported by the chain. Null when the transfer's sender could not be attributed. amount: type: string description: >- How much this single transfer moved to the deposit address. Integer string in the asset's own smallest unit, NOT a decimal token amount: lamports for SOL (1 SOL = `"1000000000"`), wei for ETH/POL/BNB (1 ETH = `"1000000000000000000"`), base units for USDC/USDT (1 USDC = `"1000000"`). example: '1250000000' blockNumber: anyOf: - type: string - type: 'null' description: >- Block height (slot, on Solana) the transfer landed in, as a string because the value can exceed a safe JSON number. Null until the transfer is mined. example: '21847391' blockTime: anyOf: - type: string format: date-time description: >- UTC timestamp in ISO 8601, e.g. `2026-07-29T14:30:00.000Z`. example: '2026-07-29T14:30:00.000Z' - type: 'null' description: >- When the block carrying this transfer was produced. Null until mined. UTC timestamp in ISO 8601, e.g. `2026-07-29T14:30:00.000Z`. required: - blockchain - txHash - fromAddress - amount - blockNumber - blockTime description: One on-chain transfer credited to a payment attempt. description: >- On-chain transfers for the payment attempt this order is reported against. Empty until funds are seen. items: type: array items: type: object properties: productId: type: string format: uuid description: >- The purchased product's id. Formatted as a UUID, e.g. `3f1a9c2e-7b04-4d8e-9a6f-2c5b1e0d7a83`. example: 3f1a9c2e-7b04-4d8e-9a6f-2c5b1e0d7a83 title: type: string description: Product title, copied at purchase time. example: Nitro — 1 Month image: anyOf: - type: string - type: 'null' description: >- Absolute URL of the product image, or null when the product has none. example: https://cdn.taberna.io/products/nitro.png quantity: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Units of this product on the order. example: 2 unitPrice: type: string description: >- Price of one unit. Decimal string in the resource's fiat currency, e.g. `"49.99"` — a string, never a JSON number, so no precision is lost in transit. example: '49.99' amount: type: string description: >- Line total — `unitPrice` × `quantity`. Decimal string in the resource's fiat currency, e.g. `"49.99"` — a string, never a JSON number, so no precision is lost in transit. example: '49.99' required: - productId - title - image - quantity - unitPrice - amount description: One line on the order. description: The products bought, one entry per line. checkoutUrl: type: string description: >- The hosted checkout page to send the buyer to. Safe to share; it is what the short id unlocks. example: https://taberna.io/checkout/7Kq2mVn8pRt3XwYz5Bd4L createdAt: type: string format: date-time description: >- When the order was created. UTC timestamp in ISO 8601, e.g. `2026-07-29T14:30:00.000Z`. example: '2026-07-29T14:30:00.000Z' expiresAt: type: string format: date-time description: >- When the order stops accepting payment. UTC timestamp in ISO 8601, e.g. `2026-07-29T14:30:00.000Z`. example: '2026-07-29T14:30:00.000Z' completedAt: anyOf: - type: string format: date-time description: >- UTC timestamp in ISO 8601, e.g. `2026-07-29T14:30:00.000Z`. example: '2026-07-29T14:30:00.000Z' - type: 'null' description: >- When the order was paid in full. Null until it is. UTC timestamp in ISO 8601, e.g. `2026-07-29T14:30:00.000Z`. required: - id - status - priceAmount - priceCurrency - successUrl - cancelUrl - customerEmail - extraContext - paymentMethod - cryptoAmount - receivedAmount - transactions - items - checkoutUrl - createdAt - expiresAt - completedAt description: An order as the merchant API reports it. '400': description: >- The request failed validation (`{ "error": "Invalid request data" }`), or the operation is not allowed in the resource's current state. content: application/json: schema: type: object properties: error: type: string description: >- Human-readable explanation of what went wrong. Meant for logs and developers, not for branching — switch on the HTTP status instead. example: Order not found required: - error description: The standard error body, returned by every failing endpoint. example: error: Order not found '401': description: >- Missing, malformed, revoked or expired API key. The `WWW-Authenticate` header names the challenge that failed. content: application/json: schema: type: object properties: error: type: string description: >- Human-readable explanation of what went wrong. Meant for logs and developers, not for branching — switch on the HTTP status instead. example: Order not found required: - error description: The standard error body, returned by every failing endpoint. example: error: Order not found '403': description: The key is valid but was not granted the scope this route requires. content: application/json: schema: type: object properties: error: type: string description: >- Human-readable explanation of what went wrong. Meant for logs and developers, not for branching — switch on the HTTP status instead. example: Order not found required: - error description: The standard error body, returned by every failing endpoint. example: error: Order not found '404': description: >- No such order for this API key's store. Resources belonging to another store are reported as missing, never as forbidden. content: application/json: schema: type: object properties: error: type: string description: >- Human-readable explanation of what went wrong. Meant for logs and developers, not for branching — switch on the HTTP status instead. example: Order not found required: - error description: The standard error body, returned by every failing endpoint. example: error: Order not found security: - bearerAuth: [] components: securitySchemes: bearerAuth: type: http scheme: bearer description: >- A store API key, sent as `Authorization: Bearer `. A key looks like `tbrn_live_` followed by 48 hex characters, e.g. `tbrn_live_4f2a...c91b`. Mint one in the Taberna dashboard under Developers → API Keys, tick the scopes the integration needs, and copy it there and then — the full value is shown once and only its hash is stored, so a lost key is replaced rather than recovered. One key belongs to one store and carries a fixed scope set. Send it from a server, never from a browser: it can create orders and invoices and read every order the store has. ````