Sommaire

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.

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

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

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

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

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

GET

/ping

Clé requise

Vé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

200 OK401 clé invalide

Requête

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

Réponse

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

GET

/account

Clé requise

Statut 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

200 OK401 clé invalide

Requête

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

Réponse

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

GET

/tokens

Clé requise

Matrice 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

200 OK401 clé invalide

Requête

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

Réponse

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…" } ] }
  ]
}
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.

GET

/screen

Clé requise

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

Clé requise (plan gratuit inclus). Débit par minute selon votre plan. Adresses EVM : listes téléchargées (OFAC, UE, Royaume-Uni, Suisse) + oracle Chainalysis. Adresses Bitcoin et Solana : listes téléchargées seules. 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

200 OK400 adresse manquante401 clé invalide429 débit dépassé

Requête

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

Réponse

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

POST

/generate-qr

Clé requise

Gé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.

Clé requise (plan gratuit inclus). Débit par minute selon votre plan. Le QR vise toujours un wallet enregistré de votre compte. En-têtes 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

200 OK400 entrée invalide / mauvais endpoint401 clé invalide409 conflit Idempotency-Key429 rate limit

Requête

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

Réponse

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

POST

/create-session

Clé requise

Cré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.

Une clé de test (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

200 OK400 entrée invalide401 clé invalide402 quota mensuel épuisé409 conflit Idempotency-Key429 rate limit

Requête

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

Réponse

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

GET

/wallets

Clé requise

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

200 OK401 clé invalide

Requête

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

Réponse

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" }] }
  ]
}
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.

POST

/checkout

Clé requise

Cré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

200 OK400 entrée invalide / devise non supportée401 clé invalide402 quota mensuel épuisé409 pas de wallet / pas de rail429 rate limit

Requête

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

Réponse

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

POST

/webhooks

Clé requise

Enregistre (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é.

Signature : header Toreador-Signature = t=…,v1=… (HMAC-SHA256 hex de la chaîne {t}.{rawBody}). Events : session.created/submitted/confirming/completed/expired/failed, checkout.created. Livraison : 2xx = succès, sinon retries (jusqu'à 9, backoff). GET /webhooks liste (sans secret) ; DELETE /webhooks/{id} supprime.

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

200 OK400 URL invalide / non-HTTPS401 clé invalide403 URL hors du domaine de la clé

Requête

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

Réponse

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

GET

/payment/{id}

Clé requise

Ré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

200 OK404 introuvable

Requête

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

Réponse

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

GET

/payment/{id}/status

Clé requise

Renvoie 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

200 OK404 introuvable

Requête

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

Réponse

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

GET

/establishments

Clé requise

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

200 OK401 clé invalide

Requête

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

Réponse

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" }
  ]
}
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.

GET

/history

Clé requise

Liste 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

200 OK401 clé invalide

Requête

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

Réponse

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

GET

/sessions

Clé requise

Liste 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

200 OK401 clé invalide

Requête

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

Réponse

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

GET

/export

Clé requise

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

Lecture des champs : 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

200 OK400 paramètre invalide, ou devise exigée401 clé invalide

Requête

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

Réponse

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…" } ]
}
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
Vérification de signature & exemple complet →

Changelog

v1.0.0

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

v1.0.0 2026-06-13
  • 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 png ou svg via le paramètre format.
  • AddedEn-tête API-Version sur chaque réponse ; enveloppe d'erreur typée + idempotence (Idempotency-Key).
  • AddedÉtablissements : GET /establishments, establishmentId et establishmentName sur les paiements, filtre establishment_id sur 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).

Nous respectons votre vie privée

Nous utilisons des cookies d'analyse pour améliorer notre service. Ces cookies ne sont activés qu'avec votre consentement. Les cookies essentiels (authentification, langue, etc.) sont toujours actifs.