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
Quick Start
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
Error Handling
Constructor Options
| Option | Type | Required | Description |
|---|---|---|---|
apiKey | string | Yes | Your API key (tor_live_… or tor_test_…) |
baseURL | string | No | API base URL. Defaults to https://toreador.io/api/v1/public |
fetch | function | No | Custom 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
| Event | Trigger |
|---|---|
session.created | When /create-session succeeds |
session.submitted | Payer has broadcast the transaction |
session.confirming | First on-chain confirmation |
session.completed | Required confirmations reached |
session.expired | 15-minute expiry passed |
session.failed | Transaction failed on-chain |
checkout.created | When /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
| Header | Value |
|---|---|
Toreador-Signature | t=1761123121,v1=0xabc... |
Toreador-Event-Id | evt_xxx — consumer-side idempotency |
Toreador-Event-Type | session.completed |
Toreador-Delivery-Id | whd_xxx |
Toreador-Attempt | attempt number (1, 2, 3, ...) |
Example: Express + official SDK
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