> ## 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. # Start a payment attempt > Locks a crypto quote for the chosen token and mints a fresh deposit wallet, returning the refreshed checkout to poll. Re-selecting the live attempt's token returns that same attempt; choosing a different token abandons it and locks a new quote on a new address. Refused once the order or invoice is no longer payable. Unauthenticated: possession of the checkout id is the credential, so send no API key. The id is unguessable and every payload is redacted for a buyer audience. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/checkouts/{id}/attempts 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/checkouts/{id}/attempts: post: tags: - Checkout summary: Start a payment attempt description: >- Locks a crypto quote for the chosen token and mints a fresh deposit wallet, returning the refreshed checkout to poll. Re-selecting the live attempt's token returns that same attempt; choosing a different token abandons it and locks a new quote on a new address. Refused once the order or invoice is no longer payable. Unauthenticated: possession of the checkout id is the credential, so send no API key. The id is unguessable and every payload is redacted for a buyer audience. operationId: postV1CheckoutsByIdAttempts parameters: - in: path name: id schema: type: string pattern: ^[1-9A-HJ-NP-Za-km-z]{21,22}$ required: true requestBody: required: true content: application/json: schema: type: object properties: paymentMethod: 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 required: - paymentMethod responses: '200': description: The checkout, with the new `activeAttempt`. content: application/json: schema: oneOf: - type: object properties: type: type: string const: order id: type: string description: >- Public short id — the value that appears in checkout links. storeId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ status: type: string enum: - pending - completed - partial - expired priceAmount: type: string description: >- Fiat amount as a decimal string, e.g. "9.99". Never a number. priceCurrency: type: string enum: - usd - eur successUrl: anyOf: - type: string - type: 'null' cancelUrl: anyOf: - type: string - type: 'null' expiresAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: ISO-8601 timestamp in UTC. completedAt: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: ISO-8601 timestamp in UTC. - type: 'null' items: type: array items: type: object properties: productId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ title: type: string image: anyOf: - type: string - type: 'null' quantity: type: integer minimum: -9007199254740991 maximum: 9007199254740991 unitPrice: type: string description: >- Fiat amount as a decimal string, e.g. "9.99". Never a number. delivery: anyOf: - oneOf: - type: object properties: type: type: string const: text_pool lines: type: array items: type: string required: - type - lines - type: object properties: type: type: string const: text_shared text: type: string required: - type - text - type: object properties: type: type: string const: file_shared fileName: type: string orderItemId: type: string description: >- Public short id — the value that appears in checkout links. required: - type - fileName - orderItemId - type: object properties: type: type: string const: redirect url: type: string required: - type - url - type: 'null' required: - productId - title - image - quantity - unitPrice - delivery hasCustomerEmail: type: boolean store: type: object properties: id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ name: type: string image: anyOf: - type: string - type: 'null' enabledPaymentMethods: type: array items: 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 requireCustomerEmail: type: boolean required: - id - name - image - enabledPaymentMethods - requireCustomerEmail activeAttempt: anyOf: - type: object properties: status: type: string enum: - processing - completed - partial - expired - abandoned paymentMethod: 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 cryptoAmount: type: string description: >- Amount in the asset's smallest unit (wei / lamports / token base units), as an integer string. receivedAmount: anyOf: - type: string description: >- Amount in the asset's smallest unit (wei / lamports / token base units), as an integer string. - type: 'null' destinationAddress: type: string transactions: type: array items: type: object properties: blockchain: type: string enum: - solana - base - ethereum - polygon - bnb txHash: type: string fromAddress: anyOf: - type: string - type: 'null' amount: type: string description: >- Amount in the asset's smallest unit (wei / lamports / token base units), as an integer string. blockNumber: anyOf: - type: string - type: 'null' blockTime: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: ISO-8601 timestamp in UTC. - type: 'null' required: - blockchain - txHash - fromAddress - amount - blockNumber - blockTime confirmation: type: object properties: state: type: string enum: - waiting - detected - confirming - confirmed confirmations: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' required: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' stale: type: boolean required: - state - confirmations - required - stale expiresAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: ISO-8601 timestamp in UTC. completedAt: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: ISO-8601 timestamp in UTC. - type: 'null' required: - status - paymentMethod - cryptoAmount - receivedAmount - destinationAddress - transactions - confirmation - expiresAt - completedAt - type: 'null' required: - type - id - storeId - status - priceAmount - priceCurrency - successUrl - cancelUrl - expiresAt - completedAt - items - hasCustomerEmail - store - activeAttempt - type: object properties: type: type: string const: invoice id: type: string description: >- Public short id — the value that appears in checkout links. number: type: integer minimum: -9007199254740991 maximum: 9007199254740991 status: type: string enum: - open - paid - partial - expired - voided items: type: array items: type: object properties: name: type: string description: anyOf: - type: string - type: 'null' quantity: type: integer minimum: -9007199254740991 maximum: 9007199254740991 unitAmount: type: string description: >- Fiat amount as a decimal string, e.g. "9.99". Never a number. amount: type: string description: >- Fiat amount as a decimal string, e.g. "9.99". Never a number. required: - name - description - quantity - unitAmount - amount totalAmount: type: string description: >- Fiat amount as a decimal string, e.g. "9.99". Never a number. currency: type: string enum: - usd - eur customerName: anyOf: - type: string - type: 'null' memo: anyOf: - type: string - type: 'null' successUrl: anyOf: - type: string - type: 'null' cancelUrl: anyOf: - type: string - type: 'null' expiresAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: ISO-8601 timestamp in UTC. paidAt: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: ISO-8601 timestamp in UTC. - type: 'null' store: type: object properties: id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ name: type: string image: anyOf: - type: string - type: 'null' enabledPaymentMethods: type: array items: 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 required: - id - name - image - enabledPaymentMethods activeAttempt: anyOf: - type: object properties: status: type: string enum: - processing - completed - partial - expired - abandoned paymentMethod: 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 cryptoAmount: type: string description: >- Amount in the asset's smallest unit (wei / lamports / token base units), as an integer string. receivedAmount: anyOf: - type: string description: >- Amount in the asset's smallest unit (wei / lamports / token base units), as an integer string. - type: 'null' destinationAddress: type: string transactions: type: array items: type: object properties: blockchain: type: string enum: - solana - base - ethereum - polygon - bnb txHash: type: string fromAddress: anyOf: - type: string - type: 'null' amount: type: string description: >- Amount in the asset's smallest unit (wei / lamports / token base units), as an integer string. blockNumber: anyOf: - type: string - type: 'null' blockTime: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: ISO-8601 timestamp in UTC. - type: 'null' required: - blockchain - txHash - fromAddress - amount - blockNumber - blockTime confirmation: type: object properties: state: type: string enum: - waiting - detected - confirming - confirmed confirmations: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' required: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' stale: type: boolean required: - state - confirmations - required - stale expiresAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: ISO-8601 timestamp in UTC. completedAt: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: ISO-8601 timestamp in UTC. - type: 'null' required: - status - paymentMethod - cryptoAmount - receivedAmount - destinationAddress - transactions - confirmation - expiresAt - completedAt - type: 'null' required: - type - id - number - status - items - totalAmount - currency - customerName - memo - successUrl - cancelUrl - expiresAt - paidAt - store - activeAttempt '400': description: >- The request failed validation, or the checkout is no longer payable — expired, already paid, or the store does not accept the requested token. content: application/json: schema: type: object properties: error: type: string required: - error description: Error response. '404': description: No checkout with that id. content: application/json: schema: type: object properties: error: type: string required: - error description: Error response. security: [] ````