REST API
L'API HTTP publique de Toreador : générez des QR codes crypto et créez des sessions de paiement non-custodial. Toreador ne détient jamais les fonds — chaque paiement va directement du payeur au wallet du marchand, on-chain.
https://toreador.io/api/v1/public
Spécification machine : openapi.json (OpenAPI 3.1).
Authentication
La plupart des endpoints exigent une clé API, passée dans l'en-tête X-API-Key. La clé identifie votre compte ; vos droits (plan, quota) sont évalués à chaque requête. Générez vos clés depuis le tableau de bord.
tor_test_…
Sandbox sur testnet, ouverte à tous, hors quota. Pour développer et tester.
tor_live_…
Production (mainnet). Soumise au plan et au quota de paiements confirmés on-chain.
Limites de débit
Le débit est limité par compte (pas par clé). Un dépassement renvoie 429 avec un en-tête Retry-After. Tous les endpoints exigent une clé (le plan gratuit en fournit une).
- Débit par minute selon le plan (en-têtes
X-RateLimit-*sur chaque réponse).
| Formule | Débit API | Clés API | Paiements confirmés on-chain / mois |
|---|---|---|---|
| Free | 10/min | 1 | Illimité |
| Starter | 30/min | 1 | 150 |
| Pro | 120/min | 3 | 1000 |
| Plus | 600/min | 10 | 5000 |
| Entreprise | Illimité | Illimité | Illimité |
Valeurs de la grille par défaut ; votre limite exacte peut varier selon votre région et s'affiche dans votre tableau de bord. Le débit avec clé est par compte (créer plusieurs clés ne le multiplie pas).
Idempotence
Pour les requêtes POST, ajoutez un en-tête Idempotency-Key : un rejeu avec la même clé renvoie la réponse d'origine (en-tête Idempotent-Replayed: true), sans recréer de session. Même clé + corps différent → 409.
Erreurs
Les erreurs utilisent une enveloppe à double forme : error reste une chaîne (rétro-compat) et error_details porte le détail typé (code, type, message, request_id, doc_url).
Codes d'erreur
| code | HTTP | Quand |
|---|---|---|
| missing_field | 400 | Un champ requis manque (token, chainId, amount, recipientAddress). |
| invalid_parameter | 400 | token, chaîne ou format inconnu. |
| invalid_address | 400 | L'adresse destinataire n'est pas valide pour cette chaîne. |
| invalid_amount | 400 | Montant non décimal ou hors bornes (0–1 000 000). |
| incompatible_token_chain | 400 | Ce token n'existe pas sur cette chaîne (ex. BTC sur Ethereum). |
| wrong_endpoint | 400 | Mauvais endpoint : natif ↔ ERC-20 (utilisez l'autre). |
| missing_api_key | 401 | Clé API absente. |
| invalid_api_key | 401 | Clé API invalide ou révoquée. |
| quota_exceeded | 402 | Quota mensuel de paiements confirmés on-chain épuisé (porte used/limit/upgrade_url). |
| forbidden | 403 | La clé n'a pas le droit d'accéder à cette ressource. |
| recipient_blocked | 403 | L'adresse destinataire figure sur une liste de sanctions : aucun QR code ni page de paiement n'est créé. |
| session_not_found | 404 | Session introuvable (ou expirée/purgée). |
| payment_not_found | 404 | Paiement introuvable. |
| idempotency_conflict | 409 | Même Idempotency-Key réutilisée avec un corps différent. |
| no_rail | 409 | Aucun rail utilisable pour ce paiement : la paire jeton/réseau n'est pas créditée par le wallet d'exchange connecté, ou l'émetteur du stablecoin a gelé l'adresse de réception sur ce réseau. |
| rate_limited | 429 | Débit dépassé (en-tête Retry-After). |
| internal_error | 500 | Erreur serveur inattendue — réessayez, puis contactez le support. |
Pagination
Les endpoints de liste (/history, /sessions) sont paginés par curseur : passez limit (1–100, défaut 20) et cursor. La réponse porte has_more et next_cursor — réinjectez ce dernier pour la page suivante.
Endpoints
Référence des endpoints
/ping
Clé requiseVérifie la connectivité et la validité de la clé. Renvoie l'environnement (test/live), le plan et la version d'API. Idéal pour un bouton « Tester la connexion ».
Aucun paramètre.
Codes de réponse
Requête
Réponse
Tester cet endpoint
La requête part vers l'API réelle, en votre nom. Utilisez une clé de test (tor_test_…) — un appel live crée de vraies données. La clé n'est ni stockée ni envoyée ailleurs.
/account
Clé requiseStatut du compte : plan effectif, environnement, abonnement (essai vs payé), quota mensuel (used/limit/remaining) et limites (débit, clés, wallets). Le champ subscription (status trialing/active, realPlan, trialEndsAt en epoch s, trialDaysRemaining) doit porter le badge plan — pas plan seul, qui vaut 'plus' pendant l'essai.
Aucun paramètre.
Codes de réponse
Requête
Réponse
Tester cet endpoint
La requête part vers l'API réelle, en votre nom. Utilisez une clé de test (tor_test_…) — un appel live crée de vraies données. La clé n'est ni stockée ni envoyée ailleurs.
/tokens
Clé requiseMatrice des moyens de paiement supportés (tokens × chaînes), dérivée de la config (source de vérité unique, contrats vérifiés on-chain). À récupérer au lieu de coder en dur la liste → elle reste à jour quand une chaîne/token est ajouté. Ne renvoie que les paires RÉELLEMENT payables (natif, ou ERC-20/SPL avec contrat). Contrats selon l'env de la clé (test/live).
Aucun paramètre.
Codes de réponse
Requête
Réponse
Tester cet endpoint
La requête part vers l'API réelle, en votre nom. Utilisez une clé de test (tor_test_…) — un appel live crée de vraies données. La clé n'est ni stockée ni envoyée ailleurs.
/screen
Clé requiseVérifie si une adresse crypto figure sur les listes de SANCTIONS que nous consultons (listes OFAC, UE, Royaume-Uni et Suisse téléchargées par nous ; oracle on-chain Chainalysis en plus pour les adresses EVM). Renvoie sanctioned (true/false), ou null si l'adresse ne peut être vérifiée (invalide, chaîne non supportée, oracle indisponible). À appeler avant d'envoyer ou de recevoir des fonds. Résultat mis en cache (fraîcheur ~24 h).
sanctioned: null = vérification impossible (adresse invalide, liste périmée, oracle muet). Information de conformité, sans valeur d'avis juridique.address (query, requis) — l'adresse à vérifier.
Codes de réponse
Requête
Réponse
Tester cet endpoint
La requête part vers l'API réelle, en votre nom. Utilisez une clé de test (tor_test_…) — un appel live crée de vraies données. La clé n'est ni stockée ni envoyée ailleurs.
/generate-qr
Clé requiseGénère un QR code (PNG base64) encodant un URI de paiement standard (BIP-21, EIP-681, Solana Pay). Pour les tokens natifs (BTC, ETH, SOL, POL) et USDC sur Solana. Pour les stablecoins ERC-20 sur EVM, utilisez /create-session.
X-RateLimit-* sur chaque réponse.Body
| token* | string — BTC, ETH, SOL, POL, USDC (Solana) |
| chainId* | string — bitcoin, ethereum, polygon, base, solana |
| amount* | string — Décimal canonique (ex. "0.001") |
| recipientAddress* | string — Adresse du destinataire (validée pour la chaîne) |
| format | string — Format de sortie : png (défaut, data-URI base64), svg (markup vectoriel) ou text (caractères blocs à afficher dans un terminal ; renvoyé dans qrCodeText). |
| textBackground | string — Pour format: text : le fond du terminal où le texte sera affiché, dark (défaut) ou light. Un mauvais fond donne un QR code inversé, que beaucoup de téléphones ne lisent pas. |
Codes de réponse
Requête
Réponse
Tester cet endpoint
La requête part vers l'API réelle, en votre nom. Utilisez une clé de test (tor_test_…) — un appel live crée de vraies données. La clé n'est ni stockée ni envoyée ailleurs.
/create-session
Clé requiseCrée une session de paiement hébergée (paiement de wallet à wallet, directement à l'adresse du marchand) pour les stablecoins ERC-20 (USDC, USDT, EURC) sur Ethereum, Polygon et Base. Renvoie une URL /pay à partager au payeur. La session expire 15 minutes après création.
tor_test_…) crée une session sandbox sur testnet, hors quota — idéale pour développer un plugin. Une clé live (tor_live_…) compte dans le quota de paiements confirmés on-chain du mois (réponse 402 si épuisé).Body
| token* | string — USDC, USDT, EURC, PYUSD, USDG, RLUSD, USAT, OUSD |
| chainId* | string — ethereum, polygon, base |
| amount* | string — Décimal canonique (ex. "100") |
| recipientAddress* | string — Adresse EVM du destinataire (validée au cœur) |
Codes de réponse
Requête
Réponse
Tester cet endpoint
La requête part vers l'API réelle, en votre nom. Utilisez une clé de test (tor_test_…) — un appel live crée de vraies données. La clé n'est ni stockée ni envoyée ailleurs.
/wallets
Clé requiseListe (LECTURE SEULE) les adresses de réception du compte. Chaque wallet renvoie address, family, label, source, ownershipProven (true = propriété prouvée par signature, ou adresse lue chez un exchange connecté), custodial (true = adresse de dépôt du compte d'exchange DU MARCHAND, type Binance/Coinbase, détenue par l'exchange, jamais par Toreador) et acceptedRails : null = aucune restriction (auto-hébergé, tous les réseaux de la famille) ; sinon les paires (token, chaîne) que la source custodiale crédite À CETTE adresse. IMPORTANT : pour un wallet custodial, bornez votre matrice de paiement à acceptedRails — une paire non créditée n'est pas proposée au payeur (l'exchange ne la créditerait pas et les fonds seraient perdus). L'ajout/suppression de wallet se fait dans le dashboard authentifié (passkey) — jamais par l'API.
Aucun paramètre.
Codes de réponse
Requête
Réponse
Tester cet endpoint
La requête part vers l'API réelle, en votre nom. Utilisez une clé de test (tor_test_…) — un appel live crée de vraies données. La clé n'est ni stockée ni envoyée ailleurs.
/checkout
Clé requiseCrée un checkout dénominé en FIAT (USD/EUR) : le marchand fixe un montant en monnaie, le payeur connecte son wallet sur la page hébergée /pay (paiement de wallet à wallet, directement à l'adresse du marchand) et choisit lui-même le stablecoin et la chaîne. À privilégier pour les intégrations (le marchand n'a pas à comprendre « USDC sur Base »).
conversion:"off" (défaut) ne propose que les stablecoins de la même devise (USD→USDC/USDT). conversion:"on" propose aussi des stablecoins d'une autre devise : le montant dû est calculé sur un cours de référence indicatif (source et horodatage enregistrés), arrêté au choix du rail. Toreador n'exécute aucune conversion : le payeur envoie ce stablecoin directement au wallet du marchand.Body
| amount* | number — Montant en DEVISE (ex. 50), pas en token |
| currency* | string — USD, EUR |
| recipientAddress* | string — Adresse de réception (EVM 0x… ou Solana). Fournie par VOTRE système — gère la rotation. |
| description | string — Libellé montré au payeur (≤ 500 car.) |
| conversion | string — "off" (défaut) ou "on" |
| acceptNative | boolean — Propose AUSSI le paiement en crypto native (ETH/POL) ; montant calculé au cours du moment (référence indicative). Le marchand assume la volatilité. |
| reference | string — Référence libre (ex. ID de commande), renvoyée sur le checkout, /payment/{id} et /sessions — pour corréler le paiement côté intégration (≤ 255 car.). |
Codes de réponse
Requête
Réponse
Tester cet endpoint
La requête part vers l'API réelle, en votre nom. Utilisez une clé de test (tor_test_…) — un appel live crée de vraies données. La clé n'est ni stockée ni envoyée ailleurs.
/webhooks
Clé requiseEnregistre (ou met à jour, IDEMPOTENT par URL) l'endpoint webhook du compte pour recevoir les events en PUSH. Une intégration l'appelle automatiquement après le Connect. Renvoie le secret HMAC UNE seule fois — à stocker chiffré. L'URL doit être HTTPS publique et, si la clé a été émise via Connect, sur le domaine de la clé.
Body
| url* | string — Endpoint HTTPS public (sur le domaine de la clé) |
| events | string[] — Events souscrits (défaut : session.completed/failed/expired) |
| description | string — Libellé (≤ 200 car.) |
Codes de réponse
Requête
Réponse
Tester cet endpoint
La requête part vers l'API réelle, en votre nom. Utilisez une clé de test (tor_test_…) — un appel live crée de vraies données. La clé n'est ni stockée ni envoyée ailleurs.
/payment/{id}
Clé requiseRécupère un objet Payment unifié — QR natif (type: native) ou session ERC-20 (type: session) — avec sa timeline. Accepte AUSSI un id de checkout (co_…) : il résout vers le paiement de ce checkout (idéal pour suivre une commande via son checkoutId, sans connaître l'id de session).
Paramètre de chemin
| id* | string — Id de paiement / session, OU id de checkout (co_…) |
Codes de réponse
Requête
Réponse
Tester cet endpoint
La requête part vers l'API réelle, en votre nom. Utilisez une clé de test (tor_test_…) — un appel live crée de vraies données. La clé n'est ni stockée ni envoyée ailleurs.
/payment/{id}/status
Clé requiseRenvoie l'état courant d'une session de paiement. Pour le suivi temps réel côté payeur, la page /pay utilise un flux SSE ; côté serveur, préférez les webhooks signés (voir plus bas).
Paramètre de chemin
| id* | string — Identifiant de session (renvoyé par /create-session) |
Codes de réponse
Requête
Réponse
Tester cet endpoint
La requête part vers l'API réelle, en votre nom. Utilisez une clé de test (tor_test_…) — un appel live crée de vraies données. La clé n'est ni stockée ni envoyée ailleurs.
/establishments
Clé requiseListe (LECTURE SEULE) les établissements de la clé : id, name, isDefault. Un identifiant sert de establishment_id, à la création d'une demande de paiement comme en filtre de /sessions, /history et /export.
Aucun paramètre.
Codes de réponse
Requête
Réponse
Tester cet endpoint
La requête part vers l'API réelle, en votre nom. Utilisez une clé de test (tor_test_…) — un appel live crée de vraies données. La clé n'est ni stockée ni envoyée ailleurs.
/history
Clé requiseListe paginée des QR codes générés par l'organisation de la clé et son équipe (les plus récents d'abord). Chaque ligne porte establishmentId et establishmentName. Une clé ne lit que les paiements de son environnement : une clé de production ne renvoie jamais un paiement d'essai, une clé d'essai ne renvoie que des paiements d'essai.
Query
| limit | integer — 1–100, défaut 20 |
| cursor | string — Curseur opaque (next_cursor de la page précédente) |
| establishment_id | string — Seulement les paiements de cet établissement (un identifiant rendu par GET /establishments) |
Codes de réponse
Requête
Réponse
Tester cet endpoint
La requête part vers l'API réelle, en votre nom. Utilisez une clé de test (tor_test_…) — un appel live crée de vraies données. La clé n'est ni stockée ni envoyée ailleurs.
/sessions
Clé requiseListe paginée des sessions de paiement de l'organisation de la clé et de son équipe (les plus récentes d'abord). Chaque ligne porte establishmentId et establishmentName. Une clé ne lit que les paiements de son environnement : une clé de production ne renvoie jamais un paiement d'essai, une clé d'essai ne renvoie que des paiements d'essai.
fxRate, fxSource et fxQuotedAt décrivent le cours de référence indicatif qui a servi à calculer le montant en token (valeur, source, horodatage). Toreador n'exécute aucune conversion : token et amount sont ce que le payeur a envoyé on-chain, depuis son wallet, au wallet du marchand.Query
| limit | integer — 1–100, défaut 20 |
| cursor | string — Curseur opaque de pagination |
| establishment_id | string — Seulement les paiements de cet établissement (un identifiant rendu par GET /establishments) |
Codes de réponse
Requête
Réponse
Tester cet endpoint
La requête part vers l'API réelle, en votre nom. Utilisez une clé de test (tor_test_…) — un appel live crée de vraies données. La clé n'est ni stockée ni envoyée ailleurs.
/export
Clé requiseExport COMPTABLE des paiements confirmés on-chain, avec le cours de référence (montant facturé ↔ montant payé on-chain + cours indicatif + source + horodatage + tx). En CSV (défaut, téléchargeable) ou JSON. Période optionnelle (from/to). Avec format=quickbooks, xero, odoo ou pennylane : le fichier d'import de transactions bancaires de ce logiciel, une devise par fichier. Une clé ne lit que les paiements de son environnement : une clé de production ne renvoie jamais un paiement d'essai, une clé d'essai ne renvoie que des paiements d'essai.
settlementToken, settlementChain et settlementAmount = token, réseau et montant effectivement payés on-chain par le payeur, depuis son wallet, au wallet du marchand (Toreador ne règle rien) ; fxRate, fxSource et fxQuotedAt = cours de référence indicatif ayant servi à calculer ce montant, sa source et son horodatage (informatif, aucune conversion exécutée) ; invoiceAmount / invoiceCurrency = montant facturé par le marchand.Query
| format | string — "csv" (défaut) ou "json" : l'export complet. "quickbooks", "xero", "odoo" ou "pennylane" : un fichier pour l'import de transactions bancaires de ce logiciel de comptabilité |
| currency | string — Fichiers d'import seulement : la devise du fichier. Facultative quand la période ne contient qu'une devise |
| from | integer — Début de période (epoch s, sur completed_at) |
| to | integer — Fin de période (epoch s) |
| establishment_id | string — Seulement les paiements de cet établissement (un identifiant rendu par GET /establishments) |
Codes de réponse
Requête
Réponse
Tester cet endpoint
La requête part vers l'API réelle, en votre nom. Utilisez une clé de test (tor_test_…) — un appel live crée de vraies données. La clé n'est ni stockée ni envoyée ailleurs.
Webhooks
Pour être notifié des changements d'état côté serveur (sans polling), enregistrez un endpoint webhook. Toreador POST un événement signé HMAC-SHA256 (en-tête Toreador-Signature: t=…,v1=…) à chaque transition.
session.createdsession.submittedsession.confirmingsession.completedsession.expiredsession.failedcheckout.created
Changelog
v1.0.0La majeure de version est portée par l'URL (/v1/). Les changements rétro-compatibles (nouveaux champs, paramètres optionnels, endpoints) sont listés ici et ne cassent pas la v1 ; un changement cassant donnerait une /v2/. Chaque réponse porte l'en-tête API-Version.
- AddedAPI publique v1 : génération de QR (natifs + Solana SPL), sessions de paiement ERC-20 hébergées (paiement de wallet à wallet, directement à l'adresse du marchand), lecture de paiement et de statut, historique et sessions paginés.
- AddedWebhooks signés HMAC-SHA256 (session.created/submitted/confirming/completed/expired/failed).
- AddedClés test/live (sandbox testnet, hors quota) ; sortie QR
pngousvgvia le paramètreformat. - AddedEn-tête
API-Versionsur chaque réponse ; enveloppe d'erreur typée + idempotence (Idempotency-Key). - AddedÉtablissements :
GET /establishments,establishmentIdetestablishmentNamesur les paiements, filtreestablishment_idsur les listes et l'export ; une clé lit les paiements créés par toute l'équipe. - AddedFichiers d'import comptables :
GET /export?format=quickbooks|xero|odoo|pennylane, une devise par fichier. - AddedLes environnements sont séparés : une clé de production ne lit que les vrais paiements, une clé d'essai que les paiements d'essai (listes, export, lecture par identifiant).