Riferimento della Merchant API

Le convenzioni comuni a tutti i metodi, più i metodi di sola lettura del catalogo. Le pagine metodo per metodo: fatture e rimborsi, trasferimenti e buoni, abbonamenti, webhook.

L’API è compatibile con Crypto Bot: un’integrazione Crypto Bot esistente funziona cambiando solo l’URL di base e il token. Tutto quello che va oltre quel contratto è segnato qui sotto come estensione.

Insieme a queste pagine pubblichiamo una specifica OpenAPI 3.1 leggibile dalle macchine, con tutta l’API — ogni metodo, oggetto, nome d’errore e webhook: crypto-pay-openapi.yaml · crypto-pay-openapi.json. Passala a un generatore di codice, a un client API o ai tuoi strumenti di AI.

Base URL e autenticazione

Tutti i metodi stanno su https://crypto.tgpaybot.com/pay/api/<methodName>.

Autentica ogni richiesta con il token nell’intestazione TgCryptoPay-API-Token (Crypto-Pay-API-Token è accettata come alias di compatibilità; se le mandi entrambe, vince quella ufficiale). Un token mancante, non valido o revocato — o il token di un’app eliminata — restituisce 401 unauthorized.

Il token ha la forma <app_id>:<secret> e si vede una volta sola, alla creazione o alla rigenerazione; il server ne conserva solo l’hash. Vedi iniziare da sviluppatore.

Token e ambiti

Ci sono due tipi di credenziali, che si autenticano allo stesso modo:

• Il token principale — accesso completo a ogni metodo, ed è l’unica chiave che firma i webhook.
• I token con permessi limitati (estensione) — fino a 10 attivi per app, creati in Altro → Merchant API sotto Token con permessi limitati, ciascuno con un’etichetta e un sottoinsieme di ambiti. Revocarne uno è immediato e non tocca gli altri; nemmeno rigenerare il token principale li tocca.

Ambito	Metodi che sblocca
(qualsiasi token valido)	getMe, getCurrencies, getExchangeRates
read	getBalance, getStats, getInvoices, getChecks, getTransfers, getSubscriptionPlans, getSubscriptions
invoices	createInvoice, deleteInvoice
refunds	refundInvoice
payouts	transfer, transferBatch
checks	createCheck, deleteCheck
subscriptions	createSubscriptionPlan, archiveSubscriptionPlan, cancelSubscription

Gli ambiti si sommano e sono indipendenti: invoices non implica read, quindi un server che si limita a creare fatture può avere un token che non riesce a leggere niente. Chiamare un metodo che il token non copre restituisce 403 scope_required. getMe riporta gli scopes del token in uso (null per il token principale) e il suo token_name, così sai sempre che cosa hai in mano.

Richieste e risposte

• I metodi di lettura sono GET, con i parametri nella query. I metodi che muovono denaro sono solo POST: parametri come corpo JSON, come form-urlencoded o nella query (in caso di conflitto vince il corpo); multipart/form-data viene rifiutato.
• Ogni risposta è JSON con la stessa busta: in caso di successo {"ok": true, "result": …}, in caso di errore {"ok": false, "error": {"code": <stato HTTP>, "name": "<nome_errore>"}}. Ramifica su error.name: è la stringa stabile e leggibile dalle macchine.
• Un caso limite: un valore di query del tipo sbagliato su un metodo GET (per esempio offset=abc) restituisce un HTTP 422 con un corpo {"detail": …} fuori dalla busta. Manda valori di query ben tipizzati.

Gli importi

• Gli importi in cripto sono stringhe decimali in unità intere di moneta ("10.5"), mai numeri JSON. Le risposte portano anche amount_minor (estensione): il valore intero nelle unità minori, come stringa, perché gli interi su scala wei superano il limite di un Number di JavaScript.
• I decimals di ogni asset arrivano da getCurrencies: fai i tuoi conti a partire da lì, invece di scriverli fissi nel codice.
• Gli importi in valuta fiat hanno al massimo 2 decimali.
• I tassi sono stringhe a virgola fissa, mai numeri.

La paginazione

I metodi che restituiscono elenchi (getInvoices, getChecks, getTransfers, getSubscriptions) accettano offset (predefinito 0) e count (predefinito 100, al massimo 1000; per getSubscriptions al massimo 500) e restituiscono {"items": […]}, dal più recente. I filtri per ID (invoice_ids, check_ids, transfer_ids) sono elenchi di interi separati da virgola. Le date e gli orari, ovunque, sono stringhe ISO 8601.

Idempotenza: spend_id

I metodi che muovono denaro accettano una chiave spend_id generata da chi chiama (da 1 a 64 caratteri): obbligatoria su transfer e su ogni elemento di transferBatch, facoltativa su createCheck e refundInvoice (estensione: usala lo stesso). Ritentare con la stessa chiave e gli stessi parametri ripete il risultato originale invece di muovere denaro due volte, quindi una richiesta andata in timeout si può sempre ritentare senza rischi. La stessa chiave con parametri diversi restituisce 409 idempotency_conflict; un tentativo mentre l’originale è ancora in esecuzione restituisce 409 idempotency_in_progress.

I limiti di frequenza

Sono per app e condivisi tra tutti i suoi token; superarli restituisce 429 rate_limited:

Metodo	Limite
createInvoice, createCheck	60 al minuto
refundInvoice, transfer	30 al minuto
transferBatch	10 al minuto

I metodi di lettura non hanno limiti di frequenza. Durante la manutenzione della piattaforma i metodi di scrittura restituiscono 503 maintenance, mentre le letture continuano a funzionare.

Metodi di catalogo e di account

getMe

GET /pay/api/getMe — nessun parametro. Restituisce l’identità dell’app: app_id, name, payment_processing_bot_username, webhook_url, webhook_events (i tipi di webhook estesi che l’app ha attivato) e i campi di introspezione del token scopes / token_name descritti sopra.

getBalance

GET /pay/api/getBalance — nessun parametro. Restituisce un elenco con una riga per ogni asset supportato, anche a zero: currency_code, available (il saldo spendibile), onhold (i fondi bloccati nei tuoi buoni ancora aperti) e amount_minor.

getCurrencies

GET /pay/api/getCurrencies — nessun parametro. L’elenco che fa fede su quello che l’API supporta: le righe delle cripto (is_blockchain: true) e le valute fiat in cui si possono prezzare le fatture (is_fiat: true). Ogni riga porta code, name, decimals e il flag is_stablecoin.

getExchangeRates

GET /pay/api/getExchangeRates — nessun parametro. Le quotazioni da cripto a valuta fiat: source, target, rate (una stringa a virgola fissa) e is_valid; false vuol dire che tutta la tabella arriva da una cache vecchia, quindi prendi quei tassi solo come indicativi.

getStats

GET /pay/api/getStats — start_at / end_at facoltativi (ISO 8601; per impostazione predefinita la finestra è le ultime 24 ore). Restituisce volume (il valore in dollari delle fatture pagate nella finestra), conversion (pagate su create, in percentuale), unique_users_count, created_invoice_count, paid_invoice_count e gli estremi effettivi della finestra. Una data illeggibile restituisce 400 invalid_date.

Errori che può restituire qualsiasi metodo

HTTP	error.name	Quando
401	unauthorized	token mancante, non valido o revocato
403	scope_required	al token manca l’ambito del metodo
400	invalid_request	parametri illeggibili o non validi (POST)
429	rate_limited	limite di frequenza superato
503	maintenance	manutenzione della piattaforma (metodi di scrittura)
500	internal_error	errore imprevisto del server

Gli errori specifici di ogni metodo sono elencati nella sua pagina.