REST API
Die öffentliche HTTP-API von Toreador: Erstellen Sie Krypto-QR-Codes und Zahlungssessions ohne Verwahrung. Toreador verwahrt nie Gelder — jede Zahlung geht direkt vom Wallet des Zahlers an das Wallet des Händlers, auf der Blockchain.
https://toreador.io/api/v1/public
Maschinenlesbare Spezifikation: openapi.json (OpenAPI 3.1).
Authentication
Die meisten Endpoints erfordern einen API-Schlüssel, der im Header X-API-Key übergeben wird. Der Schlüssel identifiziert Ihr Konto; Ihre Berechtigungen (Tarif, Kontingent) werden bei jeder Anfrage geprüft. Erstellen Sie Ihre Schlüssel in Ihrem Dashboard.
tor_test_…
Testnet-Sandbox, für alle offen, ausserhalb des Kontingents. Für Entwicklung und Tests.
tor_live_…
Produktion (Mainnet). Abhängig vom Tarif und vom Kontingent der auf der Blockchain bestätigten Zahlungen.
Ratenlimits
Die Anfragerate ist pro Konto begrenzt (nicht pro Schlüssel). Bei Überschreitung wird 429 mit einem Header Retry-After zurückgegeben. Alle Endpoints erfordern einen Schlüssel (der kostenlose Tarif enthält einen).
- Rate pro Minute nach Tarif (Header
X-RateLimit-*in jeder Antwort).
| Tarif | API-Anfragerate | API-Schlüssel | Auf der Blockchain bestätigte Zahlungen / Monat |
|---|---|---|---|
| Free | 10/min | 1 | Unbegrenzt |
| Starter | 30/min | 1 | 150 |
| Pro | 120/min | 3 | 1000 |
| Plus | 600/min | 10 | 5000 |
| Entreprise | Unbegrenzt | Unbegrenzt | Unbegrenzt |
Werte der Standardtabelle; Ihr genaues Limit kann je nach Region abweichen und wird in Ihrem Dashboard angezeigt. Die Rate mit Schlüssel gilt pro Konto (wer mehrere Schlüssel erstellt, vervielfacht sie nicht).
Idempotenz
Fügen Sie bei POST-Anfragen einen Header Idempotency-Key hinzu: Eine Wiederholung mit demselben Schlüssel gibt die ursprüngliche Antwort zurück (Header Idempotent-Replayed: true), ohne eine Session neu zu erstellen. Gleicher Schlüssel + anderer Body → 409.
Fehler
Fehler verwenden eine Hülle mit doppelter Form: error bleibt ein String (Abwärtskompatibilität), und error_details enthält das typisierte Detail (code, type, message, request_id, doc_url).
Fehlercodes
| code | HTTP | Wann |
|---|---|---|
| missing_field | 400 | Ein Pflichtfeld fehlt (token, chainId, amount, recipientAddress). |
| invalid_parameter | 400 | Unbekannter Token, unbekannte Chain oder unbekanntes Format. |
| invalid_address | 400 | Die Empfängeradresse ist für diese Chain nicht gültig. |
| invalid_amount | 400 | Betrag ist keine Dezimalzahl oder liegt ausserhalb des Bereichs (0–1'000'000). |
| incompatible_token_chain | 400 | Dieser Token existiert auf dieser Chain nicht (z. B. BTC auf Ethereum). |
| wrong_endpoint | 400 | Falscher Endpunkt: nativ ↔ ERC-20 (verwenden Sie den anderen). |
| missing_api_key | 401 | API-Schlüssel fehlt. |
| invalid_api_key | 401 | API-Schlüssel ungültig oder widerrufen. |
| quota_exceeded | 402 | Monatliches Kontingent der auf der Blockchain bestätigten Zahlungen ausgeschöpft (enthält used/limit/upgrade_url). |
| forbidden | 403 | Der Schlüssel hat keinen Zugriff auf diese Ressource. |
| recipient_blocked | 403 | Die Empfängeradresse steht auf einer Sanktionsliste: Es wird weder ein QR-Code noch eine Zahlungsseite erstellt. |
| session_not_found | 404 | Sitzung nicht gefunden (oder abgelaufen/gelöscht). |
| payment_not_found | 404 | Zahlung nicht gefunden. |
| idempotency_conflict | 409 | Derselbe Idempotency-Key wurde mit einem anderen Body wiederverwendet. |
| no_rail | 409 | Kein nutzbarer Zahlungsweg für diese Zahlung: Das Paar aus Token und Netzwerk kann vom verbundenen Wallet der Kryptobörse nicht gutgeschrieben werden, oder der Emittent des Stablecoins hat die Empfangsadresse auf diesem Netzwerk eingefroren. |
| rate_limited | 429 | Rate überschritten (Header Retry-After). |
| internal_error | 500 | Unerwarteter Serverfehler — erneut versuchen, dann den Support kontaktieren. |
Pagination
Listen-Endpoints (/history, /sessions) sind per Cursor paginiert: Übergeben Sie limit (1–100, Standard 20) und cursor. Die Antwort enthält has_more und next_cursor — übergeben Sie Letzteren erneut, um die nächste Seite zu erhalten.
Endpoints
Endpunkt-Referenz
/ping
Schlüssel erforderlichPrüft die Verbindung und den API-Schlüssel. Gibt die Umgebung (test/live), den Tarif und die API-Version zurück. Ideal für eine Schaltfläche „Verbindung testen“.
Keine Parameter.
Antwortcodes
Anfrage
Antwort
Diesen Endpunkt testen
Die Anfrage geht in Ihrem Namen an die Live-API. Verwenden Sie einen Testschlüssel (tor_test_…) — ein Live-Aufruf erzeugt echte Daten. Der Schlüssel wird weder gespeichert noch anderswohin gesendet.
/account
Schlüssel erforderlichKontostatus: effektiver Tarif, Umgebung, Abonnement (Testphase oder bezahlt), monatliches Kontingent (used/limit/remaining) und Limits (Anfragerate, Schlüssel, Wallets). Das Feld subscription (status trialing/active, realPlan, trialEndsAt in Epoch-Sekunden, trialDaysRemaining) sollte das Tarif-Badge bestimmen — nicht plan allein, das während der Testphase 'plus' lautet.
Keine Parameter.
Antwortcodes
Anfrage
Antwort
Diesen Endpunkt testen
Die Anfrage geht in Ihrem Namen an die Live-API. Verwenden Sie einen Testschlüssel (tor_test_…) — ein Live-Aufruf erzeugt echte Daten. Der Schlüssel wird weder gespeichert noch anderswohin gesendet.
/tokens
Schlüssel erforderlichMatrix der unterstützten Zahlungen (Token × Chains), abgeleitet aus der Konfiguration (einzige Quelle der Wahrheit, Contracts auf der Blockchain verifiziert). Rufen Sie sie ab, statt die Liste fest einzuprogrammieren → so bleibt sie aktuell, wenn Chains oder Token hinzukommen. Zurückgegeben werden nur ZAHLBARE Paare (nativ oder ERC-20/SPL mit Contract). Die Contracts hängen von der Umgebung des Schlüssels ab (test/live).
Keine Parameter.
Antwortcodes
Anfrage
Antwort
Diesen Endpunkt testen
Die Anfrage geht in Ihrem Namen an die Live-API. Verwenden Sie einen Testschlüssel (tor_test_…) — ein Live-Aufruf erzeugt echte Daten. Der Schlüssel wird weder gespeichert noch anderswohin gesendet.
/screen
Schlüssel erforderlichPrüft, ob eine Krypto-Adresse auf den SANKTIONSLISTEN steht, die wir abfragen (Listen der OFAC, der EU, des Vereinigten Königreichs und der Schweiz, von uns heruntergeladen; zusätzlich das Chainalysis-Orakel auf der Blockchain für EVM-Adressen). Gibt sanctioned (true/false) zurück, oder null, wenn die Adresse nicht geprüft werden kann (ungültig, nicht unterstützte Chain, Orakel nicht verfügbar). Rufen Sie den Endpoint auf, bevor Sie Gelder senden oder empfangen. Das Ergebnis wird zwischengespeichert (Aktualität ~24 h).
sanctioned: null = Prüfung nicht möglich (ungültige Adresse, veraltete Liste, Orakel nicht verfügbar). Information zur Compliance, keine Rechtsberatung.address (query, erforderlich) — die zu prüfende Adresse.
Antwortcodes
Anfrage
Antwort
Diesen Endpunkt testen
Die Anfrage geht in Ihrem Namen an die Live-API. Verwenden Sie einen Testschlüssel (tor_test_…) — ein Live-Aufruf erzeugt echte Daten. Der Schlüssel wird weder gespeichert noch anderswohin gesendet.
/generate-qr
Schlüssel erforderlichErstellt einen QR-Code (PNG in Base64), der eine standardisierte Zahlungs-URI kodiert (BIP-21, EIP-681, Solana Pay). Für native Token (BTC, ETH, SOL, POL) und USDC auf Solana. Für ERC-20-Stablecoins auf EVM verwenden Sie /create-session.
X-RateLimit-*-Header in jeder Antwort.Body
| token* | string — BTC, ETH, SOL, POL, USDC (Solana) |
| chainId* | string — bitcoin, ethereum, polygon, base, solana |
| amount* | string — Kanonische Dezimalzahl (z. B. „0.001“) |
| recipientAddress* | string — Empfängeradresse (für die Blockchain validiert) |
| format | string — Ausgabeformat: png (Standard, base64-Data-URI), svg (Vektor-Markup) oder text (Blockzeichen zur Ausgabe in einem Terminal; zurückgegeben als qrCodeText). |
| textBackground | string — Für format: text: Hintergrund des Terminals, in dem der Text angezeigt wird, dark (Standard) oder light. Ein falscher Hintergrund ergibt einen invertierten QR-Code, den viele Smartphones nicht lesen können. |
Antwortcodes
Anfrage
Antwort
Diesen Endpunkt testen
Die Anfrage geht in Ihrem Namen an die Live-API. Verwenden Sie einen Testschlüssel (tor_test_…) — ein Live-Aufruf erzeugt echte Daten. Der Schlüssel wird weder gespeichert noch anderswohin gesendet.
/create-session
Schlüssel erforderlichErstellt eine gehostete Zahlungssession (Zahlung von Wallet zu Wallet, direkt an die Adresse des Händlers) für ERC-20-Stablecoins (USDC, USDT, EURC) auf Ethereum, Polygon und Base. Gibt eine /pay-URL zurück, die Sie mit dem Zahler teilen. Die Session läuft 15 Minuten nach ihrer Erstellung ab.
tor_test_…) erstellt eine Session in der Sandbox im Testnet, ausserhalb des Kontingents — ideal für die Entwicklung eines Plugins. Ein Live-Schlüssel (tor_live_…) zählt zum monatlichen Kontingent der auf der Blockchain bestätigten Zahlungen (402, wenn es aufgebraucht ist).Body
| token* | string — USDC, USDT, EURC, PYUSD, USDG, RLUSD, USAT, OUSD |
| chainId* | string — ethereum, polygon, base |
| amount* | string — Kanonische Dezimalzahl (z. B. „100“) |
| recipientAddress* | string — EVM-Empfängeradresse (im Kern validiert) |
Antwortcodes
Anfrage
Antwort
Diesen Endpunkt testen
Die Anfrage geht in Ihrem Namen an die Live-API. Verwenden Sie einen Testschlüssel (tor_test_…) — ein Live-Aufruf erzeugt echte Daten. Der Schlüssel wird weder gespeichert noch anderswohin gesendet.
/wallets
Schlüssel erforderlichListet (NUR LESEND) die Empfangsadressen des Kontos auf. Jedes Wallet liefert address, family, label, source, ownershipProven (true = Eigentum per signierter Nachricht nachgewiesen, oder Adresse von einer verbundenen Börse ausgelesen), custodial (true = Einzahlungsadresse des eigenen Börsenkontos DES HÄNDLERS, z. B. Binance/Coinbase, von der Börse verwahrt, niemals von Toreador) und acceptedRails: null = keine Einschränkung (selbstverwahrt, alle Netzwerke der Familie); andernfalls die Paare (Token, Chain), die die verwahrende Quelle AUF DIESER Adresse gutschreibt. WICHTIG: Beschränken Sie bei einem verwahrten Wallet Ihre Zahlungsmatrix auf acceptedRails — ein nicht gutgeschriebenes Paar wird dem Zahler nicht angeboten (die Börse würde es nicht gutschreiben, und die Gelder gingen verloren). Wallets werden im authentifizierten Dashboard (Passkey) hinzugefügt oder entfernt — niemals über die API.
Keine Parameter.
Antwortcodes
Anfrage
Antwort
Diesen Endpunkt testen
Die Anfrage geht in Ihrem Namen an die Live-API. Verwenden Sie einen Testschlüssel (tor_test_…) — ein Live-Aufruf erzeugt echte Daten. Der Schlüssel wird weder gespeichert noch anderswohin gesendet.
/checkout
Schlüssel erforderlichErstellt einen Checkout in FIAT-Währung (USD/EUR): Der Händler legt einen Betrag in Fiat fest, der Zahler verbindet ein Wallet auf der gehosteten Seite /pay (Zahlung von Wallet zu Wallet, direkt an die Adresse des Händlers) und wählt selbst Stablecoin und Chain. Für Integrationen zu bevorzugen (der Händler muss „USDC auf Base“ nicht verstehen).
conversion:"off" (Standard) bietet nur Stablecoins derselben Währung an (USD→USDC/USDT). conversion:"on" bietet auch Stablecoins der anderen Währung an: Der geschuldete Betrag wird anhand eines unverbindlichen Referenzkurses berechnet (Quelle und Zeitstempel werden gespeichert) und bei der Wahl des Zahlungswegs festgeschrieben. Toreador führt keine Umrechnung durch: Der Zahler sendet diesen Stablecoin direkt an das Wallet des Händlers.Body
| amount* | number — Betrag in WÄHRUNG (z. B. 50), nicht in Token |
| currency* | string — USD, EUR |
| recipientAddress* | string — Empfangsadresse (EVM 0x… oder Solana). Wird von IHREM System geliefert — übernimmt die Rotation. |
| description | string — Dem Zahler angezeigte Bezeichnung (≤ 500 Zeichen) |
| conversion | string — „off“ (Standard) oder „on“ |
| acceptNative | boolean — Zusätzlich eine NATIVE Krypto-Zahlung anbieten (ETH/POL); Betrag zum aktuellen Kurs berechnet (unverbindlicher Richtwert). Der Händler trägt die Volatilität. |
| reference | string — Freie Referenz (z. B. Bestellnummer), wiedergegeben im Checkout, in /payment/{id} und /sessions — um die Zahlung auf Ihrer Seite zuzuordnen (≤ 255 Zeichen). |
Antwortcodes
Anfrage
Antwort
Diesen Endpunkt testen
Die Anfrage geht in Ihrem Namen an die Live-API. Verwenden Sie einen Testschlüssel (tor_test_…) — ein Live-Aufruf erzeugt echte Daten. Der Schlüssel wird weder gespeichert noch anderswohin gesendet.
/webhooks
Schlüssel erforderlichRegistriert (oder aktualisiert, IDEMPOTENT pro URL) den Webhook-Endpoint des Kontos, um Events per PUSH zu empfangen. Eine Integration ruft ihn nach Connect automatisch auf. Gibt das HMAC-Secret EIN EINZIGES MAL zurück — speichern Sie es verschlüsselt. Die URL muss öffentliches HTTPS sein und, falls der Schlüssel über Connect ausgestellt wurde, auf der Domain des Schlüssels liegen.
Body
| url* | string — Öffentlicher HTTPS-Endpunkt (auf der Domain des Schlüssels) |
| events | string[] — Abonnierte Ereignisse (Standard: session.completed/failed/expired) |
| description | string — Bezeichnung (≤ 200 Zeichen) |
Antwortcodes
Anfrage
Antwort
Diesen Endpunkt testen
Die Anfrage geht in Ihrem Namen an die Live-API. Verwenden Sie einen Testschlüssel (tor_test_…) — ein Live-Aufruf erzeugt echte Daten. Der Schlüssel wird weder gespeichert noch anderswohin gesendet.
/payment/{id}
Schlüssel erforderlichRuft ein einheitliches Payment-Objekt ab — nativer QR (type: native) oder ERC-20-Session (type: session) — mit seinem Ereignisverlauf. Akzeptiert AUCH eine Checkout-ID (co_…): Sie wird zur Zahlung dieses Checkouts aufgelöst (ideal, um eine Bestellung über ihre checkoutId zu verfolgen, ohne die Session-ID zu kennen).
Pfadparameter
| id* | string — Zahlungs- / Sitzungs-ID ODER eine Checkout-ID (co_…) |
Antwortcodes
Anfrage
Antwort
Diesen Endpunkt testen
Die Anfrage geht in Ihrem Namen an die Live-API. Verwenden Sie einen Testschlüssel (tor_test_…) — ein Live-Aufruf erzeugt echte Daten. Der Schlüssel wird weder gespeichert noch anderswohin gesendet.
/payment/{id}/status
Schlüssel erforderlichGibt den aktuellen Status einer Zahlungssession zurück. Für die Echtzeit-Nachverfolgung auf Seite des Zahlers nutzt die Seite /pay einen SSE-Stream; serverseitig sollten Sie signierte Webhooks bevorzugen (siehe unten).
Pfadparameter
| id* | string — Sitzungs-ID (von /create-session zurückgegeben) |
Antwortcodes
Anfrage
Antwort
Diesen Endpunkt testen
Die Anfrage geht in Ihrem Namen an die Live-API. Verwenden Sie einen Testschlüssel (tor_test_…) — ein Live-Aufruf erzeugt echte Daten. Der Schlüssel wird weder gespeichert noch anderswohin gesendet.
/establishments
Schlüssel erforderlichListet (NUR LESEND) die Standorte des Schlüssels auf: id, name, isDefault. Eine ID dient als establishment_id, sowohl beim Erstellen einer Zahlungsanforderung als auch als Filter für /sessions, /history und /export.
Keine Parameter.
Antwortcodes
Anfrage
Antwort
Diesen Endpunkt testen
Die Anfrage geht in Ihrem Namen an die Live-API. Verwenden Sie einen Testschlüssel (tor_test_…) — ein Live-Aufruf erzeugt echte Daten. Der Schlüssel wird weder gespeichert noch anderswohin gesendet.
/history
Schlüssel erforderlichPaginierte Liste der von der Organisation des Schlüssels und ihrem Team erstellten QR-Codes (neueste zuerst). Jeder Eintrag enthält establishmentId und establishmentName. Ein Schlüssel liefert nur die Zahlungen seiner eigenen Umgebung: Ein Live-Schlüssel liefert nie Testzahlungen, ein Testschlüssel liefert nur Testzahlungen.
Query-Parameter
| limit | integer — 1–100, Standard 20 |
| cursor | string — Opaker Cursor (next_cursor der vorherigen Seite) |
| establishment_id | string — Nur die Zahlungen dieses Standorts (eine id aus GET /establishments) |
Antwortcodes
Anfrage
Antwort
Diesen Endpunkt testen
Die Anfrage geht in Ihrem Namen an die Live-API. Verwenden Sie einen Testschlüssel (tor_test_…) — ein Live-Aufruf erzeugt echte Daten. Der Schlüssel wird weder gespeichert noch anderswohin gesendet.
/sessions
Schlüssel erforderlichPaginierte Liste der Zahlungssessions der Organisation des Schlüssels und ihres Teams (neueste zuerst). Jeder Eintrag enthält establishmentId und establishmentName. Ein Schlüssel liefert nur die Zahlungen seiner eigenen Umgebung: Ein Live-Schlüssel liefert nie Testzahlungen, ein Testschlüssel liefert nur Testzahlungen.
fxRate, fxSource und fxQuotedAt beschreiben den unverbindlichen Referenzkurs, mit dem der Token-Betrag berechnet wurde (Wert, Quelle, Zeitstempel). Toreador führt keine Umrechnung durch: token und amount sind das, was der Zahler auf der Blockchain von seinem eigenen Wallet an das Wallet des Händlers gesendet hat.Query-Parameter
| limit | integer — 1–100, Standard 20 |
| cursor | string — Opaker Paginierungs-Cursor |
| establishment_id | string — Nur die Zahlungen dieses Standorts (eine id aus GET /establishments) |
Antwortcodes
Anfrage
Antwort
Diesen Endpunkt testen
Die Anfrage geht in Ihrem Namen an die Live-API. Verwenden Sie einen Testschlüssel (tor_test_…) — ein Live-Aufruf erzeugt echte Daten. Der Schlüssel wird weder gespeichert noch anderswohin gesendet.
/export
Schlüssel erforderlichBUCHHALTUNGS-Export der auf der Blockchain bestätigten Zahlungen, mit dem Referenzkurs (in Rechnung gestellter Betrag ↔ auf der Blockchain bezahlter Betrag + unverbindlicher Kurs + Quelle + Zeitstempel + tx). Als CSV (Standard, herunterladbar) oder JSON. Optionaler Zeitraum (from/to). Mit format=quickbooks, xero, odoo oder pennylane: die Importdatei für Banktransaktionen der jeweiligen Software, eine Währung pro Datei. Ein Schlüssel liefert nur die Zahlungen seiner eigenen Umgebung: Ein Live-Schlüssel liefert nie Testzahlungen, ein Testschlüssel liefert nur Testzahlungen.
settlementToken, settlementChain und settlementAmount = Token, Netzwerk und Betrag, die der Zahler tatsächlich auf der Blockchain von seinem eigenen Wallet an das Wallet des Händlers bezahlt hat (Toreador wickelt nichts ab); fxRate, fxSource und fxQuotedAt = der unverbindliche Referenzkurs, mit dem dieser Betrag berechnet wurde, seine Quelle und sein Zeitstempel (zur Information, keine Umrechnung durchgeführt); invoiceAmount / invoiceCurrency = der vom Händler in Rechnung gestellte Betrag.Query-Parameter
| format | string — „csv“ (Standard) oder „json“: der vollständige Export. „quickbooks“, „xero“, „odoo“ oder „pennylane“: eine Datei für den Import von Banktransaktionen in die jeweilige Buchhaltungssoftware |
| currency | string — Nur Importdateien: die Währung der Datei. Optional, wenn der Zeitraum nur eine Währung enthält |
| from | integer — Beginn des Zeitraums (Epoch-Sekunden, bezogen auf completed_at) |
| to | integer — Ende des Zeitraums (Epoch-Sekunden) |
| establishment_id | string — Nur die Zahlungen dieses Standorts (eine id aus GET /establishments) |
Antwortcodes
Anfrage
Antwort
Diesen Endpunkt testen
Die Anfrage geht in Ihrem Namen an die Live-API. Verwenden Sie einen Testschlüssel (tor_test_…) — ein Live-Aufruf erzeugt echte Daten. Der Schlüssel wird weder gespeichert noch anderswohin gesendet.
Webhooks
Um serverseitig über Statusänderungen benachrichtigt zu werden (ohne Polling), registrieren Sie einen Webhook-Endpoint. Toreador sendet bei jedem Übergang per POST ein mit HMAC-SHA256 signiertes Event (Header Toreador-Signature: t=…,v1=…).
session.createdsession.submittedsession.confirmingsession.completedsession.expiredsession.failedcheckout.created
Changelog
v1.0.0Die Hauptversion steht in der URL (/v1/). Abwärtskompatible Änderungen (neue Felder, optionale Parameter, Endpoints) werden hier aufgeführt und brechen v1 nie; eine inkompatible Änderung würde als /v2/ erscheinen. Jede Antwort enthält den Header API-Version.
- AddedÖffentliche API v1: QR-Erstellung (nativ + Solana SPL), gehostete ERC-20-Zahlungssitzungen (Wallet zu Wallet, direkt an die Adresse des Händlers), Abruf von Zahlungen und Status, paginierter Verlauf und Sitzungen.
- AddedMit HMAC-SHA256 signierte Webhooks (session.created/submitted/confirming/completed/expired/failed).
- AddedTest-/Live-Schlüssel (Testnet-Sandbox, ausserhalb des Kontingents); QR-Ausgabe als
pngodersvgüber den Parameterformat. - AddedHeader
API-Versionin jeder Antwort; typisierte Fehlerstruktur + Idempotenz (Idempotency-Key). - AddedStandorte:
GET /establishments,establishmentIdundestablishmentNamebei Zahlungen, Filterestablishment_idbei Listen und Export; ein Schlüssel liest die vom gesamten Team erstellten Zahlungen. - AddedImportdateien für die Buchhaltung:
GET /export?format=quickbooks|xero|odoo|pennylane, eine Währung pro Datei. - AddedDie Umgebungen sind getrennt: Ein Live-Schlüssel liest nur Live-Zahlungen, ein Testschlüssel nur Testzahlungen (Listen, Export, Lesen per id).