Indice

REST API

L'API HTTP pubblica di Toreador: generi codici QR crypto e crei sessioni di pagamento senza custodia. Toreador non detiene mai i fondi — ogni pagamento va direttamente dal wallet del pagatore a quello dell'esercente, sulla blockchain.

Base URL https://toreador.io/api/v1/public

Specifica leggibile dalle macchine: openapi.json (OpenAPI 3.1).

Authentication

La maggior parte degli endpoint richiede una chiave API, passata nell'intestazione X-API-Key. La chiave identifica il Suo account; i Suoi diritti (piano, quota) vengono valutati a ogni richiesta. Generi le Sue chiavi dalla Sua dashboard.

tor_test_…

Sandbox testnet, aperta a tutti, fuori quota. Per lo sviluppo e i test.

tor_live_…

Produzione (mainnet). Soggetta al piano e alla quota di pagamenti confermati sulla blockchain.

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

Limiti di frequenza

Il limite di richieste si applica per account (non per chiave). Un superamento restituisce 429 con un'intestazione Retry-After. Tutti gli endpoint richiedono una chiave (il piano gratuito ne include una).

  • Frequenza al minuto per piano (header X-RateLimit-* su ogni risposta).
Piano Limite di richieste API Chiavi API Pagamenti confermati sulla blockchain / mese
Free 10/min 1 Illimitato
Starter 30/min 1 150
Pro 120/min 3 1000
Plus 600/min 10 5000
Entreprise Illimitato Illimitato Illimitato

Valori della tabella predefinita; il Suo limite esatto può variare in base alla Sua regione ed è indicato nella Sua dashboard. Il limite di richieste con chiave si applica per account (creare più chiavi non lo moltiplica).

Idempotenza

Per le richieste POST, aggiunga un'intestazione Idempotency-Key: ripetere la richiesta con la stessa chiave restituisce la risposta originale (intestazione Idempotent-Replayed: true), senza ricreare una sessione. Stessa chiave + corpo diverso → 409.

Errori

Gli errori usano un involucro a doppia forma: error resta una stringa (retrocompatibilità) e error_details contiene il dettaglio tipizzato (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"
  }
}

Codici di errore

code HTTP Quando
missing_field 400 Manca un campo obbligatorio (token, chainId, amount, recipientAddress).
invalid_parameter 400 Token, chain o formato sconosciuto.
invalid_address 400 L'indirizzo del destinatario non è valido per questa chain.
invalid_amount 400 Importo non decimale o fuori intervallo (0–1.000.000).
incompatible_token_chain 400 Questo token non esiste su questa chain (es. BTC su Ethereum).
wrong_endpoint 400 Endpoint errato: nativo ↔ ERC-20 (usi l'altro).
missing_api_key 401 Chiave API mancante.
invalid_api_key 401 Chiave API non valida o revocata.
quota_exceeded 402 Quota mensile di pagamenti confermati sulla blockchain esaurita (riporta used/limit/upgrade_url).
forbidden 403 La chiave non è autorizzata ad accedere a questa risorsa.
recipient_blocked 403 L'indirizzo del destinatario figura in una lista di sanzioni: non viene creato alcun codice QR né alcuna pagina di pagamento.
session_not_found 404 Sessione non trovata (o scaduta/eliminata).
payment_not_found 404 Pagamento non trovato.
idempotency_conflict 409 Stessa Idempotency-Key riutilizzata con un corpo diverso.
no_rail 409 Nessun canale utilizzabile per questo pagamento: la coppia token/rete non può essere accreditata dal wallet dell'exchange collegato, oppure l'emittente della stablecoin ha congelato l'indirizzo di ricezione su quella rete.
rate_limited 429 Frequenza superata (header Retry-After).
internal_error 500 Errore imprevisto del server: riprovi, poi contatti l'assistenza.

Pagination

Gli endpoint di elenco (/history, /sessions) sono paginati tramite cursore: passi limit (1–100, predefinito 20) e cursor. La risposta contiene has_more e next_cursor — reinvii quest'ultimo per ottenere la pagina successiva.

Endpoints

Riferimento degli endpoint

GET

/ping

Chiave richiesta

Verifica la connettività e la validità della chiave API. Restituisce l'ambiente (test/live), il piano e la versione dell'API. Ideale per un pulsante «Verifica connessione».

Nessun parametro.

Codici di risposta

200 OK401 chiave non valida

Richiesta

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

Risposta

Response · 200 OK
{
  "ok": true,
  "env": "live",
  "plan": "pro",
  "apiVersion": "1.0.0"
}
Provare questo endpoint

La richiesta viene inviata all'API reale, per Suo conto. Utilizzi una chiave di test (tor_test_…) — una chiamata in produzione crea dati reali. La chiave non viene mai memorizzata né inviata altrove.

GET

/account

Chiave richiesta

Stato dell'account: piano effettivo, ambiente, abbonamento (periodo di prova o a pagamento), quota mensile (used/limit/remaining) e limiti (frequenza delle richieste, chiavi, wallet). Il campo subscription (status trialing/active, realPlan, trialEndsAt in epoch s, trialDaysRemaining) deve determinare il badge del piano — non il solo campo plan, che vale 'plus' durante il periodo di prova.

Nessun parametro.

Codici di risposta

200 OK401 chiave non valida

Richiesta

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

Risposta

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 }
}
Provare questo endpoint

