Checkout

Taberna hosts the page the buyer pays on. You never build coin selection, exchange-rate display, deposit addresses, QR codes or confirmation progress — you redirect, and you wait for the result.

Resource	Where you get the link	Page
Order	`checkoutUrl` from `POST /v1/orders`	`{HOME_URL}/checkout/{shortId}`
Invoice	`url` from `POST /v1/invoices`	`{HOME_URL}/invoice/{shortId}`

Always use the URL Taberna returned. Do not construct it yourself — the host is environment-specific and the path may change.

What the buyer sees

Pick a token

The page offers the tokens in your store’s enabledPaymentMethods and nothing else. Choosing one starts a payment attempt.

Pay a locked quote

Taberna locks a crypto quote, generates a fresh deposit wallet for this one attempt, and shows the exact amount and address. The quote holds for up to 30 minutes — precisely, until min(now + 30 minutes, the order or invoice's own expiry), because a locked quote must never outlive its parent.

Watch it confirm

Taberna watches the chain and reports progress: detected, confirming, confirmed. See confirmation progress.

Land back in your app

On completion the page shows a Continue button pointing at your successUrl. The dead-end states — expired, partial, and voided for invoices — link to cancelUrl. Without them the buyer simply stays on the hosted page, so setting at least successUrl is recommended.

If the quote lapses

Nothing is lost. An attempt that expires holding zero funds leaves the parent order or invoice untouched and still payable — the buyer picks a token again and gets a fresh quote, and can keep doing that until the parent itself expires. An attempt that expires holding a non-zero but insufficient amount turns the parent partial, which is terminal. See Payment lifecycle.

If the buyer switches token mid-attempt

Also fine, and worth understanding precisely:

Re-selecting the same token returns the same attempt — same address, same locked quote. Reloading the page is safe.
Selecting a different token abandons the live attempt and locks a new quote on a newly generated address.

An abandoned attempt’s address stays watched until its own window ends. Funds sent to it after the buyer switched still complete the order or invoice. Abandonment is a UI affordance, not a lifecycle event — it emits no webhook.

The public checkout endpoints

The hosted page reads and drives payment through the /v1/checkouts endpoints. These are deliberately unauthenticated.

Possession of the short id is the credential. It is unguessable in practice, and every payload served here is redacted for a buyer audience — no buyer email, no merchant metadata, no payer IP. Never send an API key from a browser.The corollary: do not treat the id as a secret beyond being unguessable, and never grant value based on a status a browser reported. Fulfil from a webhook or a server-side read.

Retrieve a checkout

GET /v1/checkouts/{id} — no auth. {id} accepts either an order short id or an invoice short id; one resource serves both hosted pages. The response is a tagged union: read type first, then the branch fields.

type: order
type: invoice

{
  "type": "order",
  "id": "CcvnKdAXzvW8h3JaS1VJe",
  "storeId": "0197f8a0-2222-7bbb-9ddd-4f6e8dac2b35",
  "status": "pending",
  "priceAmount": "50",
  "priceCurrency": "usd",
  "successUrl": "https://yourapp.com/thanks",
  "cancelUrl": "https://yourapp.com/cart",
  "expiresAt": "2026-07-09T12:30:00.000Z",
  "completedAt": null,
  "items": [
    {
      "productId": "0197f8a0-1111-7aaa-8ccc-3e5d7c9b1a24",
      "title": "Pro licence",
      "image": null,
      "quantity": 1,
      "unitPrice": "50",
      "delivery": null
    }
  ],
  "hasCustomerEmail": true,
  "store": {
    "id": "0197f8a0-2222-7bbb-9ddd-4f6e8dac2b35",
    "name": "My Store",
    "image": null,
    "enabledPaymentMethods": ["usdc_base", "sol"],
    "requireCustomerEmail": true
  },
  "activeAttempt": null
}

items[].delivery is null until the order is completed — see Products and delivery.Deliberately absent: customerEmail, extraContext, the payer IP. The page only learns whether an email is on file, via hasCustomerEmail.

{
  "type": "invoice",
  "id": "CcvnBwRQaKY1rXSMLrbYe",
  "number": 42,
  "status": "open",
  "items": [
    {
      "name": "124 credits",
      "description": null,
      "quantity": 1,
      "unitAmount": "124",
      "amount": "124"
    }
  ],
  "totalAmount": "124",
  "currency": "usd",
  "customerName": "Ada Lovelace",
  "memo": null,
  "successUrl": "https://yourapp.com/topup/success",
  "cancelUrl": "https://yourapp.com/topup",
  "expiresAt": "2026-07-09T13:00:00.000Z",
  "paidAt": null,
  "store": {
    "id": "0197f8a0-2222-7bbb-9ddd-4f6e8dac2b35",
    "name": "My Store",
    "image": null,
    "enabledPaymentMethods": ["usdc_base", "sol"]
  },
  "activeAttempt": null
}

Deliberately absent: metadata, customerEmail, createdVia. The invoice branch also carries no requireCustomerEmail on store — an invoice’s recipient is set by the merchant who issued it.

A well-formed id that resolves to nothing answers 404 with { "error": "Checkout not found" } — the same message for both resources, so the endpoint never reveals which one you probed.

A malformed id never reaches the lookup. Every route that takes a short id validates it against the short-id pattern first — 21 or 22 base58 characters — and an id that fails that check is rejected by the validator as 400 { "error": "Invalid request data" }. 404 is reserved for ids that pass the pattern and then either fail to decode or decode to nothing.

The active attempt

activeAttempt is null when no quote is live, and otherwise:

{
  "status": "processing",
  "paymentMethod": "usdc_base",
  "cryptoAmount": "50010000",
  "receivedAmount": "50010000",
  "destinationAddress": "0x…",
  "transactions": [
    {
      "blockchain": "base",
      "txHash": "0xabc…",
      "fromAddress": "0xdef…",
      "amount": "50010000",
      "blockNumber": "21458822",
      "blockTime": "2026-07-09T12:15:02.000Z"
    }
  ],
  "confirmation": {
    "state": "confirming",
    "confirmations": 4,
    "required": 10,
    "stale": false
  },
  "expiresAt": "2026-07-09T12:30:00.000Z",
  "completedAt": null
}

cryptoAmount and receivedAmount are integer strings in the token’s smallest unit. transactions is [] until a transfer is attributed.

Confirmation progress

confirmation is payer-facing progress, and nothing gates on it.

Field	Meaning
`state`	`waiting`, `detected`, `confirming` or `confirmed`
`confirmations`	Depth reached, clamped to at most `required`. `null` when unknown.
`required`	Depth the chain’s indexer is waiting for. `null` when unknown.
`stale`	`true` when the counts cannot be trusted

Do not render progress while stale is true, and do not treat confirmed as “paid”. A confirmed state says the transfers on file are buried deeply enough — it says nothing about whether they add up to the amount owed. An underpayment can sit at confirmed indefinitely. The authoritative signal is the order or invoice status.

See Payment lifecycle for how each state arises and what the per-chain depths are.

Start a payment attempt

POST /v1/checkouts/{id}/attempts — no auth. Driven by the checkout UI; you normally do not call this.

Request

{ "paymentMethod": "usdc_base" }

Returns the refreshed checkout union — the same payload as the GET, now carrying the new activeAttempt. Works on both branches.

Status	Message	Cause
`404`	`Checkout not found`	A well-formed id that resolves to nothing
`400`	`Invalid request data`	The id is not a well-formed short id, or the body failed validation — e.g. an unrecognised `paymentMethod`
`400`	`Payment method is not enabled for this store`	Valid token, but not in `enabledPaymentMethods`
`400`	`Order is not payable` / `Invoice is not payable`	The parent is no longer `pending` / `open`
`400`	`Order has expired` / `Invoice has expired`	The parent’s window has passed
`400`	`Order is no longer payable` / `Invoice is no longer payable`	The parent changed state while the attempt was being created
`400`	`Exchange rates are temporarily unavailable, please try again`	No fresh enough rate to quote against

Taberna refuses to price an attempt on a stale exchange rate rather than risk mis-quoting it. That last error is transient — the buyer retrying a moment later normally succeeds.

Attach a receipt email (orders only)

PUT /v1/checkouts/{id}/email — no auth.

Request

{ "email": "buyer@example.com" }

200 OK

{ "hasCustomerEmail": true }

The address is never echoed back — the checkout payload only ever reports the boolean.

Status	Message	Cause
`404`	`Checkout not found`	A well-formed id that resolves to nothing
`400`	`Invalid request data`	The id is not a well-formed short id, or the body is not a valid email address
`400`	`Order is no longer accepting changes`	The order is no longer `pending`
`400`	`Not applicable to invoice checkouts`	The id belongs to an invoice

This route is order-only. An invoice’s recipient is set by the merchant who issued it, so passing an invoice id is a 400 — not a 404.

Get a delivery download link (orders only)

GET /v1/checkouts/{id}/download/{orderItemId} — no auth. Mints a short-lived presigned URL for a file_shared delivery on a completed order item.

200 OK

{
  "url": "https://…presigned…",
  "fileName": "handbook.pdf",
  "expiresIn": 300
}

expiresIn is the link’s lifetime in seconds — 300, five minutes. Every substantive failure — unknown checkout, order not completed, wrong item, a delivery that is not a file, an invoice id — answers with the same 404 and the same message, { "error": "Download not available" }, so the endpoint never reveals which check failed.

Both path segments are short ids and both are validated first, as everywhere else: if {id} or {orderItemId} is not a well-formed short id the request is rejected as 400 { "error": "Invalid request data" } before any lookup runs.

Polling

You may poll GET /v1/checkouts/{id} as a fallback, and the hosted page does exactly that while an attempt is live. But for your integration:

Webhooks are the recommended completion signal. If you poll from your own server, poll the authenticated endpoints — GET /v1/orders/{id} or GET /v1/invoices/{id} — not the public checkout resource. They are the merchant view, they carry extraContext and metadata, and they are not readable by anyone holding the link.

Reasonable polling shape, if you need one:

// Reconciliation fallback — webhooks remain primary.
async function reconcile(orderId, { attempts = 20, intervalMs = 15_000 } = {}) {
	for (let i = 0; i < attempts; i++) {
		const res = await fetch(`https://api.taberna.io/v1/orders/${orderId}`, {
			headers: { Authorization: `Bearer ${process.env.TABERNA_API_KEY}` },
		});
		if (!res.ok) throw new Error((await res.json()).error);

		const order = await res.json();
		if (order.status !== 'pending') return order; // completed, partial or expired

		await new Promise((r) => setTimeout(r, intervalMs));
	}
	return null; // still pending — leave it to the webhook
}

Stop polling as soon as status leaves pending (or open, for invoices): every other state is terminal.

Get started

Charging a customer

Getting paid

Reference

What the buyer sees

If the quote lapses

If the buyer switches token mid-attempt

The public checkout endpoints

Retrieve a checkout

The active attempt

Confirmation progress

Start a payment attempt

Attach a receipt email (orders only)

Get a delivery download link (orders only)

Polling

​What the buyer sees

​If the quote lapses

​If the buyer switches token mid-attempt

​The public checkout endpoints

​Retrieve a checkout

​The active attempt

​Confirmation progress

​Start a payment attempt

​Attach a receipt email (orders only)

​Get a delivery download link (orders only)

​Polling

What the buyer sees

If the quote lapses

If the buyer switches token mid-attempt

The public checkout endpoints

Retrieve a checkout

The active attempt

Confirmation progress

Start a payment attempt

Attach a receipt email (orders only)

Get a delivery download link (orders only)

Polling