Inhalt

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.

Base URL 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.

cURL
curl https://toreador.io/api/v1/public/sessions \
  -H "X-API-Key: tor_live_a1b2c3..."

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

Response · 4xx
{
  "error": "Invalid amount: must be a decimal number between 0 and 1,000,000",
  "error_details": {
    "code": "invalid_amount",
    "type": "invalid_request",
    "message": "Invalid amount...",
    "request_id": "req_3f9a1c2b4d5e6f70",
    "doc_url": "https://toreador.io/docs/errors#invalid_amount"
  }
}

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

GET

/ping

Schlüssel erforderlich

Prü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

200 OK401 ungültiger Schlüssel

Anfrage

curl "https://toreador.io/api/v1/public/ping" \
  -H "X-API-Key: tor_live_..."

Antwort

Response · 200 OK
{
  "ok": true,
  "env": "live",
  "plan": "pro",
  "apiVersion": "1.0.0"
}
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.

GET

/account

Schlüssel erforderlich

Kontostatus: 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

200 OK401 ungültiger Schlüssel

Anfrage

curl "https://toreador.io/api/v1/public/account" \
  -H "X-API-Key: tor_live_..."

Antwort

Response · 200 OK
{
  "success": true,
  "plan": "plus",
  "env": "live",
  "subscription": { "status": "trialing", "realPlan": "free", "onTrial": true, "trialEndsAt": 1782329542, "trialDaysRemaining": 10 },
  "quota": { "used": 0, "limit": 5000, "remaining": 5000 },
  "limits": { "ratePerMinute": 600, "apiKeysMax": 10, "walletsMax": 50 }
}
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.

GET

/tokens

Schlüssel erforderlich

Matrix 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

200 OK401 ungültiger Schlüssel

Anfrage

curl "https://toreador.io/api/v1/public/tokens" \
  -H "X-API-Key: tor_live_..."

Antwort

Response · 200 OK
{
  "success": true,
  "env": "live",
  "chains": [ { "id": "base", "name": "Base", "nativeToken": "ETH", "family": "evm",
                "explorerTx": "https://basescan.org/tx/{hash}" } ],
  "tokens": [
    { "symbol": "ETH", "decimals": 18, "isNative": true,
      "chains": [ { "chain": "base", "type": "native", "contract": null } ] },
    { "symbol": "USDC", "decimals": 6, "isNative": false,
      "chains": [ { "chain": "base", "type": "erc20", "contract": "0x833589fC…" } ] }
  ]
}
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.

GET

/screen

Schlüssel erforderlich

Prü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).

Schlüssel erforderlich (auch im kostenlosen Tarif enthalten). Anfragerate pro Minute gemäss Ihrem Tarif. EVM-Adressen: heruntergeladene Listen (OFAC, EU, Vereinigtes Königreich, Schweiz) + Chainalysis-Orakel. Bitcoin- und Solana-Adressen: nur heruntergeladene Listen. 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

200 OK400 fehlende Adresse401 ungültiger Schlüssel429 Anfragelimit überschritten

Anfrage

curl "https://toreador.io/api/v1/public/screen?address=0x098B716B8Aaf21512996dC57EB0615e2383E2f96" \
  -H "X-API-Key: tor_live_..."

Antwort

Response · 200 OK
{
  "success": true,
  "address": "0x098B716B…",
  "status": "sanctioned",
  "sanctioned": true,
  "source": "chainalysis_oracle"
}
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.

POST

/generate-qr

Schlüssel erforderlich

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

Schlüssel erforderlich (auch im kostenlosen Tarif enthalten). Anfragerate pro Minute gemäss Ihrem Tarif. Der QR-Code zielt immer auf ein registriertes Wallet Ihres Kontos. 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

200 OK400 ungültige Eingabe / falscher Endpunkt401 ungültiger Schlüssel409 Idempotency-Key-Konflikt429 Anfragelimit

Anfrage

curl -X POST "https://toreador.io/api/v1/public/generate-qr" \
  -H "X-API-Key: tor_live_..." \
  -H "Content-Type: application/json" \
  -d '{"token":"BTC","chainId":"bitcoin","amount":"0.001","recipientAddress":"1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"}'

Antwort

Response · 200 OK
{
  "success": true,
  "type": "native",
  "qrData": "bitcoin:bc1q...?amount=0.001",
  "format": "png",
  "qrCodeURL": "data:image/png;base64,iVBORw0KGgo...",  // format=svg → "qrCodeSvg" · format=text → "qrCodeText"
  "token": { "symbol": "BTC", "name": "Bitcoin", "decimals": 8 },
  "chain": { "id": "bitcoin", "name": "Bitcoin", "symbol": "BTC" },
  "amount": "0.001",
  "recipientAddress": "bc1q..."
}
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.