La richiesta viene inviata all'API reale, per Suo conto. Utilizzi una chiave di test (tor_test_…) — una chiamata in produzione crea dati reali. La chiave non viene mai memorizzata né inviata altrove.

GET

/tokens

Chiave richiesta

Matrice dei pagamenti supportati (token × catene), derivata dalla configurazione (unica fonte di verità, contratti verificati sulla blockchain). La recuperi invece di scrivere l'elenco a mano → resta aggiornata quando si aggiungono catene o token. Vengono restituite solo le coppie PAGABILI (native, oppure ERC-20/SPL con un contratto). I contratti dipendono dall'ambiente della chiave (test/live).

Nessun parametro.

Codici di risposta

200 OK401 chiave non valida

Richiesta

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

Risposta

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…" } ] }
  ]
}
Provare questo endpoint

La richiesta viene inviata all'API reale, per Suo conto. Utilizzi una chiave di test (tor_test_…) — una chiamata in produzione crea dati reali. La chiave non viene mai memorizzata né inviata altrove.

GET

/screen

Chiave richiesta

Verifica se un indirizzo crypto figura nelle liste di SANZIONI che consultiamo (liste OFAC, UE, Regno Unito e Svizzera, scaricate da noi; in più l'oracolo di Chainalysis sulla blockchain per gli indirizzi EVM). Restituisce sanctioned (true/false), oppure null quando l'indirizzo non può essere verificato (non valido, catena non supportata, oracolo non disponibile). Da chiamare prima di inviare o ricevere fondi. Il risultato viene memorizzato nella cache (validità di circa 24 h).

Chiave obbligatoria (piano gratuito incluso). Limite di richieste al minuto in base al Suo piano. Indirizzi EVM: liste scaricate (OFAC, UE, Regno Unito, Svizzera) + oracolo di Chainalysis. Indirizzi Bitcoin e Solana: solo liste scaricate. sanctioned: null = verifica impossibile (indirizzo non valido, lista non aggiornata, oracolo non disponibile). Informazione di conformità, non consulenza legale.

address (query, obbligatorio) — l'indirizzo da verificare.

Codici di risposta

200 OK400 indirizzo mancante401 chiave non valida429 limite di richieste superato

Richiesta

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

Risposta

Response · 200 OK
{
  "success": true,
  "address": "0x098B716B…",
  "status": "sanctioned",
  "sanctioned": true,
  "source": "chainalysis_oracle"
}
Provare questo endpoint

La richiesta viene inviata all'API reale, per Suo conto. Utilizzi una chiave di test (tor_test_…) — una chiamata in produzione crea dati reali. La chiave non viene mai memorizzata né inviata altrove.

POST

/generate-qr

Chiave richiesta

Genera un codice QR (PNG in base64) che codifica un URI di pagamento standard (BIP-21, EIP-681, Solana Pay). Per i token nativi (BTC, ETH, SOL, POL) e USDC su Solana. Per le stablecoin ERC-20 su EVM, utilizzi /create-session.

Chiave obbligatoria (piano gratuito incluso). Limite di richieste al minuto in base al Suo piano. Il QR punta sempre a un wallet registrato nel Suo account. Intestazioni X-RateLimit-* in ogni risposta.

Body

token* string — BTC, ETH, SOL, POL, USDC (Solana)
chainId* string — bitcoin, ethereum, polygon, base, solana
amount* string — Decimale canonico (es. «0.001»)
recipientAddress* string — Indirizzo del destinatario (convalidato per la rete)
format string — Formato di output: png (predefinito, data URI in base64), svg (markup vettoriale) o text (caratteri a blocchi da stampare in un terminale; restituito come qrCodeText).
textBackground string — Per format: text: sfondo del terminale in cui verrà mostrato il testo, dark (predefinito) o light. Uno sfondo sbagliato produce un codice QR invertito che molti telefoni non riescono a leggere.

Codici di risposta

200 OK400 input non valido / endpoint errato401 chiave non valida409 conflitto di Idempotency-Key429 limite di richieste

Richiesta

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

Risposta

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..."
}
Provare questo endpoint

