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, ottieni un token, emetti fatture dal codice e ricevi webhook di pagamento firmati. Un agente MCP compatibile può aiutarti con l'integrazione. I pagamenti dal saldo del portafoglio vengono regolati nel servizio; quelli sulla blockchain seguono le regole di conferma della rete scelta.
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
Con un pulsante o un link nel tuo bot, l'utente paga dal saldo del portafoglio. Gli importi elevati richiedono la conferma con PIN o Face ID.
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 ha un server MCP. Collegalo in un client agente compatibile: l'agente può leggere la documentazione, richiedere la creazione di un'app, configurare i webhook e aiutare a scrivere l'integrazione. Tu approvi l'app in Telegram, poi verifichi e provi il risultato.
- Passaggio 1
Invia la richiesta al tuo agente
Usa un client agente con supporto per MCP remoto disponibile per il tuo account o spazio di lavoro. La richiesta è anche 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
Completa e prova l'integrazione
L'agente riceve un token limitato e aiuta a configurare fatture, piani di abbonamento e webhook. Per ottenere la chiave di firma dei webhook, rinnova il token principale nell'app e conservalo in modo sicuro sul tuo server.
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 MCP server (https://app.tgpaycrypto.com/mcp) and integrate payments via the 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. Per ogni app puoi attivare gli eventi di scadenza di fatture e buoni, riscatto dei buoni, rimborso, pagamento in uscita e abbonamento.
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
Collega app.tgpaycrypto.com/mcp in un client agente che supporta server MCP remoti. Dopo la tua approvazione in Telegram, l'agente può creare un'app e aiutarti con l'integrazione. Verifica e prova il risultato prima di usarlo.
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