Quickstart

This walks the order flow end to end. If your amounts are decided per request rather than drawn from a catalogue, read Invoices instead — steps 1 to 3 are identical and step 4 becomes a single POST /v1/invoices call with no product setup.

There is no test mode yet. Every payment method is a live chain and every payment moves real funds. Develop against small amounts, and expect a real transfer to be needed before an order reaches completed.

Create a store and make it payable

In the dashboard:

Create a store. Give it a name and an image — both appear on the hosted checkout page the buyer sees.
Enable payment methods. Pick from the 13 supported methods. A store with none enabled cannot create orders: POST /v1/orders fails with Store has no payment methods enabled.
Set a payout wallet per chain. This is where swept funds go. Register an address for every chain whose methods you enabled.

Starting with a single stablecoin on a cheap chain — usdc_base — keeps the buyer’s gas cost low and removes exchange-rate volatility from the payment window.

Create at least one listed product

Still in the dashboard, create a product with a title, a price (a decimal string like "50.00"), a currency (usd or eur), and — importantly — listed turned on.An unlisted product is rejected at order creation with Product is not available. Note the product’s id, a UUID: that is what you pass as productId.Optionally attach a delivery — a pool of licence keys, a shared file, a redirect. See Products and delivery.

Mint an API key with the scopes you need

In the dashboard’s developer settings, create a key. You must choose scopes; there is no implicit full-access key. For this quickstart:

orders:write — to create and expire orders
orders:read — to read them back

The raw key is shown once, at creation. Taberna stores only a SHA-256 hash, so if you lose it, revoke and mint a new one.Verify it works with the whoami call, which needs no scope at all:

curl https://api.taberna.io/v1/store \
  -H 'Authorization: Bearer tbrn_live_3f1c2b9a7d4e4f889a102c6e5b4d1a90aabbccdd001122'

const res = await fetch('https://api.taberna.io/v1/store', {
	headers: { Authorization: `Bearer ${process.env.TABERNA_API_KEY}` },
});
const store = await res.json();
console.log(store.name, store.scopes, store.enabledPaymentMethods);

import os, requests

res = requests.get(
	"https://api.taberna.io/v1/store",
	headers={"Authorization": f"Bearer {os.environ['TABERNA_API_KEY']}"},
)
store = res.json()
print(store["name"], store["scopes"], store["enabledPaymentMethods"])

Response

{
  "id": "0197f8a0-2222-7bbb-9ddd-4f6e8dac2b35",
  "name": "My Store",
  "image": null,
  "enabledPaymentMethods": ["usdc_base", "sol"],
  "requireCustomerEmail": true,
  "createdAt": "2026-07-01T09:12:44.000Z",
  "slug": "my-store",
  "storefrontEnabled": true,
  "scopes": ["orders:read", "orders:write"],
  "storefrontUrl": "https://my-store.taberna.io"
}

The scopes array is the calling key’s own — so an integration can discover what it may do without provoking a 403 to find out. enabledPaymentMethods confirms step 1 landed.

Create an order

curl -X POST https://api.taberna.io/v1/orders \
  -H 'Authorization: Bearer tbrn_live_3f1c2b9a7d4e4f889a102c6e5b4d1a90aabbccdd001122' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: purchase_8213' \
  -d '{
    "items": [{ "productId": "0197f8a0-1111-7aaa-8ccc-3e5d7c9b1a24", "quantity": 1 }],
    "customerEmail": "buyer@example.com",
    "extraContext": { "userId": "u_123" },
    "successUrl": "https://yourapp.com/thanks",
    "cancelUrl": "https://yourapp.com/pricing"
  }'

const res = await fetch('https://api.taberna.io/v1/orders', {
	method: 'POST',
	headers: {
		Authorization: `Bearer ${process.env.TABERNA_API_KEY}`,
		'Content-Type': 'application/json',
		'Idempotency-Key': purchaseId,
	},
	body: JSON.stringify({
		items: [{ productId: PRODUCT_ID, quantity: 1 }],
		customerEmail: user.email,
		extraContext: { userId: user.id },
		successUrl: 'https://yourapp.com/thanks',
		cancelUrl: 'https://yourapp.com/pricing',
	}),
});
if (!res.ok) throw new Error((await res.json()).error);
const order = await res.json();

import os, requests