La richiesta viene inviata all'API reale, per Suo conto. Utilizzi una chiave di test (tor_test_…) — una chiamata in produzione crea dati reali. La chiave non viene mai memorizzata né inviata altrove.

POST

/create-session

Chiave richiesta

Crea una sessione di pagamento ospitata (pagamento da wallet a wallet, direttamente all'indirizzo dell'esercente) per le stablecoin ERC-20 (USDC, USDT, EURC) su Ethereum, Polygon e Base. Restituisce un URL /pay da condividere con il pagatore. La sessione scade 15 minuti dopo la creazione.

Una chiave di test (tor_test_…) crea una sessione nell'ambiente di prova su testnet, fuori quota — ideale per sviluppare un plugin. Una chiave di produzione (tor_live_…) rientra nella quota mensile di pagamenti confermati sulla blockchain (402 quando è esaurita).

Body

token* string — USDC, USDT, EURC, PYUSD, USDG, RLUSD, USAT, OUSD
chainId* string — ethereum, polygon, base
amount* string — Decimale canonico (es. «100»)
recipientAddress* string — Indirizzo EVM del destinatario (convalidato a livello centrale)

Codici di risposta

200 OK400 input non valido401 chiave non valida402 quota mensile esaurita409 conflitto di Idempotency-Key429 limite di richieste

Richiesta

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

Risposta

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..."
}
Provare questo endpoint

La richiesta viene inviata all'API reale, per Suo conto. Utilizzi una chiave di test (tor_test_…) — una chiamata in produzione crea dati reali. La chiave non viene mai memorizzata né inviata altrove.

GET

/wallets

Chiave richiesta

Elenca (SOLA LETTURA) gli indirizzi di ricezione dell'account. Ogni wallet restituisce address, family, label, source, ownershipProven (true = proprietà dimostrata da un messaggio firmato, oppure indirizzo letto da un exchange collegato), custodial (true = indirizzo di deposito del conto exchange DELL'ESERCENTE stesso, ad es. Binance/Coinbase, detenuto dall'exchange, mai da Toreador) e acceptedRails: null = nessuna restrizione (wallet in autocustodia, tutte le reti della famiglia); altrimenti le coppie (token, catena) che la fonte custodial accredita SU QUESTO indirizzo. IMPORTANTE: per un wallet custodial, limiti la Sua matrice di pagamento ad acceptedRails — una coppia non accreditata non viene proposta al pagatore (l'exchange non la accrediterebbe e i fondi andrebbero persi). L'aggiunta o la rimozione dei wallet avviene nella dashboard autenticata (passkey) — mai tramite l'API.

Nessun parametro.

Codici di risposta

200 OK401 chiave non valida

Richiesta

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

Risposta

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" }] }
  ]
}
Provare questo endpoint