POST

/create-session

Schlüssel erforderlich

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

Ein Testschlüssel (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

200 OK400 ungültige Eingabe401 ungültiger Schlüssel402 monatliches Kontingent ausgeschöpft409 Idempotency-Key-Konflikt429 Anfragelimit

Anfrage

curl -X POST "https://toreador.io/api/v1/public/create-session" \
  -H "X-API-Key: tor_live_..." \
  -H "Content-Type: application/json" \
  -d '{"token":"USDC","chainId":"base","amount":"100","recipientAddress":"0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18"}'

Antwort

Response · 200 OK
{
  "success": true,
  "sessionId": "3f9a1c2b4d5e6f708192a3b4c5d6e7f8",
  "url": "https://pay.toreador.io/pay/3f9a1c2b4d5e6f708192a3b4c5d6e7f8",
  "expiresAt": 1718000000,
  "expiresIn": 900,
  "token": { "symbol": "USDC", "name": "USD Coin", "decimals": 6 },
  "chain": { "id": "base", "name": "Base", "symbol": "ETH" },
  "amount": "100",
  "recipientAddress": "0x742d35Cc..."
}
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.

GET

/wallets

Schlüssel erforderlich

Listet (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

200 OK401 ungültiger Schlüssel

Anfrage

curl "https://toreador.io/api/v1/public/wallets" \
  -H "X-API-Key: tor_live_..."

Antwort

Response · 200 OK
{
  "success": true,
  "wallets": [
    { "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18", "family": "evm", "label": "Treasury", "source": "self_custodial", "custodial": false, "ownershipProven": true, "acceptedRails": null },
    { "address": "0xb14d1444f13984dd573056254c15a32783e05996", "family": "evm", "label": "Binance", "source": "binance", "custodial": true, "ownershipProven": true, "acceptedRails": [{ "token": "USDC", "chain": "polygon" }, { "token": "USDT", "chain": "arbitrum" }] }
  ]
}
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.

POST

/checkout

Schlüssel erforderlich

Erstellt 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

200 OK400 ungültige Eingabe / nicht unterstützte Währung401 ungültiger Schlüssel402 monatliches Kontingent ausgeschöpft409 kein Wallet / kein Zahlungsweg429 Anfragelimit

Anfrage

curl -X POST "https://toreador.io/api/v1/public/checkout" \
  -H "X-API-Key: tor_live_..." \
  -H "Content-Type: application/json" \
  -d '{"amount":"50","currency":"USD","description":"Order #42","conversion":"off","reference":"wc-order-42","recipientAddress":"0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18"}'

Antwort

Response · 200 OK
{
  "success": true,
  "checkoutId": "co_00a527da53a144c5bc2f1267a0fac074",
  "reference": "wc-order-42",
  "url": "https://pay.toreador.io/pay/co_00a527da53a144c5bc2f1267a0fac074",
  "amount": 50,
  "currency": "USD",
  "conversion": false,
  "recipient": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
  "allowedRails": [ { "token": "USDC", "chain": "base" } ],
  "expiresAt": 1718003600,
  "expiresIn": 3600
}
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.

POST

/webhooks

Schlüssel erforderlich

Registriert (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.

Signatur: Header Toreador-Signature = t=…,v1=… (HMAC-SHA256 in Hex des Strings {t}.{rawBody}). Events: session.created/submitted/confirming/completed/expired/failed, checkout.created. Zustellung: 2xx = Erfolg, sonst Wiederholungen (bis zu 9, mit Backoff). GET /webhooks listet sie auf (ohne Secret); DELETE /webhooks/{id} löscht einen.

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

200 OK400 ungültige URL / keine HTTPS-URL401 ungültiger Schlüssel403 URL nicht auf der Domain des Schlüssels

Anfrage

curl -X POST "https://toreador.io/api/v1/public/webhooks" \
  -H "X-API-Key: tor_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-store.com/wp-json/toreador/v1/webhook"}'

Antwort

Response · 200 OK
{
  "success": true,
  "id": "whk_…",
  "url": "https://your-store.com/wp-json/toreador/v1/webhook",
  "events": [ "session.completed", "session.failed", "session.expired" ],
  "secret": "whsec_…",
  "created": true
}
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.

GET

/payment/{id}

Schlüssel erforderlich

Ruft 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

200 OK404 nicht gefunden

Anfrage

curl "https://toreador.io/api/v1/public/payment/3f9a1c2b4d5e6f708192a3b4c5d6e7f8" \
  -H "X-API-Key: tor_live_..."

Antwort

Response · 200 OK
{
  "success": true,
  "id": "3f9a1c2b4d5e6f708192a3b4c5d6e7f8",
  "object": "payment",
  "type": "session",
  "status": "completed",
  "token": "USDC",
  "chain": "base",
  "amount": "100",
  "recipient": "0x742d35Cc...",
  "txHash": "0x89bca0...",
  "confirmations": 1,
  "requiredConfirmations": 1,
  "createdAt": 1718000000,
  "completedAt": 1718000045,
  "checkoutId": "co_00a527da53a144c5bc2f1267a0fac074",
  "reference": "wc-order-42",
  "timeline": [ { "type": "completed", "at": 1718000045 } ]
}
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.

GET

/payment/{id}/status

Schlüssel erforderlich

Gibt 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

200 OK404 nicht gefunden

Anfrage

curl "https://toreador.io/api/v1/public/payment/3f9a1c2b4d5e6f708192a3b4c5d6e7f8/status" \
  -H "X-API-Key: tor_live_..."

Antwort

Response · 200 OK
{
  "success": true,
  "sessionId": "3f9a1c2b...",
  "status": "confirming",
  "token": "USDC",
  "chainId": "base",
  "amount": "100",
  "recipientAddress": "0x742d35Cc...",
  "txHash": "0x89bca0...",
  "confirmations": 0,
  "requiredConfirmations": 1,
  "expiresAt": 1718000900,
  "completedAt": null
}
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.

GET

/establishments

Schlüssel erforderlich

Listet (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

200 OK401 ungültiger Schlüssel

Anfrage

curl "https://toreador.io/api/v1/public/establishments" \
  -H "X-API-Key: tor_live_..."

Antwort

Response · 200 OK
{
  "success": true,
  "data": [
    { "id": "est_3f9a…", "name": "Main street", "isDefault": true, "organizationId": "org_81c2…", "organizationName": "Corner Books" },
    { "id": "est_b07d…", "name": "Harbour", "isDefault": false, "organizationId": "org_81c2…", "organizationName": "Corner Books" }
  ]
}
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.

GET

/history

Schlüssel erforderlich

Paginierte 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

200 OK401 ungültiger Schlüssel

Anfrage

curl "https://toreador.io/api/v1/public/history?limit=20" \
  -H "X-API-Key: tor_live_..."

Antwort

Response · 200 OK
{
  "success": true,
  "data": [ { "id": "...", "type": "native", "amount": "0.001", "createdAt": 1718000000 } ],
  "has_more": true,
  "next_cursor": "eyJpZCI6..."
}
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.

GET

/sessions

Schlüssel erforderlich

Paginierte 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

200 OK401 ungültiger Schlüssel

Anfrage

curl "https://toreador.io/api/v1/public/sessions?limit=20" \
  -H "X-API-Key: tor_live_..."

Antwort

Response · 200 OK
{
  "success": true,
  "data": [ { "id": "...", "status": "completed", "token": "EURC", "amount": "43.226420", "amountUsd": 50, "fxRate": 0.8645, "fxSource": "ecb", "checkoutId": "co_00a527…", "reference": "wc-order-42", "invoice": { "currency": "USD", "amount": 50 } } ],
  "has_more": false,
  "next_cursor": null
}
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.

GET

/export

Schlüssel erforderlich

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

Feldübersicht: 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

200 OK400 ungültiger Parameter oder Währung erforderlich401 ungültiger Schlüssel

Anfrage

curl "https://toreador.io/api/v1/public/export?format=json" \
  -H "X-API-Key: tor_live_..."

Antwort

Response · 200 OK
{
  "success": true,
  "count": 2,
  "truncated": false,
  "data": [ { "id": "...", "completedAt": 1781344545, "invoiceCurrency": "USD", "invoiceAmount": 50, "settlementToken": "EURC", "settlementAmount": "43.226420", "amountUsd": 50, "fxRate": 0.8645, "fxSource": "ecb", "txHash": "0x…" } ]
}
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
Signaturprüfung & vollständiges Beispiel →

Changelog

v1.0.0

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

v1.0.0 2026-06-13
  • 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 png oder svg über den Parameter format.
  • AddedHeader API-Version in jeder Antwort; typisierte Fehlerstruktur + Idempotenz (Idempotency-Key).
  • AddedStandorte: GET /establishments, establishmentId und establishmentName bei Zahlungen, Filter establishment_id bei 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).

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.