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.
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.
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).
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
/ping
Chiave richiestaVerifica 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
Richiesta
Risposta
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.
/account
Chiave richiestaStato 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
Richiesta
Risposta
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.
/tokens
Chiave richiestaMatrice 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
Richiesta
Risposta
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.
/screen
Chiave richiestaVerifica 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).
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
Richiesta
Risposta
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.
/generate-qr
Chiave richiestaGenera 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.
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
Richiesta
Risposta
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.
/create-session
Chiave richiestaCrea 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.
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
Richiesta
Risposta
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.
/wallets
Chiave richiestaElenca (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
Richiesta
Risposta
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.
/checkout
Chiave richiestaCrea 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
Richiesta
Risposta
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
Chiave richiestaRegistra (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.
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
Richiesta
Risposta
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.
/payment/{id}
Chiave richiestaRecupera 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
Richiesta
Risposta
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.
/payment/{id}/status
Chiave richiestaRestituisce 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
Richiesta
Risposta
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.
/establishments
Chiave richiestaElenca (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
Richiesta
Risposta
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.
/history
Chiave richiestaElenco 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
Richiesta
Risposta
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.
/sessions
Chiave richiestaElenco 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
Richiesta
Risposta
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.
/export
Chiave richiestaEsportazione 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.
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
Richiesta
Risposta
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
Changelog
v1.0.0La 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.
- 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
pngosvgtramite il parametroformat. - AddedHeader
API-Versionsu ogni risposta; struttura di errore tipizzata + idempotenza (Idempotency-Key). - AddedPunti vendita:
GET /establishments,establishmentIdeestablishmentNamesui pagamenti, filtroestablishment_idsu 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).