La richiesta viene inviata all'API reale, per Suo conto. Utilizzi una chiave di test (tor_test_…) — una chiamata in produzione crea dati reali. La chiave non viene mai memorizzata né inviata altrove.

POST

/checkout

Chiave richiesta

Crea un checkout espresso in valuta FIAT (USD/EUR): l'esercente fissa un importo in valuta, il pagatore connette un wallet nella pagina ospitata /pay (pagamento da wallet a wallet, direttamente all'indirizzo dell'esercente) e sceglie la stablecoin e la catena. Da preferire per le integrazioni (l'esercente non deve capire «USDC su Base»).

conversion:"off" (predefinito) propone solo stablecoin della stessa valuta (USD→USDC/USDT). conversion:"on" propone anche stablecoin dell'altra valuta: l'importo dovuto viene calcolato su un tasso di riferimento indicativo (fonte e marca temporale registrate), fissato al momento della scelta della coppia stablecoin/rete. Toreador non esegue alcuna conversione: il pagatore invia quella stablecoin direttamente al wallet dell'esercente.

Body

amount* number — Importo in VALUTA (es. 50), non in token
currency* string — USD, EUR
recipientAddress* string — Indirizzo di ricezione (EVM 0x… o Solana). Fornito dal SUO sistema, che gestisce la rotazione.
description string — Etichetta mostrata al pagatore (≤ 500 caratteri)
conversion string — «off» (predefinito) o «on»
acceptNative boolean — Offre anche il pagamento in crypto NATIVA (ETH/POL); importo calcolato al tasso attuale (riferimento indicativo). La volatilità è a carico dell'esercente.
reference string — Riferimento libero (es. id dell'ordine), riportato sul checkout, su /payment/{id} e su /sessions, per correlare il pagamento dal Suo lato (≤ 255 caratteri).

Codici di risposta

200 OK400 input non valido / valuta non supportata401 chiave non valida402 quota mensile esaurita409 nessun wallet / nessun rail429 limite di richieste

Richiesta

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

Risposta

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
}
Provare questo endpoint

La richiesta viene inviata all'API reale, per Suo conto. Utilizzi una chiave di test (tor_test_…) — una chiamata in produzione crea dati reali. La chiave non viene mai memorizzata né inviata altrove.

POST

/webhooks

Chiave richiesta

Registra (o aggiorna, in modo IDEMPOTENTE per URL) l'endpoint webhook dell'account per ricevere gli eventi in PUSH. Un'integrazione lo chiama automaticamente dopo Connect. Restituisce il segreto HMAC UNA SOLA VOLTA — da conservare cifrato. L'URL deve essere HTTPS pubblico e, se la chiave è stata emessa tramite Connect, appartenere al dominio della chiave.

Firma: intestazione Toreador-Signature = t=…,v1=… (HMAC-SHA256 in esadecimale della stringa {t}.{rawBody}). Eventi: session.created/submitted/confirming/completed/expired/failed, checkout.created. Consegna: 2xx = successo, altrimenti nuovi tentativi (fino a 9, con backoff). GET /webhooks li elenca (senza segreto); DELETE /webhooks/{id} lo elimina.

Body

url* string — Endpoint HTTPS pubblico (sul dominio della chiave)
events string[] — Eventi sottoscritti (predefinito: session.completed/failed/expired)
description string — Etichetta (≤ 200 caratteri)

Codici di risposta

200 OK400 URL non valido / non HTTPS401 chiave non valida403 URL fuori dal dominio della chiave

Richiesta

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

Risposta

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
}
Provare questo endpoint

La richiesta viene inviata all'API reale, per Suo conto. Utilizzi una chiave di test (tor_test_…) — una chiamata in produzione crea dati reali. La chiave non viene mai memorizzata né inviata altrove.

GET

/payment/{id}

Chiave richiesta

Recupera un oggetto Payment unificato — QR nativo (type: native) o sessione ERC-20 (type: session) — con la cronologia dei suoi eventi. Accetta ANCHE un id di checkout (co_…): viene risolto nel pagamento di quel checkout (ideale per seguire un ordine tramite il suo checkoutId, senza conoscere l'id della sessione).

Parametro di percorso

id* string — Id del pagamento / della sessione, OPPURE id di un checkout (co_…)

Codici di risposta

200 OK404 non trovato

Richiesta

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

Risposta

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 } ]
}
Provare questo endpoint

