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.
2. Digita un Nome dell’app (per esempio “Il mio negozio”) e, se vuoi, un URL del webhook.
3. Tocca Crea app.
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 TgCryptoPay-API-Token.

La tua prima chiamata

Punta il client sulla base dell’API https://crypto.tgpaybot.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 che muovono denaro — createInvoice, transfer, createCheck e i corrispondenti metodi di eliminazione — sono solo POST, ed è voluto: importi e chiavi di idempotenza non devono finire nei log degli accessi. I parametri si possono mandare come corpo JSON, come form-urlencoded o come parametri nella query.

Gestire un’app

Ogni scheda app in Merchant API mostra il suo ID e il suo saldo, e da lì puoi:

• Impostare o cambiare l’URL del webhook e salvarlo.
• Scegliere gli eventi webhook aggiuntivi — una volta impostato un URL, con le opzioni Eventi webhook aggiuntivi attivi i tipi di evento oltre a invoice_paid (vedi il riferimento dei webhook).
• Creare token con permessi limitati — token API in più, sotto Token con permessi limitati, ciascuno ristretto agli ambiti che scegli (vedi il riferimento dell’API).
• Rigenera il 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.
• Eliminare — l’app smette di autenticarsi, ma il suo saldo e lo storico dei pagamenti restano. Eliminare un’app non fa sparire i suoi soldi.

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 TgCryptoPay-API-Signature (con Crypto-Pay-API-Signature come alias di compatibilità): HMAC-SHA256 sul corpo grezzo, con chiave l’SHA-256 del tuo token API. 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 viene consegnato sempre. 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 limitato senza l’ambito payouts può creare fatture ma non potrà mai mandare fuori il tuo saldo.