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
Schnellstart
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
Fehlerbehandlung
Konstruktoroptionen
| Option | Type | Erforderlich | Description |
|---|---|---|---|
apiKey | string | Ja | Ihr API-Schlüssel (tor_live_… oder tor_test_…) |
baseURL | string | No | Basis-URL der API. Standard: https://toreador.io/api/v1/public |
fetch | function | No | Eigene 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
| Event | Auslöser |
|---|---|
session.created | Wenn /create-session erfolgreich ist |
session.submitted | Der Zahler hat die Transaktion übermittelt |
session.confirming | Erste Bestätigung auf der Blockchain |
session.completed | Erforderliche Bestätigungen erreicht |
session.expired | Ablauffrist von 15 Minuten überschritten |
session.failed | Transaktion auf der Blockchain fehlgeschlagen |
checkout.created | Wenn /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
| Header | Wert |
|---|---|
Toreador-Signature | t=1761123121,v1=0xabc... |
Toreador-Event-Id | evt_xxx — Idempotenz auf Empfängerseite |
Toreador-Event-Type | session.completed |
Toreador-Delivery-Id | whd_xxx |
Toreador-Attempt | Nummer des Versuchs (1, 2, 3, ...) |
Beispiel: Express + offizielles SDK
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