La richiesta viene inviata all'API reale, per Suo conto. Utilizzi una chiave di test (tor_test_…) — una chiamata in produzione crea dati reali. La chiave non viene mai memorizzata né inviata altrove.

GET

/payment/{id}/status

Chiave richiesta

Restituisce lo stato attuale di una sessione di pagamento. Per il tracciamento in tempo reale lato pagatore, la pagina /pay utilizza un flusso SSE; lato server, preferisca i webhook firmati (vedere più sotto).

Parametro di percorso

id* string — Id della sessione (restituito da /create-session)

Codici di risposta

200 OK404 non trovato

Richiesta

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

Risposta

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
}
Provare questo endpoint

La richiesta viene inviata all'API reale, per Suo conto. Utilizzi una chiave di test (tor_test_…) — una chiamata in produzione crea dati reali. La chiave non viene mai memorizzata né inviata altrove.

GET

/establishments

Chiave richiesta

Elenca (SOLA LETTURA) i punti vendita della chiave: id, name, isDefault. Un id si usa come establishment_id, sia alla creazione di una richiesta di pagamento sia come filtro di /sessions, /history e /export.

Nessun parametro.

Codici di risposta

200 OK401 chiave non valida

Richiesta

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

Risposta

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" }
  ]
}
Provare questo endpoint

La richiesta viene inviata all'API reale, per Suo conto. Utilizzi una chiave di test (tor_test_…) — una chiamata in produzione crea dati reali. La chiave non viene mai memorizzata né inviata altrove.

GET

/history

Chiave richiesta

Elenco paginato dei codici QR generati dall'organizzazione della chiave e dal suo team (prima i più recenti). Ogni elemento riporta establishmentId e establishmentName. Una chiave restituisce solo i pagamenti del proprio ambiente: una chiave di produzione non restituisce mai pagamenti di test, una chiave di test restituisce solo pagamenti di test.

Query

limit integer — 1–100, predefinito 20
cursor string — Cursore opaco (next_cursor della pagina precedente)
establishment_id string — Solo i pagamenti di questo punto vendita (un id da GET /establishments)

Codici di risposta

200 OK401 chiave non valida

Richiesta

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

Risposta

Response · 200 OK
{
  "success": true,
  "data": [ { "id": "...", "type": "native", "amount": "0.001", "createdAt": 1718000000 } ],
  "has_more": true,
  "next_cursor": "eyJpZCI6..."
}
Provare questo endpoint

La richiesta viene inviata all'API reale, per Suo conto. Utilizzi una chiave di test (tor_test_…) — una chiamata in produzione crea dati reali. La chiave non viene mai memorizzata né inviata altrove.

GET

/sessions

Chiave richiesta

Elenco paginato delle sessioni di pagamento dell'organizzazione della chiave e del suo team (prima le più recenti). Ogni elemento riporta establishmentId e establishmentName. Una chiave restituisce solo i pagamenti del proprio ambiente: una chiave di produzione non restituisce mai pagamenti di test, una chiave di test restituisce solo pagamenti di test.

fxRate, fxSource e fxQuotedAt descrivono il tasso di riferimento indicativo usato per calcolare l'importo in token (valore, fonte, marca temporale). Toreador non esegue alcuna conversione: token e amount sono ciò che il pagatore ha inviato sulla blockchain, dal proprio wallet, al wallet dell'esercente.

Query

limit integer — 1–100, predefinito 20
cursor string — Cursore di paginazione opaco
establishment_id string — Solo i pagamenti di questo punto vendita (un id da GET /establishments)

Codici di risposta

200 OK401 chiave non valida

Richiesta

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

Risposta

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
}
Provare questo endpoint

La richiesta viene inviata all'API reale, per Suo conto. Utilizzi una chiave di test (tor_test_…) — una chiamata in produzione crea dati reali. La chiave non viene mai memorizzata né inviata altrove.

GET

/export

Chiave richiesta

