Merchant API (Sviluppatori)
La Merchant API: app, fatture, trasferimenti e webhook.
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.
Iniziare da sviluppatore
Crei un'app nella Mini App, copi il token API l'unica volta in cui te lo mostriamo e cominci a chiamare l'API. Tutta la configurazione sta sotto Altro → Merchant API.
Collegare un agente AI
Collega un agente AI per lo sviluppo che supporti server MCP remoti a https://app.tgpaycrypto.com/mcp. Può leggere la documentazione API, richiedere un'app per commercianti, configurare i webhook e aiutarti a scrivere l'integrazione. Approvi la creazione dell'app nel bot e l'agente riceve un token con permessi limitati, senza che tu debba copiarlo a mano. Controlla e prova l'integrazione prima di accettare pagamenti reali.
Incassare con le fatture
Con una fattura chiedi un pagamento a un utente Telegram. La crei tramite l'API e mandi il link a chi deve pagare. Quando il pagamento va a buon fine, l'importo viene accreditato sul saldo della tua app al netto della commissione.
Commissioni e limiti della Merchant API
Le fatture hanno una commissione della piattaforma, che viene detratta da quello che incassi; trasferimenti e buoni hanno limiti di importo. I valori qui sotto sono le impostazioni attuali, non clausole contrattuali: quando non coincidono con quello che vedi ha ragione l'app, e la fonte affidabile restano sempre le tue fatture pagate.
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.
Riferimento API: fatture e rimborsi
I metodi delle fatture: createInvoice, getInvoices, deleteInvoice, refundInvoice. Le convenzioni comuni (autenticazione, struttura delle risposte, importi, spend_id) stanno nella pagina Riferimento della Merchant API; la guida passo passo è Incassare con le fatture.
Riferimento API: trasferimenti e buoni
I metodi per effettuare pagamenti. Un trasferimento invia fondi dal saldo della tua app al portafoglio di un utente Telegram oppure li tiene bloccati finché un nuovo destinatario non apre il bot. Un buono è un link da riscattare che finanzi in anticipo. Le convenzioni comuni (autenticazione, struttura delle risposte, importi, spend_id) sono descritte nella pagina Riferimento della Merchant API.
Riferimento API: abbonamenti
Fatturazione ricorrente: un'estensione rispetto a Crypto Bot. Crei un piano (importo + periodo), mandi agli utenti il suo link di approvazione, e la piattaforma addebita la quota sul loro saldo a ogni periodo, accreditando l'importo sul saldo della tua app al netto della commissione. Le convenzioni comuni sono descritte nella pagina Riferimento della Merchant API.
Riferimento API: webhook
I webhook inviano gli eventi al tuo server dopo che si verificano. Imposta l'URL del webhook (facoltativo) sulla tua app in Altro → Merchant API: da lì in poi la piattaforma manda in POST un corpo JSON firmato per ogni evento a cui sei iscritto.
Condizioni della Merchant API
Queste condizioni regolano la Merchant API: app, token API, fatture, abbonamenti, trasferimenti, buoni, webhook e il collegamento di un agente AI. Si applicano in aggiunta alle condizioni d'uso generali dell'app e alla sua politica AML. Creando un'app le accetti; continuando a usare un'app creata prima del 7 settembre 2026 le accetti allo stesso modo.