Entwickler

Dokumentation

Alles, was Sie brauchen, um Toreador in Ihre Anwendung zu integrieren.

REST API Vollständige Referenz der HTTP-API: Endpunkte, Authentifizierung, Fehler, Paginierung. Referenz ansehen TypeScript SDK Das offizielle @toreador/sdk für Node.js, Deno und Edge-Runtimes. Anleitung lesen Webhooks Mit HMAC-SHA256 signierte HTTPS-Benachrichtigungen, wenn sich der Status Ihrer Sitzungen ändert. Anleitung lesen WordPress-Plugin Installieren Sie das Plugin, verbinden Sie Ihre Website und kassieren Sie in Krypto mit WooCommerce und Ihren Formularen. Anleitung lesen Häufige Fragen Verwahrung, Zahlungen, Wallets, Tarife und Verifizierung: die Antworten, nach Thema geordnet. Antworten lesen
Inhalt

TypeScript SDK

Das offizielle @toreador/sdk bietet eine typsichere TypeScript-Schnittstelle für die Toreador API. Kompatibel mit Node.js 18+, Deno und modernen Browsern.

Installation

Terminal
npm install @toreador/sdk

Schnellstart

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,...

Verfügbare Methoden

client.checkouts.create(params)

Erstellt eine Zahlungsanforderung in USD oder EUR: Der Zahler wählt den Stablecoin und das Netzwerk auf der gehosteten Seite. Die massgebliche Ressource für eine Integration.

Rückgabe: { checkoutId, url, allowedRails, expiresAt, ... }

client.payments.retrieve(id)

Einheitliches Zahlungsobjekt nach Checkout-ID (co_…) oder Sitzungs-ID: Status, Transaktions-Hash, Zeitachse.

Rückgabe: { id, status, token, chain, amount, txHash, timeline, ... }

client.qrcode.generate(params)

Erstellt einen QR-Code für native Token (BTC, ETH, SOL, POL) oder Solana-SPL-Token.

Rückgabe: { success, type, qrData, qrCodeURL, token, chain, amount, recipientAddress }

client.qrcode.history()

Listet Ihre letzten 50 erstellten QR-Codes auf.

Rückgabe: { data: PaymentRecord[], has_more, next_cursor }

client.sessions.create(params)

Erstellt eine Zahlungssitzung für nicht-native EVM-Token (USDC, USDT, EURC).

Rückgabe: { sessionId, url, expiresIn, ... }

client.sessions.list()

Listet Ihre letzten 50 Zahlungssitzungen auf.

Rückgabe: { data: SessionRecord[], has_more, next_cursor }

client.sessions.getStatus(sessionId)

Prüft den Status einer Zahlungssitzung.

Rückgabe: { status: 'pending' | 'submitted' | 'confirming' | 'completed' | 'expired' | 'failed', ... }

client.account.establishments()

Die Standorte Ihrer Organisation auflisten. Zahlungen tragen ihren Standort, unabhängig davon, wer im Team sie erstellt hat.

Rückgabe: { data: Establishment[] }

client.payments.export(options)

Bestätigte Zahlungen als JSON oder CSV exportieren oder als Importdatei für Banktransaktionen einer Buchhaltungssoftware (quickbooks, xero, odoo, pennylane).

Rückgabe: { count, truncated, data: ExportRecord[] } | string

Beispiel: USDC-Zahlungssitzung

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' | ...

Fehlerbehandlung

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
  }
}

Konstruktoroptionen

OptionTypeErforderlichDescription
apiKeystringJaIhr API-Schlüssel (tor_live_… oder tor_test_…)
baseURLstringNoBasis-URL der API. Standard: https://toreador.io/api/v1/public
fetchfunctionNoEigene fetch-Implementierung. Standard: globalThis.fetch

Webhooks

Empfangen Sie mit HMAC-SHA256 signierte Ereignisse in Echtzeit, wenn sich der Status Ihrer Sitzungen ändert. Konfigurieren Sie Endpunkte in Ihrem Dashboard.

Gesendete Ereignisse

EventAuslöser
session.createdWenn /create-session erfolgreich ist
session.submittedDer Zahler hat die Transaktion übermittelt
session.confirmingErste Bestätigung auf der Blockchain
session.completedErforderliche Bestätigungen erreicht
session.expiredAblauffrist von 15 Minuten überschritten
session.failedTransaktion auf der Blockchain fehlgeschlagen
checkout.createdWenn /checkout erfolgreich ist

Signaturprüfung

Jede Zustellung enthält einen Header Toreador-Signature: t=<unix>,v1=<hex>. Die Signatur ist ein HMAC-SHA256 über <timestamp>.<rawBody> mit dem Secret Ihres Endpunkts. Prüfen Sie immer die Signatur, bevor Sie das Ereignis verarbeiten.

Gesendete Header

HeaderWert
Toreador-Signaturet=1761123121,v1=0xabc...
Toreador-Event-Idevt_xxx — Idempotenz auf Empfängerseite
Toreador-Event-Typesession.completed
Toreador-Delivery-Idwhd_xxx
Toreador-AttemptNummer des Versuchs (1, 2, 3, ...)

Beispiel: Express + offizielles 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;
  }
});

Wiederholungsrichtlinie

Gibt Ihr Endpunkt keinen 2xx-Code zurück oder antwortet er nicht innerhalb von 10 Sekunden, wiederholt Toreador die Zustellung mit exponentiellem Backoff: 0s, 5s, 5min, 30min, 2h, 5h, 10h, 24h, 48h (insgesamt 9 Versuche über ~4 Tage), danach Status failed. Ein Endpunkt wird nach 50 aufeinanderfolgenden Fehlschlägen automatisch deaktiviert.

Zustellungen können im Dashboard manuell wiederholt werden. Idempotenz auf Empfängerseite: Verwenden Sie den Header Toreador-Event-Id, um Duplikate zu erkennen.

Bereit loszulegen?

Erstellen Sie ein kostenloses Konto, um Ihren API-Schlüssel zu erhalten – einen Testschlüssel für die Sandbox, einen Live-Schlüssel für das Mainnet – und beginnen Sie mit der Integration von Toreador.

Preise ansehen

Wir respektieren Ihre Privatsphäre

Wir verwenden Analyse-Cookies, um unseren Dienst zu verbessern. Diese Cookies werden nur mit Ihrer Einwilligung aktiviert. Notwendige Cookies (Authentifizierung, Sprache usw.) sind immer aktiv.