Esportazione CONTABILE dei pagamenti confermati sulla blockchain, con il tasso di riferimento (importo fatturato ↔ importo pagato sulla blockchain + tasso indicativo + fonte + marca temporale + tx). In CSV (predefinito, scaricabile) o JSON. Periodo facoltativo (from/to). Con format=quickbooks, xero, odoo o pennylane: il file di importazione delle transazioni bancarie di quel software, una valuta per file. Una chiave restituisce solo i pagamenti del proprio ambiente: una chiave di produzione non restituisce mai pagamenti di test, una chiave di test restituisce solo pagamenti di test.

Guida ai campi: settlementToken, settlementChain e settlementAmount = token, rete e importo effettivamente pagati sulla blockchain dal pagatore, dal proprio wallet, al wallet dell'esercente (Toreador non regola nulla); fxRate, fxSource e fxQuotedAt = il tasso di riferimento indicativo usato per calcolare tale importo, la sua fonte e la sua marca temporale (informativo, nessuna conversione eseguita); invoiceAmount / invoiceCurrency = l'importo fatturato dall'esercente.

Query

format string — «csv» (predefinito) o «json»: l'esportazione completa. «quickbooks», «xero», «odoo» o «pennylane»: un file per l'importazione delle transazioni bancarie di quel software di contabilità
currency string — Solo file di importazione: la valuta del file. Facoltativo quando il periodo contiene una sola valuta
from integer — Inizio del periodo (epoch s, su completed_at)
to integer — Fine del periodo (epoch s)
establishment_id string — Solo i pagamenti di questo punto vendita (un id da GET /establishments)

Codici di risposta

200 OK400 parametro non valido, o valuta obbligatoria401 chiave non valida

Richiesta

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

Risposta

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…" } ]
}
Provare questo endpoint

La richiesta viene inviata all'API reale, per Suo conto. Utilizzi una chiave di test (tor_test_…) — una chiamata in produzione crea dati reali. La chiave non viene mai memorizzata né inviata altrove.

Webhooks

Per essere avvisato dei cambiamenti di stato lato server (senza polling), registri un endpoint webhook. Toreador invia in POST un evento firmato HMAC-SHA256 (intestazione Toreador-Signature: t=…,v1=…) a ogni transizione.

session.createdsession.submittedsession.confirmingsession.completedsession.expiredsession.failedcheckout.created
Verifica della firma ed esempio completo →

Changelog

v1.0.0

La versione principale è indicata nell'URL (/v1/). Le modifiche retrocompatibili (nuovi campi, parametri facoltativi, endpoint) sono elencate qui e non rompono mai la v1; una modifica incompatibile verrebbe pubblicata come /v2/. Ogni risposta contiene l'intestazione API-Version.

v1.0.0 2026-06-13
  • AddedAPI pubblica v1: generazione di QR (nativi + Solana SPL), sessioni di pagamento ERC-20 ospitate (da wallet a wallet, direttamente all'indirizzo dell'esercente), recupero di pagamenti e stati, cronologia e sessioni paginate.
  • AddedWebhook firmati HMAC-SHA256 (session.created/submitted/confirming/completed/expired/failed).
  • AddedChiavi di test/produzione (sandbox testnet, fuori quota); QR in uscita in png o svg tramite il parametro format.
  • AddedHeader API-Version su ogni risposta; struttura di errore tipizzata + idempotenza (Idempotency-Key).
  • AddedPunti vendita: GET /establishments, establishmentId e establishmentName sui pagamenti, filtro establishment_id su elenchi ed esportazione; una chiave legge i pagamenti creati da tutto il team.
  • AddedFile di importazione contabile: GET /export?format=quickbooks|xero|odoo|pennylane, una valuta per file.
  • AddedGli ambienti sono separati: una chiave di produzione legge solo i pagamenti di produzione, una chiave di test legge solo i pagamenti di test (elenchi, esportazione, lettura per id).

Rispettiamo la Sua privacy

Utilizziamo cookie analitici per migliorare il nostro servizio. Questi cookie vengono attivati solo con il Suo consenso. I cookie essenziali (autenticazione, lingua ecc.) sono sempre attivi.