Pagamenti crypto in un bot Telegram: fatture, webhook e pagamenti agli utenti
La Merchant API è l'API di pagamento di TgPay Crypto per bot e servizi. Crea un'app nel bot, ottieni un token, emetti fatture dal codice e ricevi un webhook firmato a ogni pagamento. Puoi anche affidare l'integrazione al tuo agente AI tramite il server MCP. I pagamenti avvengono nel servizio, senza commissioni di rete né attese per le conferme.
Base API: app.tgpaycrypto.com/pay/api · Testnet: testnet.tgpaycrypto.com
Dal token al primo pagamento in quattro passaggi
Crea una fattura, mostra il link e attendi l'evento di pagamento.
Crea un'app
Nel bot apri Altro → Merchant API, inserisci un nome e l'URL del webhook. Il token viene mostrato una sola volta: conservalo sul server.
Crea una fattura
Una richiesta POST a createInvoice con importo in crypto o valuta, descrizione e scadenza. La risposta contiene il link di pagamento.
Mostra il link all'utente
Aggiungi un pulsante o un link al bot. L'utente paga dal saldo del portafoglio.
Gestisci il webhook
Il server riceve invoice_paid firmato con HMAC-SHA256. Verifica la firma, elimina i duplicati tramite update_id e consegna il prodotto.
Il tuo agente AI può preparare l'integrazione
La Merchant API dispone di un server MCP. Passa l'URL all'agente: consulta la documentazione, crea l'app con il tuo consenso, configura il webhook e scrive il codice. Non devi copiare token a mano.
- Passaggio 1
Invia la richiesta al tuo agente
Usa Claude Code, claude.ai, Claude Desktop, ChatGPT o un altro client MCP. La stessa richiesta è nell'app, in Altro → Merchant API → Collega un agente AI.
- Passaggio 2
Approva l'app in Telegram
L'agente fornisce un link t.me. Il bot mostra la richiesta e tu la approvi. Il link è monouso e nulla viene creato prima del tuo consenso.
- Passaggio 3
L'agente completa la configurazione
Riceve un token limitato e configura fatture, piani di abbonamento e webhook. La chiave di firma del webhook resta a tua disposizione nell'app.
Il token fornito da questo percorso può ricevere pagamenti e configurare il webhook, ma non trasferire fondi, creare buoni o rimborsare. Le operazioni in uscita richiedono permessi separati sotto il tuo controllo.
Il percorso con l'agente nella documentazioneConnect the tgpay MCP server (https://app.tgpaycrypto.com/mcp) and integrate payments via the TgPay Merchant API.
claude mcp add --transport http tgpay https://app.tgpaycrypto.com/mcp
Aggiungi app.tgpaycrypto.com/mcp come server MCP nelle impostazioni del tuo client
https://testnet.tgpaycrypto.com/mcp
Commissioni e limiti
I valori provengono dal catalogo pubblico dei limiti al momento della generazione della pagina. L'app mostra i valori in vigore.
Cosa offre la Merchant API
L'app ha un saldo separato dal portafoglio: le fatture lo accreditano, pagamenti e buoni lo addebitano.
Fatture e rimborsi
Importo fisso in crypto, prezzo in valuta o importo libero scelto dal pagatore. Rimborsi totali o parziali, anche per pagatori anonimi.
Abbonamenti
L'utente approva un piano una volta. Gli addebiti successivi sono automatici, con un evento per ciascuno.
Trasferimenti e buoni
Pagamenti agli utenti Telegram dal saldo dell'app e buoni da condividere tramite link, riscattabili secondo le condizioni impostate.
Webhook
invoice_paid viene sempre inviato. Gli eventi per scadenza delle fatture, riscatto dei buoni, rimborsi e abbonamenti si attivano per ogni app.
Testnet
La stessa API e mini app in @tgpaycrypto_testnet_bot. Un pulsante nella schermata principale fornisce crypto di test una volta all'ora.
Agente AI e MCP
Passa app.tgpaycrypto.com/mcp al tuo agente: crea l'app, configura il webhook e prepara l'integrazione. Tu approvi la creazione nel bot.
Compatibilità con l'API Crypto Bot
Nomi dei metodi, struttura {ok, result} e firma dei webhook sono compatibili. Cambia URL di base e token, poi verifica i metodi usati dall'integrazione.
Token sotto controllo
Token con permessi limitati, rotazione immediata, pagamenti solo a utenti autorizzati o disattivati e limite giornaliero in caso di perdita del token.
Domande sull'API
Token, firme dei webhook, test e migrazione da altre API.
La creazione può richiedere la verifica dell'identità completata, secondo le regole in vigore. Se compare un errore di verifica, completa i passaggi nell'app e riprova.
L'header TgPayCrypto-API-Signature contiene l'HMAC-SHA256 del corpo della richiesta, con lo SHA-256 del token principale come chiave. Confronta la firma sui byte originali del corpo. Non consegnare prodotti e non segnare la fattura come pagata finché la verifica non riesce.
La Merchant API riprende metodi, struttura {ok, result}, importi come stringhe decimali e firma dell'API Crypto Bot. Cambia URL di base e token, poi prova l'integrazione. L'header Crypto-Pay-API-Token è accettato come alias.
La testnet usa la stessa API e mini app: bot @tgpaycrypto_testnet_bot, base testnet.tgpaycrypto.com/pay/api. Il pulsante nella schermata principale fornisce 1.000 USDT, 1.000 GRAM e 0,01 BTC di test una volta all'ora. I token di mainnet e testnet non sono intercambiabili.
L'agente riceve un token limitato per creare fatture e piani di abbonamento, leggere saldo e statistiche e configurare il webhook. Trasferimenti, buoni e rimborsi richiedono permessi aggiuntivi e le relative funzionalità abilitate.
Documentazione pubblica Merchant API
Riferimento dei metodi, specifica OpenAPI e guide dettagliate su docs.tgpaycrypto.com.
Integra i pagamenti nel tuo prodotto
Crea un'app in @tgpaycryptobot oppure passa il link del server MCP al tuo agente AI e approva la creazione nel bot.
Apri il bot