res = requests.post(
	"https://api.taberna.io/v1/orders",
	headers={
		"Authorization": f"Bearer {os.environ['TABERNA_API_KEY']}",
		"Content-Type": "application/json",
		"Idempotency-Key": purchase_id,
	},
	json={
		"items": [{"productId": PRODUCT_ID, "quantity": 1}],
		"customerEmail": user.email,
		"extraContext": {"userId": user.id},
		"successUrl": "https://yourapp.com/thanks",
		"cancelUrl": "https://yourapp.com/pricing",
	},
)
if not res.ok:
	raise RuntimeError(res.json()["error"])
order = res.json()

201 Created

{
  "id": "CcvnKdAXzvW8h3JaS1VJe",
  "checkoutUrl": "https://taberna.io/checkout/CcvnKdAXzvW8h3JaS1VJe",
  "status": "pending",
  "expiresAt": "2026-07-09T12:30:00.000Z",
  "items": [
    {
      "productId": "0197f8a0-1111-7aaa-8ccc-3e5d7c9b1a24",
      "title": "Pro licence",
      "quantity": 1,
      "unitPrice": "50",
      "currency": "usd"
    }
  ]
}

Three things to do with that response:

Persist id. It is the order’s public short id and the value every webhook for this order carries as data.id.
Note expiresAt. 30 minutes from creation by default; pass expiresIn (10 minutes to 90 days) to widen it.
Use extraContext to carry your own correlation data. It is echoed back verbatim in every webhook for this order, which is how you find the user again.

The Idempotency-Key header makes the create safe to retry. A repeat with the same key returns the original order rather than minting a second one — no matter how the body changed.

Redirect the buyer to checkoutUrl

Send the customer to checkoutUrl. Everything from there is Taberna’s hosted page: the buyer picks a token from your enabled methods, gets a locked quote and a deposit address, pays, and watches confirmations tick up.When the payment completes, the page shows a Continue button pointing at your successUrl. The dead-end states — expired, partial — link to cancelUrl. Neither is required, but without successUrl the buyer simply stays on the hosted page.

Never grant anything based on the buyer arriving at your successUrl. It is a browser redirect with no authentication. Fulfil on the webhook, or on a server-side read of GET /v1/orders/:id.

Learn that it was paid

Two mechanisms, and you want the first.Webhooks (recommended). Set a webhook URL in the dashboard, save the returned tbrn_whsec_… secret, and handle order.completed:

Node.js (Express)

import crypto from 'node:crypto';
import express from 'express';

const app = express();

// The raw body is required — a re-serialized object will not match the signature.
app.post(
	'/webhooks/taberna',
	express.raw({ type: 'application/json' }),
	(req, res) => {
		const timestamp = req.get('x-taberna-timestamp');
		const received = req.get('x-taberna-signature');
		if (!timestamp || !received) return res.sendStatus(400);

		const expected = crypto
			.createHmac('sha256', process.env.TABERNA_WEBHOOK_SECRET)
			.update(`${timestamp}.${req.body}`)
			.digest('hex');

		const a = Buffer.from(expected);
		const b = Buffer.from(received);
		if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
			return res.sendStatus(400);
		}

		// Reject stale timestamps to blunt replays (5-minute tolerance).
		if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
			return res.sendStatus(400);
		}

		const { event, data } = JSON.parse(req.body.toString('utf8'));
		if (event === 'order.completed') {
			// Idempotent: this may arrive more than once.
			fulfil(data.extraContext.userId, data.id);
		}

		res.sendStatus(200); // Respond fast; do heavy work asynchronously.
	},
);

Polling (fallback). Read the order back from your server whenever a webhook did not arrive:

curl https://api.taberna.io/v1/orders/CcvnKdAXzvW8h3JaS1VJe \
  -H 'Authorization: Bearer tbrn_live_…'

Act on status === "completed". See Webhooks for the full event list, signature scheme and retry schedule.

Authentication

The eight scopes, what each unlocks, and 401 versus 403.

Webhooks

Payload shapes, signature verification in three languages, retries.

Payment lifecycle

State machines, partial payments, confirmation depths.

Errors and limits

Status conventions, body limits, and what Taberna does not do yet.

Get started

Charging a customer

Getting paid

Reference

What to read next

Authentication

Webhooks

Payment lifecycle

Errors and limits

​What to read next

Authentication

Webhooks

Payment lifecycle

Errors and limits

What to read next