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.
È il lato sviluppatore dello stesso prodotto che vedono gli utenti: una fattura che crei dall’API è la fattura che loro pagano dal saldo con un tocco.
Che cosa ci puoi fare
- Fatture — crei una fattura (un importo fisso in cripto, uno prezzato in valuta fiat o un importo libero che sceglie chi paga), mandi il link a chi deve pagare e ricevi una notifica firmata nel momento in cui viene pagata.
- Rimborsi — restituisci l’importo di una fattura pagata, in tutto o in parte, a chi l’ha pagata: anche a chi ha pagato in forma anonima.
- Trasferimenti — mandi cripto dal saldo della tua app a un utente Telegram, uno alla volta o fino a 100 in un colpo solo.
- Buoni — emetti dal saldo della tua app dei link che chiunque può riscattare.
- Abbonamenti — fatturazione ricorrente: l’utente approva un piano una volta e viene addebitato da solo a ogni periodo.
- Saldi, valute, tassi di cambio e statistiche — endpoint di sola lettura per la tua contabilità.
Come si incastra tutto
- La tua app ha un saldo, separato dal tuo portafoglio personale.
- Le fatture pagate dagli utenti accreditano quel saldo dell’app.
- Trasferimenti e buoni escono da quel saldo.
- Ogni evento che conta ti arriva sul tuo server come webhook firmato.
I pagamenti si chiudono dentro l’app, non on-chain: niente commissione di rete, nessuna conferma da aspettare e fondi utilizzabili nell’istante in cui arrivano. Chi paga può comunque coprire una fattura da un portafoglio esterno: il suo deposito arriva sul suo portafoglio e la fattura si salda da lì in automatico; dal tuo lato è identica a qualsiasi altra fattura pagata.
Compatibile con Crypto Bot
L’API è fatta apposta per rispecchiare quella di Crypto Bot: stessi nomi dei
metodi, stessa busta {ok, result}, stessi importi come stringhe decimali,
stesso schema di firma dei webhook. Un’integrazione Crypto Bot esistente la
punti su di noi cambiando l’URL di base e il token: le forme di richiesta e
risposta non cambiano.
L’intestazione ufficiale del token è TgPayCrypto-API-Token, e accettiamo
Crypto-Pay-API-Token come alias, così le librerie client esistenti continuano
a funzionare senza modifiche.
⚠️ Il tuo token API può spendere i tuoi fondi
Chi ce l’ha può svuotare il saldo della tua app. Tienilo lato server, fuori dalle app client e dai repository, e rigeneralo appena sospetti che sia trapelato. Per i server che non hanno bisogno dell’accesso completo, emetti un token con permessi limitati, ristretto agli ambiti che usano davvero: vedi il riferimento dell’API.
Il prossimo passo
Questa guida ti è stata utile?
Grazie del riscontro.