Developers

Documentation

Everything you need to integrate Toreador into your application.

REST API Complete HTTP API reference: endpoints, authentication, errors, pagination. View reference TypeScript SDK The official @toreador/sdk for Node.js, Deno, and edge runtimes. Read the guide Webhooks HMAC-SHA256-signed HTTPS notifications when your sessions change state. Read the guide WordPress plugin Install the plugin, connect your site and get paid in crypto with WooCommerce and your forms. Read the guide Common questions Custody, payments, wallets, plans and verification: the answers, by theme. Read the answers
Contents

TypeScript SDK

The official @toreador/sdk provides a type-safe TypeScript interface for the Toreador API. Compatible with Node.js 18+, Deno, and modern browsers.

Installation

Terminal
npm install @toreador/sdk

Quick Start

TypeScript
import Toreador from "@toreador/sdk";

// Initialize the client
const client = new Toreador({ apiKey: "tor_live_your_key_here" });

// Generate a Bitcoin QR code
const qr = await client.qrcode.generate({
  token: "BTC",
  chainId: "bitcoin",
  amount: "0.001",
  recipientAddress: "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
});

console.log(qr.qrCodeURL); // data:image/png;base64,...

Available Methods

client.checkouts.create(params)

Create a payment request in USD or EUR: the payer picks the stablecoin and the network on the hosted page. The canonical resource for an integration.

Returns: { checkoutId, url, allowedRails, expiresAt, ... }

client.payments.retrieve(id)

Unified payment object by checkout id (co_…) or session id: status, transaction hash, timeline.

Returns: { id, status, token, chain, amount, txHash, timeline, ... }

client.qrcode.generate(params)

Generate a QR code for native tokens (BTC, ETH, SOL, POL) or Solana SPL tokens.

Returns: { success, type, qrData, qrCodeURL, token, chain, amount, recipientAddress }

client.qrcode.history()

List your last 50 QR code generations.

Returns: { data: PaymentRecord[], has_more, next_cursor }

client.sessions.create(params)

Create a payment session for non-native EVM tokens (USDC, USDT, EURC).

Returns: { sessionId, url, expiresIn, ... }

client.sessions.list()

List your last 50 payment sessions.

Returns: { data: SessionRecord[], has_more, next_cursor }

client.sessions.getStatus(sessionId)

Check the status of a payment session.

Returns: { status: 'pending' | 'submitted' | 'confirming' | 'completed' | 'expired' | 'failed', ... }

client.account.establishments()

List the establishments of your organization. Payments carry their establishment, whoever on the team created them.

Returns: { data: Establishment[] }

client.payments.export(options)

Export confirmed payments as JSON or CSV, or as the bank-transaction import file of an accounting software (quickbooks, xero, odoo, pennylane).

Returns: { count, truncated, data: ExportRecord[] } | string

Example: USDC Payment Session

TypeScript
import Toreador from "@toreador/sdk";

const client = new Toreador({ apiKey: "tor_live_your_key_here" });

// Create a USDC payment session on Ethereum
const session = await client.sessions.create({
  token: "USDC",
  chainId: "ethereum",
  amount: "100",
  recipientAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
});

console.log(session.url);       // Payment page URL
console.log(session.expiresIn); // Seconds until expiry

// Check status later
const status = await client.sessions.getStatus(session.sessionId);
console.log(status.status); // 'pending' | 'completed' | ...

Error Handling

TypeScript
import { Toreador, ToreadorError } from "@toreador/sdk";

try {
  await client.qrcode.generate({ /* ... */ });
} catch (err) {
  if (err instanceof ToreadorError) {
    console.error(err.message); // "Missing required fields: ..."
    console.error(err.status);  // 400
    console.error(err.body);    // Full error response
  }
}

Constructor Options

OptionTypeRequiredDescription
apiKeystringYesYour API key (tor_live_… or tor_test_…)
baseURLstringNoAPI base URL. Defaults to https://toreador.io/api/v1/public
fetchfunctionNoCustom fetch implementation. Defaults to globalThis.fetch

Webhooks

Receive HMAC-SHA256-signed events in real time when your sessions change state. Configure endpoints from your dashboard.

Emitted events

EventTrigger
session.createdWhen /create-session succeeds
session.submittedPayer has broadcast the transaction
session.confirmingFirst on-chain confirmation
session.completedRequired confirmations reached
session.expired15-minute expiry passed
session.failedTransaction failed on-chain
checkout.createdWhen /checkout succeeds

Signature verification

Every delivery includes a Toreador-Signature: t=<unix>,v1=<hex> header. The signature is HMAC-SHA256 over <timestamp>.<rawBody> with your endpoint secret. Always verify the signature before processing the event.

Headers sent

HeaderValue
Toreador-Signaturet=1761123121,v1=0xabc...
Toreador-Event-Idevt_xxx — consumer-side idempotency
Toreador-Event-Typesession.completed
Toreador-Delivery-Idwhd_xxx
Toreador-Attemptattempt number (1, 2, 3, ...)

Example: Express + official SDK

TypeScript
import { webhooks, WebhookSignatureError } from "@toreador/sdk";
import express from "express";

const app = express();

// Raw body, not parsed JSON: the signature covers the exact bytes
app.post("/webhook", express.raw({ type: "application/json" }), async (req, res) => {
  try {
    const event = await webhooks.constructEvent(
      req.body.toString("utf8"),
      req.headers["toreador-signature"] as string,
      process.env.TOREADOR_WEBHOOK_SECRET!
    );

    if (event.type === "session.completed") {
      // fulfill order, update DB, send receipt, etc.
    }

    res.sendStatus(204);
  } catch (err) {
    if (err instanceof WebhookSignatureError) return res.sendStatus(400);
    throw err;
  }
});

Retry policy

If your endpoint returns non-2xx or does not respond within 10 seconds, Toreador retries with exponential backoff: 0s, 5s, 5min, 30min, 2h, 5h, 10h, 24h, 48h (9 attempts total over ~4 days), then status failed. An endpoint is auto-disabled after 50 consecutive failures.

Deliveries can be manually retried from the dashboard. Consumer-side idempotency: use the Toreador-Event-Id header to detect duplicates.

Ready to get started?

Create a free account to get your API key — a test key for the sandbox, a live key for mainnet — and start integrating Toreador.

See pricing

We respect your privacy

We use analytics cookies to improve our service. These cookies are only activated with your consent. Essential cookies (authentication, language etc.) are always active.