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.

Come si fa

1. Apri Altro → Merchant API e scegli Crea app.
2. Inserisci un Nome dell’app (per esempio “Il mio negozio”) e, se vuoi, un URL del webhook (facoltativo).
3. Accetta le condizioni nel modulo e tocca Crea app. Conferma con PIN o biometria quando richiesto. Creando un’app accetti le condizioni della Merchant API: per che cosa puoi usare l’API e per che cosa no.
4. Copia subito il token API. Lo mostriamo una volta sola e mai più: l’app ne conserva solo un hash.
5. Manda la tua prima richiesta con il token nell’intestazione TgPayCrypto-API-Token.

La tua prima chiamata

Punta il client sulla base dell’API https://app.tgpaycrypto.com/pay/api e chiama getMe per verificare che il token funzioni. getBalance restituisce i saldi della tua app, getCurrencies gli asset che puoi usare.

I metodi di lettura sono GET. Quelli di scrittura, come createInvoice, transfer, createCheck, deleteInvoice e deleteCheck, accettano solo POST. Puoi inviare i parametri come corpo JSON, come form-urlencoded o nella query. Preferisci il corpo della richiesta per evitare che importi e chiavi di idempotenza finiscano nei log degli URL.

Testnet

Costruisci l’integrazione prima sulla rete di prova: stessa API, stessa Mini App, fondi di prova senza valore reale.

	Mainnet	Testnet
Bot	@tgpaycryptobot	@tgpaycrypto_testnet_bot
Base dell’API	https://app.tgpaycrypto.com/pay/api	https://testnet.tgpaycrypto.com/pay/api
Server MCP	https://app.tgpaycrypto.com/mcp	https://testnet.tgpaycrypto.com/mcp

App e token sono separati: un token della testnet non funziona sulla mainnet, e viceversa. Per avere dei fondi, apri la Mini App della testnet e tocca Ricevi monete di prova nella schermata principale. Il servizio accredita un pacchetto di fondi di prova come normali depositi, saltando gli asset sulle reti disattivate. L’app mostra che cosa è stato accreditato e quando puoi inviare un’altra richiesta. Puoi usare un secondo account Telegram come cliente che paga le fatture di prova.

Depositi e prelievi usano una custodia simulata, senza transazioni reali sulla blockchain. Non inviare mai fondi reali a un indirizzo della testnet. L’interfaccia API è la stessa, ma funzioni disponibili, tassi e limiti possono differire dalla mainnet. Quando hai finito, crea un’app di produzione in @tgpaycryptobot e cambia l’URL di base.

Gestire un’app

Apri un’app in Merchant API per vedere il suo ID e il suo saldo. Da lì puoi:

• Impostare o cambiare l’URL del webhook nella sezione Webhook e salvarlo.
• Scegliere gli eventi webhook aggiuntivi — con le opzioni Eventi webhook aggiuntivi nella sezione Webhook attivi i tipi di evento oltre a invoice_paid (vedi il riferimento dei webhook).
• Limitare chi può ricevere pagamenti dall’API — in Impostazioni dei pagamenti, per un’app nuova Pagamenti tramite API è su Qualsiasi utente; passa a Solo utenti in elenco (e inserisci i destinatari) oppure a Disattivati se la tua integrazione non paga mai nessuno: una protezione nel caso in cui il token trapeli (vedi la modalità dei pagamenti).
• Creare token con permessi limitati — apri Accesso e token per creare token API aggiuntivi sotto Token con permessi limitati, ciascuno ristretto agli ambiti che scegli (vedi il riferimento dell’API).
• Rigenera il token — in Accesso e token, emette un token nuovo e invalida quello vecchio all’istante. Usalo se un token è trapelato; anche il nuovo si vede una volta sola, come alla creazione.
• Elimina — prima trasferisci il saldo disponibile; altrimenti l’eliminazione viene rifiutata con app_has_balance. Risolvi anche i buoni ancora attivi e i pagamenti in attesa prima di eliminare l’app. L’app scompare dall’elenco e i suoi token smettono di funzionare; lo storico dei pagamenti resta.

I webhook

Se imposti un URL per il webhook, l’app ci manda in POST un corpo JSON firmato:

{ "update_id": …, "update_type": "invoice_paid", "request_date": …, "payload": { … } }

La firma sta nell’intestazione TgPayCrypto-API-Signature (con TgCryptoPay-API-Signature e Crypto-Pay-API-Signature come alias di compatibilità): HMAC-SHA256 sul corpo grezzo, con chiave l’SHA-256 del tuo token API principale. Verificala prima di fidarti di qualsiasi cosa ci sia dentro.

Le consegne vengono ritentate con attese crescenti per un periodo lungo, e update_id resta lo stesso a ogni tentativo: usa quello per deduplicare e fai in modo che il tuo gestore sia idempotente.

invoice_paid non richiede un’attivazione separata se è configurato un URL per i webhook. Gli altri tipi di evento — fatture scadute, buoni riscattati, rimborsi, eventi degli abbonamenti — si attivano a scelta con le opzioni Eventi webhook aggiuntivi. L’elenco completo, la forma dei payload e il calendario dei tentativi stanno nel riferimento dei webhook.

⚠️ Custodisci il token come una chiave privata

Autorizza pagamenti in uscita dal saldo della tua app. Tienilo sul tuo server, mai dentro un’app per telefono, un bundle front-end o una configurazione committata. Se hai anche solo il dubbio che sia trapelato, rigeneralo: è immediato e non costa niente. E dai a ogni server solo quello che gli serve: un token con il solo ambito invoices può creare ed eliminare fatture, ma non può trasferire fondi, creare buoni o emettere rimborsi.