Che cos'è la Merchant API?
La Merchant API è l’API di pagamento dell’app per aziende e bot. Crei un’app, ottieni un token API e con quello fatturi agli utenti Telegram, gli mandi pagamenti e controlli il tuo saldo, tutto dal tuo codice.
È il lato sviluppatore dello stesso prodotto che vedono gli utenti: una fattura che crei dall’API è la fattura che loro pagano dal saldo dopo aver confermato il pagamento.
Che cosa ci puoi fare
- Fatture — crei una fattura (un importo fisso in cripto, uno prezzato in valuta fiat o un importo libero che sceglie chi paga), mandi il link a chi deve pagare e ricevi un webhook firmato dopo il pagamento, se hai configurato un URL per i webhook.
- Rimborsi — restituisci l’importo di una fattura pagata, in tutto o in parte, a chi l’ha pagata: anche a chi ha pagato in forma anonima.
- Trasferimenti — mandi cripto dal saldo della tua app a un utente Telegram, uno alla volta o fino a 100 in un colpo solo.
- Buoni — finanzi dal saldo della tua app link riscattabili da chiunque o da destinatari nominativi, secondo le impostazioni dei pagamenti.
- Abbonamenti — fatturazione ricorrente: l’utente approva un piano una volta e la quota viene addebitata automaticamente a ogni periodo.
- Saldi, valute, tassi di cambio e statistiche — endpoint di sola lettura per la tua contabilità.
Come si incastra tutto
- La tua app ha un saldo, separato dal tuo portafoglio personale.
- Le fatture pagate dagli utenti accreditano quel saldo dell’app.
- Trasferimenti e buoni escono da quel saldo.
- Gli eventi di pagamento supportati possono arrivare al tuo server come webhook firmato, se configuri l’URL e attivi gli eventi desiderati.
I pagamenti si chiudono dentro l’app, non on-chain: niente commissione di rete,
nessuna conferma da aspettare e fondi utilizzabili nell’istante in cui arrivano.
Chi paga può anche versare i fondi da un portafoglio esterno, se l’opzione è
disponibile. Il deposito viene accreditato sul suo portafoglio; il pagamento
automatico richiede anche saldo sufficiente, nessuna restrizione in uscita
e un termine di pagamento valido. Prima di evadere l’ordine, controlla
che lo stato della fattura sia paid.
Compatibile con Crypto Bot
L’API è fatta apposta per rispecchiare quella di Crypto Bot: stessi nomi dei
metodi, stessa struttura di risposta {ok, result}, stessi importi come stringhe decimali,
stesso schema di firma dei webhook. Per adattare un’integrazione esistente,
cambia l’URL di base e il token, poi prova i metodi che usi seguendo
il nostro riferimento. Come Crypto Bot, anche noi abbiamo una
testnet, con un bot e un URL di base
separati.
L’intestazione ufficiale del token è TgPayCrypto-API-Token;
TgCryptoPay-API-Token, il nome in uso prima del 2026-09-07, funziona
ancora, e accettiamo Crypto-Pay-API-Token come alias, così le librerie
client esistenti continuano a funzionare senza modifiche.
⚠️ Il tuo token API può spendere i tuoi fondi
Il token principale autorizza pagamenti entro la modalità e i limiti dell’app. Tienilo lato server, fuori dalle app client e dai repository, e rigeneralo appena sospetti che sia trapelato. Per i server che non hanno bisogno dell’accesso completo, emetti un token con permessi limitati, ristretto agli ambiti che usano davvero: vedi il riferimento dell’API.
Il prossimo passo
Questa guida ti è stata utile?
Grazie del riscontro.